statlab-mcp —— Servidor MCP de análisis estadístico

Proyecto independiente, no afiliado con los complementos oficiales de ningún proveedor (declaración histórica del README: sin relación con DeepSeek Harness). Permite que los agentes de IA (Claude Code / Cursor / DeepSeek Harness / Codex, etc.) tengan capacidades estadísticas reales: si un LLM calcula estadísticas directamente de memoria, inventa números; en este proyecto todos los resultados estadísticos provienen de un cálculo real (numpy / scipy / statsmodels / scikit-learn / pmdarima); la IA solo se encarga de invocar e interpretar. Dentro de las 25 herramientas de la primera capa está prohibido que cualquier LLM participe en el cálculo.

¿Para qué sirve?

Una vez instalado, le dices a la IA «analiza estos datos de ventas»; la IA ya no afirma sin base, sino que invoca 25 herramientas estadísticas reales: calcula estadísticos descriptivos, examina correlaciones, ejecuta pruebas de hipótesis, ajusta regresiones, hace agrupaciones (clustering), pronostica series temporales y dibuja gráficos en chino: cada número proviene de librerías estadísticas validadas, reproducible y trazable. El campo summary ofrece una conclusión en una línea en chino, y result devuelve los datos estructurados completos, por ejemplo:

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

¿Para quién es?

Qué problemas resuelve

Características y capacidades destacadas

1. Determinismo ante todo: todos los procesos aleatorios usan semilla fija (42); ejecutar dos veces el mismo archivo da resultados idénticos byte a byte (es la base de la trazabilidad; hay afirmaciones específicas en las pruebas).

2. Diseño antialucinación: las 25 herramientas de la primera capa tienen cero LLM; los textos de conclusión se generan con números insertados por plantilla de código; p<0.001 se muestra siempre como «<0.001»; cada conclusión incluye una declaración de limitaciones (correlación ≠ causalidad, si se hizo algo o no con los datos, tamaño de muestra).

3. Criterios fijados y recalculables: q1/q3 = interpolación lineal (mismo criterio que Excel QUARTILE.INC), asimetría/curtosis = criterio Fisher de scipy, std=ddof=1 (Excel STDEV.S) — la documentación lo hace explícito y las pruebas verifican de forma independiente las fórmulas manuales y las librerías estándar (223 pytest, cobertura en docs/).

4. Cadena completa en chino: nombres de columna en chino, codificación GBK con retroceso automático, gráficos con fuentes chinas, tipo de letra en chino (si no existe, cae a inglés y lo indica), mensajes de error en chino con sugerencia de solución.

5. Seguridad y protección: archivos locales únicamente, rechaza rutas UNC/NUL, sin subir nada a la red; protección de tamaño robusta: &>50MB / 200 filas / 500MB de memoria; también protección ante zip o xlsx bomba zip y rangos de fecha; salida de datos atípicos limitada por truncamiento (para que entradas maliciosas no bloqueen el proceso).

6. Los números tienen dueño (estructura y protocolo):

   • Éxito: {status:"ok", result:{...}, summary:"..."}

   • Error: {status:"error", message:"..."}

   • Imágenes: las herramientas que incluyen gráficos añaden __image__ en el nivel superior del JSON devuelto (ruta absoluta de la imagen; prohibido base64).

7. Integración fluida:

   • Todos los resultados son deterministas y reproducibles.

   • Cada summary es una frase de conclusión en chino.

   • Cada result es una estructura de datos completa.

   • Parámetros y valores devueltos documentados (equivalente a docstring completa).

   • Cada conclusión incluye limita el alcance (correlación–causalidad, si se ha corregido o no, tamaño de muestra).

8. Ingeniería completa: 12 documentos de diseño (tabla de parámetros/tabla de límites por herramienta + esquema JSON + método de verificación), configuración para clientes, cobertura de herramientas de 82–96%, ruff todo pase, smoke test del protocolo stdio.

Inicio rápido

# 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

Conectar Claude Code (.mcp.json en la raíz del proyecto):

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

Tres obligatorios: -m statlab_mcp.server (no introduzcas la ruta server.py), cwd apuntando a la raíz del proyecto y PYTHONUTF8=1. El resto de clientes (Cursor/VSCode/Codex/Hermes/DSH) se ven en docs/clients.md.

Primera llamada (se puede usar directamente desde la consola sin conectar un cliente):

.\.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))"

