# QPanda3 Runtime MCP Server

[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![FastMCP](https://img.shields.io/badge/FastMCP-2.8.1+-green.svg)](https://github.com/jlowin/fastmcp)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![Documentation](https://img.shields.io/badge/docs-latest-brightgreen.svg)](https://originquantum.github.io/qpanda3-runtime-mcp-server/)

A Model Context Protocol (MCP) server that enables AI assistants to interact with Origin Quantum computing services through QPanda3 Runtime.

## Features

- **Account Management**: Configure and manage Origin Quantum cloud account authentication
- **Device Management**: List and query available QPU devices
- **Quantum Computing Tasks**: Execute sampling and estimation tasks
- **Batch Operations**: Run multiple circuits efficiently
- **Multi-Objective Decisions**: CircuitObservableBinding for complex optimization
- **Task Management**: Query task status, retrieve results, cancel tasks
- **Example Circuits**: Provides common quantum circuit example resources

## Documentation

| Document | Description |
|----------|-------------|
| **[English Docs](https://originquantum.github.io/qpanda3-runtime-mcp-server/)** | English documentation site |
| **[中文文档](https://originquantum.github.io/qpanda3-runtime-mcp-server/zh/)** | Chinese documentation site |
| **[Getting Started](docs/getting_started.md)** | Complete beginner's guide - START HERE |
| **[Installation Guide](docs/installation.md)** | Detailed installation instructions |
| **[Quick Start](docs/quickstart.md)** | Fast setup for experienced users |
| **[Configuration](docs/configuration.md)** | Environment and client configuration |
| **[User Guide](docs/user_guide/account.md)** | Detailed feature documentation |
| **[API Reference](docs/api/runtime.md)** | Auto-generated API documentation |

## Installation

### One-Click Setup (Recommended)

The project provides setup scripts that automate the entire process:

**Linux / macOS:**
```bash
git clone https://github.com/OriginQ/qpanda3-runtime-mcp-server.git
cd qpanda3-runtime-mcp-server
chmod +x scripts/setup_configure.sh
./scripts/setup_configure.sh
```

**Windows (PowerShell):**
```powershell
git clone https://github.com/OriginQ/qpanda3-runtime-mcp-server.git
cd qpanda3-runtime-mcp-server
.\scripts\setup_configure.ps1
```

The script handles everything: dependency setup, API key configuration, and MCP client setup.

> See [Installation Guide](docs/installation.md) for manual install options.

## Quick Start

```bash
# 1. Configure your API key
cp .env.example .env
# Edit .env and set QPANDA3_API_KEY=your_api_key_here

# 2. Run the server
.venv/bin/python -m qpanda3_runtime_mcp_server       # Linux/macOS
# .venv\Scripts\python.exe -m qpanda3_runtime_mcp_server  # Windows
```

> See [Configuration](docs/configuration.md) for MCP client setup and advanced options.

## MCP Tools

### Account Management

| Tool | Description |
|------|-------------|
| `setup_origin_quantum_account_tool` | Configure Origin Quantum cloud account authentication |
| `list_saved_accounts_tool` | List saved account information (session-based) |
| `active_account_info_tool` | Get currently active account information |

### Device Management

| Tool | Description |
|------|-------------|
| `list_qpu_devices_tool` | List all available QPU (Quantum Processing Unit) devices |
| `get_qpu_properties_tool` | Get detailed properties of a specific QPU device |

### Quantum Computing Tasks

| Tool | Description |
|------|-------------|
| `sample_tool` | Execute quantum circuit sampling task on a QPU device |
| `estimate_tool` | Execute expectation estimation task for a quantum circuit |
| `batch_sample_tool` | Batch execute multiple quantum circuit sampling tasks |
| `batch_estimate_tool` | Batch execute estimation tasks for multiple circuits with one observable |

### Multi-Objective Decision (CircuitObservableBinding)

| Tool | Description |
|------|-------------|
| `create_circuit_observable_binding_tool` | Create a binding for multiple circuits and observables |
| `add_product_rule_tool` | Add Cartesian product combination rule (all combinations) |
| `add_zip_rule_tool` | Add one-to-one combination rule (paired combinations) |
| `estimate_with_binding_tool` | Execute estimation using the created binding |
| `list_bindings_tool` | List all stored CircuitObservableBinding objects |
| `delete_binding_tool` | Delete a stored CircuitObservableBinding object |

### Task Management

| Tool | Description |
|------|-------------|
| `get_task_status_tool` | Get the execution status of a task (`PENDING`/`RUNNING`/`DONE`/`FAILED`/`CANCELLED`) |
| `get_task_results_tool` | Get the computation results of a completed task |
| `cancel_task_tool` | Cancel a running or pending task |
| `list_my_tasks_tool` | List user's recent quantum computing tasks |

## MCP Resources

| Resource URI | Description |
|--------------|-------------|
| `qpanda://status` | Service status |
| `circuits://bell-state` | Bell state circuit example |
| `circuits://ghz-state` | GHZ state circuit example |
| `circuits://random` | Random number generator circuit |
| `circuits://superposition` | Superposition circuit example |

## Example Usage

### Configure Account

```python
# Auto-configure via environment variables
# Or call explicitly
await setup_origin_quantum_account_tool(
    api_key="your_api_key"
)
```

### List Devices

```python
devices = await list_qpu_devices_tool()
print(f"Available devices: {devices['total_devices']}")
```

### Execute Sampling Task

```python
# Bell state circuit
circuit = """QINIT 2
CREG 2
H q[0]
CNOT q[0],q[1]
MEASURE q[0],c[0]
MEASURE q[1],c[1]"""

result = await sample_tool(
    circuit=circuit,
    device_id="20",
    shots=1000
)
task_id = result["task_id"]

# Check status and get results
status = await get_task_status_tool(task_id)
if status["task_status"] == "DONE":
    results = await get_task_results_tool(task_id)
    print(f"Measurement results: {results['results']}")
```

## Configure in AI Coding Platforms

> **Auto-configure:** Use `./scripts/setup_configure.sh --mcp claude-desktop` (or `--mcp cline`, `--mcp cursor`, etc.)

All clients use the same config format (replace `/path/to/...` with your actual path):

```json
{
  "mcpServers": {
    "qpanda3-runtime": {
      "command": "/path/to/qpanda3-runtime-mcp-server/.venv/bin/python",
      "args": ["-m", "qpanda3_runtime_mcp_server"],
      "cwd": "/path/to/qpanda3-runtime-mcp-server",
      "env": { "QPANDA3_API_KEY": "your_api_key_here" }
    }
  }
}
```

| Client | Config File Location |
|--------|---------------------|
| **Claude Code** | `~/.claude.json` |
| **Claude Desktop** | macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` |
| **Cline** | `~/.vscode-server/data/User/globalStorage/saoudrizwan.cline/settings/cline_mcp_settings.json` |
| **Cursor** | `.cursor/mcp.json` (project root) |
| **Windsurf** | `~/.codeium/windsurf/mcp_config.json` |

> For more clients (Trae etc.), see [Configuration Guide](docs/configuration.md).

## Development

### Install Development Dependencies

```bash
uv sync --extra dev --extra test
```

### Run Tests

```bash
uv run pytest
```

### Code Linting

```bash
uv run ruff check .
uv run mypy src/
```

### Build Documentation

```bash
# Install documentation dependencies
uv sync --extra docs

# Build documentation (English + Chinese)
./scripts/build-docs.sh

# Local preview with live reload (language switching supported)
mkdocs serve
```

## Project Structure

```
qpanda3-runtime-mcp-server/
├── src/
│   └── qpanda3_runtime_mcp_server/
│       ├── __init__.py          # Package entry point
│       ├── server.py            # MCP server definition
│       ├── runtime.py           # QPanda3 Runtime core logic
│       └── utils.py             # Utility functions
├── scripts/
│   ├── setup_configure.sh       # One-click setup (Linux/macOS)
│   ├── setup_configure.ps1      # One-click setup (Windows PowerShell)
│   ├── setup_configure.bat      # One-click setup (Windows CMD)
│   ├── build-docs.sh            # Build all documentation
│   └── serve-docs.sh            # Serve docs with live reload
├── tests/
│   ├── __init__.py
│   ├── conftest.py              # pytest configuration
│   ├── test_server.py           # Server tests
│   └── test_runtime.py          # Runtime tests
├── docs/
│   ├── *.md                     # English documentation (default)
│   └── cn/                      # Chinese documentation
├── mkdocs.yml                   # MkDocs configuration (i18n)
├── .github/
│   └── workflows/               # GitHub Actions workflows
├── pyproject.toml               # Project configuration
├── README.md                    # Project documentation
├── LICENSE                      # Apache 2.0 License
├── .env.example                 # Environment variable example
└── .gitignore                   # Git ignore file
```

## Notes

1. **Default Server**: The server connects to `https://qpanda3-runtime.qpanda.cn` by default. Set `QPANDA3_SERVER_URL` to override.
2. **Channel**: The server uses the qcloud channel by default
3. **Async Support**: All tool functions are `async` functions
4. **Error Handling**: All functions return dictionaries containing a `status` field
5. **Type Hints**: Python type hints are used for better code readability

## License

This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.

## Related Links

- [QPanda3 Runtime Documentation](qpanda3_runtime.pdf)
- [FastMCP Framework](https://github.com/jlowin/fastmcp)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [Reference Implementation: Qiskit MCP Server](https://github.com/Qiskit/mcp-servers/tree/main/qiskit-ibm-runtime-mcp-server)

## Contributing

See [Contributing Guide](docs/development/contributing.md) for details.

## Changelog

See [Changelog](docs/development/changelog.md) for version history.