Public Risk Intelligence MCP

一个开源的公共证据收集、实体解析和风险关联工具包，用于研究公司、个人及其关联关系。它将美国各州官方商业登记、选定的免费监管数据集、浏览器辅助证据收集、CLI、面向 AI 代理的 MCP 服务器以及可复用的 JavaScript 库整合为规范化的调查档案。

该项目在可用时优先使用免费的官方 API。否则，它会为 MCP 客户端提供针对用户现有 Chrome 会话的版本化浏览器配方，捕获公共登记证据，并将每个来源规范化为相同的结果契约。对于接受新浏览器配置文件的站点，也提供直接的 Playwright 执行。

它不提交文件、购买证书、绕过 CAPTCHA、访问浏览器凭据，也不会将登记、名称筛查或关联证据转化为欺诈判决、反洗钱裁定、不利决定或许可。

当前覆盖范围

• 35 个经实时验证的 Playwright 浏览器配方

• 4 条官方 API 路由

• 2 条官方批量或导出路由

• 6 个人工验证边界

• 4 条交互式自动化阻止路由

• 0 个未映射的司法管辖区

• 3 个匿名官方监管数据集：OFAC SDN、HHS OIG LEIE 和 SEC 公司关联

• 1 个已编目的免费带密钥来源：SAM.gov 排除项

• 1 个规范化的人员/公司调查层，具有证据来源、实体解析、关系、矛盾、覆盖缺口、有界审查信号和基于证据的跨实体关联

运行 npm run audit:recipes 获取机器可读的当前目录和配方签名。

工作原理

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

受信任的配方包含精确的字段、按钮、可选的提交前操作、结果行选择器、列映射和安全详情行为。当已知选择器发生变化时，配方引擎返回 RECIPE_DRIFT_DETECTED 而不是猜测。新观察结果会保留在候选存储中，直到出现两个匹配的观察结果并通过人工审查。

参见 架构、主机浏览器协议、阻止路由替代方案、配方格式、规范化结果、免费监管筛查 和 调查案例。

安装

要求：Node.js 20 或更高版本，以及用于浏览器路由的 Chrome 或 Chromium。

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

作为包安装时，public-risk-intelligence 是主要命令。旧版 sos-research 命令仍然是等效的兼容别名。

浏览器启动始终通过 --browser 选择启用。仅对不需要可见人工验证的来源使用 --headless。

受保护登记处优先使用现有 Chrome

某些登记处（包括 2026 年 8 月 26 日实时验证期间的田纳西州）会挑战新启动的自动化配置文件，但在用户现有的 Chrome 会话中正常工作。对于这些站点，请使用 MCP 配对：

1. prepare_browser_search 返回官方 URL、签名配方和精确控件。

2. MCP 客户端操作其已连接的 Chrome 浏览器。

3. finalize_browser_search 验证主机并规范化公共行。

4. build_investigation_report 将该规范化结果与主体、报告的关系、监管筛查结果、其他归因证据和计划检查相结合。

如果登记处要求人工验证，客户端应提示用户，暂停，并在用户完成后恢复。如果等待窗口过期，规范化响应使用 status: "manual_challenge_required" 和结构化的 humanIntervention 对象。不会尝试绕过 CAPTCHA 或安全措施。

提供给组合工具的证据被视为不可信的、来源归因的输入。其报告始终标记为 human_review_only；它不是欺诈判决、反洗钱裁定或许可。

通过本地 Chrome 调试端口附加

CLI 可以附加到暴露本地 DevTools 端口的 Chrome 实例。连接仅限于回环主机，CLI 仅打开和关闭自己的页面。

在 CLI 可以附加之前，必须使用调试端口启动 Chrome；Playwright 无法附加到任意现有的 Chrome 进程。在 macOS 上启动专用的持久配置文件：

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

然后运行：

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

您还可以设置 SOS_CHROME_PATH 或 SOS_CHROME_CDP_URL；请参阅 .env.example。这些旧版环境变量名称仍然受支持，以避免破坏现有安装。此 CDP 路由是可选的——主机浏览器 MCP 协议是可移植的现有浏览器集成。

MCP 服务器

使用以下命令启动 stdio 服务器：

npm run start:mcp

Codex 配置：

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

Claude Code 配置：

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

