jamovi MCP

English | 简体中文

MCP-сервер для управления jamovi из MCP-клиентов. Он запускает локальный процесс движка jamovi, подключается через WebSocket/protobuf API jamovi и предоставляет инструменты для открытия наборов данных, чтения и записи данных, запуска анализов, экспорта результатов и сохранения файлов .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 выбирает установку jamovi через config.py, создает среду процесса на основе собственного файла bin/env.conf jamovi и запускает jamovi.server. Затем MCP-сервер подключается к этому локальному движку через JamoviConnection. Файловые операции используют HTTP-маршруты jamovi, в то время как операции с наборами данных и анализами используют сообщения WebSocket, закодированные с помощью прилагаемых определений protobuf.

Быстрый старт

1. Установите jamovi на Windows.

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

• автоматическое обнаружение установленных каталогов jamovi* в Program Files

• динамическая настройка среды из собственного bin/env.conf jamovi

Если установлено несколько версий jamovi, по умолчанию выбирается самая новая обнаруженная версия.

Совместимость

Проверено локально:

• Windows

• Python 3.12

• jamovi 2.6.19.0

Запланированная совместимость:

• Любая установка jamovi с теми же Frameworks, Resources, bin/env.conf, HTTP-маршрутами, WebSocket API и контрактом сообщений protobuf.

• Явный выбор версии через JAMOVI_HOME.

• Автоматический выбор новейшей версии при наличии нескольких каталогов jamovi* в стандартных местах Program Files.

Известное ограничение:

• Если будущий релиз 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 должен указывать на каталог установки jamovi, содержащий Frameworks и Resources.

Конфигурация 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: реестр анализов, созданный из YAML-файлов модулей jamovi.

• 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 должен указывать на каталог установки jamovi, содержащий Frameworks и Resources.

Пример:

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

jamovi установлен, но не обнаружен

Явно установите JAMOVI_HOME в конфигурации MCP-клиента. Это также рекомендуется при тестировании конкретной версии jamovi.

Ошибка открытия или сохранения файла

Используйте абсолютные пути Windows и убедитесь, что у пользователя, запускающего MCP-клиент, есть разрешение на чтение или запись в этом месте. Для операций сохранения передайте "overwrite": true, если целевой файл уже существует.

Инструменты анализа возвращают неожиданные результаты

Сначала вызовите jamovi_list_analyses, затем jamovi_get_analysis_options для целевого анализа. Схемы опций анализа jamovi зависят от модуля и могут различаться в зависимости от версий или установленных модулей.

Примечания по безопасности

Этот MCP запускает локальный процесс jamovi и читает или записывает локальные файлы, пути к которым предоставляются через вызовы инструментов MCP.

• Движок запускается локально и подключается через 127.0.0.1.

• Пути к файлам предоставляются MCP-клиентом/пользователем.

• Не предоставляйте доступ к этому серверу ненадежным клиентам.

• Не передавайте конфиденциальные файлы данных MCP-клиенту, которому вы не доверяете.

• Не добавляйте в репозиторий частную локальную конфигурацию, токены доступа, ключи API или наборы данных.

Дорожная карта

• Добавить CI через GitHub Actions.

• Добавить более широкие интеграционные тесты для различных версий jamovi.

• Улучшить структурированный парсинг полезных нагрузок результатов анализа.

• Добавить более явные типизированные схемы ответов для каждого инструмента MCP.

• Документировать общие рецепты анализа jamovi.

Участие в разработке

Pull-запросы приветствуются. Пожалуйста, делайте изменения сфокусированными, запускайте набор тестов перед отправкой и включайте тесты для изменений поведения.

Для работы над совместимостью укажите версию jamovi, версию Windows и версию Python, использованные для тестирования.

Содержимое репозитория

Файлы, которые следует добавлять в репозиторий:

• README.md

• LICENSE

• .gitignore

• pyproject.toml

• src/

• tests/

Файлы и каталоги, которые не следует добавлять:

• lib/

• .pytest_cache/

• .ruff_cache/

• __pycache__/

• локальные файлы CSV/OMV/log/tmp

• частная локальная конфигурация, токены и ключи API

Лицензия

MIT