statlab-mcp —— 統計分析 MCP Server

独立プロジェクトであり、いかなるベンダーの公式プラグインとも無関係（README の過去の宣言：DeepSeek Harness とは無関係）。 AI エージェント（Claude Code / Cursor / DeepSeek Harness / Codex など）に真の統計学的能力を持たせる： LLM が直接暗算で統計を出そうとすると数字を捏造する；本プロジェクトのすべての統計結果は実際の計算 （numpy / scipy / statsmodels / scikit-learn / pmdarima）に由来し、AI は呼び出しと解釈のみを担当する。 第1層の 25 ツール内ではいかなる LLM の計算関与も禁止。

何に使えるのか

これを導入すると、AI に「この売上データを分析して」と言うだけで、AI は根拠のない断言をせず、25 個の実在の統計ツールを呼び出す：記述統計の計算、相関の確認、仮説検定の実行、回帰の当てはめ、クラスタリング、時系列予測、中国語グラフの描画——すべての数字は検証済みの統計ライブラリに由来し、再現可能で説明責任がある。summary フィールドは中国語の一行結論を返し、result は完全な構造化データを返す。例：

{"status": "ok", "result": {"p_value": 0.0241, "mean_diff": 5.5, "effect_size": 0.65},
 "summary": "Welch t 检验：均值差 5.5（95% CI [0.74, 10.26]），p=0.0241 <0.05 拒绝 H0……相关≠因果"}

Related MCP server: shewhart-mcp

誰に向けたものか

どんな問題を解決できるか

特徴と突出した能力

1. 決定論最優先：すべてのランダム過程は seed（42）に固定。同じファイルを 2 回実行すると結果はバイト単位で一致（これは説明責任の基盤であり、テストに専用のアサーションがある）

2. 幻覚防止設計：第1層の 25 ツールは LLM 不使用。結論の文言はコードテンプレートが数字を埋め込んで生成。p<0.001 は一律「<0.001」と表示。各結論には必ず限界の声明を添付（相関≠因果、補正の有無、サンプルサイズ）

3. 定義を固定し再計算可能：q1/q3=線形補間（Excel QUARTILE.INC と同定義）、歪度/尖度=scipy Fisher 定義、std=ddof=1（Excel STDEV.S）——ドキュメントに明記し、テストは手計算式と標準ライブラリで独立に照合（223 個の pytest、カバレッジは docs/ 参照）

4. 中国語フルチェーン：中国語の列名、GBK エンコーディングの自動フォールバック、中国語フォントのグラフ（フォントがない場合は英語に自動フォールバックして明記）、解決策の提案付き中国語エラーメッセージ

5. 堅牢なセキュリティと防御：ローカルファイルのみ、UNC/NUL パス拒否、ネットワークアップロードなし、>50MB/200万行/500MB メモリの三重保護、xlsx zip 爆弾と日付範囲の防御、異常出力は上限で切り詰め（悪意ある入力によるフリーズを防止）

6. 統一された呼び出し体験：全ツールが同型（参数校验 → 中文报错或 result+summary）、エージェントも人間も苦労なく使える。MCP ツールの説明 = 完全な docstring（パラメータ表/戻り構造/例）、エージェントがツールリストを開けばそのまま取扱説明書

7. エンジニアリング完備：設計ドキュメント 12 部（各ツールのパラメータ表/境界表/JSON Schema/検証方法）+ クライアント接続設定 + カバレッジ 82–96% + ruff 全量パス + stdio プロトコルのスモークテスト

クイックスタート

# 1. 安装（Python 3.13+，仅 pip）
git clone https://github.com/good-boy4069/statlab-mcp.git
cd statlab-mcp
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -i https://pypi.tuna.tsinghua.edu.cn/simple -r requirements.txt --timeout 60

# 2. 验证能跑（应输出 ALL-STDIO-OK）
$env:PYTHONUTF8="1"
.\.venv\Scripts\python.exe tests\smoke_stdio.py

Claude Code への接続（プロジェクトルート .mcp.json）：

{
  "mcpServers": {
    "statlab-mcp": {
      "command": "C:\\path\\to\\statlab-mcp\\.venv\\Scripts\\python.exe",
      "args": ["-m", "statlab_mcp.server"],
      "cwd": "C:\\path\\to\\statlab-mcp",
      "env": {"PYTHONUTF8": "1"}
    }
  }
}

必須条件は 3 つ：-m statlab_mcp.server（server.py のパスではなく）、cwd をプロジェクトルートに指定、PYTHONUTF8=1。他のクライアント（Cursor/VSCode/Codex/Hermes/DSH）は docs/clients.md 参照。

初回の呼び出し（クライアントに接続しなくてもコマンドラインで直接使用可）：

.\.venv\Scripts\python.exe -c "import sys; sys.path.insert(0,'.'); from statlab_mcp.tools.data_exploration_describe_statistics import describe_statistics; import json; print(json.dumps(describe_statistics('samples/clean.csv'), ensure_ascii=False, indent=1))"

