K-Phi — 공개 MCP 서버(스켈레톤)

K-Phi 분석을 AI 어시스턴트(Claude, ChatGPT, Cursor, Copilot…)에 노출하는 MCP 서버(Streamable HTTP, 무상태). 익명 액세스는 속도 제한, 대용량 파일은 서명된 업로드, 전환을 위한 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, 현금흐름, covenants, 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 구현(인라인 CSV용 analyze, 업로드된 파일용 analyzeFromStorage).

2. store.ts — MemoryStore를 Postgres로 교체(전용 스키마 mcp_public, 30일 후 삭제); 업로드 토큰은 DB 또는 Redis에 저장.

3. server.ts /upload/:token — S3/R2 사전 서명 URL + 안티바이러스로 교체하고, 인라인 대신 이벤트 기반으로 분석을 트리거.

4. ratelimit.ts — Redis의 할당량; 기존 인증에 연결된 OAuth 2.1(Bearer) 검증을 추가하여 계정의 할당량을 해제.

K-Phi 애플리케이션 측: 매직 링크로 계정을 만들고 분석을 연결하는 /a/:analysis_id 경로(전환 지점)와 공유 가능한 읽기 전용 /r/:analysis_id 경로.

등록(디렉토리)

디렉토리의 일반적인 전제 조건: 공개 HTTPS URL, 문서화된 OAuth 2.1 또는 익명 액세스, 개인정보 처리방침, 지원 연락처, 설명 및 아이콘. 최신 기준 확인: https://docs.claude.com 및 https://support.claude.com (Claude), ChatGPT용 OpenAI 문서, registry.modelcontextprotocol.io.