jamovi MCP

English | 简体中文

MCPクライアントからjamoviを制御するためのMCPサーバーです。ローカルのjamoviエンジンプロセスを起動し、jamoviのWebSocket/protobuf APIを介して接続し、データセットのオープン、データの読み書き、分析の実行、結果のエクスポート、および.omvファイルの保存を行うためのツールを提供します。

機能

• ローカルのjamoviエンジンプロセスの起動と管理。

• .omv, .csv, .sav, .xlsx, .ods, .dta, .sas7bdat, .por, および .txt ファイルのオープン。

• 行数、列数、列型、測定尺度、レベルを含むデータセットスキーマの検査。

• 行優先のJSON形式でのデータ読み取り。

• 欠損値を含む単一セル値の書き込み。

• インストール済みモジュールから利用可能なjamovi分析の一覧表示とオプションスキーマの検査。

• 分析の実行と結果の取得/エクスポート。

• アクティブなデータセットを.omvファイルとして保存。

アーキテクチャ

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

起動時に、EngineManagerはconfig.pyを通じてjamoviのインストール先を選択し、jamovi自身のbin/env.confからプロセス環境を構築してjamovi.serverを起動します。その後、MCPサーバーはJamoviConnectionを通じてそのローカルエンジンに接続します。ファイル操作にはjamoviのHTTPルートを使用し、データセットおよび分析操作にはバンドルされたprotobuf定義でエンコードされたWebSocketメッセージを使用します。

クイックスタート

1. Windowsにjamoviをインストールします。

2. Python 3.12以降をインストールします。

3. リポジトリのルートからこのパッケージをインストールします：

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

4. MCPクライアントの設定にMCPサーバーを追加します：

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

5. MCPクライアントを再起動し、データセットの絶対パスを指定してjamovi_openを呼び出します。

ツール

このサーバーは10個のMCPツールを提供します。

使用例

CSVファイルを開く：

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

アクティブなデータセットのスキーマを読み取る：

{}

最初の10行と最初の3列を読み取る：

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

単一のセル値を設定する：

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

アクティブなデータセットを保存する：

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

利用可能な分析を一覧表示し、1つの分析オプションスキーマを検査する：

{}

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

分析を実行する：

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

要件

• Windows

• Python 3.12以降

• ローカルにインストールされたjamovi

このプロジェクトはjamovi 2.6.19.0でテストされていますが、起動コードはそのバージョンに固定されていません。以下をサポートしています：

• 明示的なJAMOVI_HOME

• Program Files配下のjamovi*ディレクトリの自動検出

• jamovi自身のbin/env.confからの動的な環境設定

複数のjamoviバージョンがインストールされている場合、デフォルトで検出された最新のバージョンが選択されます。

互換性

ローカルで検証済み：

• Windows

• Python 3.12

• jamovi 2.6.19.0

設計上の互換性：

• 同じFrameworks、Resources、bin/env.conf、HTTPルート、WebSocket API、およびprotobufメッセージコントラクトを持つすべてのjamoviインストール。

• JAMOVI_HOMEによる明示的なバージョン選択。

• 標準のProgram Filesの場所に複数のjamovi*ディレクトリがインストールされている場合の、最新バージョンの自動選択。

既知の制限：

• 将来のjamoviリリースでjamovi.proto、WebSocketリクエスト型、またはHTTPのオープン/保存ルートが変更された場合、このMCPのアダプター更新とprotobufコードの再生成が必要になる可能性があります。

インストール

リポジトリのルートから：

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

ローカル開発用：

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

ローカルのlib/依存関係ターゲットディレクトリをコミットしないでください。依存関係はpyproject.tomlからインストールする必要があります。

jamoviの選択

デフォルトでは、サーバーは標準のWindowsインストール場所をスキャンし、最新の有効なjamoviインストールを使用します。

特定のjamoviバージョンを強制するには：

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

JAMOVI_HOMEは、FrameworksとResourcesを含むjamoviインストールディレクトリを指している必要があります。

MCPクライアントの設定

MCPサーバー設定の例：

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

