K-Phi — serveur MCP public (squelette)

Serveur MCP (Streamable HTTP, stateless) exposant l'analyse K-Phi aux assistants IA (Claude, ChatGPT, Cursor, Copilot…). Accès anonyme rate-limité, upload signé pour les gros fichiers, deep link vers K-Phi pour la conversion.

Voir kphi-mcp-public-spec.md pour la spec complète.

Lancer

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

Variables d'environnement :

Related MCP server: HLedger MCP Server

Tester dans Claude Desktop (avant référencement)

Ajouter dans claude_desktop_config.json (ou via Paramètres → Connecteurs → Ajouter un connecteur personnalisé avec l'URL publique) :

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

Puis dans Claude : « Voici mon export de grand livre, peux-tu m'analyser ça ? » en collant un CSV. Vérifier que kphi_analyze_ledger est appelé. Tester ensuite ~20 formulations (ratios, DSCR, trésorerie, covenants, FEC, balance, « diagnostic financier »…) et ajuster la description de l'outil dans src/tools.ts jusqu'à ce que le routage soit fiable.

Structure

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

Brancher sur K-Phi (les 4 TODO)

1. engine.ts — implémenter AnalysisEngine avec votre moteur existant (analyze pour le CSV inline, analyzeFromStorage pour les fichiers déposés).

2. store.ts — remplacer MemoryStore par Postgres (schéma dédié mcp_public, purge à 30 j) ; jetons d'upload en base ou Redis.

3. server.ts /upload/:token — remplacer par une URL pré-signée S3/R2 + antivirus, et déclencher l'analyse sur événement plutôt qu'en ligne.

4. ratelimit.ts — quotas dans Redis ; ajouter la vérification OAuth 2.1 (Bearer) branchée sur votre auth existante pour lever les quotas des comptes.

Côté application K-Phi : route /a/:analysis_id qui crée un compte par magic link et rattache l'analyse (c'est le point de conversion), et route /r/:analysis_id en lecture seule partageable.

Référencement

Prérequis habituels des annuaires : URL publique HTTPS, OAuth 2.1 ou accès anonyme documenté, politique de confidentialité, contact support, description et icône. Vérifier les critères à jour : https://docs.claude.com et https://support.claude.com (Claude), documentation OpenAI pour ChatGPT, registry.modelcontextprotocol.io.