jamovi MCP

Englisch | 简体中文

MCP-Server zur Steuerung von jamovi über MCP-Clients. Er startet einen lokalen jamovi-Engine-Prozess, verbindet sich über die WebSocket/Protobuf-API von jamovi und stellt Tools zum Öffnen von Datensätzen, zum Lesen und Schreiben von Daten, zum Ausführen von Analysen, zum Exportieren von Ergebnissen und zum Speichern von .omv-Dateien bereit.

Funktionen

• Starten und Verwalten eines lokalen jamovi-Engine-Prozesses.

• Öffnen von .omv-, .csv-, .sav-, .xlsx-, .ods-, .dta-, .sas7bdat-, .por- und .txt-Dateien.

• Überprüfen des Datensatzschemas, einschließlich Zeilenanzahl, Spaltenanzahl, Spaltentypen, Messtypen und Ebenen.

• Lesen von Daten im zeilenorientierten JSON-Format.

• Schreiben einzelner Zellenwerte, einschließlich fehlender Werte.

• Auflisten verfügbarer jamovi-Analysen und Überprüfen von Optionsschemata aus installierten Modulen.

• Ausführen von Analysen und Abrufen/Exportieren von Ergebnissen.

• Speichern des aktiven Datensatzes als .omv-Datei.

Architektur

flowchart LR
    Client["MCP Client"] --> Stdio["stdio MCP transport"]
    Stdio --> Server["jamovi_mcp.server"]

    Server --> ToolMap["Tool dispatcher"]
    ToolMap --> FileTools["tools.files"]
    ToolMap --> DataTools["tools.data"]
    ToolMap --> AnalysisTools["tools.analysis"]

    FileTools --> Connection["JamoviConnection"]
    DataTools --> Connection
    AnalysisTools --> Connection

    Server --> Engine["EngineManager"]
    Engine --> Config["config.py"]
    Config --> Discovery["JAMOVI_HOME or Program Files discovery"]
    Config --> EnvConf["bin/env.conf parsing"]
    Discovery --> JamoviInstall["Local jamovi installation"]
    EnvConf --> JamoviInstall

    Engine --> JamoviServer["jamovi.server subprocess"]
    JamoviInstall --> JamoviServer

    Connection --> HTTP["HTTP open/save endpoints"]
    Connection --> WS["WebSocket + protobuf coms"]
    HTTP --> JamoviServer
    WS --> JamoviServer

    AnalysisTools --> Registry["analyses.py registry"]
    Registry --> Modules["Resources/modules YAML"]
    Modules --> JamoviInstall

Beim Start wählt EngineManager eine jamovi-Installation über config.py aus, erstellt die Prozessumgebung aus jamovis eigener bin/env.conf und startet jamovi.server. Der MCP-Server verbindet sich dann über JamoviConnection mit dieser lokalen Engine. Dateioperationen nutzen die HTTP-Routen von jamovi, während Datensatz- und Analyseoperationen WebSocket-Nachrichten verwenden, die mit den mitgelieferten Protobuf-Definitionen kodiert sind.

Schnellstart

1. Installieren Sie jamovi unter Windows.

2. Installieren Sie Python 3.12 oder neuer.

3. Installieren Sie dieses Paket vom Repository-Stammverzeichnis aus:

C:\Python312\python.exe -m pip install -e .

4. Fügen Sie den MCP-Server zu Ihrer MCP-Client-Konfiguration hinzu:

{
  "mcpServers": {
    "jamovi": {
      "command": "C:\\Python312\\python.exe",
      "args": ["-m", "jamovi_mcp"]
    }
  }
}

5. Starten Sie Ihren MCP-Client neu und rufen Sie jamovi_open mit einem absoluten Pfad zum Datensatz auf.

Tools

Dieser Server stellt 10 MCP-Tools bereit.

Anwendungsbeispiele

Öffnen einer CSV-Datei:

{
  "file_path": "C:\\Users\\you\\data\\example.csv"
}

Lesen des Schemas des aktiven Datensatzes:

{}

Lesen der ersten 10 Zeilen und ersten 3 Spalten:

{
  "row_start": 0,
  "row_count": 10,
  "column_start": 0,
  "column_count": 3
}

Setzen eines einzelnen Zellenwerts:

{
  "row": 0,
  "column": 1,
  "value": 10
}

Speichern des aktiven Datensatzes:

