Occulytics MCP Server

Un servidor MCP que permite a un asistente de IA responder preguntas de cartera para un equipo de gestión de activos de REIT de atención médica (Omega Healthcare Investors), basado en dos fuentes públicas: los archivos 10-K de Omega ante la SEC y el archivo de Información de Proveedores de Hogares de Enfermería de CMS.

El objetivo de diseño, según el encargo: el servidor debe poder decir que una respuesta es completa, incierta o no respaldada — y por qué — en lugar de producir un número confiado que nada respalda. Cada herramienta devuelve datos deterministas dentro de un sobre que lleva un estado calculado, advertencias y procedencia.

Inicio rápido

Todo se ejecuta sin conexión: los artefactos de datos están incluidos en el repositorio.

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

Pruébalo en una interfaz de usuario (MCP Inspector se abre en tu navegador):

npm run inspect

Conéctate a Claude Code: se incluye un .mcp.json de ámbito de proyecto: abre este repositorio en Claude Code después de npm run build y el servidor occulytics estará disponible. O regístralo globalmente:

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

Conéctate a Claude Desktop (claude_desktop_config.json):

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

Comprobación previa a la demo de que el servidor compilado funciona sobre stdio real: npm run smoke. Para actualizar los datos desde las fuentes en vivo: npm run ingest (consulta Pipeline de datos).

Related MCP server: Medical Billing MCP

Qué puedes preguntar

Las cinco preguntas objetivo y lo que el servidor realmente hace:

Arquitectura

Tres capas, una dirección de dependencia, sin base de datos, sin red en tiempo de ejecución:

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 — resumen de cartera del año fiscal 2025 + nota de concentración, tabla de inversión de operadores del año fiscal 2020. Cada bloque cita su presentación/sección.

• data/curated/operator-map.json — la columna vertebral de la honestidad: el mapeo de CMS de cada operador de Omega con method (chain-exact / legal-name-pattern / curated-alias), confidence (high/medium/low) y advertencias; los operadores no mapeables llevan la razón.

• src/domain/metrics.ts — toda la aritmética: clasificaciones, ocupación, comparaciones de referencia, tendencias de estrellas de panel constante. Nada numérico se deja al modelo.

• src/server/tools.ts — delgado: valida entrada (zod), llama al dominio, envuelve en sobre.

El sobre de respuesta

Cada herramienta devuelve:

