openquantum-mcp 0.1.0__py3-none-any.whl

openquantum_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""Open Quantum MCP server — agent tools for backends, jobs, and results."""
+
+__version__ = "0.1.0"

openquantum_mcp/__main__.py

@@ -0,0 +1,43 @@
+"""Entry point: python -m openquantum_mcp"""
+
+from __future__ import annotations
+
+import sys
+
+
+def main(argv: list[str] | None = None) -> None:
+    args = list(sys.argv[1:] if argv is None else argv)
+
+    if any(a in ("-h", "--help") for a in args):
+        print(
+            "usage: python -m openquantum_mcp [--help] [--version]\n"
+            "\n"
+            "Open Quantum MCP server (stdio). Set SDK credentials via\n"
+            "OPENQUANTUM_CLIENT_ID / OPENQUANTUM_CLIENT_SECRET or\n"
+            "OPENQUANTUM_SDK_KEY, then start this process from an MCP client.\n"
+            "\n"
+            "Docs: https://docs.openquantum.com/mcp/overview/\n"
+        )
+        return
+
+    if any(a in ("-V", "--version") for a in args):
+        from . import __version__
+
+        print(__version__)
+        return
+
+    if args:
+        print(
+            f"error: unrecognized arguments: {' '.join(args)}\n"
+            "Try 'python -m openquantum_mcp --help'.",
+            file=sys.stderr,
+        )
+        raise SystemExit(2)
+
+    from .server import run
+
+    run()
+
+
+if __name__ == "__main__":
+    main()

openquantum_mcp/auth.py

@@ -0,0 +1,91 @@
+"""Credential resolution and SDK client construction."""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass
+from typing import Optional, Tuple
+
+from openquantum_sdk.auth import ClientCredentials, ClientCredentialsAuth
+from openquantum_sdk.clients import ManagementClient, SchedulerClient
+
+from .config import McpConfig
+
+
+class AuthError(RuntimeError):
+    """Raised when credentials are missing or invalid."""
+
+
+def load_creds_from_file(path: str) -> ClientCredentials:
+    with open(path, "r", encoding="utf-8") as f:
+        data = json.load(f)
+    try:
+        return ClientCredentials(
+            client_id=data["client_id"], client_secret=data["client_secret"]
+        )
+    except KeyError as e:
+        raise AuthError(f"SDK key file missing field: {e}") from e
+
+
+def resolve_credentials() -> ClientCredentials:
+    """Resolve SDK credentials from environment (same rules as openquantum-sdk CLI)."""
+    sdk_key_env = os.getenv("OPENQUANTUM_SDK_KEY")
+    if sdk_key_env:
+        # Set-but-missing path is a config error, not a silent fallback.
+        if not os.path.exists(sdk_key_env):
+            raise AuthError(
+                f"OPENQUANTUM_SDK_KEY is set to {sdk_key_env!r}, but that path "
+                "does not exist. Fix the path or unset OPENQUANTUM_SDK_KEY and "
+                "use OPENQUANTUM_CLIENT_ID / OPENQUANTUM_CLIENT_SECRET instead."
+            )
+        return load_creds_from_file(sdk_key_env)
+
+    env_id = os.getenv("OPENQUANTUM_CLIENT_ID")
+    env_secret = os.getenv("OPENQUANTUM_CLIENT_SECRET")
+    if env_id and env_secret:
+        return ClientCredentials(client_id=env_id, client_secret=env_secret)
+
+    raise AuthError(
+        "Missing credentials. Set OPENQUANTUM_CLIENT_ID and "
+        "OPENQUANTUM_CLIENT_SECRET, or OPENQUANTUM_SDK_KEY to a JSON key file "
+        "from the Open Quantum portal (SDK keys)."
+    )
+
+
+@dataclass
+class SdkClients:
+    """Paired management + scheduler clients sharing auth."""
+
+    management: ManagementClient
+    scheduler: SchedulerClient
+    config: McpConfig
+
+
+def build_clients(config: Optional[McpConfig] = None) -> SdkClients:
+    cfg = config or McpConfig.from_env()
+    creds = resolve_credentials()
+    auth = ClientCredentialsAuth(
+        creds=creds,
+        keycloak_base=cfg.keycloak_base,
+        realm=cfg.keycloak_realm,
+    )
+    management = ManagementClient(base_url=cfg.management_base, auth=auth)
+    scheduler = SchedulerClient(
+        base_url=cfg.scheduler_base,
+        auth=auth,
+        management_client=management,
+    )
+    return SdkClients(management=management, scheduler=scheduler, config=cfg)
+
+
+def redact_secrets(text: str) -> str:
+    """Best-effort redaction of credential material from error strings."""
+    secret = os.getenv("OPENQUANTUM_CLIENT_SECRET") or ""
+    client_id = os.getenv("OPENQUANTUM_CLIENT_ID") or ""
+    out = text
+    if secret:
+        out = out.replace(secret, "[REDACTED_SECRET]")
+    if client_id and len(client_id) > 8:
+        out = out.replace(client_id, "[REDACTED_CLIENT_ID]")
+    return out

openquantum_mcp/config.py

@@ -0,0 +1,77 @@
+"""Environment-driven configuration for the MCP server."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+
+def _env_float(name: str, default: float) -> float:
+    raw = os.getenv(name)
+    if raw is None or raw.strip() == "":
+        return default
+    return float(raw)
+
+
+def _env_int(name: str, default: int) -> int:
+    raw = os.getenv(name)
+    if raw is None or raw.strip() == "":
+        return default
+    return int(raw)
+
+
+@dataclass(frozen=True)
+class McpConfig:
+    """Runtime configuration loaded from environment variables."""
+
+    max_credits: float = 10.0
+    default_wait_timeout_seconds: int = 600
+    default_poll_interval_seconds: float = 5.0
+    preparation_timeout_seconds: int = 300
+    preparation_poll_interval: float = 2.0
+    default_job_subcategory_id: str = "oth:oth"
+    default_shots: int = 128
+    max_result_raw_chars: int = 8_000
+    max_calibration_raw_chars: int = 8_000
+    submitted_with: str = "mcp"
+    management_base: str = "https://management.openquantum.com"
+    scheduler_base: str = "https://scheduler.openquantum.com"
+    keycloak_base: str = "https://id.openquantum.com"
+    keycloak_realm: str = "platform"
+
+    @classmethod
+    def from_env(cls) -> "McpConfig":
+        return cls(
+            max_credits=_env_float("OPENQUANTUM_MCP_MAX_CREDITS", 10.0),
+            default_wait_timeout_seconds=_env_int(
+                "OPENQUANTUM_MCP_WAIT_TIMEOUT_SECONDS", 600
+            ),
+            default_poll_interval_seconds=_env_float(
+                "OPENQUANTUM_MCP_POLL_INTERVAL_SECONDS", 5.0
+            ),
+            preparation_timeout_seconds=_env_int(
+                "OPENQUANTUM_MCP_PREP_TIMEOUT_SECONDS", 300
+            ),
+            default_job_subcategory_id=os.getenv(
+                "OPENQUANTUM_MCP_DEFAULT_SUBCATEGORY", "oth:oth"
+            ),
+            default_shots=_env_int("OPENQUANTUM_MCP_DEFAULT_SHOTS", 128),
+            max_result_raw_chars=_env_int(
+                "OPENQUANTUM_MCP_MAX_RESULT_RAW_CHARS", 8_000
+            ),
+            max_calibration_raw_chars=_env_int(
+                "OPENQUANTUM_MCP_MAX_CALIBRATION_RAW_CHARS", 8_000
+            ),
+            management_base=os.getenv(
+                "OPENQUANTUM_MANAGEMENT_BASE",
+                "https://management.openquantum.com",
+            ),
+            scheduler_base=os.getenv(
+                "OPENQUANTUM_SCHEDULER_BASE",
+                "https://scheduler.openquantum.com",
+            ),
+            keycloak_base=os.getenv(
+                "OPENQUANTUM_KEYCLOAK_BASE", "https://id.openquantum.com"
+            ),
+            keycloak_realm=os.getenv("OPENQUANTUM_KEYCLOAK_REALM", "platform"),
+        )