{
  "file_path": "C:\\Users\\you\\data\\output.omv",
  "overwrite": true
}

Auflisten verfügbarer Analysen und anschließendes Überprüfen eines Analyse-Optionsschemas:

{}

{
  "ns": "jmv",
  "name": "ttestIS"
}

Ausführen einer Analyse:

{
  "ns": "jmv",
  "name": "ttestIS",
  "options": {
    "vars": ["score"],
    "students": true
  },
  "analysis_id": 2
}

Anforderungen

• Windows

• Python 3.12 oder neuer

• Lokal installiertes jamovi

Das Projekt wurde mit jamovi 2.6.19.0 getestet, aber der Startcode ist nicht an diese Version gebunden. Er unterstützt:

• explizites JAMOVI_HOME

• automatische Erkennung installierter jamovi*-Verzeichnisse unter Program Files

• dynamische Umgebungseinrichtung aus jamovis eigener bin/env.conf

Wenn mehrere jamovi-Versionen installiert sind, wird standardmäßig die neueste erkannte Version ausgewählt.

Kompatibilität

Lokal verifiziert:

• Windows

• Python 3.12

• jamovi 2.6.19.0

Geplante Kompatibilität:

• Jede jamovi-Installation mit denselben Frameworks, Resources, bin/env.conf, HTTP-Routen, WebSocket-API und Protobuf-Nachrichtenvertrag.

• Explizite Versionsauswahl über JAMOVI_HOME.

• Automatische Auswahl der neuesten Version, wenn mehrere jamovi*-Verzeichnisse unter Standard-Program-Files-Speicherorten installiert sind.

Bekannte Einschränkung:

• Wenn eine zukünftige jamovi-Version jamovi.proto, die WebSocket-Anfragetypen oder die HTTP-Öffnen/Speichern-Routen ändert, benötigt dieses MCP möglicherweise ein Adapter-Update und neu generierten Protobuf-Code.

Installation

Vom Repository-Stammverzeichnis aus:

C:\Python312\python.exe -m pip install -e .

Für die lokale Entwicklung:

C:\Python312\python.exe -m pip install -e .
C:\Python312\python.exe -m pip install pytest

Committen Sie kein lokales lib/-Abhängigkeitszielverzeichnis. Abhängigkeiten sollten über pyproject.toml installiert werden.

jamovi-Auswahl

Standardmäßig scannt der Server Standard-Windows-Installationsorte und verwendet die neueste gültige jamovi-Installation.

Um eine bestimmte jamovi-Version zu erzwingen:

$env:JAMOVI_HOME = "C:\Program Files\jamovi 2.6.19.0"
C:\Python312\python.exe -m jamovi_mcp

JAMOVI_HOME muss auf das jamovi-Installationsverzeichnis zeigen, das Frameworks und Resources enthält.

MCP-Client-Konfiguration

Beispiel für eine MCP-Server-Konfiguration:

{
  "mcpServers": {
    "jamovi": {
      "command": "C:\\Python312\\python.exe",
      "args": ["-m", "jamovi_mcp"],
      "env": {
        "JAMOVI_HOME": "C:\\Program Files\\jamovi 2.6.19.0"
      }
    }
  }
}

Wenn Sie eine automatische jamovi-Versionserkennung wünschen, lassen Sie JAMOVI_HOME weg:

{
  "mcpServers": {
    "jamovi": {
      "command": "C:\\Python312\\python.exe",
      "args": ["-m", "jamovi_mcp"]
    }
  }
}

Verwenden Sie Python 3.12 oder neuer. Der Betrieb mit einem älteren Standard-python schlägt mit einem klaren Startfehler fehl.

Tests ausführen

C:\Python312\python.exe -m pytest -q

Die Testsuite deckt ab:

• jamovi-Installationserkennung und Umgebungsparser

• Behandlung des HTTP-Speicher-Endpunkts

• Konvertierung von Datenblöcken von spaltenorientiert zu zeilenorientiert

• Erstellung von set_data-Anfragen

Entwicklung

Installation im editierbaren Modus:

C:\Python312\python.exe -m pip install -e .

Tests ausführen:

C:\Python312\python.exe -m pytest -q

Starten des MCP-Servers direkt:

C:\Python312\python.exe -m jamovi_mcp

Wichtige Quellbereiche:

• src/jamovi_mcp/server.py: MCP-Server und Tool-Registrierung.

