Converter API + MCP

builds the FastAPI app, wraps it with FastMCP, mounts MCP HTTP 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.14+
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 (recommended)
python -m main

# with UV (install in work in progress)
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 <TOKEN>"

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

Use with MCP (VS Code Example)

Start the server as above.
Point your MCP client to the process.

// Example VS Code .vscode/mcp.json entry:
{
  "servers": {
    "UnitConverter": {
      "command": "python",
      "args": ["main.py"]
    }
  }
}

From the MCP client, list artifacts. You should see:
- Tools: celsius_to_fahrenheit, fahrenheit_to_celsius, kilometers_to_miles, miles_to_kilometers
- Resources: resource://unit_reference, resource://troubleshooting_guide
- Prompts: explain_conversion, api_usage

Inspect with the npm MCP Inspector

explore everything (tools, resources, prompts) in a browser.
with the server already running on http://localhost:8003

# If env error appears
npx @modelcontextprotocol/inspector@latest -e DUMMY=1 --url http://localhost:8003/mcp --transport streamable-http

Run Tests

Run the test suite:

python -m pytest -v

Or with UV:

uv run pytest -v

Or with just:

just test

Adding Extensions

Add new MCP tools here:

app/mcp/mcp_tools/

Add new MCP prompts here:

app/mcp/mcp_prompts/

Add new MCP resources here:

app/mcp/mcp_resources/

Add or update MCP tests here:

tests/mcp/

Add or update example LLM client code here:

example_llm_client/

Contributing

For detailed contribution guidelines, see CONTRIBUTION.md.

Handling errors

Parse error (-32700)
Invalid request (-32600)
Method not found (-32601)
Invalid params (-32602)
Internal error (-32603)

Notes