Public Risk Intelligence MCP

Ein Open-Source-Toolkit zur Sammlung öffentlicher Beweise, Entitätsauflösung und Risikokorrelation für die Recherche zu Unternehmen, Personen und deren Verbindungen. Es kombiniert offizielle US-Bundesstaats-Register, ausgewählte kostenlose Regulierungsdatensätze, browserunterstützte Beweissammlung, eine CLI, einen MCP-Server für KI-Agenten und eine wiederverwendbare JavaScript-Bibliothek zu normalisierten Ermittlungsdossiers.

Das Projekt bevorzugt eine kostenlose offizielle API, sofern verfügbar. Andernfalls stellt es einem MCP-Client ein versioniertes Browser-Rezept für die bestehende Chrome-Sitzung des Benutzers bereit, erfasst öffentliche Registerbeweise und normalisiert jede Quelle auf denselben Ergebnisvertrag. Direkte Playwright-Ausführung ist auch für Websites verfügbar, die ein neues Browserprofil akzeptieren.

Es reicht keine Dokumente ein, kauft keine Zertifikate, umgeht kein CAPTCHA, greift nicht auf Browser-Anmeldedaten zu und wandelt Register-, Namens-Screening- oder Korrelationsbeweise nicht in ein Betrugsurteil, eine AML-Entscheidung, eine nachteilige Entscheidung oder eine Freigabe um.

Aktuelle Abdeckung

• 35 live verifizierte Playwright-Browserrezepte

• 4 offizielle API-Routen

• 2 offizielle Bulk- oder Export-Routen

• 6 Grenzen für menschliche Verifizierung

• 4 interaktive automatisierungsblockierte Routen

• 0 nicht zugeordnete Gerichtsbarkeiten

• 3 anonyme offizielle Regulierungsdatensätze: OFAC SDN, HHS OIG LEIE und SEC-Unternehmensverbindungen

• 1 katalogisierte kostenlose Quelle mit Schlüssel: SAM.gov-Ausschlüsse

• 1 normalisierte Personen-/Unternehmens-Ermittlungsebene mit Beweisherkunft, Entitätsauflösung, Beziehungen, Widersprüchen, Abdeckungslücken, begrenzten Überprüfungssignalen und beweisgestützten unternehmensübergreifenden Korrelationen

Führen Sie npm run audit:recipes aus, um den maschinenlesbaren aktuellen Katalog und die Rezeptsignaturen zu erhalten.

So funktioniert es

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

Vertrauenswürdige Rezepte enthalten exakte Felder, Schaltflächen, optionale Aktionen vor dem Absenden, Ergebniszeilen-Selektoren, Spaltenzuordnungen und sicheres Detailverhalten. Wenn sich ein bekannter Selektor ändert, gibt die Rezept-Engine RECIPE_DRIFT_DETECTED zurück, anstatt zu raten. Neue Beobachtungen bleiben in einem Kandidatenspeicher, bis zwei übereinstimmende Beobachtungen und eine menschliche Überprüfung vorliegen.

Siehe Architektur, Host-Browser-Protokoll, Alternativen für blockierte Routen, Rezeptformat, Normalisierte Ergebnisse, Kostenloses regulatorisches Screening und Ermittlungsfälle.

Installation

Anforderungen: Node.js 20 oder neuer und Chrome oder Chromium für Browser-Routen.

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

Wenn als Paket installiert, ist public-risk-intelligence der primäre Befehl. Der Legacy-Befehl sos-research bleibt ein gleichwertiger Kompatibilitäts-Alias.

Der Browserstart ist immer optional mit --browser. Verwenden Sie --headless nur für eine Quelle, die keine sichtbare menschliche Verifizierung erfordert.

Bestehendes Chrome wird für geschützte Register bevorzugt

Einige Register, darunter Tennessee während der Live-Verifizierung am 26. August 2026, stellten ein neu gestartetes automatisiertes Profil in Frage, funktionierten jedoch in der bestehenden Chrome-Sitzung des Benutzers. Verwenden Sie für diese Websites das MCP-Paar:

1. prepare_browser_search gibt die offizielle URL, das signierte Rezept und die exakten Steuerelemente zurück.

2. Der MCP-Client bedient seinen bereits verbundenen Chrome-Browser.

3. finalize_browser_search validiert den Host und normalisiert die öffentlichen Zeilen.

