companies-house-screening-mcp

MCP 호스트에서 영국 기업등록소 공개 레지스터를 대상으로 영국 기업을 스크리닝합니다. 공급업체 목록 일괄 스크리닝, 한 번의 호출로 회사 스냅샷 확인, 위험 점수가 아닌 사실 기반 신호를 제공합니다.

상태: 6단계 중 6단계. 실행 중인 서버에서 생성되고 CI에서 검증되는 문서와 함께 11개의 도구, 도구 선택 평가, 라이브 API에서 기록된 픽스처가 포함되어 있습니다. 릴리스 파이프라인은 구축되었지만 아직 게시되지 않았습니다.

다른 프로젝트가 있으며, 알아두셔야 합니다

companies-house-mcp는 @aicayzer가 2025년 7월부터 운영 중이며, v4.0.0에 이르렀고, 활발히 유지보수되고 있습니다. 동일한 API를 다룹니다. 이 프로젝트는 선구자가 아니며 그렇게 주장하지도 않습니다.

두 프로젝트는 형태가 다르므로, 어떤 것을 사용할지는 작업 내용에 따라 달라집니다.

폭넓은 기능이 필요하다면 그들의 것을 사용하세요. 더 많은 API를 노출합니다 — 등록, 면제, 영국 법인, 임원 자격 상실 — 그리고 중요한 것은 제출된 서류 자체를 다운로드할 수 있다는 점입니다. 이 프로젝트는 의도적으로 그렇게 하지 않습니다: Companies House 문서 API는 여기서 범위를 벗어납니다.

브라우징이 아니라 스크리닝이 목적이라면 이 프로젝트를 사용하세요. 중요한 차이점:

11개의 결정 사항이 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 사용 시 — JSON-RPC 프레이밍을 손상시키는 TTY 때문에 -i를 사용하고 -t는 사용하지 않습니다:

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 도구를 만드는 것입니다. 22개의 얇은 패스스루, 주말 작업, 그리고 대부분의 게시된 MCP 서버가 그렇게 합니다. 또한 세 가지 특정한 방식으로 나쁩니다:

• 모든 도구 스키마는 작업에 필요하지 않더라도 매 턴마다 모델의 컨텍스트에 있습니다.

• 오케스트레이션을 모델에 떠넘깁니다. "이 공급업체를 온보딩해도 안전한가"는 검색, 프로필, 임원, 담보, 파산으로 이어집니다 — 다섯 번의 왕복과 스레드를 잃을 다섯 번의 기회.

• Companies House 페이로드는 모델이 읽지 않는 구조를 담고 있습니다 — links, etag, kind, 항목별 ETag, 제출 트랜잭션 배열, 9개 키 주소 객체. 이를 정리하면 엔드포인트에 따라 36%에서 72%까지 절약되며, 가정이 아닌 실제 기록된 응답을 기준으로 측정됩니다(npm run measure).

따라서 이 서버는 질문 중심으로 구성된 11개의 도구를 노출하며, 그 중 두 개(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

문서는 생성되며 게이트(gate)로 통제됩니다. 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

모든 개발 명령은 해당 파일을 읽습니다. 셸에 이미 설정된 값이 파일보다 우선합니다. 배포된 서버는 CH_ENV_FILE이 특정 파일을 명시하지 않는 한 .env를 읽지 않습니다 — 호스트는 자신의 작업 디렉터리에서 서버를 실행하므로, 그 자리에 우연하게 존재하는 .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로, 전체 실행 한 번당 약 4p 정도입니다. 비용 때문에 아무도 실행하지 않는 평가는 아무 효과가 없기 때문입니다. 비교를 위해 --model을 도구 지원이 있는 모델로 지정할 수 있습니다.

사람이 실제로 쓰는 방식으로 표현된 14개의 질문에 대해 어떤 도구가 첫 번째로 호출되었는지, 금지된 도구를 사용했는지, 인자가 올바른지, 그리고 가장 중요한 것은 질문에 없던 회사 번호를 모델이 지어냈는지로 채점합니다. 세 번 중 두 번 통과하는 사례는 flaky(불안정)로 보고되어 실패 처리됩니다. 선택이 확률적으로 오락가락한다는 것은 두 도구의 설명이 겹친다는 뜻이기 때문입니다.

세 가지 모델(GLM 5.2, Kimi K3, DeepSeek V4 Pro)에서 실행한 성능은 93–98%입니다. grounding 그룹 — 회사명만 주어지고 번호가 없을 때 번호를 기억하는 대신 검색하는 케이스 —에는 세 모델 모두 7/7로 통과했습니다. 실패는 한곳에 몰려 있었고, 그중 세 건은 어떤 모델의 문제가 아니라 제 도구 설명의 결함이었고, 한 건은 평가 자체의 결함이었습니다.

Companies House API 키는 필요 없습니다. 아무것도 실행되지 않습니다. 자세한 비교와 발견 사항은 evals/README.md에 있고, 판단 근거는 ADR 10에 있습니다.

설계 노트

11개의 결정이 docs/adr에 정리되어 있습니다:

1. 아키텍처 결정 기록

2. 슬라이딩 윈도우 속도 제한기와 안전 여유

3. 예외가 아닌 데이터로서의 오류 처리

4. 캐싱, TTL 및 오래된 항목 폴백

5. 질문 형태의 도구, 그리고 이름이 거부되는 이유

6. 결과 페이로드를 두 번 보내는 이유

7. 점수가 아닌 신호

8. 부분 결과 및 조용히 버리지 않기

9. 생성된 문서, CI에서 게이트하기

10. 도구 선택 평가

11. 태그 기반 릴리스와 provenance 서명

범위

영구적으로 읽기 전용입니다. 모든 도구는 readOnlyHint: true로 표시되어 있으며 쓰기 경로는 없습니다. 문서를 회사 대신 제출하는 Companies filing API는 위험 특성이 다른 별도의 제품이므로 이 저장소의 범위 밖입니다. 스트리밍 API도 범위 밖입니다. 문서 API를 통해 제출물의 PDF 또는 iXBRL을 가져오는 것은 7단계에 있고, 읽기 전용으로 유지됩니다.

로드맵

라이선스

소스 코드는 MIT입니다.

이 서버가 반환하는 데이터는 Companies House가 Open Government Licence v3.0에 따라 공개한 것으로, MIT 라이선스의 적용 대상이 아닙니다. 이 데이터를 재배포하려면 OGL이 요구하는 출처 표시를 포함해야 합니다:

공공 부문 정보를 포함하며, Open Government Licence v3.0에 따라 라이선스가 부여되었습니다.

이 프로젝트는 Companies House와 제휴 관계가 아니며, 그 승인을 받지 않았습니다.publicwise.