openquantum_mcp/logging_util.py

@@ -0,0 +1,50 @@
+"""Local-only structured logging for MCP tool calls (no secrets/circuits)."""
+
+from __future__ import annotations
+
+import logging
+import sys
+from typing import Any, Dict, Optional
+
+_LOG = logging.getLogger("openquantum_mcp")
+
+
+def configure_logging() -> None:
+    if _LOG.handlers:
+        return
+    handler = logging.StreamHandler(sys.stderr)
+    handler.setFormatter(
+        logging.Formatter("%(asctime)s %(levelname)s [openquantum_mcp] %(message)s")
+    )
+    _LOG.addHandler(handler)
+    _LOG.setLevel(logging.INFO)
+    _LOG.propagate = False
+
+
+def log_tool(
+    name: str,
+    *,
+    job_id: Optional[str] = None,
+    backend: Optional[str] = None,
+    shots: Optional[int] = None,
+    organization_id: Optional[str] = None,
+    extra: Optional[Dict[str, Any]] = None,
+    error: Optional[str] = None,
+) -> None:
+    parts = [f"tool={name}"]
+    if job_id:
+        parts.append(f"job_id={job_id}")
+    if backend:
+        parts.append(f"backend={backend}")
+    if shots is not None:
+        parts.append(f"shots={shots}")
+    if organization_id:
+        parts.append(f"org={organization_id}")
+    if extra:
+        for k, v in extra.items():
+            parts.append(f"{k}={v}")
+    if error:
+        parts.append(f"error={error}")
+        _LOG.error(" ".join(parts))
+    else:
+        _LOG.info(" ".join(parts))

