K-Phi — публичный MCP-сервер (скелет)

MCP-сервер (Streamable HTTP, stateless), предоставляющий анализ K-Phi ИИ-ассистентам (Claude, ChatGPT, Cursor, Copilot…). Анонимный доступ с ограничением скорости, подписанная загрузка для больших файлов, глубокая ссылка на K-Phi для конвертации.

См. kphi-mcp-public-spec.md для полной спецификации.

Запуск

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

Переменные окружения:

Related MCP server: HLedger MCP Server

Тестирование в Claude Desktop (перед добавлением в каталог)

Добавьте в claude_desktop_config.json (или через Настройки → Коннекторы → Добавить пользовательский коннектор с публичным URL):

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

Затем в Claude: «Вот мой экспорт главной книги, можешь проанализировать это?» вставив CSV. Проверьте, что вызывается kphi_analyze_ledger. Затем протестируйте ~20 формулировок (коэффициенты, DSCR, денежные средства, ковенанты, FEC, баланс, «финансовая диагностика»…) и настройте описание инструмента в src/tools.ts, пока маршрутизация не станет надёжной.

Структура

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

Подключение к K-Phi (4 TODO)

1. engine.ts — реализуйте AnalysisEngine с вашим существующим движком (analyze для встроенного CSV, analyzeFromStorage для загруженных файлов).

2. store.ts — замените MemoryStore на Postgres (отдельная схема mcp_public, очистка через 30 дней); токены загрузки в базе или Redis.

3. server.ts /upload/:token — замените на предварительно подписанный URL S3/R2 + антивирус, и запускайте анализ по событию, а не в режиме онлайн.

4. ratelimit.ts — квоты в Redis; добавьте проверку OAuth 2.1 (Bearer), подключённую к вашей существующей аутентификации, чтобы снимать квоты для аккаунтов.

Со стороны приложения K-Phi: маршрут /a/:analysis_id, который создаёт аккаунт по magic link и привязывает анализ (это точка конверсии), и маршрут /r/:analysis_id в режиме только для чтения, доступный для публикации.

Добавление в каталог

Обычные требования каталогов: публичный HTTPS URL, OAuth 2.1 или документированный анонимный доступ, политика конфиденциальности, контакт поддержки, описание и иконка. Проверьте актуальные критерии: https://docs.claude.com и https://support.claude.com (Claude), документация OpenAI для ChatGPT, registry.modelcontextprotocol.io.