openanalyst-mcp-server

Реальный сеанс DeepSeek Harness — агент прикрепил CSV, составил профиль и построил эти графики как узлы диалога (снимок живого интерфейса в headless-Chrome; см. запись проверки):

Статус: M1 + M2 + M3 завершены. Плагин dsh проверен вживую внутри dsh web 0.1.0-rc.8 — полная цепочка attach → profile → query → chart выполнялась в реальном сеансе, и оба графика отобразились как узлы диалога (запись проверки). MCP-сервер проходит протокольные тесты плюс stdio-smoke. См. Известные ограничения.

Что это делает

data_attach     →  register a CSV / Parquet / JSON / XLSX file as a queryable table
data_attach_db  →  attach PostgreSQL / MySQL / SQLite read-only and list its tables
data_profile    →  types, missing values, exact distinct counts, outliers, quality issues, chart ideas
data_query      →  one read-only SQL statement, results as lossless JSON
data_chart      →  bar / line / scatter / histogram / area / heatmap / boxplot — with color
                   series, stacked/grouped layout, facet small multiples; line & scatter pan/zoom
data_report     →  a self-contained HTML report (profile + charts as inline SVG); prints to PDF
data_sources    →  what is currently attached

Одни и те же пять инструментов поставляются на двух хостах из одного движка:

Каждый инструмент также доступен из Code Mode как await tools.data_*(args), поэтому агент может выстроить весь анализ внутри одной программы, не тратя на каждый шаг отдельный круговой запрос.

Workbench — панель в шапке сеанса со списком источников данных этого сеанса, галерея графиков с прокруткой по клику и сгенерированные отчёты:

Другие виды графиков в диалоге (та же тема, экспортированы из живого сеанса):

Related MCP server: chdb-mcp

Установка

DeepSeek Harness:

dsh plugin --profile web add openanalyst

Claude Code (или любой MCP-клиент, через stdio):

claude mcp add openanalyst -- npx -y openanalyst-mcp-server

Архитектура

Три решения определяют устройство кодовой базы.

Движок ничего не знает о harness. @openanalyst/core принимает пути и SQL и возвращает JSON без потерь. Он не импортирует ни одного типа dsh, MCP или CLI. Именно это позволяет позже поставлять тот же анализ в Claude Code, Codex и Cursor через MCP-адаптер без второй реализации — это самый важный фактор того, доберётся ли плагин до аудитории за пределами одного хоста.

Статистику считает DuckDB. SUMMARIZE возвращает min/max/avg/std/квартили/approx_unique/null_percentage для каждой колонки за один проход и читает CSV, Parquet и JSON напрямую с выводом типов по всему файлу. Вручную написаны только выбросы IQR, обнаружение дублирующихся строк и решение о том, что стоит помечать.

Графики — это спецификации Vega-Lite, переносимые в событиях сеанса. Типы карточек инструментов harness — это закрытый набор — generic, terminal, diff, search, web — без элемента «график», поэтому результат инструмента может лишь свести график к тексту. Настоящий график должен приходить из узла диалога, который регистрирует клиентская часть.

Это ограничение, как выяснилось, определило и формат графиков. Узел диалога должен перестраивать своё представление как чистую функцию долговечных событий — без часов, без случайности, без живого состояния, — а движок предпочитает контрольные точки целых значений дельтам. Спецификация Vega-Lite со встроенными данными — это ровно то, что нужно: одно простое значение JSON, которое воспроизводится побайтово. Vega-Lite выбрана, потому что она удовлетворяет правилу воспроизводимости, а не потому, что это популярная библиотека графиков.

@openanalyst/core            engine, profiling, DB connectors, chart specs  (host-agnostic)
  ├── @openanalyst/report    Vega-Lite -> SVG (pure JS) + self-contained HTML reports
  ├── openanalyst            dsh host half: 7 tools + chart event
  │     └── ./client         dsh browser half: conversation node + Vega canvas
  └── openanalyst-mcp-server stdio MCP server: same 7 tools, charts as SVG files

Разработка

pnpm install
pnpm -r run build
pnpm -r run test

74 теста: 46 по ядру (SQL-политика, преобразование в JSON, профилирование с точным подсчётом уникальных значений, графики и живые тесты коннекторов PostgreSQL/MySQL, которые автоматически пропускаются без Docker-фикстур), 5 по сборщику отчётов, 14, прогоняющих реальные инструменты плагина dsh end-to-end против DuckDB (включая изоляцию по агентам), и 9 протокольных MCP-тестов на in-memory транспорте SDK (плюс скриптовый stdio-smoke). Проверка вживую на запущенном dsh web прописана в сценарии scripts/mock-llm-scripted.mjs + scripts/verify-live.patch.yml — см. docs/VERIFICATION.md.

Известные ограничения

Они реальны, и их стоит прочитать, прежде чем строить что-то на этой основе.

• Пресеты PTC 模式 (Code Mode) отклоняют прямые вызовы инструментов — модель должна оборачивать их в программу run_code. При пресете Standard инструменты вызываются напрямую. Поведение проверено, задокументировано в docs/VERIFICATION.md.

• Движки dsh на агента ограничены, а не отслеживаются по жизненному циклу. Каждый сеанс агента dsh получает собственный движок (без коллизий алиасов), но harness не уведомляет плагины об удалении агента, поэтому плагин удерживает не более 32 движков и вытесняет наименее недавно использованный — такой сеанс прозрачно переподключается при следующем вызове.

• Клиентский бандл — ~860 кБ. Vega встроена, потому что harness отдаёт ровно один файл на плагин и не имеет маршрута для соседних чанков, поэтому сеанс без графиков всё равно за неё платит.

• data_attach принимает любой путь, который доступен на чтение процессу хоста. Ограждения рабочей области (workspace fencing) пока нет; наследуется всё, что разрешает песочница harness.

• XLSX зависит от read_xlsx у DuckDB, для которого при первом использовании может потребоваться загрузка расширения. CSV, Parquet и JSON покрыты тестами; XLSX — нет.

Заметки о npm-пакетах dsh

Две вещи здесь стоили времени, и их стоит зафиксировать для всех, кто собирает harness-плагин:

• latest указывает на сломанную ветку. npm view @deepseek-ai/dsh-tools version сообщает 0.0.1-rc.1, но текущая ветка — 0.1.0-rc.8. Некоторые пакеты 0.0.1-rc.1 вообще не устанавливаются — @deepseek-ai/dsh-client-runtime@0.0.1-rc.1 зависит от @deepseek-ai/dsh-compact, а @deepseek-ai/dsh-session@0.0.1-rc.1 — от @deepseek-ai/dsh-type-meta; ни один из них не опубликован. Пиньте 0.1.0-rc.8.

• Политика pnpm minimumReleaseAge блокирует rc-ветку, пока она свежая. В этом репозитории она отключена в pnpm-workspace.yaml, с пометкой вернуть её, когда у dsh появится стабильный релиз.

Дорожная карта

Лицензия

MIT