jamovi MCP

English | 简体中文

MCP 클라이언트에서 jamovi를 제어하기 위한 MCP 서버입니다. 로컬 jamovi 엔진 프로세스를 시작하고, jamovi의 WebSocket/protobuf API를 통해 연결하며, 데이터셋 열기, 데이터 읽기 및 쓰기, 분석 실행, 결과 내보내기, .omv 파일 저장을 위한 도구를 제공합니다.

기능

• 로컬 jamovi 엔진 프로세스 시작 및 관리.

• .omv, .csv, .sav, .xlsx, .ods, .dta, .sas7bdat, .por, .txt 파일 열기.

• 행 수, 열 수, 열 유형, 측정 유형, 수준을 포함한 데이터셋 스키마 검사.

• 행 우선(row-major) 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 분석 레시피 문서화.

기여

풀 리퀘스트를 환영합니다. 변경 사항을 집중적으로 유지하고, 제출하기 전에 테스트 제품군을 실행하며, 동작 변경에 대한 테스트를 포함하십시오.

호환성 작업의 경우 테스트에 사용된 jamovi 버전, Windows 버전 및 Python 버전을 포함하십시오.

저장소 내용

커밋해야 할 파일:

• README.md

• LICENSE

• .gitignore

• pyproject.toml

• src/

• tests/

커밋하지 말아야 할 파일 및 디렉토리:

• lib/

• .pytest_cache/

• .ruff_cache/

• __pycache__/

• 로컬 CSV/OMV/log/tmp 파일

• 개인 로컬 구성, 토큰 및 API 키

라이선스

MIT