K-Phi — öffentlicher MCP-Server (Grundgerüst)

MCP-Server (Streamable HTTP, zustandslos), der die K-Phi-Analyse für KI-Assistenten (Claude, ChatGPT, Cursor, Copilot…) bereitstellt. Anonymer Zugriff mit Ratenbegrenzung, signierter Upload für große Dateien, Deep Link zu K-Phi für die Konvertierung.

Siehe kphi-mcp-public-spec.md für die vollständige Spezifikation.

Starten

npm install
npm run dev            # compile + démarre sur :3000
curl localhost:3000/healthz

Umgebungsvariablen:

Related MCP server: HLedger MCP Server

Testen in Claude Desktop (vor der Registrierung)

Hinzufügen in claude_desktop_config.json (oder über Einstellungen → Konnektoren → Benutzerdefinierten Konnektor hinzufügen mit der öffentlichen URL):

{
  "mcpServers": {
    "k-phi": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:3000/mcp"]
    }
  }
}

Dann in Claude: „Hier ist mein Hauptbuch-Export, kannst du das für mich analysieren?" durch Einfügen einer CSV. Überprüfen, dass kphi_analyze_ledger aufgerufen wird. Danach ~20 Formulierungen testen (Kennzahlen, DSCR, Liquidität, Covenants, FEC, Bilanz, „Finanzdiagnose"…) und die Tool-Beschreibung in src/tools.ts anpassen, bis das Routing zuverlässig ist.

Struktur

src/
  server.ts     endpoint /mcp (stateless), /upload/:token, /healthz
  tools.ts      les 4 outils + descriptions (= le pitch lu par le modèle)
  engine.ts     interface AnalysisEngine + MockEngine
  store.ts      interface Store + MemoryStore
  ratelimit.ts  session anonyme + quotas

An K-Phi anbinden (die 4 TODOs)

1. engine.ts — AnalysisEngine mit Ihrer bestehenden Engine implementieren (analyze für die Inline-CSV, analyzeFromStorage für hochgeladene Dateien).

2. store.ts — MemoryStore durch Postgres ersetzen (dediziertes Schema mcp_public, Bereinigung nach 30 Tagen); Upload-Tokens in der Datenbank oder Redis.

3. server.ts /upload/:token — durch eine vorab signierte S3/R2-URL + Antivirus ersetzen und die Analyse ereignisbasiert statt inline auslösen.

4. ratelimit.ts — Kontingente in Redis; OAuth-2.1-Prüfung (Bearer) hinzufügen, die an Ihre bestehende Authentifizierung angebunden ist, um die Kontingente für Konten aufzuheben.

Auf der K-Phi-Anwendungsseite: Route /a/:analysis_id, die ein Konto per Magic Link erstellt und die Analyse verknüpft (das ist der Konvertierungspunkt), und Route /r/:analysis_id als teilbare, schreibgeschützte Ansicht.

Registrierung

Übliche Voraussetzungen der Verzeichnisse: öffentliche HTTPS-URL, OAuth 2.1 oder dokumentierter anonymer Zugriff, Datenschutzrichtlinie, Support-Kontakt, Beschreibung und Symbol. Aktuelle Kriterien prüfen: https://docs.claude.com und https://support.claude.com (Claude), OpenAI-Dokumentation für ChatGPT, registry.modelcontextprotocol.io.