jamovi MCP

Inglés | 简体中文

Servidor MCP para controlar jamovi desde clientes MCP. Inicia un proceso de motor de jamovi local, se conecta a través de la API WebSocket/protobuf de jamovi y expone herramientas para abrir conjuntos de datos, leer y escribir datos, ejecutar análisis, exportar resultados y guardar archivos .omv.

Características

• Iniciar y gestionar un proceso de motor de jamovi local.

• Abrir archivos .omv, .csv, .sav, .xlsx, .ods, .dta, .sas7bdat, .por y .txt.

• Inspeccionar el esquema del conjunto de datos, incluyendo el recuento de filas, el recuento de columnas, los tipos de columna, los tipos de medida y los niveles.

• Leer datos en formato JSON de orden de filas (row-major).

• Escribir valores de celdas individuales, incluyendo valores faltantes.

• Listar los análisis de jamovi disponibles e inspeccionar los esquemas de opciones de los módulos instalados.

• Ejecutar análisis y recuperar/exportar resultados.

• Guardar el conjunto de datos activo como un archivo .omv.

Arquitectura

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

Al inicio, EngineManager selecciona una instalación de jamovi a través de config.py, construye el entorno del proceso a partir del propio bin/env.conf de jamovi y lanza jamovi.server. El servidor MCP luego se conecta a ese motor local a través de JamoviConnection. Las operaciones de archivo utilizan las rutas HTTP de jamovi, mientras que las operaciones de conjunto de datos y análisis utilizan mensajes WebSocket codificados con las definiciones de protobuf incluidas.

Inicio rápido

1. Instale jamovi en Windows.

2. Instale Python 3.12 o superior.

3. Instale este paquete desde la raíz del repositorio:

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

4. Agregue el servidor MCP a la configuración de su cliente MCP:

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

5. Reinicie su cliente MCP y llame a jamovi_open con una ruta absoluta al conjunto de datos.

Herramientas

Este servidor expone 10 herramientas MCP.

Ejemplos de uso

Abrir un archivo CSV:

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

Leer el esquema del conjunto de datos activo:

{}

Leer las primeras 10 filas y las primeras 3 columnas:

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

Establecer el valor de una sola celda:

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

Guardar el conjunto de datos activo:

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

Listar los análisis disponibles, luego inspeccionar el esquema de opciones de un análisis:

{}

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

Ejecutar un análisis:

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

Requisitos

• Windows

• Python 3.12 o superior

• jamovi instalado localmente

El proyecto se prueba con jamovi 2.6.19.0, pero el código de inicio no está fijado a esa versión. Soporta:

• JAMOVI_HOME explícito

• Descubrimiento automático de directorios jamovi* instalados en Program Files

• Configuración dinámica del entorno desde el propio bin/env.conf de jamovi

Si hay varias versiones de jamovi instaladas, se selecciona por defecto la versión detectada más reciente.

Compatibilidad

Verificado localmente:

• Windows

• Python 3.12

• jamovi 2.6.19.0

Compatibilidad diseñada:

• Cualquier instalación de jamovi con los mismos Frameworks, Resources, bin/env.conf, rutas HTTP, API WebSocket y contrato de mensajes protobuf.

• Selección de versión explícita a través de JAMOVI_HOME.

• Selección automática de la versión más reciente cuando hay varios directorios jamovi* instalados en las ubicaciones estándar de Program Files.

Limitación conocida:

• Si una futura versión de jamovi cambia jamovi.proto, los tipos de solicitud WebSocket o las rutas de apertura/guardado HTTP, este MCP podría necesitar una actualización del adaptador y código protobuf regenerado.

Instalación

Desde la raíz del repositorio:

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

Para desarrollo local:

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

No confirme un directorio de destino de dependencia local lib/. Las dependencias deben instalarse desde pyproject.toml.

Selección de jamovi

Por defecto, el servidor escanea las ubicaciones de instalación estándar de Windows y utiliza la instalación de jamovi válida más reciente.

Para forzar una versión específica de jamovi:

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

JAMOVI_HOME debe apuntar al directorio de instalación de jamovi que contiene Frameworks y Resources.

Configuración del cliente MCP

Ejemplo de configuración del servidor MCP:

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

Si desea el descubrimiento automático de la versión de jamovi, omita JAMOVI_HOME:

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

