companies-house-screening-mcp

Consulta empresas del Reino Unido contra el registro público de Companies House desde un host MCP. Screening por lotes de una lista de proveedores, instantáneas de empresa en una sola llamada y señales fácticas en lugar de una puntuación de riesgo.

Estado: fase 6 de 6. Once herramientas, documentación generada desde el servidor en ejecución y controlada en CI, una evaluación de selección de herramientas y fixtures grabados de la API en vivo. Pipeline de publicación construido; aún no publicado.

Hay otro, y deberías saberlo

companies-house-mcp de @aicayzer existe desde julio de 2025, está en la v4.0.0 y se mantiene activamente. Cubre la misma API. Este proyecto no es el primero y no pretende serlo.

Los dos están planteados de forma distinta, así que cuál encaja depende de lo que estés haciendo.

Usa el suyo si quieres amplitud. Expone más de la API — registros, exenciones, establecimientos del Reino Unido, inhabilitaciones de administradores — y, lo importante, puede descargar los propios documentos presentados. Este deliberadamente no: la API de documentos de Companies House queda fuera del alcance aquí.

Usa este si haces screening en lugar de navegar. Las diferencias que importan:

Once decisiones están documentadas en docs/adr, incluidas las que no tomaron el camino obvio.

Instalación

npx -y companies-house-screening-mcp

Configuración del host:

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

O con Docker — observa -i y sin -t, porque una TTY corrompe el encuadre JSON-RPC:

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

Obtén una clave de API gratuita en developer.company-information.service.gov.uk: regístrate, crea una aplicación contra el entorno Live y crea una clave de tipo REST (una clave de stream autentica de la misma manera pero es para un servicio distinto).

Por qué otro wrapper de API

La forma obvia de construir esto es una herramienta MCP por endpoint. Veintidós pasarelas finas, el trabajo de un fin de semana, y es lo que son la mayoría de los servidores MCP publicados. También es malo en tres sentidos concretos:

• Cada esquema de herramienta está en el contexto del modelo en cada turno, lo necesite la tarea o no.

• Empuja la orquestación al modelo. "¿Es seguro incorporar a este proveedor?" se convierte en búsqueda, luego perfil, luego administradores, luego cargas, luego insolvencia — cinco idas y venidas y cinco oportunidades de perder el hilo.

• Los payloads de Companies House llevan estructura que ningún modelo lee — links, etag, kind, ETags por elemento, arrays de transacciones de presentación, objetos de dirección de nueve claves. Reformularlos ahorra entre el 36% y el 72% según el endpoint, medido contra respuestas reales grabadas en lugar de asumidas (npm run measure).

Así que este servidor expone once herramientas con forma de pregunta, dos de las cuales (company_snapshot y screen_companies) hacen el fan-out en el servidor y devuelven un objeto derivado. Las herramientas de recuperación aceptan un número de empresa y rechazan un nombre de empresa, porque dado un nombre un modelo adivinará un número, y un número de empresa erróneo plausible devuelve una empresa real que nada aguas abajo señala como incorrecto.

Las herramientas

Referencia completa: docs/tools. Ejemplos prácticos: docs/recipes — screening de proveedores, controles de conflicto de directores, verificación de facturas, riesgo de deudores, vigilancia de presentaciones de competidores.

Las señales son hechos, no una calificación. Este servidor no puntúa empresas y no te dirá si es seguro comerciar con una — informa de lo que encontró en el registro, con la fecha o el nombre detrás de cada observación, y deja el juicio a la persona que tiene el contexto. Una lista de señales vacía significa que no se encontró nada de la lista, no que la empresa sea sólida. ADR 7 contiene el razonamiento completo.

Cada herramienta está anotada con readOnlyHint: true, publica un esquema de salida y acepta verbose para devolver el payload intacto junto al reformulado.

Bajo las herramientas

284 pruebas, sin red, sin necesidad de clave de API para ejecutarlas.

Configuración

Solo se requiere una variable.

Desarrollo

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

La documentación se genera y se controla. docs/tools se renderiza desde el servidor en ejecución a través de un cliente MCP real, y cada llamada en docs/recipes se ejecuta cuando se construyen las páginas. npm run docs:check falla si lo que está confirmado difiere, CI lo ejecuta antes de las pruebas, y la suite ejecuta la misma comparación para que el fallo llegue mientras aún tienes el cambio delante de ti. Cambia una descripción de herramienta y regeneras, o la compilación se pone en rojo.

