Metadata-Version: 2.4
Name: openquantum-mcp
Version: 0.1.0
Summary: Model Context Protocol server for Open Quantum — run quantum jobs from AI coding agents
License-Expression: Apache-2.0
Project-URL: Homepage, https://www.openquantum.com
Project-URL: Documentation, https://docs.openquantum.com/mcp/overview/
Project-URL: Bug Tracker, https://github.com/Quantum-Rings/openquantum-platform/issues
Project-URL: Source, https://github.com/Quantum-Rings/openquantum-platform/tree/main/mcp
Keywords: quantum,mcp,model-context-protocol,openquantum,ai-agents
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: openquantum-sdk>=0.4.2
Requires-Dist: mcp<2,>=1.6.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: pytest-mock>=3.10; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Dynamic: license-file

# openquantum-mcp

[Model Context Protocol](https://modelcontextprotocol.io) (MCP) server for [Open Quantum](https://www.openquantum.com).

Any MCP-compatible client (Claude, Cursor, VS Code, Grok, and others) can discover backends, submit quantum jobs, wait for completion, and summarize results using your Open Quantum SDK credentials.

One stdio server, standard MCP tools — nothing client-specific in the package.

**Docs:** [docs.openquantum.com/mcp](https://docs.openquantum.com/mcp/overview/)

## Install

```bash
pip install openquantum-sdk openquantum-mcp
```

Requires **Python 3.10+**. `openquantum-mcp` depends on `openquantum-sdk` and installs it if needed:

```bash
pip install openquantum-mcp
```

Verify without starting the stdio server:

```bash
python -c "import openquantum_mcp; print(openquantum_mcp.__version__)"
python -m openquantum_mcp --version
python -m openquantum_mcp --help
```

## Authentication

Use the same SDK key credentials as the Core SDK ([portal SDK keys](https://www.openquantum.com/keys)):

| Variable | Meaning |
|----------|---------|
| `OPENQUANTUM_CLIENT_ID` | SDK key client id |
| `OPENQUANTUM_CLIENT_SECRET` | SDK key secret |
| `OPENQUANTUM_SDK_KEY` | Path to JSON key file (`client_id` + `client_secret`) |

If `OPENQUANTUM_SDK_KEY` is set but the file is missing, startup/auth fails with a clear path error (no silent fallback).

Optional configuration:

| Variable | Default | Meaning |
|----------|---------|---------|
| `OPENQUANTUM_MCP_MAX_CREDITS` | `10` | Hard cap on estimated credits per job |
| `OPENQUANTUM_MCP_WAIT_TIMEOUT_SECONDS` | `600` | Default `wait_for_job` timeout when the tool arg is omitted |
| `OPENQUANTUM_MCP_POLL_INTERVAL_SECONDS` | `5` | Default `wait_for_job` poll interval when omitted |
| `OPENQUANTUM_MCP_PREP_TIMEOUT_SECONDS` | `300` | Job preparation wait timeout |
| `OPENQUANTUM_MCP_DEFAULT_SHOTS` | `128` | Default shots when omitted |
| `OPENQUANTUM_MCP_DEFAULT_SUBCATEGORY` | `oth:oth` | Default job subcategory |
| `OPENQUANTUM_MCP_MAX_RESULT_RAW_CHARS` | `8000` | Cap on raw result text |
| `OPENQUANTUM_MCP_MAX_CALIBRATION_RAW_CHARS` | `8000` | Cap on raw calibration text |
| `OPENQUANTUM_MANAGEMENT_BASE` | production | Override management API base URL |
| `OPENQUANTUM_SCHEDULER_BASE` | production | Override scheduler API base URL |
| `OPENQUANTUM_KEYCLOAK_BASE` | production | Override Keycloak base URL |
| `OPENQUANTUM_KEYCLOAK_REALM` | `platform` | Keycloak realm |

## Run

```bash
export OPENQUANTUM_CLIENT_ID=...
export OPENQUANTUM_CLIENT_SECRET=...
python -m openquantum_mcp
# or
openquantum-mcp
```

## MCP client configuration

Point your client at a Python environment where `openquantum-mcp` is installed, and pass credentials in the server `env`. Exact config file locations differ by host; the process definition is the same:

```json
{
  "mcpServers": {
    "openquantum": {
      "command": "python",
      "args": ["-m", "openquantum_mcp"],
      "env": {
        "OPENQUANTUM_CLIENT_ID": "...",
        "OPENQUANTUM_CLIENT_SECRET": "..."
      }
    }
  }
}
```

Prefer an absolute path to `python` if the client does not inherit your shell PATH (for example, `/path/to/venv/bin/python`).

## Tools

| Tool | Purpose |
|------|---------|
| `list_organizations` | Organizations for the account |
| `get_credits` | Spark and Full credit balances |
| `list_backends` / `get_backend` | Discover devices |
| `list_job_categories` | Categories and subcategories |
| `prepare_job` | Upload circuit and return a quote (no spend) |
| `submit_job` | Create a job (does not wait for completion) |
| `get_job` / `list_jobs` | Job status |
| `wait_for_job` | Poll until terminal status or timeout |
| `get_job_results` | Compact output summary |
| `get_job_calibration` | Calibration data on demand |
| `cancel_job` | Cancel when allowed by platform rules |

`prepare_job` / `submit_job` accept `execution_plan` (`auto` / `public` / `private` / UUID) and `queue_priority` (`auto` / `standard` / `priority` / `instant` / UUID). Auto plan selection prefers **Public** so Spark can apply. Quotes include `quote_summary` with per-priority pricing.

**Security:** `file_path` is read by the MCP process and uploaded; prefer `qasm` strings when possible and least-privilege process accounts.

## Spend policy

1. Estimated cost **greater than 10 credits** (configurable) → rejected.  
2. Cost **0** → allowed.  
3. **Public** plan and **Spark ≥ cost** → auto-approved.  
4. Spend that would use **Full** credits → requires `confirm_spend=true`.

Default job subcategory: `oth:oth`. Jobs are tagged `submitted_with=mcp`.

## Example agent flow

1. `list_backends` / `get_credits`  
2. `prepare_job` with OpenQASM → review quote  
3. `submit_job` (with `confirm_spend=true` when required)  
4. `wait_for_job` (re-call if still queued; QPU queues can be long)  
5. `get_job_results`  
6. `get_job_calibration` only if needed  

## License

Apache-2.0
