ipos-open-source-2026S1

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

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

⸻

Run the HTTP + MCP server

# start the server

# with CPython
python3.14 -m main

# with UV (recommended)
uv run main.py

# with just
just run

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)

Using Mac:

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"

Using Windows:

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

rem 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"

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.

Use with MCP (VS Code Example)

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

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

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

JSON-RPC Examples for Prompts & Resources

(On Windows, paste those into a text editor and replace all \ with ^)

1. List all prompts

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

⸻

1. Get a specific prompt

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

⸻

1. Render/execute a prompt with variables

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}'

1. List available resources

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

1. Read a resource by URI

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}'

1. Search resources (if supported)

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.

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

Windows CMD

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