KingMinos

KingMinos by OutboundSync — MCP

https://api.kingminos.com のライブ KingMinos エンリッチメント API をラップする、Streamable HTTP MCP サーバーです。Bearer 認証されたリソースルートごとに 1 つのツールを提供します。/v1/auth/* と /v1/account/* 配下のセッションルートと Cookie ルートは、恒久的に対象外です。これは OutboundSync 製品の MCP ではなく、OutboundSync のアカウント、ソース、同期ツールは公開しません。

LeadMagic、Wiza、Findymail、AI Ark は、承認済みの共通キー利用ベンダーです。ZoomInfo、BuiltWith、Prospeo、Apollo、Company URL Finder、People Data Labs、HG Insights、Brandfetch、Enrich-CRM、Lemlist、Snov.io は、BYOK として put_credentials を使用します。Websearch は共通キーのみで、保存できません。Snov.io は OAuth（clientId／clientSecret）を使用し、クレデンシャルベンダー専用です。Cognism、Lusha、Starbridge、Clay、Databar、QuickEnrich、GetLeads、BlitzAPI は API キーのクレデンシャル専用ベンダーで、ルーティングにはまだ対応していません。このサーバーにベンダーキーを埋め込むことはなく、テナントの Bearer やクレデンシャルの本文をログに記録することもありません。

SF ではなく、SFDC と表記してください。

BYOK プロバイダーのロールアウト： 4 リポジトリのチェックリストと説明は docs/byok-provider-playbook.md にあります。Cursor エージェントは .cursor/skills/byok-provider-rollout/SKILL.md を読み込めます。

本番ホスト

管理者ツール（管理者トークン専用）

abuse_report、partner_report、partner_payout、feedback_report、partner_admin は、それぞれ /v1/admin/abuse/daily、/v1/admin/partners/analytics、/v1/admin/partners/payouts、/v1/admin/feedback、/v1/admin/partners（一覧表示、パートナーとコードの作成、コードの追加／無効化）をラップします。これらが登録されるのは、MCP Bearer が KingMinos 管理者トークン（kmadm_…。API の D1 にハッシュ化して保存され、kingminos-application の scripts/mint-admin-token.ts を使って Harris が発行）である場合のみです。それ以外の Bearer では tools/list に表示されません。管理者 Bearer には、これらの管理者ツールのみが表示されます。API は呼び出しのたびにトークンを再検証します。これらは OpenAPI のリソース操作ではないため、check:surfaces の対象外です。

本番環境は、既存の OutboundSync Cloudflare アカウント上の Cloudflare Worker kingminos-mcp-prod です。Janus は Wrangler を使ってデプロイします。

npx wrangler deploy

本番 MCP URL：https://mcp.kingminos.com/mcp。カスタムドメイン mcp.kingminos.com は Cloudflare でアタッチされ、wrangler.jsonc の routes（custom_domain: true）にも記録されているため、Janus のデプロイ後もホスト名が維持されます。workers_dev は false のため、この Worker は *.workers.dev では公開されず、カスタムドメインのみで公開されます。

この Worker では、D1 の outboundsync-router、R2 の outboundsync-router-raw、または Worker の outboundsync-router にバインドしてはいけません。API のベース URL は https://api.kingminos.com のままです。

Fly は本番ホストではありません。fly.example.toml／Dockerfile はローカル用の Node フォールバックサンプルにすぎず、本番設定ではありません。

パス	用途
GET /health	稼働確認
GET /	サービスカード
GET /.well-known/mcp/server-card.json	MCP サーバーカード（https://mcp.kingminos.com/mcp に加え、privacy_url／terms_url を通知）
POST /mcp	Streamable HTTP MCP
OPTIONS /mcp	Allow: POST, OPTIONS を通知
GET／DELETE /mcp	405 Method Not Allowed

ローカルで実行する

Node 22 が必要です。

npm install
npm run build
npm start

プロセスは HOST（デフォルトは 127.0.0.1）と PORT（デフォルトは 8080）でリッスンし、Worker と同じパスを提供します。

