Korea Ground-Truth MCP

Headless, AI-native SaaS, чей клиент — AI-агент. Предоставляет корейские инструменты проверки фактов через MCP (Streamable HTTP) и REST; использование тарифицируется предоплаченными кредитами.

Live: https://kr-groundtruth-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-groundtruth-mcp (ref kzjzjahokqduktphxpsj, ap-northeast-2)

• Vercel-проект chloepark85s-projects/kr-groundtruth-mcp; переменные окружения заданы для продакшена (vercel env ls)

• Листинги: Official MCP Registry io.github.ChloePark85/kr-groundtruth (server.json + mcp-publisher), Smithery hapark85/kr-groundtruth (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-проект → выполните supabase/migrations/0001_core.sql в 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: заявка на OPEN API на law.go.kr (одобрение администратора 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), поэтому success-redirect от Toss и вебхук могут безопасно выполняться оба.

• Во всех таблицах включён RLS и нет политик; доступ к ним имеет только service-role ключ (сервер).

Метрики

• npm run metrics [-- --days 7 --include-test] — еженедельный отчёт (главная метрика = Weekly Active API Keys; воронка: создание → первый вызов → вызов на 2-й день → 402 → пополнение; время до первого вызова; вызовы по инструментам; выручка). Тестовые аккаунты (@example.com) исключаются, если не указан --include-test.

• GET /v1/admin/metrics?days=7 с заголовком x-admin-token: $ADMIN_TOKEN возвращает тот же 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