create-connector

Einen entfernten MCP-Connector erstellen

Erstellt einen stateless Streamable-HTTP MCP-Server (TypeScript, @modelcontextprotocol/sdk), der als benutzerdefinierter Connector für claude.ai funktioniert, optional mit visuellen Inline-Karten (MCP Apps), und stellt ihn auf Vercel bereit. Bewährt in einem echten Projekt mit über 30 Tools.

Vorlagen befinden sich in templates/ neben dieser Datei. Weiterführende Notizen sind in references/; lies sie nur, wenn der Schritt sie benötigt:

• references/mcp-apps-cards.md — Inline-Karten: ui://-Ressource, postMessage-Protokoll, CSP, klickbare Listen
• references/deploy-vercel.md — Vercel-Setup, Deployment, erneutes Hinzufügen des Connectors in claude.ai
• references/gotchas.md — Fallstricke, die echte Zeit kosten (vor dem Debuggen lesen)

Arbeitsablauf

1. Kläre (frage nur, was du nicht ableiten kannst): welche Daten/API, schreibgeschützt oder schreibend, benötigt Authentifizierung oder nicht, möchte Karten oder nur Text. Standard: öffentliche Daten, schreibgeschützt, keine Authentifizierung, Text + Karten.
2. Teste jede Upstream-API, bevor du Code schreibst. curl jeden Endpunkt: Status, Antwortformat, Datumsformate, Rate-Limits, Timeouts, Weiterleitungen (ein 301 bedeutet, dass sich die URL geändert hat, z.B. api.frankfurter.dev, nicht .app). Öffentliche SPARQL/Such-Endpunkte können langsam sein: messe die Zeit, halte Abfragen einfach, filtere im Code.
3. Gerüst erstellen aus templates/ (kopiere package.json, tsconfig.json, vercel.json, api/, src/, scripts/), benenne my-connector um, npm install.
4. Schreibe Tools in src/server.ts (pro Tool ein registerTool). Die Regeln unten.
5. Füge jedes Tool zu scripts/test-client.ts hinzu. Der Runner schlägt bei nicht getesteten Tools, leerer Ausgabe und isError fehl.
6. Lokal verifizieren: npm run typecheck, starte PORT=<freier Port> npm run dev, bestätige, dass das Log „listening“ sagt (nicht EADDRINUSE), dann npm test -- http://localhost:<port>/mcp. Ziel: Untested tools: none. Problems: 0.
7. Dokumentieren: README-Tooltabelle (eine Zeile pro Tool), CONTRIBUTING, LICENSE.
8. Committen, pushen, deployen nur mit Zustimmung des Benutzers (siehe references/deploy-vercel.md), dann den Test gegen die Live-URL ausführen.
9. Sage dem Benutzer, den Connector in claude.ai zu entfernen und neu hinzuzufügen (es cached die Tool-Liste) und 3–5 kurze Test-Prompts zu geben.

Tool-Entwurfsregeln

• Wenige, wirklich funktionierende Tools. Namen sind snake_case-Verben: search_x, get_x, list_x.
• Zod-Schema mit Limits für jede Eingabe (min/max, default); beschreibe jedes Feld mit einem Beispiel.
• Die Beschreibung sagt, was das Tool zurückgibt und wann es verwendet werden soll, in ein bis zwei Sätzen. Das Modell liest sie, um das Tool auszuwählen.
• Annotationen: readOnlyHint: true, idempotentHint: true, destructiveHint: false, plus openWorldHint: true für externe APIs.
• Jeden Handler in safe(...) einwickeln: Upstream-Fehler werden zu isError-Ergebnissen mit einer lesbaren Nachricht, nie zu einem Absturz.
• Die Datenquelle in jedem Ergebnis nennen. Wenn Daten von der Community bearbeitet oder vorläufig sind, dies angeben.
• Nie bei fehlenden Feldern abstürzen; auf „unbekannt“ zurückfallen.
• Tipptoleranz: bei keiner Übereinstimmung „meinten Sie“-Vorschläge zurückgeben, statt eines leeren Ergebnisses.
• Upstream-Aufrufe cachen (die Vorlage getJson/getText hat TTL, In-Flight-Deduplizierung, kurzen Fehler-Cache, Timeout). Verwende kurze TTLs (Minuten) für Live-Daten, Stunden für statische Daten. Sei nett zu kostenlosen APIs.
• Gib sowohl Text (für das Modell) als auch structuredContent (für die Karte) über einen Helfer wie card(text, data) zurück.
• Keine Geheimnisse im Repository. Wenn ein Schlüssel erforderlich ist, lies ihn aus process.env und dokumentiere ihn.
• Filtere aufwändige Arbeit im Code, nicht in der Upstream-Abfrage, wenn der Upstream langsam ist.

Zustandsloser Server (Vercel-kompatibel)

Ein neuer McpServer und Transport werden pro Anfrage erstellt (src/handler.ts); keine Sitzungen, kein Speicher zwischen Anfragen. Der einzige Zustand ist der In-Memory-Cache, der auf Best-Effort-Basis arbeitet. CORS und eine Größenbeschränkung für den Body befinden sich im Handler. api/mcp.ts exportiert { fetch } und maxDuration: 30; vercel.json leitet /mcp auf /api/mcp um.

Karten (MCP Apps), Kurzversion

Registriere eine ui://… HTML-Ressource (mimeType: text/html;profile=mcp-app), dann gib jedem Tool _meta: { ui: { resourceUri }, "ui/resourceUri": resourceUri } und gib structuredContent mit einem kind-Feld zurück. Das HTML ist eine eigenständige Datei, die nach kind rendert. Siehe references/mcp-apps-cards.md und templates/src/view.ts.

Ausgabe an den Benutzer

Sei präzise. Berichte: was gebaut wurde (Tool-Liste), Testergebnis, URL und die genauen Schritte zum Aktualisieren des Connectors. Gib Einschränkungen ehrlich an (nicht verifizierte UI-Pfade, langsame Upstreams, Community-Daten).