statlab-mcp — MCP-сервер для статистического анализа

Независимый проект, не связан с официальными плагинами ни одного производителя (историческое примечание в README: отношения к DeepSeek Harness не имеет). Даёт AI-агентам (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»; кажный вывод всегда сопровождается ограничениями (корреляция ≠ причинность, что уже correction applied, sample size).

3. Методики зафиксированы можно пересчитать: q1/q3 = linear interpolation (совпадает с Excel QUARTILE.INC), skewness/в Europe (kurtosis принимается по Формуле scipy Fisher, std=1 — Excel STDEV.S) — в документации, тесты независимо сверяются с альтернативными формулами и стандартными библиотеками (223 тест, список тестов см. в docs/).

4. Полный путь на китайском: китайские названия колонок, автоподборка кодировки GBK, графики с китайскими шрифтами (при отсутствии шрифта — дефолт на английский с пометкой), сообщения об ошибках на китайском с предложениями по решения.

5. Жёсткая безопасность и защита: только локальные файлы; отказ путей UNC/NUL; никаких сетевых загрузок; тройная защита >50 МБ / 2 млн строк / 500 МБ памяти; защита от zip-бомб и дыр по датам в xlsx; аварийный выход обрезан по лимиту (чтобы злоумышленных входных данных не «подвесили» процесс).

6. Единый опыт вызова: все инструменты однотипные (проверка параметров → ошибка на русском либо result+summary), справиться и агент, и человек; описание MCP-инструментов = полный docstring (таблица parameters/структура возврата/примеры) — у агента список инструментов уже является инструкцией по применению.

7. Инженерная завершённость: 12 проектных документов (по каждому инструменту параметры/границы/JSON Schema/методы проверки) + конфигурации подключения клиентов + покрытие 82–96 % + полный прогон ruff + smoke-тест протокола 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 / Shame / Harmes) см. 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 инструментов

Wait seasonal decompose: original "seasonal_decompose" transparent. Keep.

Основные ценности и единый протокол

• За результаты — полный разбор: результаты детерминированы, воспроизводимы, тестируемы, один и тот же вход и повторный запуск дают один результат (глобальный java seed=42).

• Единая структура: в случае успеха {status:"ok", result:{...}, summary:"一句话中文结论"}; при ошибке {status:"error", message:"中文原因有效提示"}.

• Изображения как вложение: инструменты, возвращающие графику, добавляют в верхний уровень JSON __image__ (абсолютный путь к файлу; base64 запрещено).

Подготовка окружения (Windows)

1. Требуется Python 3.13 и старше, отдельный virtualenv (только 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 (иначе Python отправит Chinese JSON через uCodepage GBK и MCP-подключение упадёт):

   $env:PYTHONUTF8="1"

   В верхней точки файла-входа также подключён защитный sys.stdout.reconfigure(encoding="utf-8").

4. Все данные читаются через обёртку read_table(): пробуется utf-8-sig → если csv/tsv read не получился, автоматически switching к 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=300; директорию можно чистить в любой момент (на вычисления не влияет).

Патент безопасности

• Выполняется анализ только явно переданных локальных файловых файлов; отказ путей UNC/NNS и NIC paths; никакой передачи в сеть.

• Заявление о доверии к пути: инструмент не проверяет источник файла (читает напрямую тому же пути), поэтому не принимайте пути из непроверенных источников; реальные данные кладите вне каталога проекта.

• Защита больших данных: >50Mb — отказ; 5–50Mb сначала оцениваем количество строк и память; при превышении → отказ; zip-бомб и attack через большие даты тоже защищены.

Тестирование и сдача

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

• Тестовые данные генерируются tests/make_fixtures.py seed way, создающим случай deterministically, and stored; ключевые числа проверяются про реальными независимыми расчётами (statistics.mean / таблицы ожидаемых значений), без кругового обоснования.

• Процедура сдачи (с 2026-08-26 in mode «drop»): round all-greens + verify on two datasets with stdout archived in record — request + PROGRESS registration; requester retains right to spot-check.

• The base: thr tests, coverage instrumentation methods 82–96%, full pass by ruff, stdio-smoke protocol “ALL-STDIO-OK”.

Технические заметки (mcp 2.x)

Зафиксирована зависимость mcp 2.1.0: mcp.server.fastmcp.FastMCP вытеснён сервером mcp.server.mcpserver.MCPServer (совместим с add\_tool/tool decoration, list_tools/call_tool/l.connect/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(“защита от выдумывания” как образц) .

Структура каталога

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

Lisense

MIT (Copyright © 2026 周翔宇)