# MCP Utility Server

A production-grade [Model Context Protocol](https://modelcontextprotocol.io) server with **10 utility tools** for daily operations. Built with FastMCP, stdlib-first, fully tested (TDD).

**Why this server:** it demonstrates real MCP engineering — not a hello-world. It includes:
- **Retry/backoff with jitter** on all external HTTP calls (429/5xx handling)
- **State persistence** for page monitoring (SHA-256 diff tracking)
- **Observability** — per-tool retry counters exposed as an MCP tool
- **Sandboxing** for file operations (optional `FILE_SANDBOX`)
- **Deterministic outputs** (word-of-day selection is hash-based, same all day)
- **~30 pytest tests** with mocked network (no external deps in CI)

## Tools

| Tool | Description |
|------|-------------|
| `file_convert` | Convert MD/HTML/CSV/JSON/Text formats (stdlib-only) |
| `page_monitor` | Poll a URL, SHA-256 diff, optional Telegram notify on change |
| `telegram_poll` | Send Telegram polls (2-10 options) |
| `trade_signal` | Binance OHLCV → RSI(14) + SMA20/SMA50 cross → BUY/SELL/HOLD |
| `backtest_report` | Parse Freqtrade backtest JSON → markdown digest |
| `word_of_day` | German word (A1/A2) with translations, IPA, examples — deterministic per date |
| `soc_lang_card` | Daily language card: German word + SOC term (EN/DE/RU) |
| `weather_alert` | Open-Meteo threshold alerts (wind/rain) for configured cities |
| `antimatter_scan` | Scan trading logs for trades/errors/signals + resonance score |
| `mcp_stats` | Retry/backoff observability snapshot |

## Quick start

```bash
# Install
uv sync

# Run (stdio transport — default for MCP clients)
uv run server.py

# Run (SSE transport — for remote clients)
uv run server.py --transport sse

# Test
uv run pytest
```

## Configuration (env vars)

| Env | Default | Purpose |
|-----|---------|---------|
| `TELEGRAM_BOT_TOKEN` | — | Required for `telegram_poll` / page_monitor notify |
| `TELEGRAM_CHAT_ID` | — | Default chat for Telegram tools |
| `FILE_SANDBOX` | unset (allow-all) | Restrict `file_convert` to a directory. **Set on production!** |
| `STATE_DIR` | `~/.mcp-utility/state` | Page-monitor state location |
| `HTTP_MAX_RETRIES` | `2` | Max retries on 429/5xx (1 initial + N retries) |
| `HTTP_RETRY_DELAY` | `1.0` | Base backoff seconds (exponential, ±20% jitter) |
| `MCP_STATS_PATH` | `/tmp/mcp_utility_stats.json` | Retry stats persistence |
| `MCP_LOG` | `INFO` | Logging level |
| `MCP_TRANSPORT` | `stdio` | `stdio` or `sse` |

## Example: Claude Desktop

```json
{
  "mcpServers": {
    "mcp-utility": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/mcp-utility-server", "server.py"]
    }
  }
}
```

## Example: trade signal

```bash
echo '{"symbol":"BTCUSDT","interval":"1d"}' | uv run server.py
# → {"status":"ok","symbol":"BTCUSDT","rsi":42.3,"ma_fast":42100.0,
#    "ma_slow":41800.5,"signal":"BUY","reasons":["MA20 > MA50"],...}
```

## Security notes

- `file_convert` accepts **any path** when `FILE_SANDBOX` is unset — always set it in production
- Telegram token is read from env only, never logged
- `antimatter_scan("docker:...")` executes `docker logs` — requires docker socket access

## License

MIT