Public Risk Intelligence MCP

공개 증거 수집, 개체 식별, 위험 상관관계 분석을 위한 오픈소스 도구로, 기업, 인물 및 그들의 연관 관계를 조사하기 위해 설계되었습니다. 미국 주정부 사업자 등록부, 선별된 무료 규제 데이터셋, 브라우저 지원 증거 수집, CLI, AI 에이전트용 MCP 서버, 재사용 가능한 JavaScript 라이브러리를 결합하여 표준화된 조사 도큐먼트를 생성합니다.

이 프로젝트는 공식 무료 API가 제공되는 경우 이를 우선 사용합니다. 그렇지 않은 경우 MCP 클라이언트에 사용자의 기존 Chrome 세션을 활용하는 버전 관리된 브라우저 레시피를 제공하고, 공개 등록부 증거를 캡처한 후 모든 소스를 동일한 결과 계약으로 표준화합니다. 새로운 브라우저 프로필을 허용하는 사이트의 경우 직접 Playwright 실행도 가능합니다.

이 도구는 문서를 제출하거나, 증명서를 구매하거나, CAPTCHA를 우회하거나, 브라우저 자격 증명에 접근하거나, 등록부·이름 스크리닝·상관관계 증거를 사기 판정, AML 판정, 불리한 결정 또는 승인으로 전환하지 않습니다.

현재 적용 범위

• 라이브 검증된 Playwright 브라우저 레시피 35개

• 공식 API 경로 4개

• 공식 벌크 또는 내보내기 경로 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로 표시됩니다. 이는 사기 판정, AML 판정 또는 승인이 아닙니다.

로컬 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