# BigBugAI MCP (Python + FastMCP)

[![CI](https://github.com/bigbugAi/bigbugai-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/bigbugAi/bigbugai-mcp/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

Production-ready MCP server exposing BigBugAI tools with stdio transport for local MCP clients (Claude Desktop, Cursor) and optional HTTP/SSE transport (FastAPI + uvicorn) for remote access.

- Auth via API key (env var)
- Per-key rate limiting (moving window; configurable via env)
- Typed Pydantic schemas for tool I/O
- Clean error handling and JSON-stable outputs
- Tests, ruff, and mypy configuration

## Tools

- `get_trending_tokens(limit: int = 10) -> list[dict]`
  - GET `${BTUNIFIED_API}/api/tokens/newly-ingested` by default
  - Falls back to `${BTUNIFIED_API}/v1/trending/tokens` and a few other candidates if 404
  - Override primary path with `BTUNIFIED_TRENDING_PATH`
  - Normalizes `{items: [...]} -> [...]`
- `token_analysis_by_contract(chain: str, address: str) -> dict`
  - GET `${BTUNIFIED_API}/api/token-intel/{chain}/{address}/report`

## Requirements

- Python 3.11+
- Packages: `mcp[cli]`, `httpx`, `pydantic`, `fastapi`, `uvicorn`, `limits`, `pytest`, `ruff`, `mypy`

## Environment variables

- `BIGBUGAI_MCP_API_KEY` (required)
- `BIGBUGAI_API_KEY` / `BIGBUGAI_API_TOKEN` (optional; used for upstream HTTP calls if set.
  If not set, HTTP calls will fall back to `BIGBUGAI_MCP_API_KEY`.)
- `BTUNIFIED_API` (default: `https://api.bigbug.ai`)
- `MCP_RATE_LIMIT` (default: `60/hour`, rate string per `limits`)

## Install

Using uv (recommended):

- Unix/macOS

```bash
uv venv
source .venv/bin/activate
uv pip install -e .[dev]
```

- Windows PowerShell

```powershell
uv venv
.venv\Scripts\Activate.ps1
uv pip install -e .[dev]
```

Alternatively, you can explicitly add packages (will update pyproject as needed):

```bash
uv add "mcp[cli]" httpx pydantic fastapi uvicorn limits pytest ruff mypy
```

## Run (STDIO)

```bash
export BIGBUGAI_MCP_API_KEY="your-secret"
export BTUNIFIED_API="https://api.bigbug.ai"
uv run -m bigbugai_mcp.server_stdio
```

Windows PowerShell:

```powershell
$env:BIGBUGAI_MCP_API_KEY="your-secret"
$env:BTUNIFIED_API="https://api.bigbug.ai"
uv run -m bigbugai_mcp.server_stdio
```

This mode is intended for local MCP clients (e.g., Claude Desktop, Cursor).

Note: Tools no longer require `api_key` in the payload. The server reads the API key
from the environment (`BIGBUGAI_MCP_API_KEY`) and applies rate limiting based on it.

## Claude Desktop config

Create `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "bigbugai": {
      "command": "uv",
      "args": ["-m", "bigbugai_mcp.server_stdio"],
      "env": {
        "BIGBUGAI_MCP_API_KEY": "your-secret",
        "BTUNIFIED_API": "https://api.bigbug.ai",
        "MCP_RATE_LIMIT": "60/hour"
      }
    }
  }
}
```

## Run (HTTP)

```bash
uv run -m bigbugai_mcp.server_http
# server on :8000
curl -s http://localhost:8000/healthz
```

Expected output:

```
ok
```

MCP HTTP/SSE endpoints are mounted under `/mcp`. Depending on your FastMCP version, an SSE stream may be available at `/mcp/sse`.

Example cURL (SSE; may require `-N` to keep the connection open and is primarily for debugging):

```bash
curl -N http://localhost:8000/mcp/sse
```

Note: MCP over HTTP/SSE is designed for compatible clients; manual cURL interaction is limited.

## Smoke scripts

Quick sanity checks for the tools (require an API key in env):

- Trending
  ```bash
  # uses BIGBUGAI_API_KEY/BIGBUGAI_API_TOKEN/BIGBUGAI_MCP_API_KEY from env
  uv run python scripts/smoke_trending.py -l 5
  ```

- Token analysis
  ```bash
  # requires BIGBUGAI_MCP_API_KEY in env; optionally set BB_CHAIN/BB_ADDRESS
  $env:BIGBUGAI_MCP_API_KEY="your-secret"        # PowerShell
  uv run python scripts/smoke_token_analysis.py
  ```

## Testing and Quality

```bash
# Run unit tests
uv run pytest -q

# Lint
uv run ruff check .

# Type check
uv run mypy src
```

## Project layout

```
bigbugai-mcp/
  .github/workflows/ci.yml
  CODE_OF_CONDUCT.md
  CONTRIBUTING.md
  LICENSE
  README.md
  SECURITY.md
  pyproject.toml
  scripts/list_tools.py
  scripts/smoke_token_analysis.py
  scripts/smoke_trending.py
  src/bigbugai_mcp/__init__.py
  src/bigbugai_mcp/auth.py
  src/bigbugai_mcp/models.py
  src/bigbugai_mcp/server_http.py
  src/bigbugai_mcp/server_stdio.py
  src/bigbugai_mcp/tools.py
  tests/test_tools.py
```

## Security

- Rotate API keys regularly
- Keep HTTP mode behind OAuth/reverse proxy if exposed publicly
- Rate limits are per API key in a moving window strategy

See [SECURITY.md](SECURITY.md) for reporting vulnerabilities.

## Extending

Add more tools for BigBugAI endpoints (portfolio manager, investment suggester, etc.).

- Add new Pydantic request/response models in `src/bigbugai_mcp/models.py`
- Add the tool function in `src/bigbugai_mcp/tools.py`
- Decorate with `@guarded` and register in `register_tools()`
- Write tests in `tests/`

## Contributing

Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## Code of Conduct

This project follows the [Contributor Covenant](CODE_OF_CONDUCT.md).

## License

MIT — see [LICENSE](LICENSE).