GJQ-Runtime-MCP-Server

Model Context Protocol (MCP) 서버로, AI 어시스턴트가 gjq-client Python SDK를 통해 국제 양자 컴퓨팅 클라우드 플랫폼과 상호작용할 수 있도록 합니다.

기능

• 계정 관리: 클라우드 플랫폼 자격 증명 구성 및 확인

• 장치 관리: 백엔드 목록, 구성/보정 정보 조회, 가장 한가한 백엔드 가져오기

• 계산 작업: OpenQASM에서 샘플링(sampling) 및 기대값 추정(estimation) 작업 제출

• 작업 관리: 상태 폴링, 결과/로그/세부 정보 가져오기, 작업 나열

• 예제 회로: Bell/GHZ/중첩/무작위, MCP 리소스 형태로 제공

기능 시연

Related MCP server: mcp-qiskit

설치 및 시작 (Cursor 기준)

1. 저장소를 클론하고 가상 환경 생성

git clone <this-repo>
cd gjq-runtime-mcp-server
python -m venv .venv

# Windows
.\.venv\Scripts\activate
# Linux/macOS
source .venv/bin/activate

pip install -e .

2. .env.example을 .env로 이름 변경 후, GJQ_API_KEY=당신의_api_키 설정 (API 키는 https://www.tiangongqs.com/cloud에서 획득)

3. 로컬에서 MCP 서버 시작 (먼저 실행 가능 확인)

python -m gjq_runtime_mcp_server

4. 프로젝트 루트 디렉터리에 .cursor/mcp.json 생성

# Windows(该行去除)
{
  "mcpServers": {
    "gjq-runtime": {
      "command": ".venv\\Scripts\\python.exe",
      "args": ["-m", "gjq_runtime_mcp_server"],
      "cwd": "/path/to/gjq-runtime-mcp-server",
      "env": { "GJQ_API_KEY": "你的_api_key" }
    }
  }
}

# Linux/macOS(该行去除)
{
  "mcpServers": {
    "gjq-runtime": {
      "command": ".venv/bin/python",
      "args": ["-m", "gjq_runtime_mcp_server"],
      "cwd": "/path/to/gjq-runtime-mcp-server",
      "env": { "GJQ_API_KEY": "你的_api_key" }
    }
  }
}

5. Cursor에서 확인

• Cursor 프로세스를 완전히 종료한 후 다시 엽니다.

• Ctrl + Shift + P를 눌러 Open Customize를 열고 MCPs 탭을 선택합니다.

• gjq-runtime이 있는지 확인하고, 스위치를 켠 후 초록색 점이 표시되는지 확인합니다.

MCP 도구

• 계정: setup_gjq_account_tool, active_account_info_tool

• 장치: list_backends_tool, get_backend_configuration_tool, get_backend_properties_tool, least_busy_tool

• 계산: sample_tool, estimate_tool

• 작업: get_task_status_tool, get_task_result_tool, get_task_log_tool, get_task_detail_tool, list_my_tasks_tool

모든 도구는 {"status": "success" | "error", ...} 형식을 반환합니다.

회로 제출 시 OpenQASM 2.0은 기본 지원됩니다. OpenQASM 3 회로를 제출하려면 추가로 파싱 라이브러리를 설치하세요: pip install qiskit_qasm3_import.

MCP 리소스

gjq://status, circuits://bell-state, circuits://ghz-state, circuits://superposition, circuits://random

기타 MCP 클라이언트 설정

위 JSON은 Cursor, Claude Desktop 등 JSON 기반 설정 클라이언트에 적용됩니다.

Codex는 JSON 대신 TOML을 사용하므로, ~/.codex/config.toml에 다음 내용을 추가하세요 (최상위 테이블 이름은 mcp_servers여야 함):

[mcp_servers.gjq-runtime]
command = "/path/to/gjq-runtime-mcp-server/.venv/bin/python"
args = ["-m", "gjq_runtime_mcp_server"]
cwd = "/path/to/gjq-runtime-mcp-server"

[mcp_servers.gjq-runtime.env]
GJQ_API_KEY = "你的_api_key"

Agent 스킬

해당 스킬은 skills/gjq-quantum-runtime/에 있습니다. Cursor에서 사용하려면 해당 디렉터리를 .cursor/skills/ (프로젝트 수준) 또는 ~/.cursor/skills/ (개인 수준)에 복사하세요.

보안 설명

• API 키는 ~/.gjq_client/gjq_client_account.json 및 MCP 클라이언트 설정의 env에 평문으로 저장되므로, 기밀 정보로 취급하여 안전하게 보관하고 .env를 커밋하지 마십시오.

개발

pip install -e ".[test]"
pytest

라이선스

Apache License 2.0