# Unit Converter API + MCP Tutorial

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

## Prerequisites

- Python 3.10+ (tested with 3.12).
- Virtual environment.
- npm inspector below.

⸻

## Setup from this folder

```bash
python -m venv .venv

# Mac or Gitbash
source .venv/bin/activate

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

⸻

## Run the HTTP + MCP server

```bash
# start the server
python converter_streamable_http_server.py

# or
python -m converter_streamable_http_server

```

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
- SSE: http://localhost:8003/sse

⸻

## Try the HTTP endpoints (curl)

```bash
curl -X POST "http://localhost:8003/miles-to-kilometers?miles=3.1" \
 -H "Authorization: Bearer 143f4a46d74fee0d7918b2857577868cb3daf9e6e50ee91c2f7975ba26fdb8f7"

# If we use pydantic models
curl -X POST "http://localhost:8003/miles-to-kilometers" \
 -H "Content-Type: application/json" \
 -H "Authorization: Bearer Y658139cf61948208ed76a4b36122b9552ec5c3f6da5e02f7c5d85d995dede17dE" \
 -d "3.1"
```

```bash
# Celsius → Fahrenheit
curl -X POST "http://localhost:8003/celsius-to-fahrenheit" \
 -H "Content-Type: application/json" \
 -d "25"
```

```bash
# Fahrenheit → Celsius
curl -X POST "http://localhost:8003/fahrenheit-to-celsius" \
 -H "Content-Type: application/json" \
 -d "86"
```

```bash
# Kilometers → Miles
curl -X POST "http://localhost:8003/kilometers-to-miles" \
 -H "Content-Type: application/json" \
 -d "5"
```

```bash
# Miles → Kilometers (rejects negative values)
curl -X POST "http://localhost:8003/miles-to-kilometers" \
 -H "Content-Type: application/json" \
 -d "3.1"
```

Each endpoint returns JSON like:

- { "result": <number>, "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)

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

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

3. 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

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

# If you want to test the older HTTP:
npx @modelcontextprotocol/inspector@latest -e DUMMY=1 --url http://localhost:8003/mcp --transport http

# If you want to test the deprecated SSE:
npx @modelcontextprotocol/inspector@latest -e DUMMY=1 --url http://localhost:8003/sse --transport sse
```

## To run the STDIO server only

```bash
# If venv is ".venv", change to .\.venv\Scripts\python.exe
npx @modelcontextprotocol/inspector python converter_stdio_server.py
```

- UI runs on localhost:5173 by default.
- Change UI port if needed: CLIENT_PORT=8080 npx @modelcontextprotocol/inspector --url http://localhost:8003/mcp --transport http
- Add headers if required: --header "Authorization: Bearer TOKEN".

## JSON-RPC Examples for Prompts & Resources

1. List all prompts

```bash
curl -s -X POST <SERVER_URL> \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"prompts/list","params":{},"id":1}'
```

⸻

2. Get a specific prompt

```bash
curl -s -X POST <SERVER_URL> \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"prompts/get","params":{"name":"summarize"},"id":2}'
```

⸻

3. Render/execute a prompt with variables

```bash
curl -s -X POST <SERVER_URL> \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"prompts/render","params":{"name":"summarize","variables":{"text":"This is the content to summarize","tone":"neutral"}},"id":3}'
```

4. List available resources

```bash
curl -s -X POST <SERVER_URL> \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"resources/list","params":{},"id":4}'
```

5. Read a resource by URI

```bash
curl -s -X POST <SERVER_URL> \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"resources/read","params":{"uri":"file:///data/report.pdf"},"id":5}'
```

6. Search resources (if supported)

```bash
curl -s -X POST <SERVER_URL> \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"resources/search","params":{"query":"error OR exception","limit":50},"id":6}'
```

⸻

## Handling errors

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

## Notes

macOS/Linux (bash/zsh)
• The examples above will work as-is.

```bash
# Windows PowerShell
curl -Method POST <SERVER_URL> `  -Headers @{ "Content-Type"="application/json" }`
-Body '{"jsonrpc":"2.0","method":"prompts/list","params":{},"id":1}'
```

Windows CMD

```bash
curl -s -X POST <SERVER_URL> -H "Content-Type: application/json" -d "{\"jsonrpc\":\"2.0\",\"method\":\"prompts/list\",\"params\":{},\"id\":1}"
```