GJQ-Runtime-MCP-Server

Un servidor Model Context Protocol (MCP) que permite a los asistentes de IA interactuar con la Plataforma de Computación Cuántica Nacional de China a través del SDK de Python gjq-client.

Funcionalidades

• Gestión de cuentas: Configurar y ver las credenciales de la plataforma en la nube

• Gestión de dispositivos: Listar backends, consultar información de configuración/calibración, obtener el backend menos ocupado

• Tareas de computación: Enviar tareas de muestreo (sampling) y estimación de valores esperados (estimation) desde OpenQASM

• Gestión de tareas: Consultar estado, obtener resultados/logs/detalles, listar tareas

• Circuitos de ejemplo: Bell/GHZ/Superposición/Aleatorio, proporcionados como recursos MCP

Demostración de funcionalidades

Related MCP server: mcp-qiskit

Instalación e inicio (con Cursor como ejemplo)

1. Clonar el repositorio y crear un entorno virtual

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. Renombrar .env.example a .env, y configurar GJQ_API_KEY=tu_api_key. (La clave API se obtiene de https://www.tiangongqs.com/cloud)

3. Iniciar el servidor MCP localmente (verificar primero que funcione)

python -m gjq_runtime_mcp_server

4. Crear .cursor/mcp.json en la raíz del proyecto

# 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. Verificar en Cursor

• Cerrar completamente el proceso de Cursor y volver a abrirlo.

• Usar Ctrl + Shift + P para abrir Open Customize, seleccionar la pestaña MCPs.

• Confirmar que aparece gjq-runtime, activar el interruptor y verificar que se muestra un punto verde.

Herramientas MCP

• Cuenta: setup_gjq_account_tool, active_account_info_tool

• Dispositivos: list_backends_tool, get_backend_configuration_tool, get_backend_properties_tool, least_busy_tool

• Computación: sample_tool, estimate_tool

• Tareas: get_task_status_tool, get_task_result_tool, get_task_log_tool, get_task_detail_tool, list_my_tasks_tool

Todas las herramientas devuelven {"status": "success" | "error", ...}.

Al enviar circuitos, OpenQASM 2.0 funciona directamente; si necesita enviar circuitos OpenQASM 3, instale la biblioteca de análisis adicional: pip install qiskit_qasm3_import.

Recursos MCP

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

Configuración para otros clientes MCP

El JSON anterior es adecuado para clientes basados en configuración JSON como Cursor, Claude Desktop, etc.

Codex usa TOML en lugar de JSON. Agregue lo siguiente en ~/.codex/config.toml (el nombre de la tabla superior debe ser 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"

Habilidades del agente

Las habilidades complementarias se encuentran en skills/gjq-quantum-runtime/. Para usarlas en Cursor, copie ese directorio a .cursor/skills/ (a nivel de proyecto) o ~/.cursor/skills/ (a nivel personal).

Nota de seguridad

• La clave API se almacena en texto plano en ~/.gjq_client/gjq_client_account.json y en el env de la configuración del cliente MCP. Trátela como confidencial y no suba el archivo .env.

Desarrollo

pip install -e ".[test]"
pytest

Licencia

Apache License 2.0