KingMinos

OutboundSync 的 KingMinos — MCP

Streamable HTTP MCP 服务，封装了 https://api.kingminos.com 上的 KingMinos 实时数据增强 API。每个使用 Bearer 身份验证的资源路由对应一个工具。/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 或凭据正文。

请说 SFDC，不要说 SF。

BYOK 供应商接入： 四仓库检查清单与说明见 docs/byok-provider-playbook.md；Cursor Agent 可加载 .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 中，由 Harris 使用 kingminos-application 中的 scripts/mint-admin-token.ts 创建）时，才会注册这些工具。其他任何 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[] 进行比较。新增 BYOK ID（例如 prospeo、companyurlfinder、peopledatalabs、hginsights、brandfetch、enrichcrm 或 lemlist）后，如果 Zod 枚举和固定清单都未列出它，CI 就会失败。这能确保 routing.only: ["prospeo"] 和 put_credentials({ provider: "prospeo" }) 继续被接受。

/v1/auth/* 和 /v1/account/* 有意不作为 MCP 工具（Cookie/会话应用接口）。这些接口由 nonToolPathPrefixes 和经过审核的 excludedOperationIds 目录拒绝。不要将这约 24 个操作实现为工具。

实时 OpenAPI 漂移检查（定时 CI / workflow_dispatch，或本地运行）。接口检查仅比较经过拒绝列表过滤后的 bearer 资源操作——实时规范中的账户/认证接口不会导致检查失败。实时供应商检查为单向：只有生产环境列出了 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 hooks（simple-git-hooks）：pre-commit 会对暂存文件运行 biome check --write，pre-push 会运行类型检查和测试。每晚运行的实时漂移任务会创建 Live OpenAPI drift issue，而不会阻止 PR。所有 kingminos-* 仓库的 CI 导览见：kingminos-application/docs/ci.md。

发布（CalVer）

推送到 main 后，CI 成功时，CalVer Release 工作流会为该提交打标签（YYYY.MM.DD.N，UTC），并创建包含自动生成说明的 GitHub release。它不会向 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 标签，但不会创建 release。

预览下一个标签和说明：npm run release:preview。

租户 Bearer

KingMinos 租户 Bearer 由客户端以 Authorization: Bearer <token> 的形式发送。服务器绝不会生成、嵌入或记录该值。

Worker 模式不会从 process.env 或 Worker 绑定中读取 KINGMINOS_API_KEY。在 Worker 上，缺少 Authorization 标头时始终返回 401。

本地 Node 进程仅在同时满足以下所有条件时，才可回退到 KINGMINOS_API_KEY：

• 进程绑定到环回地址（127.0.0.1、localhost 或 ::1）
• KINGMINOS_MCP_ALLOW_ENV_BEARER=1

生产环境中的 Worker 不会存储此密钥。此处不会打印该值。

POST /mcp 会拒绝存在但不在允许列表中的 Origin。不发送 Origin 的客户端仍可正常使用（典型情况是 MCP 客户端访问 https://mcp.kingminos.com/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 — 设为 1 以启用本地环回地址的环境变量 Bearer 回退
• 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 会话不会继承 shell 的 .env 文件。请将 KINGMINOS_API_KEY 导出到 GUI 环境，以便解析 ${env: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	Agent 链式调用方案；批量运行前询问速度／平衡／准确度／覆盖率
company_resolve	POST /v1/company/resolve	电子邮件／域名／网站。除非 dry_run 为 true，否则会消耗额度（API 默认值为 false）。仅提供名称时为 no_decision。result.operator（0 额度）会指出某产品品牌的运营方（fizzy.do → 37signals），不会更改 company_name
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 为 true、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 的平衡模式；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；仅当结果非 low 且身份已确认时，才设置 safe_to_write.description；仅对胜出结果计费；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；仅在 medium 及以上时返回 recommended_language / local_language；routing.path 为 speed（上限 1）| balance（默认，上限 3）| accuracy（上限 4），coverage 会返回 400 invalid_routing；skip_cache / cache_bypass
person_phone	POST /v1/person/phone	根据工作电子邮件或 LinkedIn URL 查询某人的一个可拨打电话号码。必需提供 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；由 Agent 管理的路由器在 < 10 秒内返回结果：所有符合条件的供应商（ZoomInfo / QuickEnrich / Blitz BYOK、LeadMagic、AI Ark、仅限美国的 Findymail、Wiza）都会在约 8.5 秒的时限内并行运行；超时的供应商会被丢弃（计费 0）。通过 routing.path 提供四种模式：speed（优先调用 LeadMagic，领先 3 秒，然后与成本最低的备用供应商竞速；上限 10，绝不使用 Wiza）、balance（默认：根据供应商先验、地区和线路类型选择最佳单个号码，无需等待结果一致）、accuracy（要求结果一致，只返回一个号码；conflicting_numbers → 不安全）、coverage（最多返回 5 个排序后的号码，每个都附有来源、线路类型、置信度和共识度）。每个号码均包含 consensus 和 do_not_call；routing.only / ignore 用于筛选供应商池。仅对返回号码所对应的供应商计费（coverage：对每个返回号码计费），上限为 38 额度；未命中时为 0；BYOK 为 0.1；缓存 30 天，支持 skip_cache / cache_bypass；仅限 API 租户；电话号码属于联系人 PII
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；仅在使用 BYOK 密钥时才搜索 ZoomInfo；若出现 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 为规范 URL，result.candidates 为候选项（胜出项在前，包含 agrees），并返回 result.flags；routing.path 为 speed | balance（默认）| accuracy，无 coverage 档位 — 命中时按结果计费，分别为 2 / 3 / 5 额度；未命中、不匹配或低于最低置信度而不返回时计费 0；写入依据仅为 confidence（无 safe_to_write）：两个来源一致为 high，一个来源为 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）；角色邮箱会标记为 role_address，不消耗额度；result.name_source 为 vendor | email_local_parse（最后备用方案 parsed_only，置信度低），并返回 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	脱敏的 Your Keys 目录。绝不返回原始密钥
put_credentials	PUT /v1/credentials/{provider}	租户的 Your Keys（密文）。请先确认。密钥会在此对话中显示；建议使用 Web 应用 https://app.kingminos.com/app/keys/
delete_credentials	DELETE /v1/credentials/{provider}	撤销 Your Keys。请先确认
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}	单个端点：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。