MCP Agent Homework

Ein TypeScript-MCP-System (Model Context Protocol), das für die Aufgabe in MCP_HOMEWORK_SKILL.md erstellt wurde: ein Agent-Host, der eine Agent-Skill (SKILL.md) lädt, sich über alle drei erforderlichen Transports mit drei MCP-Servern verbindet, deren Tools erkennt/aggregiert und Gemini das richtige Tool auf dem richtigen Server auswählen und aufrufen lässt.

Architektur

                          Agent Host (src/host)
                     skill-loader + connection-manager
                       + tool-bridge + gemini-client
                                 |
              +------------------+------------------+
              |                  |                   |
              v                  v                   v
        stdio server       local HTTP server    public HTTP server
     (src/servers/stdio-  (src/servers/http-   (same http-server.ts,
        server.ts)          server.ts, no auth)   API-key protected)
              |                  |                   |
              +------------------+-------------------+
                                 |
              shared tool logic (src/servers/shared/tools.ts)
       3 tools (calculator, text_stats, unit_convert) + 1 resource + 1 prompt

• src/servers/shared/tools.ts — die einzige Implementierung der 3 Tools, 1 Ressource und 1 Prompts, die auf jedem Server identisch registriert wird, sodass dieselbe Logik überall wiederverwendet wird (keine duplizierte Geschäftslogik).

• src/servers/stdio-server.ts — MCP über stdio (als Kindprozess gestartet).

• src/servers/http-server.ts — MCP über Streamable HTTP. Exakt dieselbe Datei bzw. derselbe Code läuft sowohl für den „lokalen“ als auch den „öffentlichen“ Server; der einzige Unterschied ist die Konfiguration (PORT, PUBLIC_MCP_API_KEY).

• src/host/connection-manager.ts — der MCP-Host: verbindet sich mit jedem konfigurierten Server, erkennt Tools/Ressourcen/Prompts, setzt Tool-Namen als <namespace>__<tool> in Namensräume, um Kollisionen zu vermeiden, und leitet Tool-Aufrufe an den zugehörigen Server zurück.

• src/host/tool-bridge.ts — konvertiert erkannte MCP-Tools in Gemini-Funktionsdeklarationen.

• src/host/gemini-client.ts — die Gemini-Tool-Aufruf-Schleife (Nachricht senden → Funktionsaufrufe lesen → über den Verbindungsmanager weiterleiten → Funktionsantworten zurücksenden → wiederholen, bis der endgültige Text vorliegt).

• src/host/skill-loader.ts — lädt SKILL.md und injiziert es als Systemanweisung des Modells, sodass die Skill die Tool-Nutzung aktiv prägt.

• src/host/agent-host.ts — verbindet das oben Genannte über config/servers.json.

• src/host/cli.ts — CLI-Einstiegspunkt (interaktiv oder --demo).

Related MCP server: mcp-tools-server

Einrichtung

npm install

Geheimnisse liegen in api.env (bereits gitignored):

API_KEY=your-gemini-api-key
# Optional, only needed once you deploy the public server:
# PUBLIC_MCP_URL=https://your-app.onrender.com/mcp
# PUBLIC_MCP_API_KEY=some-strong-random-key

Ausführen der einzelnen Komponenten

stdio-Server (20 Punkte)

npm run server:stdio            # run directly
npm run inspector:stdio         # open MCP Inspector against it