{
  "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 se calcula a partir de la ruta de datos, no está codificado: un operador no mapeado produce unsupported con la razón registrada en la entrada de mapeo; cualquier cosa que toque la tabla del año fiscal 2020 es partial con la advertencia de desactualización; el proxy de ocupación siempre es partial.

Superficie de herramientas

Racional de granularidad: las herramientas tienen forma de pregunta pero son componibles: la agregación determinista (donde la aritmética del LLM sobre más de 100 filas es un riesgo de corrección) es responsabilidad de la herramienta; la síntesis narrativa es del modelo. Cada herramienta que acepta operadores acepta texto libre y resuelve internamente, por lo que un cliente nunca necesita un protocolo de dos pasos; una resolución fallida es una respuesta unsupported (con candidatos y el universo conocido), no un error.

Las preguntas entre fuentes (pieza 10-K ↔ pieza CMS) son de primera clase: la identidad del operador es la clave de unión, verificada de ida y vuelta (cada nombre en la clasificación 10-K se resuelve en cada herramienta respaldada por CMS, probado de extremo a extremo), y cada bloque de operador resuelto incrusta su contexto 10-K (omegaContext: rango del año fiscal 2020 y % de la cartera, concentración divulgada del año fiscal 2025), por lo que preguntas del estilo "¿qué tan bueno es nuestro operador más grande?" se resuelven sin una segunda llamada.

Decisiones clave y compensaciones

1. Dos añadas, nunca mezcladas. El hallazgo de investigación decisivo: los 10-K de Omega posteriores al año fiscal 2020 no contienen una tabla de inversión por operador: la presentación del año fiscal 2025 solo nombra a Maplewood (≥10% de las inversiones) y a CommuniCare (7.2%). Por lo tanto, un "top cinco" actual no es totalmente respaldable a partir de las fuentes nombradas, y el servidor dice exactamente eso: las clasificaciones vienen como dos bloques con fechas separadas, y el estado es partial con la razón. Compensación: menos satisfactorio que una lista limpia; elegido porque una lista mezclada sería numéricamente incoherente (dólares de 2020 frente a porcentajes de 2025 en denominadores diferentes).

2. Hechos de la SEC transcritos a mano, datos de CMS ingeridos por máquina. Los hechos de Omega son ~30 números en dos tablas en dos presentaciones con formatos diferentes. Un analizador genérico de 10-K a este alcance tiene el peor modo de fallo posible para este encargo: extracción silenciosamente incorrecta. En su lugar: JSON curado con citas por hecho, protegido por pruebas de suma de verificación (cada columna sumable debe reproducir los subtotales y totales de la propia presentación: un dígito mal escrito falla la compilación). El lado de CMS (14,693 filas × 3 añadas mensuales) está completamente automatizado con validación, porque a esa escala la automatización es la opción más segura. Compensación: actualizar para un nuevo 10-K es una edición manual; aceptado para un documento presentado anualmente.

3. La unión operador→CMS es un artefacto curado y etiquetado con confianza. Ningún conjunto de datos referencia al otro. La unión (nombre de operador 10-K → cadena de CMS) es la inferencia más arriesgada del sistema, por lo que es datos, no código: cada mapeo registra cómo se hizo y cuánto confiar en él, y los operadores no mapeables registran por qué (Maplewood: vivienda para personas mayores, fuera de CMS; Healthcare Homes: Reino Unido). Los mapeos de baja confianza (Agemo → Signature) se excluyen de los agregados agrupados por defecto y se muestran cuando se incluyen. Compensación: no escala a cientos de REIT; correcto para los ~11 operadores nombrados de un REIT, y el mecanismo (método/confianza/advertencia por mapeo) es lo que escalaría.

4. Las métricas de cadena son superconjuntos, y lo dicen. La cartera a nivel de instalaciones de Omega no es pública (verificado: el Anexo III agrega por estado). Por lo tanto, las métricas de CMS describen la operación completa de un operador, no solo los edificios de Omega: cada respuesta afectada lleva esa advertencia, y el proxy de ocupación informa qué parte de la cartera (del año fiscal 2020) representa su cobertura (~40%). Compensación: una reconstrucción a nivel de instalaciones a partir del archivo de Propiedad de CMS era posible, pero es un trabajo de coincidencia difusa de varios días; el proxy honesto con contabilidad de cobertura es la respuesta de cuatro horas. Esa reconstrucción es el siguiente paso natural.

5. La metodología es parte de la respuesta. La tendencia de estrellas = panel constante (instalaciones evaluadas en ambas instantáneas de punto final), con tamaño del panel, exclusiones y el sesgo conocido (la pertenencia a la cadena es solo actual) en la respuesta. El punto de referencia de personal = reportado total de enfermeras HPRD, media de instalación (lo que pregunta la pregunta, sin ajustar; existe ajustado por caso mixto y se señala). Ocupación = promedio de residentes/día ÷ camas certificadas, lo que subestima la ocupación operativa (certificadas > camas en servicio). Todo se indica en los payloads, no solo aquí.

6. JSON en memoria, sin base de datos, artefactos confirmados. 15k filas se cargan en milisegundos; una base de datos añade superficie operativa sin necesidad de consultas. Los artefactos confirmados (~6MB) significan que instalar → construir → demo funciona sin red: la demo en vivo no puede romperse por una caída de CMS o una URL de descarga cambiada. Coste: el repositorio lleva los datos; la ingesta los re-deriva de las fuentes en cualquier momento.

7. Salidas acotadas. Las listas de instalaciones se paginan (por defecto 25) con un bloque de resumen siempre completo y el recuento total: una cadena de 185 instalaciones nunca inunda el contexto del cliente.

Pruebas

• tests/curated.test.ts — sumas de verificación de transcripción contra los totales propios de las presentaciones.

• tests/metrics.test.ts, tests/resolve.test.ts — unidades de dominio en fixtures (valores exactos).

• tests/e2e.test.ts — un cliente MCP real sobre un transporte en memoria contra los datos reales: una prueba por pregunta de demostración, incluyendo las rutas no soportadas.

• npm run smoke — el servidor compilado sobre stdio real desde un cwd externo.

Eficiencia y coste de tokens

npm run cost mide lo que un cliente LLM paga en contexto por pregunta de demostración (texto de resultado de herramienta + esquemas de herramienta únicos), totalmente sin conexión. Las cifras de tokens son estimaciones (caracteres ÷ 4; los tokenizadores reales varían ±20%) — el valor es el coste relativo y el seguimiento de regresiones.

Mediciones actuales (artefactos confirmados):

Cada respuesta también sella su propio bloque cost ({chars, estTokens, basis}) para que el asistente pueda citar cuánto costó una respuesta en contexto — etiquetado como estimación, porque la tokenización real ocurre en el lado del cliente y el servidor nunca la ve (en Claude Code, /cost y /context siguen siendo la verdad fundamental a nivel de sesión).

Dos optimizaciones deliberadas mantienen esto ligero (una reducción del 31% frente a la versión ingenua, medida): el espejo de texto orientado al modelo es JSON compacto (solo el espacio en blanco de pretty-print era ~26% del payload), y las cadenas de metodología repetidas viven una vez por respuesta en las advertencias del sobre en lugar de en cada bloque de tendencia. Las listas de instalaciones se paginan; los resúmenes siempre son de población completa. El sello de coste añade ~21 tokens por respuesta — medido, y vale la pena por la visibilidad.

Canal de datos

npm run ingest descarga y reconstruye data/processed/:

1. Resuelve la URL actual del CSV de Información de Proveedores desde la API de metastore de CMS PDC (la URL del archivo cambia mensualmente), lo descarga junto con dos instantáneas archivadas (Jul 2024, Jul 2025) para la tendencia.

2. Valida (recuentos de filas, columnas requeridas con alias de encabezado en los cambios de nombre de columnas de CMS 2024→2025, rangos de calificación, tasas de nulos) — falla de forma ruidosa, nunca escribe artefactos parciales.

3. Proyecta a tres artefactos: segmento por instalación, historial de calificación CCN→, puntos de referencia nacionales (con métodos registrados en el archivo).

Las descargas sin procesar se almacenan en caché en data/raw/ (ignorado por git); --force vuelve a descargar.

Estructura del repositorio

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)

Limitaciones conocidas y próximos pasos

• Las instalaciones propiedad de Omega no son identificables individualmente → proxy de cadena de operador (próximo: cruzar los registros de empresa de propiedad del archivo de Propiedad de CMS).

• La clasificación de operadores del año actual es inherentemente incompleta (la divulgación se detuvo en FY2020); los suplementos trimestrales de Omega podrían reducir esto, pero están fuera de las fuentes del encargo.

• Las tendencias (estrellas, personal, ocupación) usan dos instantáneas de punto final + un punto medio; más instantáneas mensuales las suavizarían.

• Las instalaciones del Reino Unido (17.7% de los bienes raíces) no tienen ingesta equivalente a CMS (CQC sería la fuente análoga del Reino Unido).