Converter API + MCP

• builds the FastAPI app, wraps it with FastMCP, mounts MCP HTTP/SSE endpoints, registers resources and prompts, and starts uvicorn.
• requirements.txt - Python dependencies.

System Architecture

This project uses main.py as the main entry point.

The FastAPI app provides the HTTP API, documentation pages, and health check. FastMCP wraps the FastAPI app and exposes MCP tools, resources, and prompts through the MCP endpoint.

main.py
  |
  |-- FastAPI app
  |     |-- HTTP routes
  |     |-- Swagger UI
  |     |-- ReDoc
  |     |-- health check
  |
  |-- FastMCP
        |-- MCP tools
        |-- MCP resources
        |-- MCP prompts
        |-- /mcp endpoint

Important folders:

app/mcp/mcp_tools/        # MCP tools and FastAPI route logic
app/mcp/mcp_prompts/      # MCP prompt templates
app/mcp/mcp_resources/    # MCP resource definitions
tests/mcp/                # MCP test suite
example_llm_client/       # Example Gemini / LLM client

Prerequisites

• Python 3.13
• Virtual environment.
• npm inspector below.

Setup from this folder

python -m venv .venv

# Mac or Gitbash
source .venv/bin/activate

# Windows powershell:
.venv\Scripts\activate
python -m pip install -r requirements.txt

# or use UV:
uv sync

Configure Gemini

The project includes an example environment file called .env.example.

Create a local .env file from .env.example, then add your Gemini configuration:

GEMINI_API_KEY=your_api_key_here
GEMINI_MODEL=gemini-2.5-flash
MCP_SERVER_URL=http://localhost:8003/mcp

You can get a Gemini API key from Google AI Studio.

The .env file is ignored by git, so your API key should stay local and should not be committed.

Run the HTTP + MCP server

# start the server

# with Python 
python -m main

# with UV (recommended)
uv run main.py

# with just
just run

To run test curl commands see app/docs/curl_testing/mcp_curl_test_examples.md.

You’ll see:

• Swagger UI: http://localhost:8003/docs
• ReDoc: http://localhost:8003/redoc

MCP endpoints served by FastMCP:

• streamable-http: http://localhost:8003/mcp

Each endpoint returns JSON like:

• { “result”: , “operation”: “…” } or { “error”: “…” } for invalid input.

Headers & Authentication (common to all)

Add JSON content type (and optionally your auth token)

-H "Content-Type: application/json"
-H "Authorization: Bearer "

Our server doesn’t require auth yet, we can omit the Authorization header.

Rate Limiting

The API includes rate limiting middleware for HTTP and MCP endpoints.

• Limit: 50 requests per client IP every 3600 seconds.
• Storage: request timestamps are tracked in memory and expired records are cleared.
• Exceeded limit: returns 429 Too Many Requests with a Retry-After header.
• Missing client IP: returns 400 Bad Request.

Use with MCP (VS Code Example)