MCP Local FastMCP Server

This repo keeps the existing Docker/GitHub Actions deployment and rollback wrapper, but replaces the demo Nginx HTML page with a lightweight Python FastMCP server.

What changed from the demo app

• Removed the Nginx demo app.
• Removed index.html.
• Added FastMCP Python application under app/.
• Added pinned Python dependencies in requirements.txt.
• Container now listens on internal port 8000.
• Host port remains controlled by APP_PORT, default 127.0.0.1:8002.
• MCP endpoint: http://127.0.0.1:8002/mcp.
• SearXNG runs as an internal Docker service for free search.
• Tavily can be enabled as fallback by setting TAVILY_API_KEY.
• Reference records are saved to the mcp-data Docker volume as JSONL.
• Mail and real DB providers are abstract placeholders for later implementation.

Run locally

cp .env.example .env
docker compose --env-file .env up --build

MCP endpoint on the host:

http://127.0.0.1:8002/mcp

Deploy locally using existing deployment flow

./scripts/deploy-local.sh

Available MCP tools

• health_check
• web_search
• web_search_and_scrape
• scrape_url
• extract_image_urls
• mail_search abstract placeholder
• mail_read abstract placeholder
• mail_create_draft abstract placeholder
• mail_send_draft abstract placeholder

Persistent data

Scraped references are stored at /data/references.jsonl inside the container, backed by the mcp-data Docker volume.

Production note

Keep HOST_BIND=127.0.0.1 unless you intentionally want the MCP endpoint reachable from outside the server. Caddy can continue reverse proxying to 127.0.0.1:8002 if needed.