Skip to main content
Glama

jamovi MCP

English | 简体中文

MCP-сервер для управления jamovi из MCP-клиентов. Он запускает локальный процесс движка jamovi, подключается через WebSocket/protobuf API jamovi и предоставляет инструменты для открытия наборов данных, чтения и записи данных, запуска анализов, экспорта результатов и сохранения файлов .omv.

Обзор jamovi MCP

Обзор архитектуры jamovi MCP

Возможности

  • Запуск и управление локальным процессом движка jamovi.

  • Открытие файлов .omv, .csv, .sav, .xlsx, .ods, .dta, .sas7bdat, .por и .txt.

  • Просмотр схемы набора данных, включая количество строк, количество столбцов, типы столбцов, типы измерений и уровни.

  • Чтение данных в формате JSON (построчно).

  • Запись значений в отдельные ячейки, включая пропущенные значения.

  • Список доступных анализов jamovi и просмотр схем опций из установленных модулей.

  • Запуск анализов и получение/экспорт результатов.

  • Сохранение активного набора данных в файл .omv.

Related MCP server: Malloy MCP Server

Архитектура

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 .
  1. Добавьте MCP-сервер в конфигурацию вашего MCP-клиента:

{
  "mcpServers": {
    "jamovi": {
      "command": "C:\\Python312\\python.exe",
      "args": ["-m", "jamovi_mcp"]
    }
  }
}
  1. Перезапустите MCP-клиент и вызовите jamovi_open с абсолютным путем к набору данных.

Рабочий процесс jamovi MCP

Инструменты

Этот сервер предоставляет 10 инструментов MCP.

Инструмент

Назначение

Основные аргументы

jamovi_open

Открыть локальный файл данных в jamovi.

file_path

jamovi_get_schema

Прочитать метаданные набора данных, столбцы, типы, уровни и количество строк.

Нет

jamovi_get_data

Прочитать прямоугольный диапазон данных в виде JSON-строк.

row_start, row_count, column_start, column_count

jamovi_set_data

Установить значение одной ячейки набора данных.

row, column, value

jamovi_list_analyses

Список анализов, обнаруженных в установленных модулях jamovi.

Нет

jamovi_get_analysis_options

Прочитать схему опций для одного анализа.

ns, name

jamovi_run_analysis

Запустить анализ для активного набора данных.

ns, name, options, analysis_id

jamovi_get_analysis

Получить результаты для ранее запущенного анализа.

analysis_id

jamovi_export_results

Экспортировать результаты анализа в виде текста или HTML.

analysis_id, fmt

jamovi_save

Сохранить активный набор данных как файл .omv.

file_path, overwrite

Примеры использования

Открыть 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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      A
      maintenance
      MCP server for interacting with Creo Parametric CAD software. Enables tool calls like file_open, feature_set, and J-Link execution through a Python-based server and optional Java gateway.
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      MCP server to drive a local JDownloader 2 instance through its entire download lifecycle, including adding links/containers, linkgrabber management, queue control, priority, force-start, progress tracking, and cleanup.
      17
      5
      MIT