Occulytics MCP Server

MCP-сервер, который позволяет ИИ-ассистенту отвечать на вопросы о портфеле для команды по управлению активами healthcare-REIT (Omega Healthcare Investors), опираясь на два публичных источника: SEC 10-K файлы Omega и файл 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 с областью проекта — откройте этот репозиторий в Claude Code после npm run build, и сервер 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 — проверено e2e), и каждый разрешённый блок оператора встраивает свой контекст 10-K (omegaContext: ранг и % портфеля FY2020, раскрытая концентрация FY2025), так что вопросы типа «насколько хорош наш крупнейший оператор?» разрешаются без второго вызова.

Ключевые решения и компромиссы

1. Два года, никогда не смешиваются. Решающий исследовательский вывод: 10-K Omega после FY2020 не содержат таблицы инвестиций по операторам — файл FY2025 называет только Maplewood (≥10% инвестиций) и CommuniCare (7.2%). Таким образом, текущий «топ-5» полностью не подтверждается названными источниками, и сервер говорит именно это: рейтинги представлены двумя отдельно датированными блоками, а статус — 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; корректен для ~11 названных операторов одного REIT, и механизм (метод/уверенность/оговорка для каждого сопоставления) — это то, что масштабировалось бы.

4. Метрики цепочек — супермножества, и об этом говорится. Портфель Omega на уровне объектов не публичен (проверено: Приложение III агрегирует по штатам). Поэтому метрики CMS описывают всю деятельность оператора, а не только здания Omega — каждый затронутый ответ несёт эту оговорку, а прокси заполняемости сообщает, какую долю портфеля (FY2020) покрывает его охват (~40%). Компромисс: реконструкция на уровне объектов из файла владения CMS была возможна, но это многодневная работа по нечёткому сопоставлению; честный прокси с учётом покрытия — это ответ за четыре часа. Эта реконструкция — естественный следующий шаг.

5. Методология — часть ответа. Тренд звёзд = постоянная панель (объекты, оценённые в обоих конечных снимках), с размером панели, исключениями и известным смещением (членство в сети учитывается только на текущую дату) в ответе. Бенчмарк по персоналу = заявленный суммарный HPRD медсестёр, среднее по объектам (то, о чём спрашивается, без корректировки; существует и поправка на структуру пациентов, она отмечена). Заполняемость = среднее число проживающих в день ÷ сертифицированные койки, что занижает операционную заполняемость (сертифицированных коек больше, чем действующих). Всё указано в полезных нагрузках, а не только здесь.

6. JSON в памяти, без базы данных, артефакты в репозитории. 15 тыс. строк загружаются за миллисекунды; БД добавляет операционную поверхность при нулевой потребности в запросах. Закоммиченные артефакты (~6 МБ) означают, что установка → сборка → демо работает без сети — живое демо невозможно сломать сбоем 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 (только пробелы pretty-print составляли ~26% полезной нагрузки), а повторяющиеся строки методологии размещаются один раз на ответ в оговорках конверта, а не в каждом блоке тренда. Списки объектов разбиты на страницы; сводки всегда по всей совокупности. Сам штамп стоимости добавляет ~21 токен на ответ — измерено, и оно того стоит ради прозрачности.

Конвейер данных

npm run ingest загружает и пересобирает data/processed/:

1. Разрешает текущий URL CSV Provider Information из API метастора CMS PDC (URL файла меняется ежемесячно), загружает его плюс два архивных снимка (июль 2024, июль 2025) для тренда.

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, не идентифицируются по отдельности → прокси операторской сети (далее: сквозная сверка записей компаний-собственников из файла Ownership CMS).

• Рейтинг операторов за текущий год по своей природе неполон (раскрытие прекратилось в FY2020); ежеквартальные дополнения Omega могли бы сузить этот пробел, но они вне источников, указанных в задании.

• Тренды (звёзды, персонал, заполняемость) используют два конечных снимка + среднюю точку; больше ежемесячных снимков сгладили бы их.

• Для объектов в Великобритании (17,7% недвижимости) нет ингестии, аналогичной CMS (аналогом для Великобритании был бы CQC).