Occulytics MCP Server

헬스케어 REIT 자산운용팀(Omega Healthcare Investors)을 위해 AI 어시스턴트가 포트폴리오 질문에 답할 수 있게 해주는 MCP 서버로, 두 가지 공개 소스(Omega의 SEC 10-K 보고서와 CMS Nursing Home Provider Information 파일)에 근거합니다.

브리프에 따른 설계 목표: 서버는 아무 근거도 없는 확신에 찬 숫자를 만들어 내는 대신, 답변이 완전함, 불확실함, 또는 근거 없음 — 그리고 그 이유를 말할 수 있어야 합니다. 모든 도구는 계산된 상태, 주의사항, 출처 정보를 담은 봉투(envelope) 안에 결정적(deterministic) 데이터를 반환합니다.

빠른 시작

모든 것이 오프라인으로 실행됩니다 — 데이터 아티팩트는 커밋되어 있습니다.

npm install
npm run build
npm test          # 41 tests: curated-data checksums, domain units, full e2e over MCP

UI에서 사용해 보기(MCP Inspector가 브라우저에서 열립니다):

npm run inspect

Claude Code에 연결: 프로젝트 범위의 .mcp.json이 포함되어 있습니다 — npm run build 후 Claude Code에서 이 저장소를 열면 occulytics 서버를 사용할 수 있습니다. 또는 전역으로 등록하세요:

claude mcp add occulytics -- node /absolute/path/to/occulytics-mcp/dist/src/server/index.js

Claude Desktop에 연결(claude_desktop_config.json):

{
  "mcpServers": {
    "occulytics": {
      "command": "node",
      "args": ["/absolute/path/to/occulytics-mcp/dist/src/server/index.js"]
    }
  }
}

데모 전에 컴파일된 서버가 실제 stdio에서 작동하는지 확인: npm run smoke. 실시간 소스에서 데이터를 새로 고치려면: npm run ingest (데이터 파이프라인 참조).

Related MCP server: Medical Billing MCP

무엇을 물어볼 수 있나

다섯 가지 대상 질문과 서버가 실제로 수행하는 작업:

아키텍처

세 계층, 단일 의존성 방향, 데이터베이스 없음, 런타임 네트워크 없음:

scripts/ingest.ts      CMS download → validate → project → data/processed/*.json  (committed)
data/curated/*.json    Hand-transcribed 10-K facts + operator→CMS map, per-fact citations
        │
src/domain/            Pure, deterministic, unit-tested: store, resolve, metrics
        │
src/server/            MCP wiring: 9 tools + 1 resource → envelope responses (stdio)

• data/curated/omega-10k.json — FY2025 포트폴리오 요약 + 집중도 메모, FY2020 운영사 투자 표. 모든 블록은 해당 보고서/섹션을 인용합니다.

• data/curated/operator-map.json — 정직성의 중추: 각 Omega 운영사의 CMS 매핑과 method(체인 정확 / 법적 이름 패턴 / 큐레이션된 별칭), confidence(높음/중간/낮음), 주의사항; 매핑 불가한 운영사는 그 이유를 기록합니다.

• src/domain/metrics.ts — 모든 산술 연산: 순위, 점유율, 벤치마크 비교, 상수 패널 별점 추세. 어떤 숫자도 모델에 맡기지 않습니다.

• src/server/tools.ts — 얇은 계층: 입력 검증(zod), 도메인 호출, 봉투로 감싸기.

답변 봉투(Envelope)

모든 도구가 반환하는 것:

{
  "status": "complete" | "partial" | "unsupported",   // brief's complete / uncertain / unsupported
  "data": { /* deterministic numbers & records, never prose */ },
  "caveats": [ /* why partial; staleness; method notes — computed, not decorative */ ],
  "provenance": [ { "source", "asOf", "detail", "url" } ],
  "cost": { "chars", "estTokens", "basis" }   // self-reported payload size, labeled estimate
}

status는 하드코딩이 아니라 데이터 경로에서 계산됩니다: 매핑되지 않은 운영사는 매핑 항목에 기록된 이유와 함께 unsupported를 산출하고, FY2020 표와 관련된 모든 것은 오래됨 주의사항과 함께 partial이며, 점유율 프록시는 항상 partial입니다.

도구 표면

세분화 근거: 도구는 질문 형태로 만들어졌지만 구성 가능합니다 — 결정적 집계(100개 이상의 행에 대한 LLM 산술이 정확성 위험이 되는 경우)는 도구의 책임이고, 서술적 종합은 모델의 책임입니다. 운영사를 받는 모든 도구는 자유 텍스트를 받아 내부적으로 해석하므로 클라이언트가 2단계 프로토콜을 필요로 하지 않습니다; 해석 실패는 오류가 아니라 unsupported 답변(후보와 알려진 전체 집합 포함)입니다.

