openanalyst-mcp-server

一个真实的 DeepSeek Harness 会话——代理附加了一个 CSV，对其进行了剖析，并把 这些图表绘制为对话节点（无头 Chrome 对实时界面的捕获；请参阅 验证记录）：

状态：M1 + M2 + M3 已完成。 dsh 插件已在 dsh web 0.1.0-rc.8 中通过实时验证——完整的附加 → 剖析 → 查询 → 图表链路在真实会话中运行，两个图表均渲染为对话节点 （验证记录）。MCP 服务器通过了协议级测试以及 stdio 冒烟测试。请参阅已知限制。

它能做什么

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) 调用，因此 代理可以在一个程序内串联整个分析，而不是每一步都花费一次往返。

工作台——一个会话头部面板，列出本会话的数据源、带点击滚动功能的图表画廊，以及生成的报告：

更多会话内图表类型（同一主题，从实时会话中导出）：

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

架构

三个决策塑造了代码库。

引擎对宿主一无所知。 @openanalyst/core 接收路径和 SQL，并返回无损 JSON。它不导入任何 dsh、MCP 或 CLI 类型。正是这一点让同一套分析可以稍后通过 MCP 适配器交付到 Claude Code、Codex 和 Cursor，而无需第二次实现——这是决定插件能否触达单一宿主之外用户群的最大因素。

统计由 DuckDB 完成。 SUMMARIZE 在一次遍历中返回每一列的 min/max/avg/std/quartiles/approx_unique/null_percentage，并直接读取 CSV、Parquet 和 JSON，进行全文件类型推断。只有 IQR 离群值、重复行检测，以及判断哪些内容值得标记，是手工编写的。

图表是承载在会话事件上的 Vega-Lite 规范。 宿主的工具卡片种类是一个封闭集合——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 转换、精确去重计数的剖析、图表，以及在没有 Docker fixture 时自动跳过的实时 PostgreSQL/MySQL 连接器测试），5 个覆盖报告构建器，14 个在真实 dsh 插件工具上针对 DuckDB 进行端到端驱动（包括按代理隔离），9 个通过 SDK 的内存传输进行协议级 MCP 测试（外加一个脚本化 stdio 冒烟测试）。针对正在运行的 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 代理会话都有自己的引擎（不会发生别名冲突），但宿主不会在代理销毁时通知插件，因此插件最多持有 32 个引擎，并驱逐最近最少使用的引擎——该会话会在下一次调用时透明地重新附加。

• 客户端打包体积是 ~860 kB。 Vega 被内联，因为宿主每个插件只提供一个文件，并且没有兄弟块的路由，因此即使没有图表的会话也要为它付出代价。

• data_attach 接受宿主进程可读取的任何路径。 目前还没有工作区隔离；它继承了宿主沙箱所允许的一切。

• XLSX 依赖 DuckDB 的 read_xlsx，首次使用时可能需要下载扩展。CSV、Parquet 和 JSON 已被测试覆盖；XLSX 尚未覆盖。

关于 dsh npm 包的说明

这里有两件事比较耗时，值得记录下来供其他构建宿主插件的人参考：

• 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