mcp-agent-toolkit

Live-Demo: noch nicht bereitgestellt — geplant unter agent.build-with-deepak.com. Dieses Repo ist vollständig und lokal verifiziert (Build, Lint, 25 Unit-Tests — inklusive eines echten MCP-Protokoll-Round-Trips — und 5 E2E-Tests); es wurde jedoch noch nicht bereitgestellt oder gegen ein echtes Ollama/Postgres getestet. Siehe Status.

Das Problem

Die meisten „KI-Agent“-Demos sind ein einziger versteckter Tool-Aufruf, der als Autonomie inszeniert wird. Diese hier zeigt ihre Arbeit: ein Model-Context-Protocol-Agent mit drei echten Tools — einer schreibgeschützten PostgreSQL-Commerce-Datenbank, einer Live-Wetter-API und einem Taschenrechner —, der Fragen beantwortet, die tatsächlich mehr als eines davon erfordern („Gesamtumsatz von Kunden aus Dubai, und wie ist das Wetter dort?“). Jeder Tool-Aufruf, seine Argumente, sein Ergebnis, seine Latenz und — wichtig — seine Fehler und die Erholung des Modells davon werden live auf den Bildschirm gestreamt, während sie geschehen.

Related MCP server: MCP Tool Server

Ausprobieren

Mit Demo-Konto fortfahren startet eine echte 2-Stunden-Sitzung gegen die echte API — derselbe Agent, dieselben Tools, dieselben Daten. Die Beispieldatenbank wird gemeinsam genutzt und ist schreibgeschützt, daher benötigen Demo-Sitzungen keine Bereinigung pro Benutzer: Nichts, was ein Besucher tut, kann etwas schreiben. Die Registrierung (persistente benutzerspezifische Daten) ist in Arbeit; der Button „Registrieren“ und POST /api/auth/register (501) sagen das beide ehrlich.

Architektur

