K-Phi — public MCP server (skeleton)

MCP server (Streamable HTTP, stateless) exposing K-Phi analysis to AI assistants (Claude, ChatGPT, Cursor, Copilot…). Anonymous rate-limited access, signed upload for large files, deep link to K-Phi for conversion.

See kphi-mcp-public-spec.md for the full spec.

Run

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

Environment variables:

Related MCP server: HLedger MCP Server

Test in Claude Desktop (before listing)

Add to claude_desktop_config.json (or via Settings → Connectors → Add custom connector with the public URL):

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

Then in Claude: "Here is my general ledger export, can you analyze this for me?" while pasting a CSV. Verify that kphi_analyze_ledger is called. Then test ~20 phrasings (ratios, DSCR, cash flow, covenants, FEC, balance sheet, "financial diagnostic"…) and adjust the tool description in src/tools.ts until routing is reliable.

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

Connect to K-Phi (the 4 TODOs)

1. engine.ts — implement AnalysisEngine with your existing engine (analyze for inline CSV, analyzeFromStorage for uploaded files).

2. store.ts — replace MemoryStore with Postgres (dedicated mcp_public schema, 30-day purge); upload tokens in database or Redis.

3. server.ts /upload/:token — replace with a pre-signed S3/R2 URL + antivirus, and trigger analysis on event rather than inline.

4. ratelimit.ts — quotas in Redis; add OAuth 2.1 (Bearer) verification wired to your existing auth to lift quotas for accounts.

On the K-Phi application side: /a/:analysis_id route that creates an account via magic link and attaches the analysis (this is the conversion point), and /r/:analysis_id route in read-only shareable mode.

Listing

Usual directory prerequisites: public HTTPS URL, OAuth 2.1 or documented anonymous access, privacy policy, support contact, description and icon. Check current criteria: https://docs.claude.com and https://support.claude.com (Claude), OpenAI documentation for ChatGPT, registry.modelcontextprotocol.io.