companies-house-screening-mcp

Проверяйте британские компании по публичному реестру Companies House из MCP-хоста. Пакетная проверка списка поставщиков, мгновенные снимки компании одним вызовом и фактические сигналы вместо оценки риска.

Статус: этап 6 из 6. Одиннадцать инструментов, документация, генерируемая из работающего сервера и проверяемая в CI, эвал выбора инструментов и фикстуры, записанные с живого API. Пайплайн релиза построен; ещё не опубликован.

Есть ещё один проект, и вам стоит о нём знать

companies-house-mcp от @aicayzer существует с июля 2025 года, находится на версии v4.0.0 и активно поддерживается. Он покрывает тот же API. Этот проект не первый и не претендует на это.

Они устроены по-разному, так что выбор зависит от ваших задач.

Используйте их, если вам нужна широта. Он открывает больше API — реестры, освобождения, британские представительства, дисквалификации должностных лиц — и, что важно, он умеет скачивать сами поданные документы. Этот проект намеренно этого не делает: API документов Companies House здесь вне области действия.

Используйте этот, если вы проверяете, а не просматриваете. Различия, которые имеют значение:

Одиннадцать решений описаны в 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

Получите бесплатный ключ API на developer.company-information.service.gov.uk: зарегистрируйтесь, создайте приложение в среде Live и создайте ключ типа REST (ключ потока аутентифицируется так же, но предназначен для другого сервиса).

Зачем ещё одна обёртка над API

Очевидный способ построить это — один MCP-инструмент на эндпоинт. Двадцать два тонких прокси, работа на выходные — и именно так устроено большинство опубликованных MCP-серверов. Это плохо по трём конкретным причинам:

• Каждая схема инструмента находится в контексте модели на каждом ходу, независимо от того, нужна ли она для задачи.

• Это перекладывает оркестрацию на модель. «Безопасно ли онбордить этого поставщика» превращается в поиск, затем профиль, затем должностных лиц, затем обременения, затем банкротство — пять кругов и пять шансов потерять нить.

• Полезные нагрузки Companies House несут структуру, которую ни одна модель не читает — links, etag, kind, ETag'и на каждый элемент, массивы поданных транзакций, объекты адресов с девятью ключами. Упрощение экономит от 36% до 72% в зависимости от эндпоинта, измерено на реальных записанных ответах, а не на предположениях (npm run measure).

Поэтому этот сервер предоставляет одиннадцать инструментов, сформированных вокруг вопросов, два из которых (company_snapshot и screen_companies) выполняют разветвление на стороне сервера и возвращают один производный объект. Инструменты поиска принимают номер компании и отказываются от названия, потому что, получив название, модель угадает номер, а правдоподобный неверный номер компании возвращает реальную компанию, которую ничто ниже по конвейеру не помечает как ошибочную.

Инструменты

Полный справочник: docs/tools. Рабочие примеры: docs/recipes — проверка поставщиков, проверка конфликтов директоров, верификация счетов, риск дебитора, наблюдение за отчётностью конкурентов.

Сигналы — это факты, а не рейтинг. Этот сервер не оценивает компании и не скажет вам, безопасно ли с ними торговать — он сообщает, что нашёл в реестре, с датой или именем за каждым наблюдением, и оставляет суждение человеку, у которого есть контекст. Пустой список сигналов означает, что в списке ничего не найдено, а не то, что компания надёжна. ADR 7 содержит полную аргументацию.

Каждый инструмент аннотирован readOnlyHint: true, публикует схему вывода и принимает verbose, чтобы вернуть нетронутую полезную нагрузку вместе с упрощённой.

Под капотом

284 теста, без сети, для запуска не требуется ключ API.

Конфигурация

Требуется только одна переменная.

Development

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

Документация генерируется и проверяется CI. docs/tools рендерится из работающего сервера через реального MCP-клиента, а каждый вызов из docs/recipes выполняется при сборке страниц. npm run docs:check завершается ошибкой, если закоммиченное отличается; CI запускает его перед тестами, а тестовый набор выполняет ту же сверку, так что сбой приходит, пока вы ещё держите изменения перед глазами. Изменили описание инструмента — перегенерируйте, иначе сборка покраснеет.

