Public Risk Intelligence MCP

Открытый набор инструментов для сбора публичных доказательств, разрешения сущностей и корреляции рисков, предназначенный для исследования компаний, людей и их связей. Он объединяет официальные реестры бизнеса штатов США, отдельные бесплатные регуляторные наборы данных, сбор доказательств с помощью браузера, CLI, MCP-сервер для ИИ-агентов и переиспользуемую JavaScript-библиотеку в нормализованные досье расследований.

Проект предпочитает бесплатный официальный API, если он доступен. В противном случае он предоставляет MCP-клиенту версионированный рецепт браузера для существующей сессии Chrome пользователя, собирает публичные доказательства из реестра и нормализует каждый источник к одному и тому же контракту результатов. Для сайтов, которые принимают новый профиль браузера, также доступно прямое выполнение Playwright.

Он не подает документы, не покупает сертификаты, не обходит CAPTCHA, не получает доступ к учетным данным браузера и не превращает данные реестров, проверки имен или корреляции в вердикт о мошенничестве, определение AML, неблагоприятное решение или допуск.

Текущее покрытие

• 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 предпочтителен для защищенных реестров

Некоторые реестры, включая Теннесси во время живой проверки 26 августа 2026 года, отклоняли недавно запущенный автоматизированный профиль, но работали в существующей сессии 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; это не вердикт о мошенничестве, определение AML или допуск.

Подключение через локальный порт отладки Chrome

CLI может подключаться к экземпляру Chrome, который открывает локальный порт DevTools. Соединения ограничены хостами loopback, и CLI открывает и закрывает только свою собственную страницу.

Chrome должен быть запущен с портом отладки до того, как CLI сможет подключиться; 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-схема результата реестра находится в 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: у человека есть проверенные связи с несколькими компаниями, имеющими сильно атрибутированные неблагоприятные официальные статусы реестра или лицензии.

Каждая корреляция содержит идентификаторы субъектов, подтверждающие доказательства и/или идентификаторы связей, уверенность в идентичности strong или confirmed и ограничение, описывающее безобидные альтернативы. Корреляции общих фактов добавляют SHA-256 отпечаток и пути доказательств/фактов, чтобы исследователи могли различить совпавший факт без раскрытия сырых значений банковских счетов. Значения Sentinel, маскированные, частичные и с низкой информативностью исключаются. Вывод детерминированно ограничен 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