companies-house-screening-mcp

Prüfe britische Unternehmen gegen das öffentliche Register von Companies House von einem MCP-Host aus. Stapelprüfung einer Lieferantenliste, Unternehmens-Snapshots mit einem einzigen Aufruf und faktische Signale statt eines Risiko-Scores.

Status: Phase 6 von 6. Elf Tools, aus dem laufenden Server generierte und in CI abgesicherte Dokumentation, eine Tool-Auswahl-Evaluation und aus der Live-API aufgezeichnete Fixtures. Release-Pipeline gebaut; noch nicht veröffentlicht.

Es gibt noch ein anderes, und du solltest davon wissen

companies-house-mcp von @aicayzer existiert seit Juli 2025, ist bei v4.0.0 und wird aktiv gepflegt. Es deckt dieselbe API ab. Dieses Projekt ist nicht das erste und erhebt auch nicht diesen Anspruch.

Die beiden sind unterschiedlich gestaltet, sodass es davon abhängt, was du tust, welches passt.

Nutze ihres, wenn du Breite willst. Es legt mehr von der API offen — Register, Befreiungen, UK-Niederlassungen, Disqualifikationen von Amtsträgern — und, was wichtig ist, es kann die eingereichten Dokumente selbst herunterladen. Dieses hier tut das bewusst nicht: Die Companies-House-Dokument-API liegt hier außerhalb des Rahmens.

Nutze dieses, wenn du eher prüfst als stöberst. Die Unterschiede, die zählen:

Elf Entscheidungen sind in docs/adr dokumentiert, auch die, die nicht den naheliegenden Weg gegangen sind.

Installation

npx -y companies-house-screening-mcp

Host-Konfiguration:

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

Oder mit Docker — beachte -i und kein -t, weil ein TTY das JSON-RPC-Framing beschädigt:

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

Hol dir einen kostenlosen API-Schlüssel unter developer.company-information.service.gov.uk: Registriere dich, erstelle eine Anwendung für die Live-Umgebung und erstelle einen Schlüssel vom Typ REST (ein Stream-Schlüssel authentifiziert auf dieselbe Weise, ist aber für einen anderen Dienst).

Warum ein weiterer API-Wrapper

Der naheliegende Weg, das zu bauen, ist ein MCP-Tool pro Endpunkt. Zweiundzwanzig dünne Durchreichungen, ein Wochenende Arbeit, und genau das sind die meisten veröffentlichten MCP-Server. Es ist aber aus drei konkreten Gründen schlecht:

• Jedes Tool-Schema liegt bei jedem Turn im Kontext des Modells, ob die Aufgabe es braucht oder nicht.

• Es schiebt die Orchestrierung dem Modell zu. „Ist dieser Lieferant sicher anzubinden?“ wird zu Suche, dann Profil, dann Geschäftsführer, dann Belastungen, dann Insolvenz — fünf Roundtrips und fünf Gelegenheiten, den Faden zu verlieren.

• Companies-House-Payloads tragen Struktur, die kein Modell liest — links, etag, kind, ETags pro Eintrag, Filing-Transaktions-Arrays, Adressobjekte mit neun Schlüsseln. Sie wegzuformen spart je nach Endpunkt zwischen 36 % und 72 %, gemessen an echten aufgezeichneten Antworten statt angenommenen (npm run measure).

Dieser Server stellt also elf Tools bereit, die um Fragen herum geformt sind, von denen zwei (company_snapshot und screen_companies) das Fan-out serverseitig erledigen und ein abgeleitetes Objekt zurückgeben. Abruf-Tools akzeptieren eine Unternehmensnummer und lehnen einen Unternehmensnamen ab, denn wenn ein Modell einen Namen erhält, rät es eine Nummer, und eine plausibel falsche Unternehmensnummer liefert ein echtes Unternehmen, das nachgelagert nichts als falsch kennzeichnet.

Die Tools

Vollständige Referenz: docs/tools. Ausgearbeitete Beispiele: docs/recipes — Lieferantenprüfung, Interessenkonflikt-Checks für Geschäftsführer, Rechnungsprüfung, Schuldnerrisiko, Beobachtung von Wettbewerber-Einreichungen.

Die Signale sind Fakten, keine Bewertung. Dieser Server bewertet Unternehmen nicht und sagt dir nicht, ob es sicher ist, mit einem Geschäfte zu machen — er berichtet, was er im Register gefunden hat, mit dem Datum oder dem Namen hinter jeder Beobachtung, und überlässt das Urteil der Person, die den Kontext hat. Eine leere Signalliste bedeutet, dass nichts auf der Liste gefunden wurde, nicht, dass das Unternehmen solide ist. ADR 7 enthält die vollständige Begründung.

Jedes Tool ist mit readOnlyHint: true annotiert, veröffentlicht ein Ausgabeschema und nimmt verbose entgegen, um die unveränderte Payload neben der geformten zurückzugeben.

Unter den Tools

284 Tests, kein Netzwerk, kein API-Schlüssel nötig, um sie auszuführen.

Konfiguration

Nur eine Variable ist erforderlich.

Entwicklung

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

Die Dokumentation wird generiert und geprüft. docs/tools wird aus dem laufenden Server über einen echten MCP-Client gerendert, und jeder Aufruf in docs/recipes wird ausgeführt, wenn die Seiten erstellt werden. npm run docs:check schlägt fehl, wenn das Eingecheckte abweicht, CI führt es vor den Tests aus, und die Suite führt denselben Vergleich durch, sodass der Fehler auftritt, während Sie die Änderung noch vor sich haben. Ändern Sie eine Tool-Beschreibung und generieren Sie neu, oder der Build wird rot.

