GJQ-Runtime-MCP-Server

Model Context Protocol（MCP）サーバーで、AIアシスタントがgjq-clientPython 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_key を設定します。（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