La suite se ejecuta sin conexión contra fixtures grabados de la API real de Companies House, por lo que un clon nuevo funciona sin nada configurado. npm run record-fixtures los vuelve a grabar — consulta tests/fixtures/README.md para saber de qué empresas provienen y por qué se eligieron esas.

Una vez que tengas una clave, copia .env.example a .env y complétalo:

npm run test:live

Cada comando de desarrollo lee ese archivo. Cualquier cosa ya definida en tu shell tiene prioridad sobre él. El servidor publicado no lee un .env a menos que CH_ENV_FILE nombre uno — un host lo lanza con el directorio de trabajo del host, y recoger cualquier .env que esté ahí es una buena manera de cargar las credenciales equivocadas.

Esa prueba se ejecuta cada noche en CI. Su trabajo no es pasar — es fallar en voz alta la semana en que Companies House cambie un campo, para que los fixtures se actualicen antes de que un usuario encuentre la desviación.

La evaluación de selección de herramientas

Cada prueba en este repositorio pregunta ¿funciona la herramienta?. Una cosa que ninguna de ellas puede preguntar es si un modelo recurre a la herramienta correcta cuando una persona hace una pregunta real — una herramienta puede ser correcta, rápida y totalmente cubierta y aun así nunca ser elegida, porque su descripción es vaga o se solapa con otra. Ese es el defecto real más común en los servidores MCP publicados.

npm run eval -- --repeat 3

Se ejecuta a través de OpenRouter o la API de Anthropic — define OPENROUTER_API_KEY o ANTHROPIC_API_KEY. Por defecto usa z-ai/glm-5.2 en OpenRouter, alrededor de 4p por una pasada completa, porque una evaluación que nadie ejecuta por el costo no está haciendo nada. Apunta --model a cualquier cosa con soporte de herramientas para comparar.

Catorce preguntas formuladas como las haría una persona, puntuadas según qué herramienta se llamó primero, si se tocó una herramienta prohibida, si los argumentos eran correctos y — la que importa — si el modelo inventó un número de empresa que no estaba en la pregunta. Un caso que pasa dos de tres ejecuciones se reporta como inestable y falla, porque la selección intermitente significa que dos descripciones se solapan.

Ejecutada en tres modelos (GLM 5.2, Kimi K3, DeepSeek V4 Pro) obtiene una puntuación del 93–98%. El grupo de fundamentación — dado un nombre de empresa y sin número, buscar en lugar de recordar uno — pasa 7/7 en los tres. Los fallos se agruparon, y tres de ellos resultaron ser defectos en mis propias descripciones de herramientas y uno en la evaluación en sí, en lugar de en cualquier modelo.

No se necesita clave de Companies House; no se ejecuta nada. Comparación completa y lo que encontró en evals/README.md, razonamiento en ADR 10.

Notas de diseño

Once decisiones están documentadas en docs/adr:

1. Registro de decisiones de arquitectura

2. El limitador de velocidad de ventana deslizante y su margen de seguridad

3. Errores como datos en lugar de excepciones

4. Caché, TTLs y el respaldo obsoleto

5. Herramientas con forma de pregunta, y por qué se rechaza un nombre

6. Por qué el payload de resultados se envía dos veces

7. Señales, no puntuaciones

8. Resultados parciales, y nunca descartar nada en silencio

9. Documentación generada, controlada en CI

10. La evaluación de selección de herramientas

11. Lanzamientos impulsados por etiquetas, firmados con procedencia

Alcance

Solo lectura, permanentemente. Cada herramienta está anotada con readOnlyHint: true y no hay ruta de escritura. La API de presentación de Companies House, que envía documentos en nombre de una empresa, es un producto diferente con un perfil de riesgo diferente y está fuera del alcance de este. La API de streaming también está fuera del alcance. Obtener el PDF o iXBRL de una presentación a través de la API de documentos es la fase 7 y seguiría siendo de solo lectura.

Hoja de ruta

Licencia

Código fuente: MIT.

Los datos devueltos por este servidor son publicados por Companies House bajo la Open Government Licence v3.0 y no están cubiertos por la licencia MIT. Si los redistribuyes, lleva la atribución que requiere la OGL:

Contiene información del sector público licenciada bajo la Open Government Licence v3.0.

Este proyecto no está afiliado ni respaldado por Companies House.