開発用（tsx、ビルドなし）：

npm run dev

ベンダー提供のインベントリ（inventory/openapi-surfaces.json）に対するコントラクトチェックです。決定論的で、ネットワークには接続しません。デフォルトの PR CI ではこの固定データを使用し、本番の OpenAPI は取得しません。

npm run check:surfaces
npm run check:providers

check:surfaces は、公開されている MCP ツールと operations[] を比較します。check:providers は、Zod の ProviderName／CredentialProvider 列挙型と、固定データの providers[]／credentialProviders[] を比較します。prospeo、companyurlfinder、peopledatalabs、hginsights、brandfetch、enrichcrm、lemlist などの新しい BYOK ID は、両方の Zod 列挙型と固定リストに追加されるまで CI で失敗します。これにより、routing.only: ["prospeo"] と put_credentials({ provider: "prospeo" }) が引き続き受け付けられます。

/v1/auth/* と /v1/account/* は、意図的に MCP ツールではありません（Cookie／セッションを扱うアプリのサーフェスです）。これらは nonToolPathPrefixes と、レビュー済みの excludedOperationIds カタログによって拒否されます。これら約 24 件の操作をツールとして実装しないでください。

ライブ OpenAPI のドリフトチェック（定期 CI／workflow_dispatch、またはローカルで実行）。サーフェス比較では、拒否リスト適用後のベアラーリソース操作のみを対象とします。ライブ仕様におけるアカウント／認証操作は失敗の原因になりません。ライブのプロバイダーチェックは一方向です。本番に Zod に存在しないプロバイダーがある場合にのみ失敗します。本番側が固定データに遅れていて（prospeo が欠けていて）も失敗しません。KINGMINOS_OPENAPI_JSON_URL で仕様の URL を上書きできます（デフォルトは https://api.kingminos.com/openapi.json）：

npm run check:surfaces:live
npm run check:providers:live

ライブ OpenAPI から固定データを更新します（ネットワーク接続が必要です）。プロバイダーの列挙型と、新たに検出された認証／アカウントの operationId を追加します。固定済みのプロバイダーは削除しません。認証情報専用ベンダー（snovio、cognism、lusha、starbridge、clay、databar、quickenrich、getleads、blitzapi — ルーティングの経由先なし）は providers[] から除外されます。手書きの capabilityProviders 固定データは保持されます。コミットする前に差分を確認してください：

npm run inventory:refresh

アプリケーションの CI では、KINGMINOS_OPENAPI_INVENTORY=/path/to/openapi-surfaces.json を指定して、独自のインベントリを使用できます。このリポジトリには KingMinos アプリケーションのソースは含まれていません。

スモークテスト（一時的なリスナーを起動してツール一覧を取得します。ライブ仕様ではなく、ファイルのインベントリを使用します）：

npm test
npm run smoke

Worker バンドルのチェック（Cloudflare 認証は不要）：

npm run check:worker

ローカルの全テストスイート：

npm run ci

これは、PR と main で必須となる OpenAPI tool contract チェックの実行内容とまったく同じです（ブランチは最新の状態である必要があります。管理者にも保護ルールが適用されるため、main への直接プッシュはできません）。npm install では git フック（simple-git-hooks）もインストールされます。pre-commit はステージ済みファイルに対して biome check --write を実行し、pre-push は型チェックとテストを実行します。夜間のライブドリフトジョブは PR をブロックする代わりに、Live OpenAPI drift イシューを作成します。すべての kingminos-* リポジトリの CI マップは kingminos-application/docs/ci.md を参照してください。

リリース（CalVer）

main へのプッシュで CI が成功すると、CalVer Release ワークフローがそのコミットにタグ（YYYY.MM.DD.N、UTC）を付け、生成されたリリースノートを含む GitHub リリースを作成します。コミットを main にプッシュすることはありません（Workers Builds は main へのプッシュごとに kingminos-mcp-prod をデプロイします）。

ランタイムバージョン（/health、サービスカード、MCP の serverInfo）は、src/config.ts の export const VERSION から取得されます（package.json と同期されます。src/fetch.test.ts を参照）。最後のタグより新しいバージョンを本番環境で表示したい場合は、通常の PR で両方を更新してください。任意のローカルヘルパーとして、npm run release:apply を実行すると、リリースを作成せずにファイルへ次の CalVer タグを適用します。

次のタグとリリースノートをプレビューするには、npm run release:preview を実行してください。

テナント Bearer

KingMinos テナントの Bearer は、クライアントから Authorization: Bearer <token> として送信されます。サーバーがこの値を発行、埋め込み、またはログに記録することはありません。

Worker モードでは、process.env または Worker のバインディングから KINGMINOS_API_KEY を読み取ることはありません。Authorization ヘッダーがない場合、Worker は必ず 401 を返します。

ローカルの Node プロセスは、次の条件をすべて満たす場合に限り、KINGMINOS_API_KEY にフォールバックできます。

• プロセスがループバック（127.0.0.1、localhost、または ::1）にバインドされている
• KINGMINOS_MCP_ALLOW_ENV_BEARER=1

本番環境の Worker では、このシークレットを保存しません。この値がここに表示されることはありません。

POST /mcp は、許可リストにない Origin が指定されている場合、そのリクエストを拒否します。Origin を送信しないクライアントは引き続き動作します（https://mcp.kingminos.com/mcp にアクセスする一般的な MCP クライアントなど）。ローカルのデフォルトホストは localhost、127.0.0.1、[::1] です。本番環境では mcp.kingminos.com も許可されます。

任意：

• KINGMINOS_API_URL — API のベース URL（デフォルトは https://api.kingminos.com）。この URL のパスプレフィックスは保持されます。
• HOST — ローカル Node のリッスンアドレス（デフォルトは 127.0.0.1）
• PORT — ローカル Node のリッスンポート（デフォルトは 8080）
• KINGMINOS_MCP_ALLOWED_HOSTS — /mcp の Host 許可リスト（カンマ区切り。Node のデフォルトはループバック、Worker のデフォルトは空＝すべて許可）
• KINGMINOS_MCP_ALLOWED_ORIGINS — /mcp 用に追加する Origin ホスト名
• KINGMINOS_MCP_PUBLIC_URL — サーバーカードで公開する MCP URL（Worker のデフォルトは https://mcp.kingminos.com/mcp）。カードではクライアントの Host ヘッダーを使用しません。
• KINGMINOS_MCP_ALLOW_ENV_BEARER — ローカルのループバックで環境変数の Bearer へのフォールバックを有効にするには、1 に設定します
• KINGMINOS_OPENAPI_INVENTORY — check:surfaces、check:providers、および PR CI で使用するファイルインベントリへのパス
• KINGMINOS_OPENAPI_JSON_URL — check:surfaces:live／check:providers:live／inventory:refresh で使用する URL の上書き

.env.example はローカル用の名前の確認にのみコピーしてください。値を入力した .env をコミットしないでください。シークレットを Wrangler の変数やファイルに保存しないでください。

Cursor

~/.cursor/mcp.json（またはプロジェクトの .cursor/mcp.json）に追加します。

ローカル：

{
  "mcpServers": {
    "kingminos": {
      "url": "http://127.0.0.1:8080/mcp",
      "headers": {
        "Authorization": "Bearer ${env:KINGMINOS_API_KEY}"
      }
    }
  }
}

ホスト環境（本番）：

{
  "mcpServers": {
    "kingminos": {
      "url": "https://mcp.kingminos.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:KINGMINOS_API_KEY}"
      }
    }
  }
}

Cursor の GUI セッションは、シェルの .env ファイルを引き継ぎません。${env:KINGMINOS_API_KEY} が解決されるよう、GUI の環境に KINGMINOS_API_KEY をエクスポートしてください。

ツール

各ツールは、Bearer 認証された KingMinos リソースルートの snake_case の operationId です。/health、OpenAPI ドキュメント、セッション／Cookie を使用する /v1/auth/* および /v1/account/* ルートはツールではありません。

ツール	ルート	備考
get_providers	GET /v1/providers	レジストリと設定済みフラグ
get_capabilities	GET /v1/capabilities	最初の解決処理の前に呼び出してください
get_recipes	GET /v1/recipes	エージェントの連鎖レシピ。一括実行の前に、速度／バランス／精度／網羅性のどれを重視するか確認してください
company_resolve	POST /v1/company/resolve	メールアドレス／ドメイン／ウェブサイト。dry_run が true でない場合はクレジットを消費します（API のデフォルトは false）。名前のみの場合は no_decision です。result.operator（0 クレジット）は、company_name を変更せずに製品ブランドの運営元（fizzy.do → 37signals）を示します
company_domain	POST /v1/company/domain	CRM のドメインを安全に書き込むための判定
company_hierarchy	POST /v1/company/hierarchy	直接／最終親会社と上限付きの子会社リスト
company_b2b_social	POST /v1/company/b2b-social	LinkedIn 企業ページの URL。バランス＝ウェブ検索 → 自社 AI Ark。精度／網羅性では LeadMagic／AI Ark／Wiza／Findymail を積み重ねます
company_icon	POST /v1/company/icon	domain は必須、name は任意（ルーティング／パス／プリセットなし。ウェブサイト／メールアドレスは不可）。ヒット時、result.icon_url は常に https://logos.kingminos.com/i/<sha256>.png（256×256 R2）です。result.icon_source_url は任意です。元画像が 64px 未満の場合、ホストされたヒットは confidence が low、flags.low_res が設定され、safe_to_write.icon_url は true になります。企業の取り違え／無関係な画像／空の画像のみを拒否します。取得／保存に失敗した場合、icon_url は null です。処理順＝favicon-fetch（0）→ Brandfetch BYOK（1）→ ZoomInfo（1）
company_description	POST /v1/company/description	英語の result.description または null（max_chars は 80～500、デフォルト 300）。常に path を指定してください（省略時は上限 6 の balance、path: balance は上限 2）。パス：speed（meta/og → AI Ark）| balance（Jev 順位付け抽出 + AI Ark + 任意の書き換え）| accuracy（xAI による文章生成）| coverage（文章生成 + Serper／ZoomInfo BYOK）。フラグ：hype／first_person／tagline／same_as_speed／truncated／cta／grammar（キーが追加される可能性があります。不明なキーも許容してください。truncated／cta → low。grammar は情報提供のみ）。skip_cache または cache_bypass でキャッシュを回避します（Idempotency-Key の再実行ではありません。company.resolve はバイパスを無視します）。answer.confidence、answer.identity。safe_to_write.description は low 以外で、かつ identity がある場合のみ。課金は勝者のみ。AI Ark のみが企業属性情報ベンダーです
person_verify_employment	POST /v1/person/verify-employment	デフォルトは LeadMagic。Findymail は routing.only 経由の自社キーです
person_language	POST /v1/person/language	英語でやり取りできますか。できない場合、どの言語を使いますか。email または linkedin_url が必須です（名前は照合のみに使用）。result.english は yes | likely | unconfirmed | unknown、recommended_language／local_language は medium 以上の場合のみ返されます。routing.path は speed（上限 1）| balance（デフォルト、上限 3）| accuracy（上限 4）。coverage は 400 invalid_routing です。skip_cache／cache_bypass
person_phone	POST /v1/person/phone	勤務先メールアドレスまたは LinkedIn URL から、人物の発信可能な電話番号を 1 件取得します。email または linkedin_url が必須です（名前は照合のみに使用）。phone_types（mobile | landline | other | unknown、省略時はすべて）および max_results（1～10、デフォルト 3）。result.best_phone は {number（E.164）、type、source} または null、result.phones は順位付けされたリスト（mobile が先頭）、result.flags の conflicting_numbers は safe_to_write.best_phone をブロックします。エージェント管理のルーターで、10 秒未満で回答します。対象となるすべてのベンダー（ZoomInfo／QuickEnrich／Blitz BYOK、LeadMagic、AI Ark、Findymail（米国のみ）、Wiza）が約 8.5 秒の予算内で並列実行されます。遅れて応答したベンダーは除外されます（課金 0）。routing.path で 4 つのモードを指定できます。speed（LeadMagic を最初に実行し、3 秒先行させた後、最安のフォールバックを競合させます。上限 10、Wiza は使用しません）、balance（デフォルト：ベンダーの事前評価／地域／回線種別に基づき、単一の最良番号を選択し、合意を待ちません）、accuracy（合意が必要で、番号は必ず 1 件です。conflicting_numbers の場合は安全に書き込めません）、coverage（最大 5 件の順位付き番号を返し、それぞれに source、回線種別、confidence、consensus を付与）。すべての番号に consensus と do_not_call を付与します。routing.only／ignore で対象を絞り込みます。返された番号に関与したベンダーのみ課金されます（coverage：返された番号ごと）。上限 38 クレジット、該当なしの場合は 0、BYOK は 0.1。30 日間キャッシュ、skip_cache／cache_bypass。API テナントのみ。番号は連絡先の個人情報です
person_title	POST /v1/person/title	勤務先メールアドレスまたは LinkedIn URL から、人物の現在の役職、職位レベル、職能を取得します。email または linkedin_url が必須です（名前と company_domain は照合のみに使用）。fields（title | seniority | function、省略時はすべて）で処理順を決定します。routing.path は speed | balance（デフォルト）| accuracy | coverage。ヒット時は結果に応じて 1／2／3／5 クレジット、該当なしまたは一部取得（fields_incomplete）の場合は 0 クレジットです。ZoomInfo の検索は BYOK キーがある場合のみです。conflicting_titles／unconfirmed_identity／employer_mismatch の場合、safe_to_write.title／seniority／function は false です。30 日間キャッシュ、skip_cache／cache_bypass。API テナントのみ
person_b2b_social	POST /v1/person/b2b-social	メールアドレスから人物の LinkedIn プロフィール URL を取得します。email は必須です（唯一の検索キー）。linkedin_url／first_name／last_name は照合のみに使用します（person_mismatch、0 クレジット）。result.status は found | not_found、正規化された result.linkedin_url、result.candidates（勝者が先頭で、agrees を含む）、result.flags。routing.path は speed | balance（デフォルト）| accuracy。coverage 層はありません。ヒット時は結果に応じて 2／3／5 クレジット、該当なし、ミスマッチ、または信頼度の下限を下回って保留された場合は 0 クレジットです。書き込み可否の判定には confidence のみを使用します（safe_to_write はありません）。2 つのソースが一致した場合は high、1 つの場合は medium、不一致の場合は low（conflicting_profiles）です。パスごとの下限は speed が low、balance が medium、accuracy が high です。min_confidence で上書きできます。30 日間キャッシュ、skip_cache／cache_bypass。API テナントのみ
person_name	POST /v1/person/name	メールアドレスまたは LinkedIn URL から、人物の先頭大文字表記の名／姓／フルネームを取得します。email または linkedin_url が必須です（phone／x_handle は受け付けますが、検索には使用しません → unsupported_input）。ロールアドレスは 0 クレジットの role_address になります。result.name_source は vendor | email_local_parse（最終手段の parsed_only は low）、result.matched_on、result.flags。routing.path は speed | balance（デフォルト）| accuracy | coverage。ヒット時は結果に応じて 1／2／3／5 クレジット、該当なし、競合（conflicting_names）、または信頼度の下限を下回って保留された場合は 0 クレジットです。書き込み可否の判定には answer.confidence のみを使用します（safe_to_write はありません）。パスごとの下限は speed／coverage が low、balance が medium、accuracy が high です。min_confidence で上書きできます。30 日間キャッシュ、skip_cache／cache_bypass。API テナントのみ
get_run	GET /v1/runs/{id}	記録済みの実行エンベロープ
list_credentials	GET /v1/credentials	マスク済みの「独自のキー」カタログ。キーの生値は返しません
put_credentials	PUT /v1/credentials/{provider}	テナントの「独自のキー」（暗号文）。先に確認してください。キーはこの会話で表示されるため、ウェブアプリ https://app.kingminos.com/app/keys/ の利用を推奨します
delete_credentials	DELETE /v1/credentials/{provider}	「独自のキー」を無効化します。先に確認してください
delete_subject	DELETE /v1/subjects/{subject_key}	エンコードされていないキー（例：email:[email protected]）。erase スコープが必要です。先に確認してください
list_webhooks	GET /v1/webhooks	ワークスペースのエンドポイント（kmwhk_…）。ワークスペースのゲートがオフの場合は 403 webhooks_not_enabled。すべての Webhook ツールには、明示的な webhooks スコープを持つキーが必要です（それ以外の場合は 403 webhook_scope_required）。シークレットは返しません
create_webhook	POST /v1/webhooks	HTTPS のみ。プライベート／ループバック宛先は拒否されます。ワークスペースごとに最大 20 件。署名シークレット（kmwhsec_…）は一度だけ表示されます。オーナーのみ。先に確認してください
get_webhook	GET /v1/webhooks/{id}	1 つのエンドポイント：is_active、consecutive_failures、auto_disabled_at。シークレットは含まれません
patch_webhook	PATCH /v1/webhooks/{id}	url／description／enabled_events／is_active。自動無効化後に再有効化するには is_active: true を指定します。オーナーのみ。先に確認してください
delete_webhook	DELETE /v1/webhooks/{id}	論理削除。オーナーのみ。先に確認してください
rotate_webhook_secret	POST /v1/webhooks/{id}/rotate-secret	以前のシークレットは直ちに使用できなくなります（猶予期間なし）。新しいシークレットは一度だけ返されます。オーナーのみ。先に確認してください
test_webhook	POST /v1/webhooks/{id}/test	署名付き test.ping（202 { event_id }）。一時停止中は 409 webhook_endpoint_inactive。オーナーのみ。先に確認してください
list_webhook_deliveries	GET /v1/webhooks/{id}/deliveries	status は pending | succeeded | failed | dead、last_http_status、last_error。上限 ≤ 100
replay_webhook_delivery	POST /v1/webhooks/{id}/deliveries/{delivery_id}/replay	同じイベントに対して新しい配信を作成します。先に一時停止中のエンドポイントを再有効化してください。オーナーのみ。先に確認してください
list_events	GET /v1/events	照合ログ。type、delivered（false = まだ配信に成功していません）、上限 ≤ 200。next_cursor はページが満杯の場合のみ
機能の POST はクレジットを消費し、SFDC には書き込みませんが、実行記録を書き込みます。put_credentials、delete_credentials、delete_subject、および Webhook の変更操作（create_webhook、patch_webhook、delete_webhook、rotate_webhook_secret、test_webhook、replay_webhook_delivery）は、ユーザーに確認してください。このリストが OpenAPI の一覧と異なる場合、CI は失敗します。

Sentry

src/worker.ts は @sentry/cloudflare の withSentry でラップされています（プロジェクト outboundsync/kingminos-mcp）。エラーのみを対象とします（tracesSampleRate: 0）。SENTRY_DSN シークレットが設定されていない限り、SDK は無効です（wrangler secret put、パイプ経由）。リクエスト本文、ツールの引数、認証ヘッダー、Cookie、クエリ文字列、メールアドレス、LinkedIn の URL、km*_（kmadm_、kmwhsec_ を含む）／osr_ トークンが Worker から外部に送信されることはありません（src/sentry.ts）。リリース：デプロイ時に --var SENTRY_RELEASE:$(git rev-parse HEAD) を指定します。指定しない場合は Worker のバージョン ID が使用されます。