Tres leyes de hierro sobre los datos: ① solo se aceptan archivos csv/xlsx/tsv/json; una ruta absoluta cualquiera es válida (maneja automáticamente nombres chinos/GBK/cabras de valor/fechas incorrectas); ② los datos reales se guardan fuera del directorio del proyecto; ③ en cada análisis primero se lee el summary (un dato legal en chino) y después se mira result (el resultado completo).

Las 25 herramientas de un vistazo

Valor central y protocolo común

• Números trazables: resultados deterministicos, reproducibles y comprobables; para la misma entrada el resultado una y otra vez es igual (semilla global=42).

• Estructura uniforme: éxito {status:"ok", result:{...}, summary:"一句话中文结论"}; fallo {status:"error", message:"中文原因有效提示"} .

• Adjuntos de imagen: las herramientas que devuelven gráficos adjuntan __image__ en el nivel superior del JSON (ruta absoluta de imagen, prohibido base64).

Entorno previo (Windows)

1. Dependencia Python 3.13+, entorno virtual aislado (solo pip; prohibidos 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 es la única fuente canónica de dependencias (pyproject.toml solo describe los metadatos).

3. Configurar UTF-8 antes de ejecutar (si no, stdio escribe el JSON chino como GBK y la conexión MCP se rompe):

   $env:PYTHONUTF8="1"

   La parte superior del archivo de entrada del servidor también incluye sys.stdout.reconfigure(encoding="utf-8") para mitigación.

4. La lectura de los datos pasa por el envoltorio de read_table(): intente utf-8-sig, si falla, cambie automáticamente a csv/tsv gbk; si vuelve a fallar, da error en chino «No se puede reconocer la codificación del archivo; por favor guárdese como UTF-8»; lista blanca de extensiones {csv, xlsx, tsv, json}, xlsx se lee solo la primera hoja.

Cómo ven los agentes las imágenes

• DeepSeek Harness: use la herramienta read_image para leer la ruta absoluta que viene de __image__.

• Claude Code: use la herramienta Read para leer la misma ruta.

• Todas las imágenes se guardan en reports/plots/YYYYmmdd/ (por fecha, para no acumularlas), nombre de archivo 工具名_<主列名或all>_YYYYmmdd_HHMMSS_fff.png, fuente para chino Microsoft YaHei/SimHei (si falta, se pasa a inglés y se indica dentro del gráfico), dpi=150; el directorio se puede limpiar en cualquier momento (no afecta a ningún cálculo).

Declaración de seguridad

• Solo se analizan archivos que tú proporcionas; se rechazan rutas UNC/NUL; no se sube nada a la red.

• Aviso de trust en las rutas: la herramienta no valida el origen de archivos (lee lo que le pasas tal cual); no devuelvas rutas que no sean de fiar; guarda datos reales fuera del directorio del proyecto.

• Protección con datos: rechaza >50MB; para 5–50MB primero se estima número de filas/memoria y si supera se rechaza; hay protección de la expansión zip bomb y ante rangos de fecha extraños; salida atípica truncada con un tope para que la entrada maliciosa no lo bloquee.

Pruebas y aceptación

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

• Los datos de prueba se obtienen con tests/make_fixtures.py con semilla fija y se guardan; los números clave se comprueban con una calculadora independiente común (statistics.mean / tabla de valores esperados), y se prohíbe la circularidad en la verificación.

• Ciclo de aceptación (desde 2026-08-26 en modo «IA generada»): pytest correcto + dos tipos de datos probados y comparados (el stdout real se queda documento en el registro de aceptación) → commit + actualización de PROGRESS; los usuarios conservan el derecho a auditarlo en cualquier momento.

• Línea base: 223 pytest, cobertura de módulos 82–96%, ruff que pasa, resumen correcto del protocolo stdio.

Nota técnica (mcp 2.x)

Dependencia bloqueada en mcp==2.1.0: mcp.server.fastmcp.FastMCP ha sido reemplazado por mcp.server.mcpserver.MCPServer (API compatible, add_tool es compatible; el decorador tool; list_tools/call_tool/run_stdio_async son async).

Documentación

• docs/clients.md —— configuración de acceso para cada cliente (Claude Code/Cursor/VSCode/Codex/Hermes/DSH)

• docs/SPEC.md —— protocolo y criterios estadísticos (estructura de contenido, protocolo numérico, protocolo de imagen, comportamiento)

• docs/design/ —— diseño de interfaz de cada herramienta (parámetros, límites, esquema JSON, método de validación; manual de uso para agentes y desarrolladores)

• docs/example_report.md —— informe de ejemplo del esquema auto_analysis A (forma de demostración anticuerpo)

Estructura de directorios

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

Licencia

MIT (Copyright © 2026 Zhou Xiangyu).