openanalyst-mcp-server

実際のDeepSeek Harnessセッション — エージェントがCSVを添付し、プロファイルし、 これらのチャートを会話ノードとして描画した（ヘッドレスChromeによるライブUIのキャプチャ。 検証記録を参照）：

ステータス: 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

同じ5つのツールが、1つのエンジンから2つのホストで提供される：

すべてのツールはCode Modeからawait tools.data_*(args)としても呼び出せるため、 エージェントはステップごとにラウンドトリップを消費する代わりに、分析全体を1つのプログラム内で連結できる。

ワークベンチ — セッションヘッダーパネル。このセッションのデータソース、 クリックでスクロールできるチャートギャラリー、生成されたレポートを表示する：

会話内のその他のチャート種類（同じテーマ、ライブセッションからエクスポート）：

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

アーキテクチャ

コードベースを形作る3つの決定。

エンジンはハーネスについて何も知らない。 @openanalyst/coreはパスとSQLを受け取り、ロスレスのJSONを返す。dsh、MCP、CLIの型を一切インポートしない。これにより、同じ分析を後でMCPアダプターを通じてClaude Code、Codex、Cursorに配信できる — 実装を二重に持つ必要がない。これはプラグインが単一ホストを超えたユーザーに届くかどうかを決める最大の要因である。

統計処理はDuckDBが行う。 SUMMARIZEは全カラムのmin/max/avg/std/四分位数/approx_unique/null_percentageを1パスで返し、CSV、Parquet、JSONを完全なファイル型推論で直接読み取る。IQR外れ値、重複行検出、フラグを立てる価値があるかの判断だけが手書きされている。

チャートはセッションイベントに載せられたVega-Lite仕様である。 ハーネスのツールカード種類は閉じた集合 — generic、terminal、diff、search、web — でチャートメンバーはないため、ツール結果はチャートをテキストに劣化させることしかできない。実際のチャートは会話ノードから来る必要があり、クライアント側がそれを登録する。

この制約がチャート形式も選ぶことになった。会話ノードはそのビューを永続イベントの純関数として再構築しなければならない — 時計も、乱数も、ライブ状態もない — そしてエンジンはデルタよりも全体値のチェックポイントを好む。データをインライン化したVega-Lite仕様はまさにそれだ：バイト単位でリプレイされる1つのプレーンな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フィクスチャがない場合は自動スキップするライブPostgreSQL/MySQLコネクタテスト）、レポートビルダー上で5、DuckDBに対する実際のdshプラグインツールをエンドツーエンドで駆動する14（エージェントごとの分離を含む）、SDKのインメモリトランスポート上のプロトコルレベルMCPテスト9（スクリプト化された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がインライン化されているのは、ハーネスがプラグインごとに正確に1ファイルを提供し、兄弟チャンクのルートがないためで、チャートなしのセッションでもそのコストを支払うことになる。

• data_attachはホストプロセスが読み取れる任意のパスを受け取る。 まだワークスペースフェンシングはない。ハーネスサンドボックスが許可するものをそのまま継承する。

• XLSXはDuckDBのread_xlsxに依存しており、初回使用時に拡張機能のダウンロードが必要になる場合がある。CSV、Parquet、JSONはテストでカバーされているが、XLSXはされていない。

dsh npmパッケージに関するメモ

ここで時間がかかった2つの点があり、ハーネスプラグインを構築する他の人のために記録する価値がある：

• 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