MCP Demo – Python-Agent-Tooling von Grund auf

Was ist MCP?

MCP (Model Context Protocol) ist ein standardisiertes Protokoll, das es KI-Anwendungen ermöglicht, externe Tools, Ressourcen und Prompts über eine einheitliche Schnittstelle zu entdecken und zu nutzen.

Anstatt dass jedes KI-Framework eine eigene Integration für jede Datenbank, API, jedes Dateisystem oder jeden internen Dienst erfindet, kann ein MCP-Host eine Verbindung zu einem MCP-Server herstellen und dieselbe Protokolloberfläche nutzen.

Probleme, die MCP löst

Über das Netzwerk verwendet MCP JSON-RPC-2.0-Nachrichten über Transporte wie stdio und HTTP-basierte Transporte (SSE/Streamable HTTP). Dieses Repository verwendet stdio: Der Client startet den Server als Unterprozess, sendet Protokollnachrichten über stdin und empfängt Antworten über stdout.

Related MCP server: Weather MCP Server

Architektur

flowchart TD
    A[User: "What's the weather in London?"] --> B[AI Agent<br/>OpenAI Responses API]
    B --> C[1. Discovers MCP tools]
    B --> D[2. Decides whether to call]
    B --> E[3. Emits function call]
    E --> F[MCP Client<br/>ClientSession + stdio]
    F --> G[initialize]
    F --> H[tools/list]
    F --> I[tools/call]
    I --> J[JSON-RPC 2.0<br/>stdin/stdout]
    J --> K[MCP Server subprocess]
    K --> L[get_current_weather tool]
    K --> M[greeting://{name} resource]

Warum das offizielle SDK?

Dieses Repository verwendet das offizielle Python-MCP-SDK, anstatt das Protokoll neu zu implementieren. Das SDK bietet:

• Protokoll-Lebenszyklus und -Validierung

• Transportabstraktion (stdio, HTTP/SSE)

• Typisierte Client-/Server-APIs

Der Anwendungscode macht die wichtigen MCP-Konzepte weiterhin explizit: Serverregistrierung, Tool-Schemata, initialize, tools/list, tools/call, Ressourcen-Lesevorgänge und stdio-Prozessverwaltung.

Die stabile v2-API des aktuellen SDKs verwendet MCPServer für die Serverkonstruktion und ClientSession/stdio_client für stdio-Clients.

Projektstruktur

mcp-demo/
├── README.md
├── requirements.txt
├── .env.example
├── pyproject.toml
├── src/
│   ├── mcp_server/
│   │   ├── __init__.py
│   │   ├── server.py      # MCP server entry point
│   │   ├── tools.py       # Tool implementations
│   │   ├── handlers.py    # Request handlers
│   │   └── utils.py       # Shared utilities
│   ├── mcp_client/
│   │   ├── __init__.py
│   │   ├── client.py      # MCP client wrapper
│   │   ├── agent.py       # OpenAI agent integration
│   │   └── runner.py      # Demo runner
│   └── shared/
│       ├── __init__.py
│       └── types.py       # Shared Pydantic models
├── tests/
│   ├── test_server.py
│   └── test_client.py
├── examples/
│   └── demo.ipynb
└── scripts/
    └── run_demo.sh

Anforderungen

• Python 3.10+

• OpenAI-API-Schlüssel (für die KI-Agenten-Demo)

• Kein Wetter-API-Schlüssel erforderlich – das Wetter-Tool verwendet deterministische Beispieldaten, sodass der MCP-Pfad offline funktioniert.

Schnellstart

1. Virtuelle Umgebung erstellen

python -m venv .venv
source .venv/bin/activate        # Linux/macOS
.venv\Scripts\Activate.ps1       # Windows PowerShell

2. Abhängigkeiten installieren

python -m pip install --upgrade pip
pip install -r requirements.txt

3. OpenAI konfigurieren

cp .env.example .env

Bearbeiten Sie .env mit Ihren Anmeldedaten:

OPENAI_API_KEY=your_api_key_here
OPENAI_MODEL=gpt-4.1-mini

Der Server selbst benötigt keinen OpenAI-Schlüssel.

Demo ausführen

Vom Repository-Stammverzeichnis aus

python src/mcp_client/runner.py

Was der Runner tut:

Alternative: Shell-Wrapper

bash scripts/run_demo.sh

Erwartete Ausgabe

Der genaue Wortlaut variiert je nach Modell, aber der Log-Ablauf sieht so aus:

INFO mcp_client.client: -> MCP initialize
INFO mcp_client.client: <- MCP initialize: server=mcp-demo-server
INFO mcp_client.client: -> MCP tools/list
INFO mcp_client.client: <- MCP tools/list: ["get_current_weather"]
INFO mcp_client.agent: User: What's the weather in London?
INFO mcp_client.agent: OpenAI requested tool: get_current_weather {"city":"London","units":"metric"}
INFO mcp_client.client: -> MCP tools/call name=get_current_weather arguments={"city":"London","units":"metric"}
INFO mcp_server.tools: weather lookup city=London units=metric
INFO mcp_client.client: <- MCP tools/call result={"city":"London","temperature":18.0,...}
INFO mcp_client.agent: Final: London is 18°C and partly cloudy.

Die Logs zeigen bewusst MCP-semantische Nachrichten an der Anwendungsgrenze. Das SDK übernimmt die JSON-RPC-Rahmung intern.

MCP-Server eigenständig ausführen

python src/mcp_server/server.py

Ein stdio-MCP-Server scheint zu „hängen“ – das ist erwartet. Er wartet auf Protokollnachrichten auf stdin. Ein Host/Client sollte ihn starten und die stdio-Pipes besitzen.

Interaktive Protokollprüfung

pip install "mcp[cli]"
mcp dev src/mcp_server/server.py

Demonstrierte MCP-Methoden

Das offizielle SDK übernimmt den JSON-RPC-Lebenszyklus:

Der Client ruft explizit initialize() auf, bevor er Fähigkeiten auflistet oder aufruft. Die Dekoratoren des Servers generieren Tool-/Ressourcen-Schemata aus Python-Typannotationen.

Tool: get_current_weather

get_current_weather(
    city: str,
    units: Literal["metric", "imperial"] = "metric"
) -> WeatherResponse

Gibt strukturierte, Pydantic-gestützte Nutzdaten zurück:

{
  "city": "London",
  "temperature": 18.0,
  "units": "metric",
  "condition": "partly cloudy",
  "humidity_percent": 72
}

Unbekannte Städte schlagen mit einem kontrollierten MCP-Tool-Fehler fehl, anstatt den Server zum Absturz zu bringen.

Agenten-Integrationsablauf

Der Agent verwendet einfaches OpenAI-Function-Calling (kein zusätzliches Framework), um die Demo fokussiert zu halten:

flowchart LR
    A[MCP Tool Schema] --> B[OpenAI Function Tool]
    B --> C[Model Chooses Function]
    C --> D[MCP ClientSession.call_tool]
    D --> E[MCP Server Executes Tool]
    E --> F[Function Call Output]
    F --> G[Final Model Answer]

Dies ist dasselbe Muster, das Agent-Frameworks umsetzen: MCP-Tools entdecken → Schemata dem Modell bereitstellen → ausgewählte Aufrufe über MCP zurückleiten → Ergebnisse in die nächste Modellrunde einspeisen.

Testen

pytest -q

Die Testsuite umfasst:

• ✅ Tool-Ausführung (metrisches Wetter)

• ✅ Tool-Ausführung (imperiales Wetter)

• ✅ Validierungs-/Fehlerverhalten (unbekannte Stadt)

• ✅ In-Process-MCP-Client-Erkennung und Tool-Aufruf

Tests verwenden nach Möglichkeit den In-Memory-Client des SDKs – das vermeidet Subprozess-Flakiness und übt gleichzeitig die echte MCP-Protokollebene.

Formatierung & Linting

Dieses Projekt verwendet Ruff:

# Check
ruff check .
ruff format --check .

# Format
ruff format .

Produktionshinweise

Diese Demo ist bewusst klein, repräsentiert aber mehrere Produktionsaspekte:

Für echte externe Datenquellen: Ersetzen Sie deterministisches Wetter durch authentifizierte API-/Datenbankaufrufe, fügen Sie Timeouts, Wiederholungen, Ratenbegrenzung, Beobachtbarkeit und Geheimnisverwaltung hinzu.

Protokoll-Mentales Modell

Vereinfachte JSON-RPC-Sequenz:

// Client -> Server
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{...}}

// Server -> Client
{"jsonrpc":"2.0","id":1,"result":{...}}

// Client -> Server
{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}

// Server -> Client
{"jsonrpc":"2.0","id":2,"result":{"tools":[...]}}

// Client -> Server
{"jsonrpc":"2.0","id":3,"method":"tools/call",
 "params":{"name":"get_current_weather","arguments":{"city":"London"}}}

// Server -> Client
{"jsonrpc":"2.0","id":3,"result":{"content":[...],"structuredContent":{...}}}

Das genaue Protokollschema wird von der MCP-Spezifikation und dem SDK gepflegt. Das Obige ist für Lehrzwecke bewusst vereinfacht.

Referenzen

• Offizielles MCP-Python-SDK: https://py.sdk.modelcontextprotocol.io/

• MCP-Spezifikation: https://modelcontextprotocol.io/specification/

• OpenAI Function Calling: https://platform.openai.com/docs/guides/function-calling