교차 소스 질문(10-K 부분 ↔ CMS 부분)은 일급 시민입니다: 운영사 정체성이 조인 키이며 왕복 검증됩니다(10-K 순위의 모든 이름이 모든 CMS 기반 도구에서 해석됨 — e2e 테스트됨), 그리고 모든 해석된 운영사 블록에는 10-K 맥락(omegaContext: FY2020 순위와 포트폴리오 비중, FY2025 공개 집중도)이 내장되어 있어 "우리 최대 운영사는 얼마나 좋은가?" 같은 질문이 두 번째 호출 없이 해결됩니다.

주요 결정 및 트레이드오프

1. 두 빈티지, 절대 혼합하지 않음. 결정적 연구 발견: Omega의 FY2020 이후 10-K에는 운영사별 투자 표가 없습니다 — FY2025 보고서는 Maplewood(투자 비중 ≥10%)와 CommuniCare(7.2%)만 명시합니다. 따라서 현재 "상위 5개"는 명시된 소스만으로는 완전히 뒷받침될 수 없으며, 서버는 정확히 그렇게 말합니다: 순위는 별도로 날짜가 표시된 두 블록으로 제공되고 상태는 이유와 함께 partial입니다. 트레이드오프: 하나의 깔끔한 목록보다 덜 만족스럽지만, 혼합된 목록은 수치적으로 모순되기 때문입니다(2020년 달러 vs 2025년 백분율, 서로 다른 분모).

2. 수기로 큐레이션된 SEC 사실, 기계로 수집된 CMS 데이터. Omega 사실은 서로 다른 형식의 두 보고서에 있는 두 표에 걸친 약 30개의 숫자입니다. 이 범위에서 일반적인 10-K 파서는 이 브리프에 가능한 최악의 실패 모드를 가집니다 — 조용히 잘못된 추출. 대신: 사실별 인용이 있는 큐레이션된 JSON, 체크섬 테스트로 보호됩니다(모든 합산 가능한 열은 보고서 자체의 소계와 합계를 재현해야 함 — 오타 하나가 빌드를 실패시킵니다). CMS 측(14,693행 × 3개 월별 빈티지)은 검증과 함께 완전 자동화되어 있습니다. 규모상 자동화가 더 안전한 선택이기 때문입니다. 트레이드오프: 새 10-K에 대한 새로 고침은 수동 편집입니다; 연간 제출 문서에 대해서는 수용된 선택입니다.

3. 운영사→CMS 조인은 큐레이션되고 신뢰도가 태그된 아티팩트입니다. 두 데이터셋 모두 서로를 참조하지 않습니다. 조인(10-K 운영사 이름 → CMS 체인)은 시스템에서 가장 위험한 추론이므로 코드가 아닌 데이터입니다: 각 매핑은 어떻게 만들어졌고 얼마나 신뢰할 수 있는지 기록하며, 매핑 불가한 운영사는 이유를 기록합니다(Maplewood: 시니어 리빙, CMS 범위 밖; Healthcare Homes: 영국). 낮은 신뢰도 매핑(Agemo → Signature)은 기본적으로 통합 집계에서 제외되고 포함 시 표면화됩니다. 트레이드오프: 수백 개의 REIT로 확장되지는 않습니다; 한 REIT의 약 11개 명시된 운영사에는 정확하며, 메커니즘(매핑별 method/confidence/caveat)이 확장 가능한 부분입니다.

4. 체인 지표는 상위 집합이며 그렇게 명시합니다. Omega의 시설 수준 포트폴리오는 공개되지 않습니다(검증됨: Schedule III는 주별로 집계). 따라서 CMS 지표는 Omega 건물만이 아니라 운영사의 전체 운영을 설명합니다 — 영향을 받는 모든 응답은 그 주의사항을 담고, 점유율 프록시는 커버리지가 (FY2020) 포트폴리오의 어느 비중을 대표하는지 보고합니다(약 40%). 트레이드오프: CMS Ownership 파일에서 시설 수준 재구성이 가능했지만 며칠이 걸리는 퍼지 매칭 작업입니다; 커버리지 회계가 있는 정직한 프록시가 4시간짜리 답변입니다. 그 재구성이 자연스러운 다음 단계입니다.

5. 방법론도 답의 일부입니다. 별점 추세 = 고정 패널(두 엔드포인트 스냅샷 모두에서 평가된 시설), 패널 크기, 제외 기준, 그리고 알려진 편향(체인 소속은 현재 시점 기준)이 응답에 포함됩니다. 인력 벤치마크 = 보고된 총 간호사 HPRD, 시설 평균(질문이 묻는 그대로, 보정되지 않음; 케이스믹스 보정값도 존재하며 그렇게 명시됨). 점유율 = 평균 입소자 수/일 ÷ 인증 병상 수로, 이는 운영상 점유율을 과소평가합니다(인증 병상 > 가동 병상). 이 모든 사항은 여기뿐 아니라 페이로드에도 명시되어 있습니다.

