Metadata-Version: 2.4
Name: qiskit-gym-mcp-server
Version: 0.1.0
Summary: MCP server for qiskit-gym reinforcement learning quantum circuit synthesis
Project-URL: Homepage, https://github.com/Qiskit/mcp-servers
Project-URL: Repository, https://github.com/Qiskit/mcp-servers
Project-URL: Documentation, https://github.com/Qiskit/mcp-servers/tree/main/qiskit-gym-mcp-server#readme
Project-URL: Bug Tracker, https://github.com/Qiskit/mcp-servers/issues
Author-email: Qiskit Community <qiskit@us.ibm.com>
License: Apache-2.0
Requires-Python: <3.14,>=3.10
Requires-Dist: fastmcp>=2.12.4
Requires-Dist: nest-asyncio>=1.5.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: qiskit-gym>=0.3.0
Requires-Dist: qiskit-ibm-runtime>=0.34.0
Requires-Dist: qiskit-mcp-server
Requires-Dist: qiskit>=1.3.0
Provides-Extra: all
Requires-Dist: bandit[toml]>=1.9.2; extra == 'all'
Requires-Dist: langchain-anthropic>=0.3.0; extra == 'all'
Requires-Dist: langchain-mcp-adapters>=0.1.0; extra == 'all'
Requires-Dist: langchain>=0.3.0; extra == 'all'
Requires-Dist: mypy>=1.15.0; extra == 'all'
Requires-Dist: pytest-asyncio>=1.2.0; extra == 'all'
Requires-Dist: pytest-cov>=4.1.0; extra == 'all'
Requires-Dist: pytest-mock>=3.15.1; extra == 'all'
Requires-Dist: pytest>=8.4.2; extra == 'all'
Requires-Dist: python-dotenv>=1.0.0; extra == 'all'
Requires-Dist: ruff>=0.11.13; extra == 'all'
Provides-Extra: dev
Requires-Dist: mypy>=1.15.0; extra == 'dev'
Requires-Dist: ruff>=0.11.13; extra == 'dev'
Provides-Extra: examples
Requires-Dist: langchain-anthropic>=0.3.0; extra == 'examples'
Requires-Dist: langchain-mcp-adapters>=0.1.0; extra == 'examples'
Requires-Dist: langchain>=0.3.0; extra == 'examples'
Requires-Dist: python-dotenv>=1.0.0; extra == 'examples'
Provides-Extra: test
Requires-Dist: bandit[toml]>=1.9.2; extra == 'test'
Requires-Dist: pytest-asyncio>=1.2.0; extra == 'test'
Requires-Dist: pytest-cov>=4.1.0; extra == 'test'
Requires-Dist: pytest-mock>=3.15.1; extra == 'test'
Requires-Dist: pytest>=8.4.2; extra == 'test'
Description-Content-Type: text/markdown

# Qiskit Gym MCP Server

A Model Context Protocol (MCP) server that provides reinforcement learning-based quantum circuit synthesis capabilities using [qiskit-gym](https://github.com/AI4quantum/qiskit-gym).

## Features

- **Train RL Models**: Train reinforcement learning agents to synthesize optimal quantum circuits
- **Background Training**: Run long training sessions in background threads with polling support
- **Three Synthesis Types**:
  - **Permutation**: Qubit routing with minimal SWAP gates
  - **Linear Function**: CNOT synthesis for linear Boolean functions
  - **Clifford**: Optimal Clifford circuit synthesis with custom gate sets
- **Hardware Support**: Presets for IBM Heron, Nighthawk, and common grid/linear topologies
- **Exact IBM Topologies**: Access exact coupling maps from IBM Quantum fake backends (offline, no credentials needed)
- **Subtopology Extraction**: Extract connected subgraphs from hardware coupling maps for targeted training
- **Model Persistence**: Save, load, and manage trained models
- **TensorBoard Integration**: Monitor training progress with TensorBoard

## Installation

```bash
pip install qiskit-gym-mcp-server
```

Or install from source:

```bash
git clone https://github.com/Qiskit/mcp-servers
cd mcp-servers/qiskit-gym-mcp-server
pip install -e .
```

## Quick Start

### Claude Desktop Configuration

Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "qiskit-gym": {
      "command": "qiskit-gym-mcp-server"
    }
  }
}
```

### Example Workflow

```
User: "Train a model to synthesize Clifford circuits on a 3x3 grid topology"

AI Agent:
1. create_clifford_env_tool(num_qubits=9, preset="grid_3x3")  # -> env_id
2. start_training_tool(env_id, algorithm="ppo", num_iterations=200)  # -> session_id, model_id
3. save_model_tool(session_id, model_name="clifford_3x3_v1")  # -> saved to disk
```

```
User: "Train on all 6-qubit subtopologies from IBM Nighthawk"

AI Agent:
1. extract_subtopologies_tool(preset="ibm_nighthawk", num_qubits=6)  # -> list of subtopologies
2. For each subtopology:
   - create_clifford_env_tool(num_qubits=6, coupling_map=subtopology["edges"])
   - start_training_tool(env_id, algorithm="ppo", num_iterations=100)
   - save_model_tool(session_id, model_name=f"nighthawk_6q_{i}")
```

```
User: "Train a model using the exact topology of IBM Fez backend"

AI Agent:
1. get_fake_backend_coupling_map_tool(backend_name="fake_fez")  # -> exact 156-qubit Heron topology
2. extract_subtopologies_tool(edges=coupling_map["edges"], num_qubits=5)  # -> 5-qubit subtopologies
3. For each subtopology:
   - create_permutation_env_tool(num_qubits=5, coupling_map=subtopology["edges"])
   - start_training_tool(env_id, algorithm="ppo", num_iterations=100)
```

```
User: "Train a model in the background so I can do other things"

