GJQ-Runtime-MCP-Server

Ein Model Context Protocol (MCP)-Server, der KI-Assistenten über das gjq-client Python SDK die Interaktion mit der Guoji Quantum Computing Cloud Platform ermöglicht.

Funktionen

• Kontoverwaltung: Konfiguration und Anzeige der Cloud-Plattform-Anmeldeinformationen

• Geräteverwaltung: Auflisten von Backends, Abfragen von Konfigurations-/Kalibrierungsinformationen, Abrufen des am wenigsten ausgelasteten Backends

• Rechenaufgaben: Einreichen von Sampling- und Schätzung (Estimation)-Aufgaben aus OpenQASM

• Aufgabenverwaltung: Abfragen des Status, Abrufen von Ergebnissen/Logs/Details, Auflisten von Aufgaben

• Beispielschaltungen: Bell/GHZ/Überlagerung/Zufall, bereitgestellt als MCP-Ressourcen

Funktionsdemonstration

Related MCP server: mcp-qiskit

Installation und Start (am Beispiel von Cursor)

1. Repository klonen und virtuelle Umgebung erstellen

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 in .env umbenennen und GJQ_API_KEY=dein_api_key setzen. (API-Key von https://www.tiangongqs.com/cloud abrufen)

3. MCP-Server lokal starten (zuerst die Ausführbarkeit prüfen)

python -m gjq_runtime_mcp_server

4. Im Projektstammverzeichnis .cursor/mcp.json erstellen

# 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. In Cursor überprüfen

• Cursor-Prozess vollständig beenden und erneut öffnen.

• Mit Ctrl + Shift + P Open Customize öffnen, den Reiter MCPs auswählen.

• Sicherstellen, dass gjq-runtime vorhanden ist, den Schalter aktivieren und prüfen, ob ein grüner Punkt angezeigt wird.

MCP-Werkzeuge

• Konto: setup_gjq_account_tool, active_account_info_tool

• Geräte: list_backends_tool, get_backend_configuration_tool, get_backend_properties_tool, least_busy_tool

• Rechnen: sample_tool, estimate_tool

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

Alle Werkzeuge geben {"status": "success" | "error", ...} zurück.

OpenQASM 2.0-Schaltungen funktionieren sofort; für OpenQASM 3-Schaltungen muss zusätzlich die Parser-Bibliothek installiert werden: pip install qiskit_qasm3_import.

MCP-Ressourcen

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

Konfiguration anderer MCP-Clients

Das obige JSON ist für Cursor, Claude Desktop und andere JSON-basierte Clients geeignet.

Codex verwendet TOML statt JSON. Fügen Sie in ~/.codex/config.toml Folgendes hinzu (Der oberste Tabellenname muss mcp_servers sein):

[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-Fähigkeiten

Die zugehörigen Fähigkeiten befinden sich in skills/gjq-quantum-runtime/. Bei Verwendung in Cursor kopieren Sie das Verzeichnis nach .cursor/skills/ (projektebene) oder ~/.cursor/skills/ (benutzerebene).

Sicherheitshinweise

• Der API-Key wird im Klartext in ~/.gjq_client/gjq_client_account.json sowie in der env-Konfiguration des MCP-Clients gespeichert. Behandeln Sie ihn als vertraulich und committen Sie niemals .env.

Entwicklung

pip install -e ".[test]"
pytest

Lizenz

Apache License 2.0