Public Risk Intelligence MCP

Un kit de herramientas de código abierto para la recopilación de evidencia pública, resolución de entidades y correlación de riesgos, diseñado para investigar empresas, personas y sus conexiones. Combina registros oficiales de empresas de los estados de EE. UU., conjuntos de datos regulatorios gratuitos seleccionados, recopilación de evidencia asistida por navegador, una CLI, un servidor MCP para agentes de IA y una biblioteca JavaScript reutilizable en expedientes de investigación normalizados.

El proyecto prefiere una API oficial gratuita cuando está disponible. De lo contrario, proporciona a un cliente MCP una receta de navegador versionada para la sesión de Chrome existente del usuario, captura evidencia de registros públicos y normaliza cada fuente al mismo contrato de resultados. También se ofrece ejecución directa con Playwright para sitios que aceptan un nuevo perfil de navegador.

No presenta documentos, compra certificados, evita CAPTCHA, accede a credenciales del navegador ni convierte evidencia de registros, cribado de nombres o correlación en un veredicto de fraude, determinación de AML, decisión adversa o autorización.

Cobertura actual

• 35 recetas de navegador Playwright verificadas en vivo

• 4 rutas oficiales de API

• 2 rutas oficiales de exportación o carga masiva

• 6 límites de verificación humana

• 4 rutas interactivas bloqueadas por automatización

• 0 jurisdicciones sin mapear

• 3 conjuntos de datos regulatorios oficiales anónimos: OFAC SDN, HHS OIG LEIE y asociaciones de empresas de la SEC

• 1 fuente catalogada gratuita con clave: exclusiones de SAM.gov

• 1 capa de investigación normalizada de personas/empresas con procedencia de evidencia, resolución de entidades, relaciones, contradicciones, brechas de cobertura, señales de revisión acotadas y correlaciones entre entidades respaldadas por evidencia

Ejecuta npm run audit:recipes para obtener el catálogo actual legible por máquina y las firmas de las recetas.

Cómo funciona

company + state
      |
      v
policy-aware route selection
   /        |          \
 API    browser recipe  explicit stop
   \        |          /
      public evidence
           |
           v
 normalized evidence + investigation schema 1.0
           |
           v
 evidence-backed correlations
           |
           v
 human investigator review

Las recetas de confianza contienen campos exactos, botones, acciones opcionales previas al envío, selectores de filas de resultados, mapeos de columnas y comportamiento seguro de detalles. Cuando un selector conocido cambia, el motor de recetas devuelve RECIPE_DRIFT_DETECTED en lugar de adivinar. Las nuevas observaciones permanecen en un almacén de candidatos hasta que haya dos observaciones coincidentes y revisión humana.

Consulta Arquitectura, Protocolo de navegador anfitrión, Alternativas para rutas bloqueadas, Formato de receta, Resultados normalizados, Cribado regulatorio gratuito y Casos de investigación.

Instalación

Requisitos: Node.js 20 o superior y Chrome o Chromium para rutas de navegador.

npm install

CLI

# Free official API
npx --no-install public-risk-intelligence search "Microsoft Corporation" --state CO --json

# Prepare an exact recipe for an MCP client's existing Chrome session
npx --no-install public-risk-intelligence plan "Microsoft Corporation" --state TN --json

# Direct Playwright execution for a registry that accepts a fresh visible profile
npx --no-install public-risk-intelligence search "Example Company" --state OH --browser --json

# Inspect the exact Tennessee recipe and its signature
npx --no-install public-risk-intelligence recipe TN --json

# Produce a safe browser plan for another agent/browser host
npx --no-install public-risk-intelligence plan "Microsoft Corporation" --state TN --json

# Inspect policy and coverage
npx --no-install public-risk-intelligence state NC --json
npx --no-install public-risk-intelligence recipes --json

# Check exact names against free official regulatory datasets
npx --no-install public-risk-intelligence regulatory "Example Company LLC" --person "Example Person" --json

# Inspect source coverage and access requirements
npx --no-install public-risk-intelligence regulatory-sources --json

# Build an offline person/company research plan
npx --no-install public-risk-intelligence investigate "Example Company LLC" \
  --person "Example Person" --state NV --no-regulatory --json

# Run federal screening plus an available state-registry route
npx --no-install public-risk-intelligence investigate "Example Company LLC" \
  --person "Example Person" --state CO --registry \
  --purpose counterparty_due_diligence --json

# Validate all trusted recipes
npx --no-install public-risk-intelligence audit --json

Cuando se instala como paquete, public-risk-intelligence es el comando principal. El comando heredado sos-research sigue siendo un alias de compatibilidad equivalente.

El lanzamiento del navegador siempre es opcional con --browser. Usa --headless solo para una fuente que no requiera verificación humana visible.