6. 인메모리 JSON, 데이터베이스 없음, 산출물 커밋됨. 15,000개 행은 밀리초 단위로 로드됩니다. DB는 쿼리 요구가 전혀 없는데 운영 표면만 추가합니다. 커밋된 산출물(~6MB) 덕분에 설치 → 빌드 → 데모가 네트워크 없이 동작합니다 — 라이브 데모가 CMS 장애나 변경된 다운로드 URL로 깨질 수 없습니다. 대가: 저장소가 데이터를 보유하며, 수집 파이프라인은 언제든 소스에서 이를 다시 도출합니다.

7. 출력 크기 제한. 시설 목록은 페이지 처리(기본 25개)되며 항상 완전한 요약 블록과 총 개수가 함께 제공됩니다 — 185개 시설 체인도 클라이언트 컨텍스트를 넘치게 하지 않습니다.

테스팅

• tests/curated.test.ts — 제출 서류 자체 합계에 대한 전사 체크섬.

• tests/metrics.test.ts, tests/resolve.test.ts — 픽스처에 대한 도메인 단위 테스트(정확한 값).

• tests/e2e.test.ts — 인메모리 전송 위에서 실제 데이터를 대상으로 하는 실제 MCP 클라이언트: 데모 질문당 하나의 테스트, 지원되지 않는 경로 포함.

• npm run smoke — 외부 작업 디렉터리에서 실제 stdio를 통한 컴파일된 서버.

효율성 및 토큰 비용

npm run cost는 LLM 클라이언트가 데모 질문당 컨텍스트에서 지불하는 비용(도구 결과 텍스트 + 일회성 도구 스키마)을 완전히 오프라인으로 측정합니다. 토큰 수치는 추정치입니다(문자 수 ÷ 4; 실제 토크나이저는 ±20% 편차). 핵심 가치는 상대 비용과 회귀 추적입니다.

현재 측정값(커밋된 산출물):

모든 응답은 자체 cost 블록({chars, estTokens, basis})을 함께 기록하므로 어시스턴트가 답변의 컨텍스트 비용을 인용할 수 있습니다 — 실제 토큰화는 클라이언트 측에서 이루어지고 서버는 이를 볼 수 없으므로 추정치로 표시됩니다(Claude Code에서 /cost와 /context는 세션 수준에서 여전히 근거 자료입니다).

이를 간결하게 유지하는 두 가지 의도적 최적화가 있습니다(측정 기준, 단순 버전 대비 31% 감소): 모델 노출용 텍스트 미러는 컴팩트 JSON이며(들여쓰기 공백만 해도 페이로드의 ~26%였음), 반복되는 방법론 문자열은 모든 추세 블록이 아닌 응답의 봉투 주의사항에 한 번만 포함됩니다. 시설 목록은 페이지 처리되고, 요약은 항상 전체 모집단 기준입니다. 비용 스탬프 자체는 응답당 ~21토큰을 추가합니다 — 측정된 수치이며, 가시성을 위해 그만한 가치가 있습니다.

데이터 파이프라인

npm run ingest는 data/processed/를 다운로드하고 재구축합니다:

1. CMS PDC 메타스토어 API에서 현재 Provider Information CSV URL을 확인하고(파일 URL은 매월 변경됨), 이를 다운로드하고 추세 분석용 아카이브 스냅샷 2개(2024년 7월, 2025년 7월)도 함께 다운로드합니다.

2. 검증(행 수, CMS의 2024→2025 열 이름 변경에 대한 헤더 별칭을 포함한 필수 열, 등급 범위, null 비율) — 실패 시 명확히 오류를 내고 부분 산출물을 절대 쓰지 않습니다.

3. 세 가지 산출물로 프로젝션: 시설별 슬라이스, CCN→등급 이력, 전국 벤치마크(방법론은 파일에 기록됨).

원시 다운로드는 data/raw/에 캐시됩니다(gitignore 처리됨). --force는 재다운로드합니다.

저장소 구조

data/curated/     hand-verified 10-K facts + operator map (source-cited, checksummed)
data/processed/   generated CMS artifacts (committed; rebuild with npm run ingest)
scripts/          ingest.ts, stdio-smoke.mjs
src/domain/       types, store, resolve, metrics — pure & unit-tested
src/server/       MCP tools + entry (stdio)
tests/            checksums, units, e2e
docs/             PLAN.md (build plan + audit trail), DEMO.md (presentation script)

알려진 한계 및 다음 단계

• Omega 소유 시설은 개별 식별이 불가능 → 운영사 체인 프록시 사용(다음 단계: CMS Ownership 파일의 부동산 회사 기록과 교차 매핑).

• 당해 연도 운영사 순위는 본질적으로 불완전합니다(2020 회계연도에 공시 중단). Omega의 분기별 보충 자료가 이를 좁힐 수 있지만, 브리핑의 소스 범위를 벗어납니다.

• 추세(별점, 인력, 점유율)는 두 개의 엔드포인트 스냅샷 + 중간 지점을 사용합니다. 월별 스냅샷을 더 추가하면 더 부드러워질 것입니다.

• 영국 시설(부동산의 17.7%)은 CMS에 상응하는 수집 경로가 없습니다(CQC가 이에 상응하는 영국 소스가 될 것입니다).