# MCP Tool Server

A production-oriented MCP (Model Context Protocol) server that exposes tools
to AI agents, built on FastMCP + FastAPI, with Docker support.

Built as a learning/portfolio project referencing the architecture of
[PrefectHQ/fastmcp](https://github.com/PrefectHQ/fastmcp), extended with
several original pieces:

- **Auto-discovery tool registry** — drop a file with a `register(mcp)` function
  into `app/tools/` and it's picked up automatically. No manual wiring in `main.py`.
- **Per-client rate limiting** — in-memory token bucket, keyed by API key.
- **API key auth** on the HTTP surface (`/tools/*` endpoints), independent from
  the raw MCP protocol endpoint.
- **Structured logging** with per-request IDs and timing.
- **/health** and **/metrics** endpoints for basic observability.

## Tools included

| Tool | Description |
|---|---|
| `get_weather` | Current weather for a lat/lon (Open-Meteo API) |
| `convert_currency` | Live FX conversion between currencies |
| `text_stats` | Word/sentence count + estimated reading time for text |
| `server_info` | Server introspection (uptime, platform, python version) |

## Running locally

```bash
pip install -r requirements.txt
python -m app.main
```

Server starts on `http://localhost:8000`.

- MCP protocol clients connect to `http://localhost:8000/mcp`
- HTTP clients can call `POST /tools/{tool_name}/invoke` with header `x-api-key: <key>`

## Running with Docker

```bash
docker compose up --build
```

## Adding a new tool

Create `app/tools/my_tool.py`:

```python
def register(mcp) -> str:
    @mcp.tool()
    def my_tool(x: int) -> int:
        """Doubles a number."""
        return x * 2
    return "my_tool"
```

That's it — no changes to `main.py` needed, it's discovered on startup.

## Tests

```bash
pytest tests/
```

## Environment variables

| Variable | Default | Description |
|---|---|---|
| `PORT` | 8000 | Server port |
| `API_KEYS` | (empty = no auth) | Comma-separated allowed API keys |
| `RATE_LIMIT_CAPACITY` | 20 | Max burst requests per client |
| `RATE_LIMIT_REFILL_PER_SEC` | 2 | Token refill rate per second |
| `LOG_LEVEL` | INFO | Logging verbosity |