companies-house-screening-mcp

从 MCP 主机中对照英国公司注册处公共登记册筛查英国公司。支持供应商名单批量筛查、一次调用获取公司快照，以及提供事实性信号而非风险评分。

状态：6 个阶段中的第 6 阶段。 十一个工具、从运行中的服务器生成并在 CI 中把关的文档、一个工具选择评估，以及从实时 API 录制的测试夹具。发布流水线已构建完成；尚未发布。

还有另一个项目，你应该知道它

companies-house-mcp 由 @aicayzer 开发，自 2025 年 7 月起就已存在，目前为 v4.0.0，并且维护活跃。它覆盖同一个 API。本项目并非首创，也不声称如此。

两者的形态不同，因此哪个更合适取决于你在做什么。

如果你想要覆盖面广，就用他们的。 它暴露了更多 API——登记册、豁免、英国分支机构、高管取消资格——而且重要的是，它可以下载已提交的文件本身。本项目刻意不做这件事：英国公司注册处的文件 API 不在本项目的范围内。

如果你是在做筛查而不是浏览，就用本项目的。 关键差异如下：

十一个决策已记录在 docs/adr 中，包括那些没有走显而易见路线的决策。

安装

npx -y companies-house-screening-mcp

主机配置：

{
  "mcpServers": {
    "companies-house": {
      "command": "npx",
      "args": ["-y", "companies-house-screening-mcp"],
      "env": { "COMPANIES_HOUSE_API_KEY": "your_key" }
    }
  }
}

或者使用 Docker——注意使用 -i 且不使用 -t，因为 TTY 会破坏 JSON-RPC 的帧格式：

docker run --rm -i -e COMPANIES_HOUSE_API_KEY=your_key ghcr.io/OWNER/companies-house-screening-mcp

在 developer.company-information.service.gov.uk 获取免费 API 密钥：注册，针对 Live 环境创建应用，然后创建类型为 REST 的密钥（流密钥的认证方式相同，但用于不同的服务）。

为什么又一个 API 封装

显而易见的构建方式是为每个端点提供一个 MCP 工具。二十二个薄薄的透传，一个周末的活，这也是大多数已发布的 MCP 服务器的做法。但它在三个具体方面很糟糕：

• 每个工具的模式都会在每一轮对话中进入模型的上下文，无论任务是否需要它。

• 它把编排工作推给了模型。"这个供应商是否可以安全接入"变成了搜索、然后资料、然后高管、然后抵押、然后破产——五次往返，五次丢失线索的机会。

• 英国公司注册处的负载携带了没有模型会读取的结构——links、etag、kind、逐项 ETag、备案交易数组、九键地址对象。将这些结构塑形掉可节省 36% 到 72%，具体取决于端点，这是针对真实录制的响应而非假设进行测量的（npm run measure）。

因此，本服务器暴露了十一个围绕问题塑形的工具，其中两个（company_snapshot 和 screen_companies）在服务器端进行扇出并返回一个派生对象。检索工具接受公司编号并拒绝公司名称，因为给定一个名称，模型会猜测一个编号，而一个貌似合理但错误的公司编号会返回一家真实公司，下游没有任何环节会标记其为错误。

工具

完整参考：docs/tools。实操示例：docs/recipes——供应商筛查、董事利益冲突检查、发票核验、债务人风险、竞争对手备案监控。

信号是事实，而非评级。 本服务器不对公司评分，也不会告诉你某家公司是否适合交易——它报告在登记册上发现的内容，每条观察背后附有日期或名称，判断权留给掌握上下文的人。空的信号列表意味着列表上没有发现任何内容，而不是公司状况良好。ADR 7 中有完整的论证。

每个工具都标注了 readOnlyHint: true，发布输出模式，并接受 verbose 参数以在塑形后的对象旁边返回未经处理的负载。

工具之下

284 个测试，无需网络，运行它们不需要 API 密钥。

配置

只需要一个变量。

开发

npm install
npm test
npm run typecheck
npm run build
npm run docs:generate