Inspector erkennt 3 Tools (calculator, text_stats, unit_convert), 1 Ressource (docs://unit-conversions) und 1 Prompt (explain-tool-result) und kann alle ausführen/lesen.

Lokaler HTTP-Server

npm run server:http             # listens on http://127.0.0.1:8787/mcp, no auth
npm run inspector:http          # then connect Inspector to that URL

Öffentlicher HTTP-Server (15 Punkte)

Dieselbe http-server.ts wird zum „öffentlichen“ Server, sobald PUBLIC_MCP_API_KEY gesetzt ist — jede Anfrage erfordert dann einen passenden x-api-key-Header; fehlende/ungültige Schlüssel erhalten 401 Unauthorized.

$env:PORT=8788; $env:PUBLIC_MCP_API_KEY="a-strong-secret"; npm run server:http

Öffentliches Bereitstellen (Render.com, mit der enthaltenen render.yaml):

1. git init && git add -A && git commit -m "MCP homework" und dann in ein GitHub-Repository pushen, das dir gehört.

2. In Render: New + → Blueprint → Repository auswählen (es liest render.yaml automatisch) oder manuell einen Web Service erstellen mit:

   • Build-Befehl: npm install && npm run build

   • Start-Befehl: npm run start:http

   • Health-Check-Pfad: /health

3. Setze im Render-Dashboard die Umgebungsvariable PUBLIC_MCP_API_KEY auf ein starkes Geheimnis (niemals committen).

4. Nach der Bereitstellung die resultierende URL + Schlüssel in api.env eintragen: PUBLIC_MCP_URL=https://<your-service>.onrender.com/mcp und PUBLIC_MCP_API_KEY=<gleiches Geheimnis>.

5. Mit Inspector validieren:

   • Ohne Schlüssel → abgelehnt: curl -X POST https://<url>/mcp -H "Content-Type: application/json" -d "{...}" gibt 401 zurück.

   • Mit Schlüssel → funktioniert: --header "x-api-key: <secret>" an npx @modelcontextprotocol/inspector --cli <url> --method tools/list übergeben.

Agent-Host

npm run agent          # interactive CLI
npm run agent:demo      # runs a scripted set of demo queries

Beim Start führt der Host Folgendes aus:

1. Lädt SKILL.md als Systemanweisung.

2. Liest config/servers.json und verbindet sich mit dem stdio-Server (automatisch gestartet), dem lokalen HTTP-Server (muss bereits laufen) und dem öffentlichen HTTP-Server (wird automatisch übersprungen, wenn PUBLIC_MCP_URL/PUBLIC_MCP_API_KEY nicht gesetzt sind — er ist optional, damit die Demo auch ohne Live-Bereitstellung funktioniert).

3. Erkennt und setzt jedes Tool in einen Namensraum, übergibt sie an Gemini und leitet jeden Tool-Aufruf, den Gemini tätigt, an den richtigen MCP-Server weiter.

Konfiguration

Die Serverregistrierung ist datengesteuert über config/servers.json — Server dort hinzufügen/entfernen, statt Host-Code zu bearbeiten. ${VAR} in einer url wird beim Verbinden aus process.env aufgelöst; apiKeyEnv benennt die Umgebungsvariable, deren Wert als x-api-key gesendet wird.

Agent-Skill

SKILL.md weist den Agenten an, Tools aufzurufen, statt bei Arithmetik/Konvertierungen/Textstatistiken zu raten, pro logischer Anfrage ein Tool im Namensraum auszuwählen, bei Unsicherheit über unterstützte Konvertierungen die Ressource docs://unit-conversions zu konsultieren und Ergebnisse in einfacher Sprache zu erklären. Es wird bei jedem Lauf wörtlich in die Gemini-Systemanweisung geladen (siehe src/host/skill-loader.ts), sodass seine Regeln die Tool-Auswahl und den Antwortstil direkt beeinflussen — sichtbar in der Demo-Ausgabe (z. B. ruft der Agent für Arithmetik immer ein Tool auf, statt selbst zu rechnen).

Sicherheitshinweise

• Es werden keine Geheimnisse committet; api.env ist gitignored und der öffentliche Server liest PUBLIC_MCP_API_KEY nur aus der Umgebung.

• Der öffentliche HTTP-Server lehnt jede Anfrage ohne passenden x-api-key-Header ab (401) und akzeptiert Anfragen, sobald ein gültiger Schlüssel angegeben wird.