flowchart TB
    subgraph Browser
        UI[Angular SPA<br/>login → live tool-call timeline]
    end

    subgraph VPS -- host nginx, TLS
        Nginx[nginx :443]
    end

    subgraph "Docker Compose stack"
        Web[web container]
        subgraph API [api container — NestJS]
            Loop[Agent loop]
            Client[MCP Client]
            Server[MCP Server]
        end
        PG[(PostgreSQL<br/>sample dataset<br/>mcp_readonly role)]
    end

    Ollama[Ollama llama3.1 — on the VPS]
    Meteo[Open-Meteo API]

    UI -->|HTTPS| Nginx --> Web -->|/api/*| Loop
    Loop -->|chat + tools| Ollama
    Loop -->|listTools / callTool| Client
    Client <-->|MCP protocol, in-memory transport| Server
    Server -->|query_database| PG
    Server -->|get_weather| Meteo
    Server -->|calculate| Server

Die Schleife: Das Modell erhält die Frage plus die über MCP ermittelten Tool-Schemas → gibt Tool-Aufrufe aus → jeder Aufruf läuft durch den MCP-Client → Ergebnisse (einschließlich Fehlern) gehen zurück an das Modell → Wiederholung, bis es in Prosa antwortet oder die Schrittobergrenze (Standard: 6) erreicht. Jeder Schritt ist ein SSE-Event.

Zentrale Entscheidungen und Abwägungen

Ein echter MCP-Server und -Client in einem Prozess. Die Tools hätten einfache Funktionen sein können — die Protokollgrenze ist der Punkt. Die Agent-Schleife spricht nur mit dem MCP-Client: Sie ermittelt Tools über listTools() und ruft sie über callTool() auf, genau wie sie es gegen einen externen Server über stdio oder HTTP tun würde. Ein Tool aus diesem Prozess herauszulösen ändert eine Transportzeile, nicht den Agenten. Der In-Memory-Transport erspart einer Single-VPS-Demo zusätzliche Ports und Subprozess-Überwachung, während das SDK weiterhin Schemas in beide Richtungen validiert — und die Unit-Suite testet genau diesen tatsächlichen Handshake, kein Mock davon.

SQL-Injection wird als Standardzustand behandelt, nicht als Randfall. Der Agent schreibt SQL aus der natürlichsprachlichen Frage eines Fremden — das ist per Konstruktion nicht vertrauenswürdige Eingabe. Zwei Ebenen: Eine anwendungsseitige Schutzschicht (sql-guard.ts: Kommentarentfernung, Einzelstatement, nur SELECT/WITH, eine Keyword-Denylist, die weiß, dass set_config nicht set ist, und ein Subquery-Wrapper, der Ergebnisse auf 100 Zeilen begrenzt) schlägt schnell fehl, mit Meldungen, auf die das Modell reagieren kann; darunter wird die Abfrage als dedizierte Postgres-Rolle mcp_readonly ausgeführt — nur SELECT-Grants, default_transaction_read_only=on, 5s Statement-Timeout — was selbst dann gilt, wenn die Schutzschicht einen Bug hat. Die eigenen Tests der Schutzschicht dokumentieren ihre akzeptierte lexikalische Einschränkung.

Tool-Fehler werden an das Modell zurückgegeben, nicht als Fehlschläge angezeigt. Ein fehlgeschlagener Tool-Aufruf wird als isError-Ergebnis zurückgegeben und als Tool-Ausgabe in die Konversation aufgenommen. Das Modell liest den Fehler, korrigiert sein SQL oder wählt eine andere Stadt und versucht es erneut — und die UI kommentiert genau das („der Fehler geht zurück an das Modell — beobachte den nächsten Schritt“). Die Erholung zu beobachten ist als Beleg für das Engineering wertvoller, als niemals zu scheitern.

Der Taschenrechner ist ein 60-Zeilen-Parser, kein eval. Ein von einem LLM geschriebener Ausdruck, der an einen beliebigen JavaScript-Evaluator übergeben wird, verwandelt einen Taschenrechner in ein Tool zur Code-Ausführung. Rekursiver Abstieg mit einer expliziten Grammatik ist die langweilige, korrekte Alternative; seine Tests enthalten 1 + 1; process.exit().

Schleifenschritte sind nicht gestreamt; die Timeline ist der Stream. Ob eine Modellantwort ein Tool-Aufruf oder die endgültige Antwort ist, ist erst erkennbar, wenn sie vollständig ist, und Tool-Aufruf-Antworten sind kurz. Was live gestreamt wird, ist das eigentlich Interessante — die Tool-Aufrufe und -Ergebnisse, während sie geschehen. Die endgültige Prosa-Antwort kommt als einzelnes Ereignis. (Dieselbe Transportentscheidung — SSE über POST — wie bei der Schwester-Router-Demo, aus denselben Gründen.)

Open-Meteo für das Wetter. Kostenlos und ohne Schlüssel: Eine unbeaufsichtigte öffentliche Demo mit einem Drittanbieter-API-Schlüssel ist ein Leak, das nur darauf wartet zu passieren, und eine Rechnung, die nur darauf wartet, aufzulaufen. Der Kompromiss — kein SLA — ist akzeptabel, weil ein Ausfall des Wetter-Tools selbst eine Live-Demonstration des Fehlerbehandlungspfads ist.

Fester Beispieldatensatz mit festen IDs. Das Seeding verwendet ON CONFLICT DO NOTHING, sodass jeder Start zu denselben 15 Kunden / 12 Produkten / 32 Bestellungen konvergiert, anstatt Duplikate anzusammeln. Die Städte wurden so gewählt, dass sich DB- + Wetterfragen natürlich kombinieren lassen (Dubai, Neu-Delhi, London …).

Datenbank-Einrichtung und -Zurücksetzung

Schema, Beispieldaten und die Grants der Rolle mcp_readonly liegen in apps/api/db/schema.sql und werden bei jedem API-Start idempotent angewendet; die Rolle selbst (Passwort aus MCP_READONLY_PASSWORD) wird in db.service.ts erstellt, weil CREATE ROLE kein parametrisiertes Passwort akzeptiert. pnpm db:reset löscht die Beispieltabellen; der nächste Start erstellt alles neu. Es gibt hier bewusst keine routinemäßige Demo-Datenbereinigung — Besucher können nicht schreiben.

Was ich bei 100-fachem Maßstab ändern würde

Der In-Memory-MCP-Transport ist das Erste, das umgestellt wird: Echte Multi-Tenant-Tool-Server laufen als separate Dienste (stdio-Subprozesse oder HTTP) mit Pro-Tool-Autorisierung und Audit-Logging an der Protokollgrenze — diese Codebase ist bereits auf diesen Tausch ausgelegt. Die Agent-Schleife würde persistente Konversationen erhalten (eine conversations-Tabelle mit der Sitzung als Schlüssel — das natürliche erste Feature registrierter Konten), parallele Tool-Ausführung, wo Aufrufe unabhängig sind, und eine Obergrenze für das Token-Budget neben der Schrittobergrenze. Und das SQL-Tool würde ganz aufhören, rohe SELECT-Abfragen offenzulegen: Im großen Maßstab veröffentlicht man benannte, parametrisierte Abfragevorlagen und lässt das Modell Parameter ausfüllen — das Muster aus Schutzschicht plus Readonly-Rolle hier ist die auf Demogröße gebrachte Version dieser Idee, kein Ersatz dafür.

Lokale Einrichtung

Node 22+, pnpm; für das volle Erlebnis Postgres und ein Ollama mit einem toolfähigen Modell (ollama pull llama3.1:8b — einfaches llama3 gibt Tool-Aufrufe nicht zuverlässig aus).

corepack enable && pnpm install
pnpm dev:api   # :3000
pnpm dev:web   # :4200, proxies /api → :3000

Gate-Checks:

pnpm --filter api build && pnpm --filter api lint && pnpm --filter api test && pnpm --filter api test:e2e
pnpm --filter web build && pnpm --filter web test

Bereitstellung auf dem VPS

1. cp .env.example .env — setze POSTGRES_PASSWORD, MCP_READONLY_PASSWORD und JWT_SECRET (Compose weigert sich, ohne sie zu starten). Bestätige, dass ollama list auf dem VPS llama3.1:8b anzeigt.

2. docker compose up -d --build — Web bindet nur an 127.0.0.1:8092.

3. Installiere nginx/agent.build-with-deepak.com.conf in das Host-nginx, dann certbot --nginx -d agent.build-with-deepak.com.

4. GET /api/health ist der nicht authentifizierte Healthcheck.

Status

• Echter MCP-Server + -Client über den In-Memory-Transport des SDK, drei Tools, Protokoll-Round-Trip durch Tests abgedeckt

• Agent-Schleife mit Live-Timeline der SSE-Tool-Aufrufe, Feedback zur Fehlerbehebung, Schrittobergrenze

• Zwei-Schichten-SQL-Schutz (Schutzschicht + dedizierte schreibgeschützte Postgres-Rolle)

• Demo-Konto-Authentifizierung Ende-zu-Ende; Registrierung = ehrliches 501 „Bald verfügbar“

• Build, Lint, alle Tests bestanden (API: 25 Unit + 5 E2E; Web: 6)

• Noch nicht gegen echtes Ollama/Postgres ausgeführt — diese Umgebung hatte keines von beidem; insbesondere der Ollama-Tool-Aufruf-Pfad der Agent-Schleife braucht einen echten llama3.1-Lauf, bevor das jemandem präsentiert wird

• Noch nicht bereitgestellt

• Registrierung/persistente Konten — in Arbeit (bewusst Demo-first)