Utilice Python 3.12 o superior. Ejecutar con un python predeterminado más antiguo fallará con un error de inicio claro.

Ejecución de pruebas

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

El conjunto de pruebas cubre:

• Descubrimiento de instalación de jamovi y análisis de entorno

• Manejo del punto final de guardado HTTP

• Conversión de bloque de datos de orden de columnas a orden de filas

• Construcción de la solicitud set_data

Desarrollo

Instalar en modo editable:

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

Ejecutar pruebas:

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

Iniciar el servidor MCP directamente:

C:\Python312\python.exe -m jamovi_mcp

Áreas de código fuente importantes:

• src/jamovi_mcp/server.py: Servidor MCP y registro de herramientas.

• src/jamovi_mcp/engine.py: Ciclo de vida del subproceso del motor de jamovi.

• src/jamovi_mcp/config.py: Descubrimiento de instalación de jamovi y configuración del entorno.

• src/jamovi_mcp/connection.py: Comunicación HTTP, WebSocket y protobuf.

• src/jamovi_mcp/tools/: Implementaciones de herramientas MCP.

• src/jamovi_mcp/analyses.py: Registro de análisis construido a partir de archivos YAML de módulos de jamovi.

• tests/: Pruebas unitarias para conversión de datos, manejo de guardado, configuración y configuración del entorno del motor.

No confirme lib/ u otros directorios de destino de dependencias locales. Instale las dependencias a través de pyproject.toml.

Solución de problemas

jamovi-mcp requires Python 3.12 or newer

Su cliente MCP probablemente esté usando un python predeterminado más antiguo. Establezca el comando MCP en la ruta completa de Python 3.12:

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

Invalid JAMOVI_HOME

JAMOVI_HOME debe apuntar al directorio de instalación de jamovi que contiene Frameworks y Resources.

Ejemplo:

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

jamovi está instalado pero no se detecta

Establezca JAMOVI_HOME explícitamente en la configuración del cliente MCP. Esto también se recomienda al probar una versión específica de jamovi.

La apertura o el guardado de archivos falla

Utilice rutas absolutas de Windows y asegúrese de que el usuario que ejecuta el cliente MCP tenga permiso para leer o escribir en esa ubicación. Para operaciones de guardado, pase "overwrite": true si el archivo de destino ya existe.

Las herramientas de análisis devuelven resultados inesperados

Primero llame a jamovi_list_analyses, luego a jamovi_get_analysis_options para el análisis de destino. Los esquemas de opciones de análisis de jamovi son específicos del módulo y pueden diferir entre versiones o módulos instalados.

Notas de seguridad

Este MCP inicia un proceso local de jamovi y lee o escribe archivos locales cuyas rutas se proporcionan a través de llamadas a herramientas MCP.

• El motor se inicia localmente y se conecta a través de 127.0.0.1.

• Las rutas de archivo son proporcionadas por el cliente/usuario de MCP.

• No exponga este servidor a clientes no confiables.

• No pase archivos de datos confidenciales a un cliente MCP en el que no confíe.

• No confirme configuraciones locales privadas, tokens de acceso, claves API o conjuntos de datos.

Hoja de ruta

• Agregar CI de GitHub Actions.

• Agregar pruebas de integración más amplias en más versiones de jamovi.

• Mejorar el análisis estructurado para cargas útiles de resultados de análisis.

• Agregar esquemas de respuesta tipados más explícitos para cada herramienta MCP.

• Documentar recetas comunes de análisis de jamovi.

Contribución

Las solicitudes de extracción (pull requests) son bienvenidas. Mantenga los cambios enfocados, ejecute el conjunto de pruebas antes de enviar e incluya pruebas para los cambios de comportamiento.

Para el trabajo de compatibilidad, incluya la versión de jamovi, la versión de Windows y la versión de Python utilizadas para las pruebas.

Contenido del repositorio

Archivos que deben confirmarse:

• README.md

• LICENSE

• .gitignore

• pyproject.toml

• src/

• tests/

Archivos y directorios que no deben confirmarse:

• lib/

• .pytest_cache/

• .ruff_cache/

• __pycache__/

• archivos locales CSV/OMV/log/tmp

• configuraciones locales privadas, tokens y claves API

Licencia

MIT