4. build_investigation_report kombiniert dieses normalisierte Ergebnis mit Subjekten, gemeldeten Beziehungen, regulatorischen Screening-Ergebnissen, anderen zugeordneten Beweisen und geplanten Prüfungen.

Wenn das Register eine menschliche Verifizierung anfordert, sollte der Client den Benutzer auffordern, pausieren und nach Abschluss durch den Benutzer fortfahren. Die normalisierte Antwort verwendet status: "manual_challenge_required" und ein strukturiertes humanIntervention-Objekt, wenn das Wartefenster abläuft. Es wird kein CAPTCHA- oder Sicherheits-Bypass versucht.

Beweise, die dem Kompositionstool bereitgestellt werden, werden als nicht vertrauenswürdige, quellenattribuierte Eingabe behandelt. Sein Bericht ist immer als human_review_only gekennzeichnet; er ist kein Betrugsurteil, keine AML-Entscheidung oder Freigabe.

Über einen lokalen Chrome-Debugging-Port anhängen

Die CLI kann an eine Chrome-Instanz anhängen, die einen lokalen DevTools-Port bereitstellt. Verbindungen sind auf Loopback-Hosts beschränkt, und die CLI öffnet und schließt nur ihre eigene Seite.

Chrome muss mit einem Debugging-Port gestartet werden, bevor die CLI anhängen kann; Playwright kann nicht an einen beliebigen vorhandenen Chrome-Prozess anhängen. Starten Sie ein dediziertes persistentes Profil unter macOS:

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

Dann führen Sie aus:

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

Sie können auch SOS_CHROME_PATH oder SOS_CHROME_CDP_URL festlegen; siehe .env.example. Diese Legacy-Umgebungsvariablennamen bleiben unterstützt, um bestehende Installationen nicht zu brechen. Diese CDP-Route ist optional – das Host-Browser-MCP-Protokoll ist die portable Integration für bestehende Browser.

MCP-Server

Starten Sie den Stdio-Server mit:

npm run start:mcp

Codex-Konfiguration:

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

Claude-Code-Konfiguration:

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

Bestehende MCP-Client-Konfigurationen können ihren lokal zugewiesenen Alias sos-research behalten; der Server identifiziert sich jetzt als public-risk-intelligence und hält alle vorhandenen Toolnamen kompatibel.

Tools:

• search_business: führt eine offizielle API oder eine ausdrücklich autorisierte lokale Browsersuche aus.

• prepare_browser_search: gibt die offizielle URL und das exakte Rezept für den Browser eines Host-Agenten zurück.

• finalize_browser_search: validiert den offiziellen Host und normalisiert im Browser beobachtete Zeilen.

• build_investigation_report: erstellt einen normalisierten Bericht aus Register- und Regulierungsergebnissen mit gelieferten Subjekten, Beziehungen, Beweisen, geplanten Prüfungen und beweisgestützten Korrelationen.

• get_browser_recipe: untersucht ein vertrauenswürdiges Rezept, Validierungsergebnis und Signatur.

• audit_browser_recipes: validiert und erstellt Fingerabdrücke des vertrauenswürdigen Katalogs.

• list_browser_recipe_coverage: listet verifizierte, API-, Bulk-, Challenge- und blockierte Routen auf.

• record_browser_recipe_observation: speichert einen bereinigten strukturellen Kandidaten.

• list_browser_recipe_candidates: untersucht Kandidaten, die auf Bestätigung oder Überprüfung warten.

• get_state_access und list_state_access: untersucht Routing- und Richtliniengrenzen.

• screen_regulatory: prüft Unternehmens- und Personennamen gegen ausgewählte offizielle Regulierungsdatensätze.

• list_regulatory_sources: untersucht jede Regulierungsquelle, Subjektabdeckung und Zugriffsanforderung.

• investigate_subjects: erstellt eine normalisierte Personen-/Unternehmens-Ermittlung, optional mit regulatorischen und staatlichen Registerprüfungen und abgeleiteten unterstützten Korrelationen.

JavaScript-Bibliothek

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",
  },
});

Normalisierte Ausgabe

Register- und Regulierungsquellenergebnisse behalten schemaVersion: "1.0". Ermittlungsberichte standardmäßig auf schemaVersion: "2.0", das begrenzte beweisgestützte Korrelationen hinzufügt. Bibliotheks- und MCP-Aufrufer können outputSchemaVersion: "1.0" oder output_schema_version: "1.0" anfordern, wenn sie den strengen Legacy-Berichtsvertrag verwenden.

