Korea Ground-Truth MCP

无头、AI 原生的 SaaS，其客户是 AI 代理。通过 MCP（Streamable HTTP）和 REST 提供韩国事实核查工具，按预付费积分计费。

在线地址：https://kr-ground-truth-mcp.vercel.app — /llms.txt、/openapi.json、/pricing.json。MCP 端点：/api/mcp。

claude mcp add --transport http kgt https://kr-groundtruth-mcp.vercel.app/api/mcp --header "Authorization: Bearer kgt_live_..."

技术栈

Next.js 16（App Router）· mcp-handler 2（MCP SDK v2，无状态）· Supabase Postgres · Toss Payments · Vercel。

Related MCP server: 갈피 법령조회 MCP

基础设施

• Supabase 项目 kr-ground-truth-mcp（ref kzjzjahokqduktphxpsj，ap-northeast-2）

• Vercel 项目 chloepark85s-projects/kr-ground-truth-mcp；已为生产环境设置环境变量（vercel env ls）

• 收录：官方 MCP Registry io.github.ChloePark85/kr-ground-truth（server.json + mcp-publisher）、Smithery hapark85/kr-ground-truth（smithery mcp publish … --config-schema）、Glama（自动收录；通过 /.well-known/glama.json 认领）、mcp.so（issue chatmcp/mcpso#3776）

• MCP 认证：发现（initialize/tools/list）是公开的；tools/call 需要通过 Authorization: Bearer、x-api-key 或 ?apiKey= 提供密钥。

设置

1. Supabase 项目 → 在 SQL 编辑器中运行 supabase/migrations/0001_core.sql（或 supabase db push）。

2. 复制 .env.example → .env.local，填写密钥：

   • DATA_GO_KR_KEY：在 data.go.kr 申请使用「국세청_사업자등록정보 진위확인 및 상태조회」和「국토교통부_아파트 매매 실거래가」（自动批准）

   • JUSO_KEY：在 business.juso.go.kr 申请批准密钥

   • DART_KEY：在 opendart.fss.or.kr 获取认证密钥

   • LAW_OC：申请 law.go.kr 的 OPEN API（管理员批准需要 1~2 天）

   • TOSS_CLIENT_KEY / TOSS_SECRET_KEY：Toss Payments 测试密钥

3. npm run dev

4. DART 名称搜索需要公司代码列表：npx tsx scripts/sync-dart-corp-codes.ts（每月重新运行）。

流程

POST /v1/accounts {email}            → api_key (once) + 50 free credits
claude mcp add --transport http kgt $URL/api/mcp --header "Authorization: Bearer kgt_live_..."
tools/call → debit_credits (row-locked) → cache → upstream → {ok, data, meta:{cost, balance_remaining}}
402 INSUFFICIENT_CREDITS → POST /v1/topups {credits} → checkout_url → human pays (Toss) → credit_credits (idempotent)

设计说明

• src/lib/tools/registry.ts 是 MCP 工具、REST 路由、OpenAPI、定价和 llms.txt 的唯一来源。价格也会写入 tool_prices；debit_credits 扣费依据的正是该数据库行。

• 先扣费再调用上游；上游失败 → 自动退款（credit_ledger.reason='refund'）。

• credit_ledger 是只追加的（通过触发器），并带有 unique(reason, ref_id)，因此 Toss 成功重定向和 webhook 都可以安全运行。

• 所有表都启用了 RLS 且没有策略；只有 service-role 密钥（服务器）可以访问它们。

指标

• npm run metrics [-- --days 7 --include-test] — 每周报告（北极星指标 = 每周活跃 API 密钥；漏斗：创建 → 首次调用 → 次日调用 → 402 → 充值；首次调用耗时；按工具统计的调用次数；收入）。测试账号（@example.com）默认排除，除非传入 --include-test。

• 使用 header x-admin-token: $ADMIN_TOKEN 请求 GET /v1/admin/metrics?days=7 会返回相同的 JSON（metrics_report() 位于 supabase/migrations/0002_metrics.sql）。

验证清单

H=http://localhost:3000
curl -X POST $H/v1/accounts -H 'content-type: application/json' -d '{"email":"a@b.com"}'
K=kgt_live_...
curl -X POST $H/api/mcp -H "Authorization: Bearer $K" -H 'accept: application/json, text/event-stream' -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
curl -X POST $H/v1/tools/search_address -H "Authorization: Bearer $K" -H 'content-type: application/json' -d '{"keyword":"세종대로 209"}'
# race test: 50 concurrent calls on a low balance → ledger sum == balance
seq 50 | xargs -P 50 -I{} curl -s -o /dev/null -w '%{http_code}\n' -X POST $H/v1/tools/search_address -H "Authorization: Bearer $K" -H 'content-type: application/json' -d '{"keyword":"테스트 {}"}' | sort | uniq -c