Se prefiere Chrome existente para registros protegidos

Algunos registros, incluido Tennessee durante la verificación en vivo del 26 de agosto de 2026, rechazaron un perfil automatizado recién lanzado pero funcionaron en la sesión de Chrome existente del usuario. Para estos sitios, usa el par MCP:

1. prepare_browser_search devuelve la URL oficial, la receta firmada y los controles exactos.

2. El cliente MCP opera su navegador Chrome ya conectado.

3. finalize_browser_search valida el host y normaliza las filas públicas.

4. build_investigation_report combina ese resultado normalizado con sujetos, relaciones reportadas, resultados de cribado regulatorio, otra evidencia atribuida y comprobaciones planificadas.

Si el registro solicita verificación humana, el cliente debe pedir al usuario, pausar y reanudar después de que el usuario la complete. La respuesta normalizada usa status: "manual_challenge_required" y un objeto estructurado humanIntervention si expira la ventana de espera. No se intenta evitar CAPTCHA ni seguridad.

La evidencia proporcionada a la herramienta de composición se trata como entrada no confiable y atribuida a una fuente. Su informe siempre está marcado como human_review_only; no es un veredicto de fraude, determinación de AML ni autorización.

Conexión a través de un puerto de depuración local de Chrome

La CLI puede conectarse a una instancia de Chrome que exponga un puerto DevTools local. Las conexiones se restringen a hosts de bucle local y la CLI abre y cierra solo su propia página.

Chrome debe iniciarse con un puerto de depuración antes de que la CLI pueda conectarse; Playwright no puede conectarse a un proceso de Chrome existente arbitrario. Inicia un perfil persistente dedicado en macOS:

open -na "Google Chrome" --args \
  --remote-debugging-port=9222 \
  --user-data-dir=/tmp/public-risk-intelligence-chrome

Luego ejecuta:

npx --no-install public-risk-intelligence search "Microsoft Corporation" \
  --state TN \
  --browser \
  --cdp-url http://127.0.0.1:9222 \
  --json

También puedes configurar SOS_CHROME_PATH o SOS_CHROME_CDP_URL; consulta .env.example. Estos nombres de variables de entorno heredados se mantienen para no romper instalaciones existentes. Esta ruta CDP es opcional: el protocolo MCP de navegador anfitrión es la integración portátil con navegador existente.

Servidor MCP

Inicia el servidor stdio con:

npm run start:mcp

Configuración de Codex:

codex mcp add public-risk-intelligence -- node /absolute/path/to/public-risk-intelligence-mcp/src/mcp-server.js

Configuración de Claude Code:

claude mcp add public-risk-intelligence --scope local -- node /absolute/path/to/public-risk-intelligence-mcp/src/mcp-server.js

Las configuraciones existentes de clientes MCP pueden mantener su alias local sos-research; el servidor ahora se identifica como public-risk-intelligence y mantiene todos los nombres de herramientas existentes compatibles.

Herramientas:

• search_business: ejecuta una API oficial o una búsqueda de navegador local explícitamente autorizada.

• prepare_browser_search: devuelve la URL oficial y la receta exacta para el navegador de un agente anfitrión.

• finalize_browser_search: valida el host oficial y normaliza las filas observadas en el navegador.

• build_investigation_report: compone resultados normalizados de registros y regulatorios con sujetos, relaciones, evidencia, comprobaciones planificadas y correlaciones respaldadas por evidencia.

• get_browser_recipe: inspecciona una receta de confianza, su resultado de validación y firma.

• audit_browser_recipes: valida y genera huellas digitales del catálogo de confianza.

• list_browser_recipe_coverage: lista rutas verificadas, API, masivas, de desafío y bloqueadas.

• record_browser_recipe_observation: almacena un candidato estructural saneado.

• list_browser_recipe_candidates: inspecciona candidatos pendientes de confirmación o revisión.

• get_state_access y list_state_access: inspecciona límites de enrutamiento y políticas.

• screen_regulatory: verifica nombres de empresas y personas contra conjuntos de datos regulatorios oficiales seleccionados.

• list_regulatory_sources: inspecciona cada fuente regulatoria, cobertura de sujetos y requisito de acceso.

• investigate_subjects: construye una investigación normalizada de personas/empresas, opcionalmente ejecutando comprobaciones regulatorias y de registros estatales y derivando correlaciones respaldadas.

Biblioteca JavaScript

import {
  buildInvestigationReport,
  createBrowserSearchPlan,
  getRecipeRecord,
  investigateSubjects,
  listRegulatorySources,
  normalizeRecord,
  screenRegulatory,
  searchBusiness,
} from "public-risk-intelligence-mcp";

