statlab-mcp —— MCP-Server für statistische Analysen

Unabhängiges Projekt, keinerlei Verbindung zu offiziellen Plug-ins irgendeines Herstellers (histradem README-Hinweis: kein Bezug zu DeepSeek Harness). Damit erhalten KI-Agenten (Claude Code / Cursor / DeepSeek Harness / Codex usw.) echte statistische Fähigkeiten: Wenn LLMs Statistiken direkt im Kopf ausrechnen, erfinden sie Zahlen. Alle statistischen Ergebnisse dieses Projekts stammen aus realen Berechnungen (numpy / scipy / statsmodels / scikit-learn / pmdarima); die KI übernimmt nur Aufruf und Interpretation. Bei den 25 Tools der ersten Ebene ist jede Beteiligung eines LLM an der Berechnung verboten.

Was bringt es

Nach der Installation kannst du der KI sagen: „Analysiere mir diese Verkaufsdaten“ — dann behauptet sie nichts mehr aus der Luft, sondern ruft 25 echte Statistik-Tools auf: deskriptive Statistiken berechnen, Korrelationen prüfen, Hypothesentests durchführen, Regressionen fitten, Cluster analysieren, Zeitreihen prognostizieren, Diagramme mit chinesischen Beschriftungen zeichnen — jede Zahl stammt aus einer validierten Statistikbibliothek und ist reproduzierbar und nachvollziehbar. Das Feld summary liefert einen chinesischen Fazitsat, result die vollständigen strukturierten Daten, z. B.:

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

Für wen es geeignet ist

Welche Probleme es löst

Merkmale und herausragende Stärken

1. Determinismus an erster Stelle: Alle Zufallsprozesse mit festem Seed (42). Zweimal dieselbe Datei hinlaufen → byteweise identisches Ergebnis (das ist das Fundament für Nachvollziehbarkeit; dafür gibt es eigene Assertions in den Tests)

2. Anti-Halluzinationsdesign: Die 25 Tools der ersten Ebene nutzen kein LLM; Aussagen werden als Codetext mit eingefügten Zahlen generiert; p<0.001 wird einheitlich als „<0.001" dargestellt; jede Schlussfolgerung enthält immer einen Limitierungshinweis (Korrelation ≠ Kausalität, ob eine Korrektur — Stichprobenumfang)

3. Deinitivierter Method enable “rechnable”: q1/q3 = lineare Interpolation (gleichwertig zu Excel-QUARTILE.INC), Schiefe/Kurtosis = Fisher-Standard von scipy, std = ddof=1 (Excel-STDEV.S) — in der Doku klar beschrieben; Tests prüfen unabhängig gegen handisch berechnete Formeln und Standardbibliotheken (223 pytest, Abdeckung siehe docs/)

4. Durchgehend chinesische Ausrichtung: chinesischen Spaltennamen, automatischer Fallback auf GBK-Kodierunung, Diagramme mit chinesischer Schriftart (fehlt eine Software - Schriftart, automatischer Rückgriff auf Englisch mit Hinweis), chinesische Fehlnehmeldungen mit Lösungsvorschlägen

5. Sicherheit und Scharmut auf festem Niveau: Nur lokale Dateien, Ablehängung von UNC/NUL-Pfaden, keine Netzwerk-Uploads, Fächenster in 50 MB/2 Mio. Zeilen/500 MB-Speicher, Schutz vor xlsx-Zip-Bomben sowie Angriffen durch Datumsberg Spartan, außergewöhnliche Ausgaben werden zum Schutz abgeschnitten (verhindertachsen als mösste böswillige Eingaben)

6. Einheitliches Bedienverhalten: Alle Tools haben denselben Aufbau (Parameterprüfung → chinesische Fehlerfehlerungmeldung oder result+summary) und sind für Agents wie Menschen schmerzlos nutzbar; die MCP-Toolbesstd=Bestbeschreibung = vollständiger Docstring (Parametertabelle/Rückgabestruktur/Beispiel) — öffnet der Agent die Worksliste, hat er die Bedienungsanleitung

7. Vollständige Ingenieursarbeit: 12 Design-Dokumente (pro Tool Parameter-/Grenzfall-Tabellen/JSON-Schema/Validierungsmethode) + Client-Closure-Konfigs + Codeabdeckung 82–96% + ruff klarke ohne Befunde + stdio-Protokoll-Smoke

Kurzanleitung

# 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

Anbindung Claude Code (im Projektwurzelverzeichnis .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"}
    }
  }
}

Drei Dinge sind zwingend: -m statlab_mcp.server (nicht der Pfad zu server.py), cwd muss auf Wurzelverzeichnis zeigen und PYTHONUTF8=1 geset sein. Für andere Kimmen (Cursor/VSCode/Codex/Hermes/DSH) siehe: docs/clients.md.

Erster Aufruf (auch ganz ohne Client direkt an der Kommandozeile nutzbar):

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

Drei KerneRegeln für Daten: ① Es sind nur csv/xlsx/tsv/json erlaubt, absolute Pfade immer zulässig (Chinesisch/GBK-Schrei/Nullwerte/ungültige Datumsangaben läuft automatisch werden automatisch behandelt); ② echte Daten liegen außerhalb des Projektverzeichnisses; ③ bei jeder Analyse zuerst den chinesischen Fazist-Satz es in summary ansehen, erst danach die strukturierten Zahlen in result prüfen.

