K-Phi — servidor MCP público (esqueleto)

Servidor MCP (Streamable HTTP, stateless) que expone el análisis K-Phi a los asistentes de IA (Claude, ChatGPT, Cursor, Copilot…). Acceso anónimo con límite de tasa, carga firmada para archivos grandes, deep link a K-Phi para la conversión.

Ver kphi-mcp-public-spec.md para la spec completa.

Ejecutar

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

Variables de entorno:

Related MCP server: HLedger MCP Server

Probar en Claude Desktop (antes del listado)

Añadir en claude_desktop_config.json (o mediante Configuración → Conectores → Añadir un conector personalizado con la URL pública):

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

Luego en Claude: « Aquí está mi export del libro mayor, ¿puedes analizarlo? » pegando un CSV. Verificar que se llama a kphi_analyze_ledger. Probar después ~20 formulaciones (ratios, DSCR, tesorería, covenants, FEC, balance, « diagnóstico financiero »…) y ajustar la descripción de la herramienta en src/tools.ts hasta que el enrutamiento sea fiable.

Estructura

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

Conectar con K-Phi (los 4 TODO)

1. engine.ts — implementar AnalysisEngine con su motor existente (analyze para el CSV inline, analyzeFromStorage para los archivos subidos).

2. store.ts — reemplazar MemoryStore por Postgres (esquema dedicado mcp_public, purga a 30 días); tokens de carga en base de datos o Redis.

3. server.ts /upload/:token — reemplazar por una URL pre-firmada S3/R2 + antivirus, y disparar el análisis por evento en lugar de en línea.

4. ratelimit.ts — cuotas en Redis; añadir la verificación OAuth 2.1 (Bearer) conectada a su auth existente para levantar las cuotas de las cuentas.

En la aplicación K-Phi: ruta /a/:analysis_id que crea una cuenta por magic link y vincula el análisis (es el punto de conversión), y ruta /r/:analysis_id de solo lectura compartible.

Listado

Requisitos habituales de los directorios: URL pública HTTPS, OAuth 2.1 o acceso anónimo documentado, política de privacidad, contacto de soporte, descripción e icono. Verificar los criterios actualizados: https://docs.claude.com y https://support.claude.com (Claude), documentación de OpenAI para ChatGPT, registry.modelcontextprotocol.io.