Тестовый набор работает офлайн на фикстурах, записанных с живого API Companies House, так что свежий клон работает без какой-либо настройки. npm run record-fixtures перезаписывает их — см. tests/fixtures/README.md: от каких компаний они взяты и почему выбраны именно они.

Когда получите ключ, скопируйте .env.example в .env и заполните его:

npm run test:live

Каждая команда разработки читает этот файл. Всё, что уже задано в вашем окружении, имеет приоритет. Опубликованный сервер не читает .env, если только CH_ENV_FILE не указывает на нужный файл: хост запускает его в рабочей директории хоста, и подхватить случайный лежащий рядом .env — верный способ загрузить чужие учётные данные.

Этот тест запускается по ночам в CI. Его задача — не пройти, а громко упасть в ту неделю, когда Companies House изменяет какое-то поле, чтобы фикстуры обновились раньше, чем расхождение заметит пользователь.

The tool-selection eval

Каждый тест в этом репозитории отвечает на вопрос: работает ли инструмент. Но ни один из них не может ответить, потянется ли модель к правильному инструменту, когда человек задаёт реальный вопрос: инструмент может быть правильным, быстрым и полностью покрытым тестами и всё равно так и не быть выбранным, потому что его описание расплывчато или пересекается с другим. Это самый частый реальный дефект опубликованных MCP-серверов.

npm run eval -- --repeat 3

Прогон выполняется через OpenRouter или Anthropic API — задайте OPENROUTER_API_KEY или ANTHROPIC_API_KEY. По умолчанию используется z-ai/glm-5.2 на OpenRouter, примерно 4p за полный прогон: оценку, которую никто не запускает из-за цены, смысла нет. Для сравнения укажите --model любую другую модель с поддержкой инструментов.

Четырнадцать вопросов, сформулированных как их сформулировал бы человек. Оценивается: какой инструмент был вызван первым, не коснулась ли модель запрещённого инструмента, верны ли аргументы и — это самое главное — не выдумала ли модель номер компании, которого не было в вопросе. Случай, прошедший два прогона из трёх, помечается как флаки и падает в тесте: непостоянный выбор означает, что два описания пересекаются.

При прогоне на трёх моделях (GLM 5.2, Kimi K3, DeepSeek V4 Pro) результат — 93–98%. Группа grounding-запросов — дано название компании и нет номера, нужно искать, а не угадывать по памяти — проходит 7/7 на всех трёх. Сбои группировались: три из них оказались дефектами в моих собственных описаниях инструментов и один — в самой оценке, а не в какой-либо модели.

Ключ Companies House не нужен; ничего не выполняется. Полное сравнение и результаты — в evals/README.md, обоснование — в [opened in ADR 10.

Design notes

Одиннадцать решений описаны в docs/adr:

1. Запись архитектурных решений

2. Ограничитель частоты запросов со скользящим окном и его запас прочности

3. Ошибки как данные, а не исключения

4. Кэширование, TTL и запасной вариант при устаревших данных

5. Инструменты в форме вопроса и почему одно название отклоняется

6. Зачем результат отдаётся дважды

7. Сигналы, а не баллы

8. Частичные результаты и честность о бюджете, ничего не теряется тихо

9. Генерируемая документация, закрытая в CI

10. Оценка выбора инструментов

11. Релизы по тегам, с подписью происхождения (provenance)

Scope

Только чтение, навсегда. Каждый инструмент помечен readOnlyHint: true, пути записи нет. Companies House filing API, который подаёт документы от имени компании, — это другой продукт с другим профилем риска и вне рамок этого. Потоковый API тоже вне рамок. Получение PDF или iXBRL документа через document API — фаза 7 и тоже останется только на чтение.

Roadmap

Лицензия

Исходный код: MIT.

Данные, возвращаемые этим сервером, публикуются Companies House под лицензией Open Government Licence v3.0: и не покрываются лицензией MIT. Если вы распространяете их дальше, сохраняйте атрибуцию, которую требует OGL:

Содержит информацию государственного сектора по лицензии Open Government Licence v3.0.

Этот проект не аффилирован с Companies House и не одобрен им.