statlab-mcp —— 统计分析 MCP Server

独立项目，与任何厂商的官方插件无关（README 历史声明：与 DeepSeek Harness 无关）。 让 AI agent（Claude Code / Cursor / DeepSeek Harness / Codex 等）获得真实统计学能力： LLM 直接口算统计会编造数字；本项目所有统计结果都来自真实计算 （numpy / scipy / statsmodels / scikit-learn / pmdarima），AI 只负责调用与解释， 第一层 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. 防幻觉设计：第一层 25 工具零 LLM；结论文案由代码模板拼数字生成；p<0.001 统一显示"<0.001"；每个结论固定附局限声明（相关≠因果、是否校正、样本量）

3. 口径钉死并可复算：q1/q3=linear 插值（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），agent 和人都能无痛上手；MCP 工具描述 = 完整 docstring（参数表/返回结构/示例），agent 打开工具列表就是使用说明书

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"}
    }
  }
}

三个必须：-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))"

数据上的三个铁律：① 只收 csv/xlsx/tsv/json，绝对路径随意给（中文/GBK/空值/非法日期全自动处理）；② 真实数据放项目目录之外；③ 每次统计先看 summary 的中文人话结论，再翻 result 的结构化数字。

25 个工具一览

核心价值与统一协议

• 数字可追责：结果确定、可复现、可测试，同一输入两次运行结果一致（全局 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 只读第一个 sheet。

Agent 如何看图

• 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 全绿 + 两套数据实跑核对（真实 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/验证方法，agent 与二次开发者的使用说明书）

• 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 周翔宇）。