データに関する 3 つの鉄則：① 受け付けるのは csv/xlsx/tsv/json のみ。絶対パスは自由に指定してよい（中国語/GBK/空値/不正な日付はすべて自動処理）。② 本番データはプロジェクトディレクトリの外に置く。③ 統計のたびに、まず summary の中国語の平易な結論を確認し、それから result の構造化された数値を確認する。

25 ツール一覧

中核的価値と統一プロトコル

• 数字の説明責任：結果は決定論的・再現可能・テスト可能で、同じ入力に対する 2 回の実行結果は一致（全体で seed=42）

• 構造の統一：成功時 {status:"ok", result:{...}, summary:"一句话中文结论"}；失敗時 {status:"error", message:"中文原因有效提示"}

• 画像添付：グラフを含むツールは返却 JSON の最上位に __image__ を追加（画像の絶対パス。base64 禁止）

環境準備（Windows）

1. Python 3.13+ が必要。独立した仮想環境（pip のみ。uv/poetry/conda 禁止）：

   python -m venv .venv
   .\.venv\Scripts\Activate.ps1
   pip install -i https://pypi.tuna.tsinghua.edu.cn/simple -r requirements.txt --timeout 60

2. requirements.txt が依存関係の唯一の正本（pyproject.toml はメタデータのみ）。

3. 実行前に UTF-8 の設定が必須（設定しないと stdio が GBK で中国語 JSON を書き、MCP 接続が即座に落ちる）：

   $env:PYTHONUTF8="1"

   server エントリーファイルの最上部にも sys.stdout.reconfigure(encoding="utf-8") を保険として記述済み。

4. データ読み取りは read_table() ラッパーに統一：utf-8-sig で試読 → csv/tsv が失敗したら自動で gbk に切替 → それも失敗したら中国語エラー「文件编码无法识别，请另存为 UTF-8」；形式ホワイトリスト {csv, xlsx, tsv, json}、xlsx は最初のシートのみ読み取り。

エージェントはどうやって画像を見るのか

• DeepSeek Harness：read_image ツールで __image__ が返す絶対パスを読む

• Claude Code：Read ツールで同じパスを読む

• すべての画像は reports/plots/YYYYmmdd/ に保存（日付でアーカイブし蓄積を防止）。ファイル名は 工具名_<主列名或all>_YYYYmmdd_HHMMSS_fff.png、中国語フォントは Microsoft YaHei/SimHei（ない場合は英語にフォールバックし図内に明記）、dpi=150。ディレクトリはいつでも削除可能（計算には影響しない）

セキュリティ声明

• 分析対象はあなたが自ら提供したローカルデータファイルのみ。UNC/NUL パス拒否、ネットワークアップロードは一切なし

• パストラスト声明：ツールはファイルの出所を検証しない（指定されたパスをそのまま読み取る）。信頼できない出所のパスを渡さないこと。本番データはプロジェクトディレクトリの外に置くこと

• ビッグデータ保護：>50MB は拒否。5-50MB はまず行数/メモリを見積もり、上限超過なら拒否。zip 爆弾と日付範囲の攻撃面にも強固な防御あり

テストと受け入れ

& .\.venv\Scripts\python.exe -m pytest tests\ -q

• テストデータは tests/make_fixtures.py が固定 seed で生成し保存。重要な数値は独立した第三者の計算と照合（statistics.mean / 手計算の期待値表）、循環論証は禁止

• 受け入れフロー（2026-08-26 以降は AI 代行モード）：pytest オールグリーン + 2 種類のデータで実実行して照合（実際の stdout はすべて受け入れ記録に保存）→ commit + PROGRESS 登録。利用者はいつでも抜き打ち検査の権利を保持

• 品質ベースライン：223 個の pytest、ツールモジュールのカバレッジ 82–96%、ruff 全量パス、stdio プロトコルのスモーク ALL-STDIO-OK

技術ノート（mcp 2.x）

依存関係は mcp==2.1.0 に固定：mcp.server.fastmcp.FastMCP は mcp.server.mcpserver.MCPServer に置き換えられた （API は add_tool/tool デコレータと互換。list_tools/call_tool/run_stdio_async は async）。

ドキュメントナビゲーション

• docs/clients.md —— 各クライアントの接続設定（Claude Code/Cursor/VSCode/Codex/Hermes/DSH）

• docs/SPEC.md —— プロトコルと統計定義（戻り構造/数値プロトコル/画像プロトコル/動作契約）

• docs/design/ —— 各ツールのインターフェース設計（パラメータ表/境界動作表/JSON Schema/検証方法。エージェントと二次開発者向けの取扱説明書）

• docs/example_report.md —— auto_analysis プラン A のサンプルレポート（幻覚防止の鉄則の実例）

ディレクトリ構成

statlab_mcp/          # server.py（只注册工具+to_jsonable）+ tools/<组>_<工具>.py
docs/                  # SPEC.md（协议与统计口径）、design/（各工具接口设计文档）、clients.md（接入配置）
samples/               # 入库样例数据 + 生成脚本
tests/                 # pytest + fixtures 生成脚本
data/                  # 使用者亲手造的测试数据（gitignore，不入库）
reports/plots/         # 图片输出（gitignore，按日期归档可随时清理）

License

MIT（Copyright © 2026 周翔宇）。