const plan = createBrowserSearchPlan({
  state: "TN",
  query: "Microsoft Corporation",
});

const recipe = getRecipeRecord("TN");
const sources = listRegulatorySources();
const screening = await screenRegulatory({
  companyName: "Example Company LLC",
  personName: "Example Person",
});
const investigation = await investigateSubjects({
  companyName: "Example Company LLC",
  personName: "Example Person",
  state: "CO",
  relationship: "reported_owner",
  purpose: "counterparty_due_diligence",
  runRegistry: true,
});
for (const correlation of investigation.analysis.correlations) {
  console.log(correlation.title, correlation.subjectIds, correlation.basisEvidenceIds);
}
const normalized = normalizeRecord({
  fields: {
    "Control No.": "000000000",
    Name: "EXAMPLE CORPORATION",
    Status: "Active",
    "Formed In": "TENNESSEE",
  },
});

Salida normalizada

Los resultados de fuentes de registros y regulatorias conservan schemaVersion: "1.0". Los informes de investigación usan por defecto schemaVersion: "2.0", que añade correlaciones acotadas respaldadas por evidencia. Los llamadores de biblioteca y MCP pueden solicitar outputSchemaVersion: "1.0" o output_schema_version: "1.0" al consumir el contrato estricto de informe heredado.

El esquema JSON de resultados de registros está en schemas/normalized-result.schema.json. El esquema actual de investigación de personas/empresas está en schemas/investigation-report.schema.json; el contrato estricto heredado retenido está en schemas/investigation-report-v1.schema.json.

Correlaciones de riesgo respaldadas por evidencia

La capa de investigación puede correlacionar hechos y relaciones verificados entre distintos sujetos. Los tipos de correlación admitidos son:

• shared_identifier_across_subjects: dos o más sujetos fuertemente atribuidos comparten una dirección verificada, agente registrado, teléfono, correo electrónico, dominio, referencia de cuenta bancaria o hecho de beneficiario;

• multiple_company_affiliations: una persona tiene relaciones verificadas y respaldadas por evidencia con múltiples empresas;

• repeated_adverse_company_statuses: una persona tiene relaciones verificadas con múltiples empresas con estados adversos oficiales de registro o licencia fuertemente atribuidos.

Cada correlación contiene IDs de sujetos, evidencia de respaldo y/o IDs de relaciones, confianza de identidad strong o confirmed, y una limitación que describe alternativas benignas. Las correlaciones de hechos compartidos añaden una huella digital SHA-256 y rutas de evidencia/hechos para que los investigadores distingan el hecho coincidente sin exponer valores brutos de cuentas bancarias. Se excluyen valores centinela, enmascarados, parciales y de baja información. La salida se limita determinísticamente a 500 correlaciones y analysis.correlationSummary informa cualquier truncamiento.

Las correlaciones de afiliación usan solo estos tipos de relación: owner, reported_owner, beneficial_owner, member, manager, director, officer, founder, partner, principal, shareholder, employee, authorized_person y registered_agent. Cada relación verificada debe citar un elemento de evidencia de relación verificado y fuertemente atribuido cuyos hechos contengan explícitamente valores compatibles de fromSubjectId, toSubjectId y relationshipType. Otros tipos de relación permanecen en el expediente pero no crean correlaciones de afiliación.

Los detalles compartidos pueden reflejar un proveedor de servicios, hogar, sitio de coworking, reasignación, cierre ordinario, reestructuración o datos obsoletos. Por lo tanto, una correlación es una pista de revisión trazable, no prueba de control común, robo de identidad, fraude, lavado de dinero o mala conducta. Los investigadores deben revisar los registros fuente, fechas, roles, atributos de identidad y explicaciones alternativas antes de usarla en cualquier decisión.

Límites de acceso

Los sitios estatales y los términos cambian. El proyecto lo registra explícitamente:

• manual_challenge_required significa que la verificación humana impidió la finalización; no se intentó ningún bypass.

• automation_blocked significa que la política publicada o el límite de acceso actual prohíbe la ruta interactiva.

• no_matches_or_unparsed significa que el navegador no produjo filas normalizadas; no es una declaración definitiva de que la empresa no existe.

Los resultados de registros son informativos. No son certificados de buena reputación, conclusiones legales ni evidencia suficiente para una decisión de riesgo adversa.

Las coincidencias regulatorias son solo pistas de cribado por nombre hasta que se revisen los campos de identificación y el registro oficial. Ninguna coincidencia en una instantánea verificada no es una autorización.

Contribuciones

Lee CONTRIBUTING.md antes de añadir una fuente o receta. Nunca comprometas credenciales, artefactos de sesión, resultados de investigación personales ni bypass de CAPTCHA.

npm run ci

Licencia

MIT