Occulytics MCP 服务器

一个 MCP 服务器，让 AI 助手能够为医疗保健 REIT 资产管理团队（Omega Healthcare Investors）回答投资组合问题，基于两个公开来源：Omega 的 SEC 10-K 文件和 CMS 养老院提供者信息文件。

根据简报的设计目标：服务器必须能够说明答案是完整、不确定或不支持——以及原因，而不是产生一个没有依据的自信数字。每个工具都在一个信封内返回确定性数据，该信封带有计算出的状态、注意事项和来源。

快速开始

所有内容均可离线运行——数据工件已提交。

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），调用领域，包装在信封中。

答案信封

每个工具返回：

{
  "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。

工具表面

粒度理由：工具是问题形状的但可组合——确定性聚合（其中 LLM 对 100+ 行的算术是正确性风险）是工具的责任；叙述综合是模型的。每个接受运营商的工具都接受自由文本并在内部解析，因此客户端永远不需要两步协议；解析失败是一个 unsupported 答案（带有候选和已知宇宙），而不是错误。

跨源问题（10-K 部分 ↔ CMS 部分）是一等公民：运营商身份是连接键，经过往返验证（10-K 排名中的每个名称在每个 CMS 支持的工具中都能解析——端到端测试），每个已解析的运营商块都嵌入其 10-K 上下文（omegaContext：FY2020 排名和投资组合百分比，FY2025 披露的集中度），因此“我们最大的运营商有多好？”这类问题无需第二次调用即可解析。

关键决策与权衡

1. 两个年份，绝不混合。 决定性的研究发现：Omega 在 FY2020 之后的 10-K 中没有包含按运营商的投资表——FY2025 文件仅点名 Maplewood（≥10% 的投资）和 CommuniCare（7.2%）。因此，当前的“前五”无法完全从具名来源支持，服务器正是这样说的：排名以两个单独日期的块呈现，状态为 partial 并带有原因。权衡：不如一个干净的列表令人满意；选择它是因为混合列表在数值上是不连贯的（2020 年美元与 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 个具名运营商是正确的，机制（每个映射的方法/置信度/注意事项）才是可扩展的。

4. 连锁指标是超集，并说明这一点。 Omega 的设施级投资组合不是公开的（已验证：Schedule III 按州汇总）。因此 CMS 指标描述的是运营商的整个运营，而不仅仅是 Omega 的建筑——每个受影响的响应都带有该注意事项，入住率代理报告其覆盖范围代表（FY2020）投资组合的多少份额（约 40%）。权衡：从 CMS 所有权文件重建设施级是可能的，但需要多天的模糊匹配工作；带有覆盖核算的诚实代理是四小时的答案。该重建是自然的下一步。

5. 方法论是答案的一部分。 星级趋势 = 恒定面板（在两个端点快照中均被评级的设施），响应中包含面板规模、排除项和已知偏差（链成员资格仅限当前）。人员配置基准 = 报告的护士总 HPRD，设施均值（即问题所问，未经调整；存在病例组合调整版本，已注明）。入住率 = 日均居民数 ÷ 认证床位，这会低估实际运营入住率（认证床位 > 在用床位）。所有这些都在载荷中说明，而不仅仅是在这里。

6. 内存 JSON，无数据库，产物已提交。 1.5 万行毫秒级加载；数据库为零查询需求增加了运维面。已提交的产物（约 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 运行编译后的服务器。

效率与 token 成本

npm run cost 衡量 LLM 客户端在每个演示问题上支付的上下文成本（工具结果文本 + 一次性工具模式），完全离线。Token 数字为估算值（字符数 ÷ 4；真实分词器偏差 ±20%）——其价值在于相对成本和回归跟踪。

当前测量值（已提交产物）：

每个响应还会打上自己的 cost 块（{chars, estTokens, basis}），以便助手可以引用答案在上下文中花费的成本——标记为估算值，因为真实分词发生在客户端，服务器永远看不到（在 Claude Code 中，/cost 和 /context 在会话级别仍是事实依据）。

两个刻意的优化使其保持精简（经测量，相比朴素版本减少 31%）：面向模型的文本镜像为紧凑 JSON（仅美化打印的空白就约占载荷的 26%），重复的方法论字符串在每个响应的信封注意事项中只出现一次，而不是出现在每个趋势块上。设施列表分页；摘要始终为全量数据。成本戳本身每个响应增加约 21 个 token——经测量，为了可见性值得。

数据管道

npm run ingest 下载并重建 data/processed/：

1. 从 CMS PDC 元存储 API 解析当前 Provider Information CSV URL（文件 URL 每月变化），下载该文件及两个归档快照（2024 年 7 月、2025 年 7 月）用于趋势分析。

2. 验证（行数、必需列（含 CMS 2024→2025 列重命名的表头别名）、评级范围、空值率）——失败时大声报错，绝不写入部分产物。

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 的季度补充材料可以缩小这一差距，但不在简报的资料来源范围内。

• 趋势（星级、人员配置、入住率）使用两个端点快照 + 一个中点；更多月度快照可使其更平滑。

• 英国设施（占房地产的 17.7%）没有 CMS 等效的摄取（CQC 将是类似的英国来源）。