Occulytics MCP Server

ヘルスケアREITの資産管理チーム（Omega Healthcare Investors）向けに、AIアシスタントがポートフォリオに関する質問に回答できるようにするMCPサーバーです。2つの公開ソース（OmegaのSEC 10-K提出書類とCMS Nursing Home Provider Informationファイル）に基づいています。

設計目標（ブリーフによる）: サーバーは、回答が完全、不確実、または裏付けなし — そしてその理由を言える必要があり、何の裏付けもない確信的な数字を生成してはなりません。すべてのツールは、計算されたステータス、注意事項、および出所を運ぶエンベロープ内で決定的なデータを返します。

クイックスタート

すべてオフラインで動作します — データ成果物はコミットされています。

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

質問できること

5つのターゲット質問と、サーバーが実際に行うこと:

アーキテクチャ

3つのレイヤー、依存関係は一方向、データベースなし、ランタイムネットワークなし:

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）、ドメイン呼び出し、エンベロープでラップ。

回答エンベロープ

すべてのツールが返すもの:

{
  "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部分）は第一級です: オペレーターIDが結合キーであり、往復で検証されます（10-Kランキングのすべての名前がすべてのCMSバックアップツールで解決されます — e2eテスト済み）、そして解決された各オペレーターブロックには10-Kコンテキスト（omegaContext: FY2020ランクとポートフォリオの%、FY2025開示集中度）が埋め込まれているため、「最大のオペレーターはどのくらい良いか？」という質問は2回目の呼び出しなしで解決されます。

主要な決定とトレードオフ

1. 2つのビンテージ、決して混ぜない。 決定的な調査結果: OmegaのFY2020以降の10-Kにはオペレーターごとの投資テーブルが含まれていません — FY2025提出書類はMaplewood（投資の≥10%）とCommuniCare（7.2%）のみを名前で挙げています。したがって、現在の「トップ5」は名前付きソースから完全に裏付けることはできず、サーバーはまさにそれを述べます: ランキングは2つの別々に日付付きのブロックとして提供され、ステータスは理由とともにpartialです。トレードオフ: 1つのきれいなリストよりも満足度が低い; 混ぜたリストは数値的に一貫性がないため（異なる分母での2020ドル対2025パーセンテージ）選択されました。

2. 手書き転写のSEC事実、機械取り込みのCMSデータ。 Omegaの事実は、2つの異なる形式の提出書類の2つのテーブルにわたる約30の数字です。このスコープでの一般的な10-Kパーサーは、このブリーフにとって最悪の失敗モード — 黙って間違った抽出 — を持っています。代わりに: 事実ごとの引用付きのキュレーションJSON、チェックサムテストで保護（合計可能なすべての列は提出書類自身の小計と合計を再現する必要があります — タイプミスの数字はビルドを失敗させます）。CMS側（14,693行×3ヶ月ビンテージ）は検証付きで完全に自動化されています。なぜなら、その規模では自動化がより安全な選択肢だからです。トレードオフ: 新しい10-Kの更新は手動編集です; 年次提出文書には受け入れられます。

3. オペレーター→CMS結合はキュレーションされ、信頼度タグ付きの成果物です。 どちらのデータセットも他方を参照していません。結合（10-Kオペレーター名 → CMSチェーン）はシステム内で最もリスクの高い推論であるため、コードではなくデータです: 各マッピングはどのように作成されたか、どの程度信頼すべきかを記録し、マッピングできないオペレーターは理由を記録します（Maplewood: シニアリビング、CMS外; Healthcare Homes: 英国）。低信頼度マッピング（Agemo → Signature）はデフォルトでプール集計から除外され、含まれる場合は表面化されます。トレードオフ: 数百のREITにはスケールしません; 1つのREITの約11の名前付きオペレーターには正しく、メカニズム（マッピングごとの方法/信頼度/注意事項）がスケールするものです。

4. チェーンメトリクスはスーパーセットであり、その旨を述べます。 Omegaの施設レベルのポートフォリオは公開されていません（検証済み: Schedule IIIは州ごとの集計）。したがって、CMSメトリクスはオペレーターの全体の運営を説明しており、Omegaの建物だけではありません — 影響を受けるすべての応答にはその注意事項が含まれ、稼働率プロキシはそのカバレッジが（FY2020）ポートフォリオのどの割合を表すかを報告します（約40%）。トレードオフ: CMS所有権ファイルからの施設レベルの再構築は可能でしたが、数日かかるファジーマッチング作業です; カバレッジ会計付きの正直なプロキシは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クライアントを実際のデータに対して実行。デモ質問ごとに1テスト。サポート外のパスも含む。

• npm run smoke — 外部のcwdから実際のstdio上でコンパイル済みサーバーを実行。

効率性とトークンコスト

npm run cost は、LLMクライアントがデモ質問ごとにコンテキストで支払うもの（ツール結果テキスト + 一度きりのツールスキーマ）を完全オフラインで測定する。トークン数は推定値（文字数 ÷ 4。実際のトークナイザーは±20%変動する）。価値があるのは相対コストと回帰追跡である。

現在の測定値（コミット済み成果物）:

各レスポンスはまた、自身の cost ブロック（{chars, estTokens, basis}）をスタンプする。これによりアシスタントは回答がコンテキストでいくらかかったかを引用できる。推定値と明記されているのは、実際のトークン化はクライアント側で行われ、サーバーはそれを決して見ないためである（Claude Codeでは、/cost と /context がセッションレベルで真実の情報源であり続ける）。

この軽量さを維持するための2つの意図的な最適化がある（ナイーブ版と比較して31%削減、測定済み）: モデル向けテキストミラーはコンパクトなJSONである（それだけでペイロードの約26%を占めていた整形空白を削除）、そして繰り返しの方法論文字列は各トレンドブロックではなく、エンベロープの注意事項にレスポンスごとに1回だけ置かれる。施設リストはページングされ、サマリーは常に全母集団である。コストスタンプ自体はレスポンスごとに約21トークンを追加する — 測定済みであり、可視性の価値がある。

データパイプライン

npm run ingest は data/processed/ をダウンロードして再構築する:

1. CMS PDCメタストアAPIから現在のProvider Information CSV URLを解決する（ファイルURLは毎月変わる）。それをダウンロードし、傾向用に2つのアーカイブスナップショット（2024年7月、2025年7月）も取得する。

2. 検証する（行数、CMSの2024→2025年の列名変更にわたるヘッダーエイリアシングを伴う必須列、評価範囲、欠損率）— 失敗時は明確にエラーを出し、部分的な成果物は決して書き込まない。

3. 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ファイルのプロパティ会社レコードとのクロスウォーク）。

• 当年のオペレーターランキングは本質的に不完全である（開示はFY2020で停止）。Omegaの四半期補足資料で狭められる可能性があるが、ブリーフのソース範囲外である。

• 傾向（星評価、人員、稼働率）は2つのエンドポイントスナップショット + 中間点を使用。より多くの月次スナップショットがあれば平滑化できる。

• 英国の施設（不動産の17.7%）にはCMS相当の取り込みがない（CQCが英国の同等ソースとなる）。