Die Suite läuft offline gegen aufgezeichnete Fixtures der Live-Companies-House- API, sodass ein frischer Klon ohne Konfiguration funktioniert. npm run record-fixtures zeichnet sie neu auf — siehe tests/fixtures/README.md für welche Unternehmen sie stammen und warum diese ausgewählt wurden.

Sobald Sie einen Schlüssel besitzen, kopieren Sie .env.example nach .env und füllen Sie ihn aus:

npm run test:live

Jeder Entwicklungsbefehl liest diese Datei. Alles, was bereits in Ihrer Shell gesetzt ist, hat Vorrang. Der veröffentlichte Server liest keine .env-Datei, es sei denn, CH_ENV_FILE benennt eine — ein Host startet ihn mit dem Arbeitsverzeichnis des Hosts, und wenn er versehentlich eine .env-Datei aufnimmt, die dort liegt, kann das falsche Anmeldeinformationen laden.

Dieser Test läuft nächtlich in CI. Seine Aufgabe ist nicht das Bestehen — es geht darum, laut zu scheitern, wenn Companies House ein Feld ändert, damit die Fixtures aktualisiert werden, bevor ein Benutzer die Abweichung entdeckt.

Die Tool-Auswahl-Evaluierung

Jeder Test in diesem Repository fragt: Funktioniert das Tool? Was keiner von ihnen fragen kann, ist, ob ein Modell zum richtigen Tool greift, wenn eine Person eine echte Frage stellt — ein Tool kann korrekt, schnell und vollständig abgedeckt sein und trotzdem nie ausgewählt werden, weil seine Beschreibung vage ist oder sich mit einer anderen überschneidet. Das ist der häufigste echte Mangel bei veröffentlichten MCP-Servern.

npm run eval -- --repeat 3

Läuft über OpenRouter oder die Anthropic API — setzen Sie OPENROUTER_API_KEY oder ANTHROPIC_API_KEY. Standardmäßig wird z-ai/glm-5.2 auf OpenRouter verwendet, etwa 4 Pence für einen vollständigen Durchlauf, denn eine Evaluierung, die wegen der Kosten niemand ausführt, nützt nichts. Weisen Sie --model auf ein beliebiges Modell mit Tool-Unterstützung hin, um zu vergleichen.

Vierzehn Fragen, formuliert, wie eine Person sie stellen würde, bewertet danach, welches Tool zuerst aufgerufen wurde, ob ein verbotenes Tool berührt wurde, ob die Argumente korrekt waren, und — das Entscheidende — ob das Modell eine Unternehmensnummer erfunden hat, die nicht in der Frage stand. Ein Fall, der bei zwei von drei Läufen besteht, wird als fehlerhaft gemeldet, denn eine intermittierende Auswahl bedeutet, dass sich zwei Beschreibungen überschneiden.

Läuft über drei Modelle (GLM 5.2, Kimi K3, DeepSeek V4 Pro) und erreicht 93–98 %. Die Grundlagengruppe — mit einem Unternehmensnamen, aber ohne Nummer, Suche statt Erinnerung — besteht 7/7 bei allen drei. Die Fehlschläge häuften sich, und drei davon waren Fehler in meinen eigenen Tool-Beschreibungen und einer in der Evaluierung selbst, nicht in einem Modell.

Kein Companies-House-Schlüssel ist nötig; nichts wird ausgeführt. Vollständiger Vergleich und was er in evals/README.md gefunden hat, Überlegungen in ADR 10.

Entwurfsnotizen

Elf Entscheidungen sind dokumentiert in docs/adr:

1. Architekturentscheidungen aufzeichnen

2. Der Gleitfenster-Ratenbegrenzer und seine Sicherheitsmarge

3. Fehler als Daten statt als Ausnahmen

4. Caching, TTLs und der veraltete Fallback

5. Fragenförmige Tools und warum ein Name verweigert wird

6. Warum die Ergebnisnutzlast zweimal gesendet wird

7. Signale, keine Punktzahlen

8. Teilergebnisse und niemals etwas stillschweigend verwerfen

9. Generierte Dokumentation, in CI geprüft

10. Die Tool-Auswahl-Evaluierung

11. Tag-gesteuerte Veröffentlichungen, signiert mit Herkunftsnachweis

Umfang

Nur lesend, dauerhaft. Jedes Tool ist mit readOnlyHint: true annotiert, und es gibt keinen Schreibpfad. Die Companies-House-Einreichungs-API, die Dokumente im Namen eines Unternehmens übermittelt, ist ein anderes Produkt mit einem anderen Risikoprofil und liegt außerhalb des Umfangs. Die Streaming-API ist ebenfalls außerhalb des Umfangs. Das Abrufen von PDF oder iXBRL einer Einreichung über die Dokument-API ist Phase 7 und würde weiterhin nur lesend bleiben.

Fahrplan

Lizenz

Quellcode: MIT.

Daten, die dieser Server zurückgibt, werden von Companies House unter der Open Government Licence v3.0 veröffentlicht und sind nicht von der MIT-Lizenz abgedeckt. Wenn Sie sie weiterverbreiten, führen Sie die Namensnennung mit, die die OGL verlangt:

Enthält Informationen des öffentlichen Sektors, lizenziert unter der Open Government Licence v3.0.

Dieses Projekt ist weder mit Companies House verbunden noch von ihm unterstützt.