文档是生成并受门控的。 docs/tools 通过真实的 MCP 客户端从运行中的服务器渲染，并且 docs/recipes 中的每个调用在页面构建时都会执行。如果提交的内容不同，npm run docs:check 会失败，CI 在测试之前运行它，并且测试套件运行相同的比较，因此失败会在你面前仍有更改时出现。修改工具描述后需要重新生成，否则构建会变红。

测试套件针对从实时 Companies House API 录制的固定数据离线运行，因此全新克隆无需任何配置即可工作。npm run record-fixtures 会重新记录它们——参见 tests/fixtures/README.md 了解它们来自哪些公司以及为什么选择这些公司。

一旦你持有密钥，将 .env.example 复制为 .env 并填写：

npm run test:live

每个开发命令都会读取该文件。你的 shell 中已设置的任何内容都会优先于它。发布的服务器不会读取 .env，除非 CH_ENV_FILE 指定了一个——主机使用其工作目录启动它，而拾取恰好存在的 .env 是加载错误凭据的好方法。

该测试在 CI 中每晚运行。它的工作不是通过——而是在 Companies House 更改字段的那一周大声失败，以便在用户发现漂移之前刷新固定数据。

工具选择评估

此仓库中的每个测试都问工具是否有效。它们都无法问的是，当一个人提出真实问题时，模型是否会选择正确的工具——一个工具可能正确、快速且覆盖充分，但仍然永远不会被选中，因为其描述模糊或与另一个工具重叠。这是已发布的 MCP 服务器中最常见的真实缺陷。

npm run eval -- --repeat 3

通过 OpenRouter 或 Anthropic API 运行——设置 OPENROUTER_API_KEY 或 ANTHROPIC_API_KEY。它默认为 OpenRouter 上的 z-ai/glm-5.2，完整运行大约 4 便士，因为一个因费用而无人运行的评估不会起任何作用。将 --model 指向任何支持工具支持的模型以进行比较。

十四个以人们会问的方式表述的问题，根据首先调用了哪个工具、是否触及了禁止的工具、参数是否正确，以及——最重要的一点——模型是否编造了问题中不存在的公司编号来评分。一个用例在三次运行中通过两次会被报告为不稳定并失败，因为间歇性选择意味着两个描述重叠。

在三个模型（GLM 5.2、Kimi K3、DeepSeek V4 Pro）上运行，得分 93–98%。接地组——给定公司名称而没有编号，搜索而非回忆——在所有三个模型上通过 7/7。失败集中出现，其中三个结果是我自己的工具描述中的缺陷，一个是评估本身中的缺陷，而不是任何模型中的缺陷。

不需要 Companies House 密钥；不执行任何操作。完整比较及其发现见 evals/README.md，推理见 ADR 10。

设计说明

docs/adr 中记录了十一个决策：

1. 记录架构决策

2. 滑动窗口速率限制器及其安全裕度

3. 错误作为数据而非异常

4. 缓存、TTL 和过期回退

5. 问题形状的工具，以及为什么拒绝名称

6. 为什么结果负载被发送两次

7. 信号，而非分数

8. 部分结果，绝不静默丢弃任何内容

9. 生成的文档，在 CI 中门控

10. 工具选择评估

11. 标签驱动的发布，带有来源签名

范围

只读，永久。每个工具都标注了 readOnlyHint: true，并且没有写入路径。Companies House 的 filing API（代表公司提交文档）是一个具有不同风险特征的不同产品，不在本项目的范围内。流式 API 也不在范围内。通过文档 API 获取文件的 PDF 或 iXBRL 是第 7 阶段，并且将保持只读。

路线图

许可证

源代码：MIT。

此服务器返回的数据由 Companies House 按 开放政府许可证 v3.0 发布，不受 MIT 许可证保护。如果你重新分发它，请保留 OGL 要求的署名：

包含根据开放政府许可证 v3.0 许可的公共部门信息。

此项目与 Companies House 无关，也未获得其认可。