jamoviのバージョンを自動検出したい場合は、JAMOVI_HOMEを省略してください：

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

Python 3.12以降を使用してください。古いデフォルトのpythonで実行すると、明確な起動エラーで失敗します。

テストの実行

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

テストスイートは以下をカバーしています：

• jamoviインストールの検出と環境解析

• HTTP保存エンドポイントの処理

• データブロックの列優先から行優先への変換

• set_dataリクエストの構築

開発

編集可能モードでインストール：

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

テストの実行：

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

MCPサーバーを直接起動：

C:\Python312\python.exe -m jamovi_mcp

重要なソース領域：

• src/jamovi_mcp/server.py: MCPサーバーとツールの登録。

• src/jamovi_mcp/engine.py: jamoviエンジンサブプロセスのライフサイクル。

• src/jamovi_mcp/config.py: jamoviインストールの検出と環境設定。

• src/jamovi_mcp/connection.py: HTTP、WebSocket、およびprotobuf通信。

• src/jamovi_mcp/tools/: MCPツールの実装。

• src/jamovi_mcp/analyses.py: jamoviモジュールのYAMLファイルから構築された分析レジストリ。

• tests/: データ変換、保存処理、設定、エンジン環境設定のユニットテスト。

lib/やその他のローカル依存関係ターゲットディレクトリをコミットしないでください。依存関係はpyproject.tomlを通じてインストールしてください。

トラブルシューティング

jamovi-mcp requires Python 3.12 or newer

MCPクライアントが古いデフォルトのpythonを使用している可能性があります。MCPコマンドをPython 3.12のフルパスに設定してください：

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

Invalid JAMOVI_HOME

JAMOVI_HOMEは、FrameworksとResourcesを含むjamoviインストールディレクトリを指している必要があります。

例：

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

jamoviはインストールされているが検出されない

MCPクライアントの設定でJAMOVI_HOMEを明示的に設定してください。これは特定のjamoviバージョンをテストする場合にも推奨されます。

ファイルのオープンまたは保存が失敗する

Windowsの絶対パスを使用し、MCPクライアントを実行しているユーザーがその場所を読み書きする権限を持っていることを確認してください。保存操作の場合、ターゲットファイルが既に存在する場合は"overwrite": trueを渡してください。

分析ツールが予期しない結果を返す

最初にjamovi_list_analysesを呼び出し、次にターゲット分析に対してjamovi_get_analysis_optionsを呼び出してください。jamoviの分析オプションスキーマはモジュール固有であり、バージョンやインストールされているモジュールによって異なる場合があります。

セキュリティに関する注意

このMCPはローカルのjamoviプロセスを起動し、MCPツール呼び出しを通じて提供されたパスのローカルファイルを読み書きします。

• エンジンはローカルで起動され、127.0.0.1を介して接続されます。

• ファイルパスはMCPクライアント/ユーザーによって提供されます。

• このサーバーを信頼できないクライアントに公開しないでください。

• 信頼できないMCPクライアントに機密データファイルを渡さないでください。

• プライベートなローカル設定、アクセストークン、APIキー、またはデータセットをコミットしないでください。

ロードマップ

• GitHub Actions CIの追加。

• より多くのjamoviバージョンにわたる広範な統合テストの追加。

• 分析結果ペイロードの構造化解析の改善。

• 各MCPツールに対するより明示的な型付きレスポンススキーマの追加。

• 一般的なjamovi分析レシピのドキュメント化。

貢献

プルリクエストを歓迎します。変更を集中させ、提出前にテストスイートを実行し、動作変更に対するテストを含めてください。

互換性に関する作業については、テストに使用したjamoviバージョン、Windowsバージョン、およびPythonバージョンを含めてください。

リポジトリの内容

コミットすべきファイル：

• README.md

• LICENSE

• .gitignore

• pyproject.toml

• src/

• tests/

コミットすべきではないファイルとディレクトリ：

• lib/

• .pytest_cache/

• .ruff_cache/

• __pycache__/

• ローカルのCSV/OMV/ログ/tmpファイル

• プライベートなローカル設定、トークン、およびAPIキー

ライセンス

MIT