AI Agent:
1. create_clifford_env_tool(num_qubits=6, preset="grid_2x3")  # -> env_id
2. start_training_tool(env_id, algorithm="ppo", num_iterations=500, background=True)  # -> session_id (returns immediately)
3. (User can now ask other questions or the agent can do other work)
4. get_training_status_tool(session_id)  # -> check progress
5. wait_for_training_tool(session_id, timeout=600)  # -> blocks until complete, returns model_id
6. save_model_tool(session_id, model_name="clifford_6q_v1")
```

## Tools Reference

### Environment Management

| Tool | Description |
|------|-------------|
| `create_permutation_env_tool` | Create PermutationGym for SWAP routing |
| `create_linear_function_env_tool` | Create LinearFunctionGym for CNOT synthesis |
| `create_clifford_env_tool` | Create CliffordGym with custom gate sets |
| `list_environments_tool` | List active environments |
| `get_environment_info_tool` | Get environment details |
| `delete_environment_tool` | Remove an environment |

### Training

| Tool | Description |
|------|-------------|
| `start_training_tool` | Start RL training (PPO or AlphaZero), supports `background=True` |
| `wait_for_training_tool` | Wait for background training to complete |
| `batch_train_environments_tool` | Train multiple environments |
| `get_training_status_tool` | Get training progress and metrics |
| `stop_training_tool` | Stop a training session |
| `list_training_sessions_tool` | List all training sessions |

### Synthesis

| Tool | Description |
|------|-------------|
| `synthesize_permutation_tool` | Generate optimal SWAP circuit |
| `synthesize_linear_function_tool` | Generate optimal CNOT circuit |
| `synthesize_clifford_tool` | Generate optimal Clifford circuit |

### Model Management

| Tool | Description |
|------|-------------|
| `save_model_tool` | Save trained model to disk |
| `load_model_tool` | Load model from disk |
| `list_saved_models_tool` | List models on disk |
| `list_loaded_models_tool` | List models in memory |
| `delete_model_tool` | Delete a model |
| `get_model_info_tool` | Get model details |

### Coupling Maps

| Tool | Description |
|------|-------------|
| `create_coupling_map_tool` | Create custom coupling map |
| `extract_subtopologies_tool` | Extract N-qubit subtopologies from hardware |
| `list_subtopology_shapes_tool` | List subtopology shapes (line, grid, etc.) |
| `get_fake_backend_coupling_map_tool` | Get exact topology from fake IBM backend (no credentials needed) |
| `list_available_fake_backends_tool` | List all available fake backends for offline topology access |

### Utility Tools

| Tool | Description |
|------|-------------|
| `generate_random_permutation_tool` | Generate random permutation for testing |
| `generate_random_linear_function_tool` | Generate random linear function for testing |
| `generate_random_clifford_tool` | Generate random Clifford element for testing |
| `convert_qpy_to_qasm3_tool` | Convert QPY circuit to human-readable QASM3 |
| `convert_qasm3_to_qpy_tool` | Convert QASM3 circuit to QPY format |

## Hardware Presets

| Preset | Qubits | Topology | Description |
|--------|--------|----------|-------------|
| `ibm_heron_r1` | 133 | Heavy-hex | IBM Heron r1 processor |
| `ibm_heron_r2` | 156 | Heavy-hex | IBM Heron r2 processor |
| `ibm_nighthawk` | 120 | 10x12 grid | IBM Nighthawk (600% depth improvement vs Heron) |
| `grid_3x3` | 9 | Grid | 3x3 square grid |
| `grid_5x5` | 25 | Grid | 5x5 square grid |
| `linear_5` | 5 | Line | 5-qubit linear chain |
| `linear_10` | 10 | Line | 10-qubit linear chain |

## Resources

| URI | Description |
|-----|-------------|
| `qiskit-gym://workflows` | **Start here** - Step-by-step workflows and quick start guide |
| `qiskit-gym://presets/coupling-maps` | Available hardware presets |
| `qiskit-gym://algorithms` | PPO, AlphaZero documentation |
| `qiskit-gym://policies` | BasicPolicy, Conv1dPolicy docs |
| `qiskit-gym://environments` | Environment type documentation |
| `qiskit-gym://training/sessions` | Active training sessions |
| `qiskit-gym://models` | Loaded models |
| `qiskit-gym://server/config` | Server configuration |

## Configuration

Environment variables:

```bash
# Model storage directory (default: ~/.qiskit-gym/models)
QISKIT_GYM_MODEL_DIR=~/.qiskit-gym/models

# TensorBoard logs (default: ~/.qiskit-gym/runs)
QISKIT_GYM_TENSORBOARD_DIR=~/.qiskit-gym/runs

# Training limits (0 = no limit, default)
# QISKIT_GYM_MAX_ITERATIONS=10000  # Uncomment to set a limit
QISKIT_GYM_MAX_QUBITS=15
QISKIT_GYM_MAX_SEARCHES=10000
```

## Development

```bash
# Install with dev dependencies
pip install -e ".[all]"

# Run tests
./run_tests.sh

# Or manually
uv run pytest tests/ -v
uv run ruff check src tests
uv run mypy src
```

## Dependencies

- [qiskit-gym](https://github.com/AI4quantum/qiskit-gym) - RL environments for quantum circuit synthesis
- [FastMCP](https://github.com/jlowin/fastmcp) - MCP server framework
- [Qiskit](https://qiskit.org/) - Quantum computing framework
- [qiskit-ibm-runtime](https://github.com/Qiskit/qiskit-ibm-runtime) - IBM Quantum access and fake backends

## License

Apache 2.0 - See [LICENSE](../LICENSE) for details.

## Contributing

See [CONTRIBUTING.md](../CONTRIBUTING.md) for contribution guidelines.