Das JSON-Schema für Registerergebnisse befindet sich unter schemas/normalized-result.schema.json. Das aktuelle Personen-/Unternehmens-Ermittlungsschema befindet sich unter schemas/investigation-report.schema.json; der beibehaltene strenge Legacy-Vertrag befindet sich unter schemas/investigation-report-v1.schema.json.

Beweisgestützte Risikokorrelationen

Die Ermittlungsebene kann verifizierte Fakten und Beziehungen über verschiedene Subjekte hinweg korrelieren. Unterstützte Korrelationstypen sind:

• shared_identifier_across_subjects: zwei oder mehr stark attribuierte Subjekte teilen eine verifizierte Adresse, einen registrierten Agenten, Telefon, E-Mail, Domain, Bankkontoreferenz oder Begünstigtenfakt;

• multiple_company_affiliations: eine Person hat beweisgestützte, verifizierte Beziehungen zu mehreren Unternehmen;

• repeated_adverse_company_statuses: eine Person hat verifizierte Beziehungen zu mehreren Unternehmen mit stark attribuierten nachteiligen offiziellen Register- oder Lizenzstatus.

Jede Korrelation enthält Subjekt-IDs, unterstützende Beweis- und/oder Beziehungs-IDs, strong oder confirmed Identitätsvertrauen und eine Einschränkung, die harmlose Alternativen beschreibt. Gemeinsame Faktenkorrelationen fügen einen SHA-256-Fingerabdruck und Beweis-/Faktpfade hinzu, damit Ermittler den übereinstimmenden Fakt unterscheiden können, ohne rohe Bankkontowerte offenzulegen. Sentinel-, maskierte, partielle und informationsarme Werte werden ausgeschlossen. Die Ausgabe ist deterministisch auf 500 Korrelationen begrenzt, und analysis.correlationSummary meldet jede Kürzung.

Affiliationskorrelationen verwenden nur diese Beziehungstypen: owner, reported_owner, beneficial_owner, member, manager, director, officer, founder, partner, principal, shareholder, employee, authorized_person und registered_agent. Jede verifizierte Beziehung muss ein verifiziertes, stark attribuiertes Beziehungsbeweiselement zitieren, dessen Fakten explizit kompatible fromSubjectId, toSubjectId und relationshipType-Werte enthalten. Andere Beziehungstypen bleiben im Dossier, erzeugen jedoch keine Affiliationskorrelationen.

Gemeinsame Details können einen Dienstleister, Haushalt, Coworking-Standort, Neuzuweisung, gewöhnliche Schließung, Umstrukturierung oder veraltete Daten widerspiegeln. Eine Korrelation ist daher ein nachvollziehbarer Überprüfungshinweis – kein Beweis für gemeinsame Kontrolle, Identitätsdiebstahl, Betrug, Geldwäsche oder Fehlverhalten. Ermittler müssen Quelldatensätze, Daten, Rollen, Identitätsattribute und alternative Erklärungen überprüfen, bevor sie sie in einer Entscheidung verwenden.

Zugriffsgrenzen

Staatliche Websites und Bedingungen ändern sich. Das Projekt dokumentiert dies explizit:

• manual_challenge_required bedeutet, dass menschliche Verifizierung den Abschluss verhinderte; kein Bypass wurde versucht.

• automation_blocked bedeutet, dass die veröffentlichte Richtlinie oder die aktuelle Zugriffsgrenze die interaktive Route verbietet.

• no_matches_or_unparsed bedeutet, dass der Browser keine normalisierten Zeilen erzeugte; es ist keine endgültige Aussage, dass das Unternehmen nicht existiert.

Registerergebnisse sind informativ. Sie sind keine Bescheinigungen über den guten Ruf, keine rechtlichen Schlussfolgerungen oder ausreichende Beweise für eine nachteilige Risikoentscheidung.

Regulierungsübereinstimmungen sind nur Namens-Screening-Hinweise, bis identifizierende Felder und der offizielle Datensatz überprüft sind. Keine Übereinstimmung in einem geprüften Schnappschuss ist keine Freigabe.

Mitwirken

Lesen Sie CONTRIBUTING.md, bevor Sie eine Quelle oder ein Rezept hinzufügen. Committen Sie niemals Anmeldedaten, Sitzungsartefakte, persönliche Ermittlungsergebnisse oder CAPTCHA-Bypässe.

npm run ci

Lizenz

MIT