GJQ-Runtime-MCP-Server

Сервер Model Context Protocol (MCP), который позволяет AI-ассистентам взаимодействовать с Национальной квантовой облачной платформой через Python SDK gjq-client.

Возможности

• Управление аккаунтом: настройка и просмотр учётных данных облачной платформы

• Управление устройствами: список бэкендов, запрос конфигурации/калибровочной информации, получение наименее загруженного бэкенда

• Вычислительные задачи: отправка задач сэмплирования (sampling) и оценки ожиданий (estimation) из OpenQASM

• Управление задачами: опрос статуса, получение результатов/логов/деталей, список задач

• Примеры схем: 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 подходит для клиентов на основе JSON, таких как Cursor, Claude Desktop и других.

Codex использует TOML вместо JSON. Добавьте следующее в ~/.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"

Навыки агента

Соответствующие навыки находятся в skills/gjq-quantum-runtime/. При использовании в Cursor скопируйте этот каталог в .cursor/skills/ (на уровне проекта) или ~/.cursor/skills/ (на уровне пользователя).

Замечания по безопасности

• API-ключ хранится в открытом виде в ~/.gjq_client/gjq_client_account.json, а также в env конфигурации MCP-клиента. Храните его как конфиденциальную информацию, ни в коем случае не коммитьте .env.

Разработка

pip install -e ".[test]"
pytest

Лицензия

Apache License 2.0