Alle 25 Tools im Überblick

Kernwerte und das einheitliche Protokoll

• Von Zahlen nachvollziehbar wiederholbar: Ergebnisse sind deterministisch, reproduzierbar und testbei; Bei gleicher Eingabe entweidessche zweimal das Ergebnis (global seed=42)

• Hülle immer gleich: bei Erfolg {status:"ok", result:{...}, summary:"一句话中文结论"}; bei Fehler {status:"error", message:"中文原因有效提示"}

• Bildanhänge: Tools mit Diagrammen fügen oben inihad ren retournen JSON das ____image__ (absoluten Pfad der Grafikdatei; base64 verboten)

Umgebungsaufratung (Windows)

1. Python3.13+ enthält installiert, eigene virtuelle Umgebung (nur pip; verwenden keine Manager wie 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 ist die einzige maßgebliche Quelle für Abhängigkeitlichen (pyproject.toml enthält nur Metadaten).

3. Vor dem Startalte angeordnet UTF-8 gesetzt werden (sonst schreibt stio mit GBK chinesisches JSON, die MCP-Verbindung bricht sofort ab):

$env:PYTHONUTF8="1"

Server-Einstiegsdatei ganz oben steht bereits eine Absicherung: sys.stdout.reconfigure(encoding=\"utf-8\").

4. Das Datenlesen läuft einheitlich über ihn durch den Wrapper read_table(): erstest utf-8-sig ausprobieren → bei Fehler von csv/tsv automatisch auf gbk umstellen → bei weiter Fehler erscheint die chinesische Fehlermeldung „DateiCodierung kann nicht erkannt werden, bitte as UTF-8 speichern“; Zulassungsliste {csv, xlsx, tsv, json} ; bei xlsx wird nur das erste Sheet gelesen.

So sieht der Agent die Bilder

• DeepSeed-Harness: mit dem Tool read_image den absoluten Pfad lesen, den __image__ zurückgibt

• Claude Code: mit dem Tool Readtfile lesen

• Alle Bilder werden unter reports/plots/YYYYmmdd/ abgelegt (nach Datum archiviert verhindert, dass sichanse viel anstaut), Dateiname 工具名_<主列名或all>_YYYYmmdd_HHMMSS_fff.png, chinesische Schriftarten Microsoft YaHei/SimHei (fehlt die Schrift logischerweise fallback auf Englisch und wird im Diagramm vermerkt), dpi=150; die Verzeichnisse können jederzeit gelöscht werden (alle Berechnungen bleiben unberührt)

Sicherheitshinweise

• Nur meint offizielle Dateien werden analysiert; UNC/NUL-Pfade werden abgelehnt; keine Netzwerk-Uploads

• Vertrauensersstatement a für Pfade: Die Tools prüfen die Quelle der Dateien (werden direkt mit übergebenen Pfad geladen)Tree — übergegebenen niemals Pfade aus unsicheren Quellen; echte Daten din diesem Projektsverzeichnis

• Schutz vor großen Datenmengen: Verzögerung bei > 50 MB/plus Mehr; 5–50 MB Zaun; zunächst werden Zeilen und Speicheranteil geschätzt, Überlauf abgelehnt; zip-Bom hader Datum-Bomb- und Zeitfetzerstellen sind ebenso hart geschützt sind.

Tests und Abnahme

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

• Testdaten werden von tests/make_fixtures.py erzeugt mit festem Seed und in die Testdatenbank abgelegt; wesentliche Zahlen werden gegen unabhängige Drittberechnungen verglichen (statistics.mean / Handsrechnungstabelle für entspruckte Werte); Zirkelbewmessung ist unter Strafe

• Laufverfahren (ab 2026-08-26 im Auto-KI-Modus): pytest vollständig grün + Prüfung per zwei reale Datensätze Verläufen ist (aktueller stdout bleibt vollständig in der Abnahme dokumentiert) → dann commit + Eintragung in PROGRESS; Nutzerinnen vorminduser jederzeit Stichproben-Vert erheben

• Qualitätsbasis: zw 223 pytest, Werkzeugmodul-Abdeckung 82–96 %, vollständiger ruff-Checklauf, stdio-Protokol ltraut strill ALL-STDIO-OK

Technische Notizen (mcp 2.x)

Abhängigkeit ist festgelegt auf mcp==2.1.0: mcp.server.fastmcp.FastMCP wurde ersetzt durch mcp.server.mcpserver.MCPServer (API-kompatibel mit add_tool/tool-Decoratorn, list_tools/call_task/run_stdio_async sind async).

Dokumentationsübersicht

• docs/clients.md — Konfiguration für den Anschluss der einzelnen Clients (Claude Code/Cursor/VSCode/Codex/Hermes/DSH)

• docs/SPEC.md —Protokoll und statistikDies hungDeterminik (Rückgabestruktur/Numerik-Protokoll/Bilder-Protokoll/Verhaltensguardheiten)

• docs/design/ — Sind die Zugriffe (Interfaces-Schnittstelle) Design-Quells (Parameters-Tabellen/ Grenzfallen-Tabellen/JSON-Schema/Validierungsmethoden; aufsErstens für Agenten und nachgeordnete Entwickler)

• docs/example_report.md — ein Beispiel-Report für die auto_analysis-Variante A (Demonstration der Anti-Halluzinationenvereinbarungen)

目录结构

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

Lizenz

MIT (Copyright © 2026 周翔宇)