• src/jamovi_mcp/engine.py: Lebenszyklus des jamovi-Engine-Subprozesses.

• src/jamovi_mcp/config.py: jamovi-Installationserkennung und Umgebungseinrichtung.

• src/jamovi_mcp/connection.py: HTTP-, WebSocket- und Protobuf-Kommunikation.

• src/jamovi_mcp/tools/: MCP-Tool-Implementierungen.

• src/jamovi_mcp/analyses.py: Analyseregistrierung, die aus jamovi-Modul-YAML-Dateien erstellt wurde.

• tests/: Unit-Tests für Datenkonvertierung, Speicherbehandlung, Konfiguration und Engine-Umgebungseinrichtung.

Committen Sie keine lib/- oder andere lokale Abhängigkeitszielverzeichnisse. Installieren Sie Abhängigkeiten über pyproject.toml.

Fehlerbehebung

jamovi-mcp requires Python 3.12 or newer

Ihr MCP-Client verwendet wahrscheinlich ein älteres Standard-python. Setzen Sie den MCP-Befehl auf den vollständigen Pfad zu Python 3.12:

{
  "command": "C:\\Python312\\python.exe",
  "args": ["-m", "jamovi_mcp"]
}

Invalid JAMOVI_HOME

JAMOVI_HOME muss auf das jamovi-Installationsverzeichnis zeigen, das Frameworks und Resources enthält.

Beispiel:

$env:JAMOVI_HOME = "C:\Program Files\jamovi 2.6.19.0"

jamovi ist installiert, wird aber nicht erkannt

Setzen Sie JAMOVI_HOME explizit in der MCP-Client-Konfiguration. Dies wird auch empfohlen, wenn eine bestimmte jamovi-Version getestet wird.

Datei öffnen oder speichern schlägt fehl

Verwenden Sie absolute Windows-Pfade und stellen Sie sicher, dass der Benutzer, der den MCP-Client ausführt, die Berechtigung zum Lesen oder Schreiben an diesem Ort hat. Übergeben Sie bei Speicheroperationen "overwrite": true, falls die Zieldatei bereits existiert.

Analyse-Tools liefern unerwartete Ergebnisse

Rufen Sie zuerst jamovi_list_analyses auf, dann jamovi_get_analysis_options für die Zielanalyse. jamovi-Analyse-Optionsschemata sind modulspezifisch und können zwischen Versionen oder installierten Modulen variieren.

Sicherheitshinweise

Dieses MCP startet einen lokalen jamovi-Prozess und liest oder schreibt lokale Dateien, deren Pfade über MCP-Tool-Aufrufe bereitgestellt werden.

• Die Engine wird lokal gestartet und über 127.0.0.1 verbunden.

• Dateipfade werden vom MCP-Client/Benutzer bereitgestellt.

• Setzen Sie diesen Server keinen nicht vertrauenswürdigen Clients aus.

• Geben Sie keine sensiblen Datendateien an einen MCP-Client weiter, dem Sie nicht vertrauen.

• Committen Sie keine privaten lokalen Konfigurationen, Zugriffstoken, API-Schlüssel oder Datensätze.

Roadmap

• Hinzufügen von GitHub Actions CI.

• Hinzufügen umfassenderer Integrationstests über mehr jamovi-Versionen hinweg.

• Verbesserung der strukturierten Analyse für Analyseergebnis-Nutzlasten.

• Hinzufügen expliziterer typisierter Antwortschemata für jedes MCP-Tool.

• Dokumentation gängiger jamovi-Analyse-Rezepte.

Mitwirken

Pull Requests sind willkommen. Bitte halten Sie Änderungen fokussiert, führen Sie die Testsuite vor dem Einreichen aus und fügen Sie Tests für Verhaltensänderungen hinzu.

Für Kompatibilitätsarbeiten geben Sie bitte die jamovi-Version, die Windows-Version und die für Tests verwendete Python-Version an.

Repository-Inhalt

Dateien, die committet werden sollten:

• README.md

• LICENSE

• .gitignore

• pyproject.toml

• src/

• tests/

Dateien und Verzeichnisse, die nicht committet werden sollten:

• lib/

• .pytest_cache/

• .ruff_cache/

• __pycache__/

• lokale CSV/OMV/Log/Tmp-Dateien

• private lokale Konfigurationen, Token und API-Schlüssel

Lizenz

MIT