openquantum_mcp/safety.py

@@ -0,0 +1,153 @@
+"""Spend gates: credit cap, Spark auto-spend, Full requires confirm."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+from openquantum_sdk.enums import ExecutionPlanType
+
+
+class SpendBlockedError(RuntimeError):
+    """Raised when submit is blocked by safety policy."""
+
+
+@dataclass(frozen=True)
+class SpendDecision:
+    allowed: bool
+    reason: str
+    requires_confirm: bool
+    estimated_credits: float
+    spark_credits: float
+    full_credits: float
+    plan_is_public: bool
+    would_use_full_credits: bool
+
+
+def is_public_plan(execution_plan_id: str) -> bool:
+    return execution_plan_id == ExecutionPlanType.PUBLIC.value
+
+
+def evaluate_spend(
+    *,
+    estimated_credits: float,
+    spark_credits: float,
+    full_credits: float,
+    execution_plan_id: str,
+    confirm_spend: bool,
+    max_credits: float,
+) -> SpendDecision:
+    """Decide whether a job create is allowed under MCP spend policy.
+
+    Policy (decided):
+    - Hard reject if estimated cost > max_credits (default 10).
+    - Free (cost == 0): allow without confirm.
+    - Public plan and spark_credits >= cost and cost <= max: auto-allow.
+    - Any spend that would consume Full credits: require confirm_spend=True.
+    """
+    plan_public = is_public_plan(execution_plan_id)
+    cost = float(estimated_credits)
+
+    if cost > max_credits:
+        return SpendDecision(
+            allowed=False,
+            reason=(
+                f"Estimated cost {cost} credits exceeds MCP hard cap of "
+                f"{max_credits}. Reduce shots/backend cost or raise "
+                f"OPENQUANTUM_MCP_MAX_CREDITS (not recommended without care)."
+            ),
+            requires_confirm=False,
+            estimated_credits=cost,
+            spark_credits=spark_credits,
+            full_credits=full_credits,
+            plan_is_public=plan_public,
+            would_use_full_credits=True,
+        )
+
+    if cost <= 0:
+        return SpendDecision(
+            allowed=True,
+            reason="Job is free (0 credits).",
+            requires_confirm=False,
+            estimated_credits=cost,
+            spark_credits=spark_credits,
+            full_credits=full_credits,
+            plan_is_public=plan_public,
+            would_use_full_credits=False,
+        )
+
+    # Public + enough Spark → auto-spend
+    if plan_public and spark_credits >= cost:
+        return SpendDecision(
+            allowed=True,
+            reason=(
+                f"Auto-approved: {cost} credits covered by Spark balance "
+                f"({spark_credits})."
+            ),
+            requires_confirm=False,
+            estimated_credits=cost,
+            spark_credits=spark_credits,
+            full_credits=full_credits,
+            plan_is_public=plan_public,
+            would_use_full_credits=False,
+        )
+
+    # Would use Full credits (Private plan and/or insufficient Spark)
+    would_use_full = True
+    if confirm_spend:
+        total_available = spark_credits + full_credits
+        if total_available < cost:
+            return SpendDecision(
+                allowed=False,
+                reason=(
+                    f"Insufficient credits: need {cost}, have spark="
+                    f"{spark_credits} full={full_credits}."
+                ),
+                requires_confirm=False,
+                estimated_credits=cost,
+                spark_credits=spark_credits,
+                full_credits=full_credits,
+                plan_is_public=plan_public,
+                would_use_full_credits=would_use_full,
+            )
+        return SpendDecision(
+            allowed=True,
+            reason=(
+                f"Approved with confirm_spend=true: {cost} credits "
+                f"(may use Full credits; spark={spark_credits}, full={full_credits})."
+            ),
+            requires_confirm=True,
+            estimated_credits=cost,
+            spark_credits=spark_credits,
+            full_credits=full_credits,
+            plan_is_public=plan_public,
+            would_use_full_credits=would_use_full,
+        )
+
+    why = (
+        "Private plan (Full credits only)"
+        if not plan_public
+        else (
+            f"Spark balance ({spark_credits}) is less than cost ({cost}); "
+            "would consume Full credits"
+        )
+    )
+    return SpendDecision(
+        allowed=False,
+        reason=(
+            f"Spend confirmation required: {why}. "
+            f"Re-call with confirm_spend=true to approve spending up to "
+            f"{cost} credits (cap {max_credits})."
+        ),
+        requires_confirm=True,
+        estimated_credits=cost,
+        spark_credits=spark_credits,
+        full_credits=full_credits,
+        plan_is_public=plan_public,
+        would_use_full_credits=would_use_full,
+    )
+
+
+def assert_spend_allowed(decision: SpendDecision) -> None:
+    if not decision.allowed:
+        raise SpendBlockedError(decision.reason)