现有的 MCP 客户端配置可以保留其本地分配的 sos-research 别名；服务器现在标识为 public-risk-intelligence，并保持所有现有工具名称兼容。

工具：

• search_business：执行官方 API 或明确授权的本地浏览器搜索。

• prepare_browser_search：为主机代理的浏览器返回官方 URL 和精确配方。

• finalize_browser_search：验证官方主机并规范化浏览器观察到的行。

• build_investigation_report：将规范化的登记和监管结果与提供的主体、关系、证据、计划检查和基于证据的关联组合起来。

• get_browser_recipe：检查一个受信任的配方、验证结果和签名。

• audit_browser_recipes：验证并指纹识别受信任的目录。

• list_browser_recipe_coverage：列出已验证、API、批量、挑战和阻止的路由。

• record_browser_recipe_observation：存储经过净化的结构候选。

• list_browser_recipe_candidates：检查等待确认或审查的候选。

• get_state_access 和 list_state_access：检查路由和政策边界。

• screen_regulatory：根据选定的官方监管数据集检查公司和人员名称。

• list_regulatory_sources：检查每个监管来源、主体覆盖范围和访问要求。

• investigate_subjects：构建规范化的人员/公司调查，可选地运行监管和州登记检查并推导支持的关联。

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

规范化输出

登记和监管来源结果保留 schemaVersion: "1.0"。调查报告默认使用 schemaVersion: "2.0"，它增加了有界的基于证据的关联。库和 MCP 调用方在消费严格旧版报告契约时可以请求 outputSchemaVersion: "1.0" 或 output_schema_version: "1.0"。

登记结果的 JSON Schema 位于 schemas/normalized-result.schema.json。当前的人员/公司调查模式位于 schemas/investigation-report.schema.json；保留的严格旧版契约位于 schemas/investigation-report-v1.schema.json。

基于证据的风险关联

调查层可以关联不同主体之间的已验证事实和关系。支持的关联类型包括：

• shared_identifier_across_subjects：两个或更多强归因主体共享已验证的地址、注册代理、电话、电子邮件、域名、银行账户引用或受益人事实；

• multiple_company_affiliations：一个人与多家公司存在基于证据的已验证关系；

• repeated_adverse_company_statuses：一个人与多家具有强归因不利官方登记或许可状态的公司存在已验证关系。

每个关联都包含主体 ID、支持证据和/或关系 ID、strong 或 confirmed 身份置信度，以及描述良性替代方案的限制。共享事实关联添加 SHA-256 指纹和证据/事实路径，以便调查人员区分匹配的事实，而不会暴露原始银行账户值。哨兵值、掩码值、部分值和低信息值被排除。输出被确定性限制为 500 个关联，analysis.correlationSummary 报告任何截断。

关联关联仅使用以下关系类型：owner、reported_owner、beneficial_owner、member、manager、director、officer、founder、partner、principal、shareholder、employee、authorized_person 和 registered_agent。每个已验证关系必须引用一个已验证的、强归因的关系证据项，其事实明确包含兼容的 fromSubjectId、toSubjectId 和 relationshipType 值。其他关系类型保留在档案中，但不会创建关联关联。

共享细节可能反映服务提供商、家庭、共享办公场所、重新分配、普通关闭、重组或过时数据。因此，关联是可追溯的审查线索——而不是共同控制、身份盗用、欺诈、洗钱或不当行为的证明。调查人员必须在任何决策中使用之前审查源记录、日期、角色、身份属性和替代解释。

访问边界

州网站和条款会变化。项目明确记录这些：

• manual_challenge_required 表示人工验证阻止了完成；未尝试绕过。

• automation_blocked 表示已发布的政策或当前访问边界禁止交互式路由。

• no_matches_or_unparsed 表示浏览器未产生规范化行；这不是公司不存在的确定性声明。

登记结果仅供参考。它们不是良好信誉证明、法律结论或不利风险决策的充分证据。

监管匹配仅是名称筛查线索，直到审查了识别字段和官方记录。在已检查的快照中没有匹配并不构成许可。

贡献

在添加来源或配方之前，请阅读 CONTRIBUTING.md。切勿提交凭据、会话工件、个人调查结果或 CAPTCHA 绕过。

npm run ci

许可证

MIT