Metadata-Version: 2.4
Name: botrun-default-mcp
Version: 0.5.0
Summary: Botrun default MCP server (stdio)
Author-email: sebastian-hsu <sebastian.hsu@gmail.com>
License: MIT
Requires-Python: >=3.11
Requires-Dist: beautifulsoup4==4.14.3
Requires-Dist: google-auth==2.49.1
Requires-Dist: google-genai==1.69.0
Requires-Dist: httpx==0.28.1
Requires-Dist: mcp==1.26.0
Requires-Dist: plotly==6.6.0
Requires-Dist: pypdf==6.9.2
Requires-Dist: python-dotenv==1.2.2
Requires-Dist: pytz==2026.1.post1
Description-Content-Type: text/markdown

# botrun-default-mcp

A stdio-based MCP (Model Context Protocol) server providing PDF analysis, image analysis, web search, web scraping, and visualization tools. Designed to run via `uvx` with no server deployment needed.

## Tools

| Tool | Description |
|------|-------------|
| `chat_with_pdf` | Analyze local PDF files with Gemini via Botrun Gateway (supports large files via chunked parallel processing) |
| `chat_with_imgs` | Analyze local image files with Gemini Vision via Botrun Gateway |
| `web_search` | Search the web via Perplexity API (supports OpenRouter) |
| `scrape` | Scrape web pages to Markdown via ScraperAPI |
| `create_html_page` | Generate HTML pages and save to local files |
| `create_plotly_chart` | Generate interactive Plotly charts as local HTML files |
| `create_mermaid_diagram` | Generate Mermaid diagrams as local HTML files |
| `current_date_time` | Get current date/time in Asia/Taipei timezone |

## Installation

```bash
uvx botrun-default-mcp
```

Or install from source:

```bash
git clone https://github.com/sebastian-hsu/botrun_default_mcp_uv.git
cd botrun_default_mcp_uv
uv sync
```

## Configuration

The server automatically loads environment variables from a `.env` file in the working directory. Just point `cwd` to the directory containing your `.env` file — no need to pass `env` in the MCP config.

### LLM routing (chat_with_pdf / chat_with_imgs)

Both tools call Gemini. Which endpoint they use is decided by environment variables (no runtime fallback):

1. `BOTRUN_GATE_BASE_URL` + `BOTRUN_GATE_API_KEY` both set → requests go through Botrun Gateway's `/gemini/*` passthrough (`base_url = ${BOTRUN_GATE_BASE_URL}/gemini`, auth via `Authorization: Bearer`). Vertex runs behind the gateway, so no GCP service account is needed. **This is the recommended setup.**
2. Otherwise → direct Vertex AI with the `GOOGLE_APPLICATION_CREDENTIALS_FOR_FASTAPI` service account (project `scoop-386004`, region `us-central1`).
3. Neither → the tools fail fast with a message naming both options.

Models available through the gateway passthrough are the Vertex `gemini-2.5-*` family (`gemini-2.5-flash`, `gemini-2.5-pro`, `gemini-2.5-flash-lite`). Aliases such as `gemini-flash-latest` do **not** exist there and return 404.

### Claude Desktop / Claude Code

Add to your MCP settings (`claude_desktop_config.json` or `.claude.json`):

```json
{
  "mcpServers": {
    "botrun-default-mcp": {
      "command": "uvx",
      "args": ["botrun-default-mcp"],
      "cwd": "/path/to/directory/with/dotenv"
    }
  }
}
```

### LangGraph

```json
{
  "botrun-default-mcp": {
    "transport": "stdio",
    "command": "/path/to/uvx",
    "args": ["botrun-default-mcp"],
    "cwd": "/path/to/directory/with/dotenv"
  }
}
```

### .env file example

```env
BOTRUN_GATE_BASE_URL=https://gate.botrun.ai
BOTRUN_GATE_API_KEY=br-your-key-here
OPENROUTER_API_KEY=sk-or-v1-xxx
OPENROUTER_BASE_URL=https://openrouter.ai/api/v1
SCRAPERAPI_API_KEY=your-scraperapi-key
```

### Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `BOTRUN_GATE_BASE_URL` | Yes* (for PDF/image tools) | Botrun Gateway base URL, e.g. `https://gate.botrun.ai` |
| `BOTRUN_GATE_API_KEY` | Yes* (for PDF/image tools) | Gateway `br-` API key (sent as `Authorization: Bearer`) |
| `GOOGLE_APPLICATION_CREDENTIALS_FOR_FASTAPI` | Yes* (only without gateway) | GCP service account JSON key for direct Vertex AI |
| `PPLX_API_KEY` | Yes† (for web_search) | Perplexity API key |
| `OPENROUTER_API_KEY` | Yes† (for web_search) | OpenRouter API key (alternative to PPLX_API_KEY) |
| `OPENROUTER_BASE_URL` | With OpenRouter | OpenRouter base URL |
| `SCRAPERAPI_API_KEY` | Yes (for scrape) | ScraperAPI key |
| `PDF_ANALYZER_MODEL` | No | Gemini model for PDF analysis (default: `gemini-2.5-flash`); comma-separated list = fallback order |
| `IMG_ANALYZER_MODEL` | No | Gemini model for image analysis (default: `gemini-2.5-flash`); comma-separated list = fallback order |

\* Either `BOTRUN_GATE_BASE_URL` + `BOTRUN_GATE_API_KEY` (recommended) or `GOOGLE_APPLICATION_CREDENTIALS_FOR_FASTAPI` is required for `chat_with_pdf` / `chat_with_imgs`.

† Either `PPLX_API_KEY` or `OPENROUTER_API_KEY` + `OPENROUTER_BASE_URL` is required for `web_search`.

## Development

```bash
# Setup
uv sync

# Run tests
uv run pytest tests/ -v

# Build
uv build

# Publish to PyPI
cd sh && bash seba_pypi.sh
```

## License

MIT
