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
}

列出可用分析，然后检查一个分析选项架构：

{}

{
  "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 分析方案。

贡献

欢迎提交 Pull Request。请保持更改集中，在提交前运行测试套件，并包含针对行为更改的测试。

对于兼容性工作，请包含测试时使用的 jamovi 版本、Windows 版本和 Python 版本。

仓库内容

应该提交的文件：

• README.md

• LICENSE

• .gitignore

• pyproject.toml

• src/

• tests/

不应该提交的文件和目录：

• lib/

• .pytest_cache/

• .ruff_cache/

• __pycache__/

• 本地 CSV/OMV/log/tmp 文件

• 私有的本地配置、令牌和 API 密钥

许可证

MIT