Content
# Tool List
**Kaiwu SDK CLI & MCP Dual-Mode Tool** — Boson Quantum CIM Coherent Light Quantum Computer Python SDK Docker Packaging Tool, supporting Command Line (CLI), Python Library (import), and AI Agent (MCP) three calling methods.
> 📚 **Kaiwu SDK Official Documentation**: [https://kaiwu-sdk-docs.qboson.com/en/latest/index.html](https://kaiwu-sdk-docs.qboson.com/en/latest/index.html)
---
## Table of Contents
- [Architecture Overview](#architecture-overview)
- [Prerequisites](#prerequisites)
- [Quick Start](#quick-start)
- [1. Obtain Credentials](#1-obtain-credentials)
- [2. Download SDK](#2-download-sdk)
- [3. Configure User Information](#3-configure-user-information)
- [4. Build Docker Image](#4-build-docker-image)
- [5. Generate License](#5-generate-license)
- [6. Run Scripts](#6-run-scripts)
- [CLI Usage Guide](#cli-usage-guide)
- [Python Library Usage Guide](#python-library-usage-guide)
- [MCP Server Usage Guide](#mcp-server-usage-guide)
- [Project Structure](#project-structure)
- [Frequently Asked Questions](#frequently-asked-questions)
---
## Architecture Overview
```
┌─────────────────────────────────────────────┐
│ Host Machine (Host) │
│ │
│ ┌──────────┐ ┌───────────────┐ │
│ │ CLI │ │ Python │ │ MCP Server │ │
│ │ (cli.py) │ │ Library │ │ (mcp_server) │ │
│ └────┬─────┘ │(import) │ └───────┬───────┘ │
│ │ └─────┬─────┘ │ │
│ └──────────────┼────────────────┘ │
│ │ │
│ ┌──────▼──────┐ │
│ │ core.py │ Pure Business Logic Layer │
│ └──────┬──────┘ │
│ │ docker compose │
│ │ │
│ ┌────────────▼──────────────┐ │
│ │ user_script/ │ Script Directory (Persistent)│
│ │ ~/any/path/xxx.py │ Auto-Mount │
│ └───────────────────────────┘ │
│ │ │
└───────────────┼──────────────────────────────┘
│ volume mount
┌───────────────▼──────────────────────────────┐
│ Docker Container (kaiwu-sdk) │
│ │
│ • Python 3.10 │
│ • Kaiwu SDK v1.3.1 (Installed) │
│ • /user_script/ (Mapped from Host) │
│ • /mnt/script/ (External Script Auto-Mount) │
│ • named volume: kaiwu-license (Persistent) │
│ │
│ User Scripts Run in This Environment, Calling Kaiwu SDK │
│ Access Boson Quantum CIM Coherent Light Quantum Computer │
└──────────────────────────────────────────────┘
```
**Core Principle**: One Core Logic Layer (`core.py`), Three Thin Interface Layers (`cli.py` + Python import + `mcp_server.py`). CLI for Humans, Python Library for Program Calls, MCP for AI Agent, Sharing the Same Business Logic.
---
## Prerequisites
- **Docker** & **Docker Compose** (v2+)
- **Python 3.10** (Host Machine, Only for CLI/MCP Tool. Kaiwu SDK Only Supports 3.10)
- **Kaiwu SDK v1.3.1** (Current Compatible Version, `cp310` wheel)
- Boson Quantum Platform Account: [https://platform.qboson.com/](https://platform.qboson.com/)
---
## Quick Start
### 1. Obtain Credentials
Log in to [Boson Quantum Platform](https://platform.qboson.com/), obtain your **User ID (user_id)** and **SDK Authorization Code (sdk_code)**.
### 2. Download SDK
Visit **[SDK Download Page](https://platform.qboson.com/sdkDownload)**, download **Linux Version** of Kaiwu SDK (downloaded as `.zip` file, containing `.whl`).
Place the downloaded `.zip` (or extracted `.whl`) in the project `sdk/` directory:
```bash
# Method 1: Directly Place zip (Docker Builds Automatically Unzip)
cp ~/Downloads/kaiwu-*.zip ./sdk/
# Method 2: Extract and Place whl
unzip ~/Downloads/kaiwu-*.zip -d ./sdk/
```
Docker build will automatically process: `.zip` auto-unzip → find `.whl` → `pip install`.
### 3. Configure User Information
Edit `user_config.yaml`, fill in your credentials:
```yaml
user_id: "your_user_id_here"
sdk_code: "your_sdk_code_here"
```
### 4. Build Docker Image
```bash
# Use CLI Tool
python cli.py build
# Or Use docker compose
docker compose build --no-cache
```
### 5. Generate License
```bash
# Use Credentials in user_config.yaml
python cli.py license init
# Or Explicitly Specify Credentials
python cli.py license init --user-id "your_id" --sdk-code "your_code"
# Check License Status
python cli.py license check
```
> License persists through Docker named volume (`kaiwu-license`), `docker compose run --rm` won't lose.
### 6. Run Scripts
Write your Python scripts in **any location**, CLI will automatically mount them to Docker container for execution:
```bash
# Run Scripts in user_script/
python cli.py run example_tsp.py
# Run Scripts in Host Machine Any Location
python cli.py run /home/user/projects/my_tsp_solver.py
python cli.py run ~/Desktop/experiment.py
```
---
## CLI Usage Guide
### Command List
| Command | Description |
|------|------|
| `python cli.py build` | Build Kaiwu SDK Docker Image |
| `python cli.py license init` | Generate SDK License |
| `python cli.py license check` | Check License Status |
| `python cli.py run <script>` | Run Python Scripts (Support Host Machine Any Path) |
| `python cli.py solve --qubo '<json>'` | Directly Solve QUBO Matrix |
| `python cli.py solve --ising '<json>'` | Directly Solve Ising Matrix |
| `python cli.py solve --tsp '<distances>'` | **Automatically Compile TSP → QUBO → Solve** (via qubify) |
| `python cli.py solve --maxcut '<adjacency>'` | **Automatically Compile Max-Cut → QUBO → Solve** (via qubify) |
| `python cli.py solve --knapsack '<json>'` | **Automatically Compile Knapsack → QUBO → Solve** (via qubify) |
| `python cli.py solve --dsl '<json>'` | **Automatically Compile Custom Problem → QUBO → Solve** (via qubify) |
| `python cli.py compile --preset tsp --data '<json>'` | Compile Problem → QUBO Matrix (No Solve) |
| `python cli.py convert qubo-to-ising '<json>'` | QUBO Matrix → Ising Matrix |
| `python cli.py convert ising-to-qubo '<json>'` | Ising Matrix → QUBO Matrix |
| `python cli.py status` | View Container Status |
### Solver Parameters
`solve` command supports fine-grained solver parameter adjustment:
#### SA (Simulated Annealing) Parameters
| Parameter | Description | Default Value |
|------|------|--------|
| `--sa-temp` | Initial Temperature | 100 |
| `--sa-alpha` | Cooling Coefficient | 0.99 |
| `--sa-cutoff` | Cutoff Temperature | 0.001 |
| `--sa-iters` | Iterations per Temperature | 10 |
| `--sa-size` | Output Solution Count | 100 |
| `--sa-procs` | Parallel Processes (-1 for All Cores) | 1 |
#### CIM (Quantum Machine) Parameters
| Parameter | Description | Default Value |
|------|------|--------|
| `--cim-interval` | Polling Interval (Minutes) | 1 |
| `--cim-project` | Project Number | — |
| `--cim-task-mode` | Computing Mode (quota/sample) | quota |
| `--cim-samples` | Sampling Count (sample mode) | 10 |
### Example
```bash
# Build Image
python cli.py build
# Generate License (Using user_config.yaml)
python cli.py license init
# Run Custom Script (Any Path)
python cli.py run my_optimization.py
python cli.py run ~/projects/quantum/experiment.py
# Directly Solve QUBO (Automatically Convert to Ising + Precision Adjustment)
python cli.py solve --qubo '[[0.89, 0.22, 0.198], [0.22, 0.23, 0.197], [0.198, 0.197, 0.198]]'
# Use CIM Machine to Solve
python cli.py solve --ising '[[1, -1], [-1, 1]]' --cim --task-name "my-experiment"
# SA Solve with Parameters
python cli.py solve --qubo '[[1, 2], [0, 3]]' --sa-temp 1000 --sa-alpha 0.995 --sa-size 50
# Use CIM Sample Mode
python cli.py solve --qubo '[[1, 0], [0, 1]]' --cim --cim-task-mode sample --cim-samples 100
# Automatically Compile and Solve (via qubify)
python cli.py solve --tsp '[[0,10,15,20],[10,0,35,25],[15,35,0,30],[20,25,30,0]]'
python cli.py solve --maxcut '[[0,1,0],[1,0,1],[0,1,0]]'
python cli.py solve --knapsack '{"values":[60,100,120],"weights":[10,20,30],"capacity":50}'
# Compile Custom Problem (qubify DSL) and Solve
python cli.py solve --dsl '{"variables":{"x":("binary",(3,))},"objective":[{"coeff":1,"vars":[0,1]}],"constraints":[{"type":"one_hot","vars":[0,1,2]}]}'
# Only Compile No Solve (Output QUBO Matrix JSON)
python cli.py compile --preset maxcut --data '[[0,1,0],[1,0,1],[0,1,0]]'
# QUBO ↔ Ising Matrix Conversion
python cli.py convert qubo-to-ising '[[1, 2], [0, 3]]'
python cli.py convert ising-to-qubo '[[0, 1], [1, 0]]'
```
### Automatic Compilation and Solve (via qubify)
[kaiwu-cli-mcp](https://github.com/LehaoLin/kaiwu-cli-mcp) integrates **[qubify](https://github.com/LehaoLin/qubify)** — a constraint-to-QUBO compiler.
**This means you no longer need to manually derive QUBO matrices.** Just provide business data:
```
Your Business Data → qubify Compiler → QUBO Matrix → Kaiwu SDK → Solution
```
Supported preset problem types:
| Preset | Input | Example |
|--------|------|------|
| `tsp` | Distance Matrix `[[d00,d01,...], ...]` | Traveling Salesman Problem |
| `maxcut` | Adjacency Matrix `[[w00,w01,...], ...]` | Maximum Cut Problem |
| `knapsack` | `{"values":[], "weights":[], "capacity":N}` | 0/1 Knapsack Problem |
You can also use qubify DSL to describe arbitrary custom constraint problems:
```json
{
"variables": {"x": ("binary", (5,))},
"objective": [{"coeff": -1.0, "vars": [0]}],
"constraints": [
{"type": "one_hot", "vars": [0, 1, 2]},
{"type": "cardinality", "vars": [3, 4], "rhs": 1}
]
}
```
Compilation and solving are completed on the **host machine** (qubify doesn't need to be installed in Docker), only the final matrix is passed into Docker to call Kaiwu SDK.
### Solving Process
Internal processing flow of `solve --qubo` and `solve --ising`:
```
--qubo Input → QUBO→Ising Conversion (kw.conversion) → Precision Adjustment (kw.ising) → Optimizer Solve → Output
--ising Input → Precision Adjustment (kw.ising) → Optimizer Solve → Output
```
QUBO matrix is automatically converted to Ising format through `kw.conversion.qubo_matrix_to_ising_matrix()`,
and adjusted in precision through `kw.ising.adjust_ising_matrix_precision()` to ensure compatibility with CIM hardware.
### Writing User Scripts
Create `.py` files in **any location**, directly `import kaiwu as kw` to use the SDK.
- **Recommended Practice**: Place scripts in `user_script/` directory (this directory is mapped to container `/user_script/`, execution is fastest)
- **Flexible Practice**: Place scripts in host machine any path, CLI will automatically mount the script directory in read-only mode to container's `/mnt/script/`, then execute with Kaiwu SDK environment in container
Refer to [Kaiwu SDK Official Documentation - TSP Tutorial](https://kaiwu-sdk-docs.qboson.com/en/latest/index.html) to learn QUBO/Ising modeling methods.
```python
# user_script/my_solver.py
import numpy as np
import kaiwu as kw
# Define QUBO Matrix
matrix = np.array([[0.89, 0.22], [0.22, 0.23]])
# Adjust Precision
adjusted = kw.qubo.adjust_qubo_matrix_precision(matrix)
# Use Simulated Annealing to Solve
opt = kw.classical.SimulatedAnnealingOptimizer()
solution = opt.solve(adjusted)
print(f"Solution: {solution}")
```
---
## Python Library Usage Guide
`kaiwu-cli-mcp` supports being used as a Python library to import and use directly in code. Core module `core.py` returns structured dict, suitable for embedding into other programs.
### Installation
**Method 1: pip install (Recommended)**
```bash
# Install from Local Source Code (Editable Mode)
cd /path/to/kaiwu-cli-mcp
pip install -e .
```
# Tool List
## Import kaiwu_cli_mcp from any directory
python -c "import kaiwu_cli_mcp; print(kaiwu_cli_mcp.__doc__)"
```
You can also use the command-line interface directly after installation:
```bash
kaiwu-cli build
kaiwu-cli solve --qubo '[[1, 0], [0, 1]]'
```
**Method 2: Manually add path**
```bash
cp -r kaiwu-cli-mcp /your/project/vendor/
```
```python
import sys
sys.path.insert(0, "/your/project/vendor/kaiwu-cli-mcp")
from core import solve_qubo, compile_and_solve
```
### Usage Examples
```python
from core import build_image, init_license, check_license, run_script
from core import solve_qubo, solve_ising, compile_and_solve, compile_problem
from core import container_status, convert_qubo_to_ising, convert_ising_to_qubo
# Build Docker image
result = build_image()
print(result) # {"success": True, "message": "Docker image built successfully", ...}
# Generate license
result = init_license("your_user_id", "your_sdk_code")
# Directly solve QUBO matrix
result = solve_qubo('[[0.89, 0.22], [0.22, 0.23]]')
if result["success"]:
print(result["output"]) # Solution result
# Use CIM quantum computer
result = solve_ising(
'[[1, -1], [-1, 1]]',
use_cim=True,
task_name="my-experiment",
)
# Automatically compile and solve TSP
result = compile_and_solve(
preset="tsp",
data='[[0,10,15,20],[10,0,35,25],[15,35,0,30],[20,25,30,0]]',
)
# Automatically compile and solve Knapsack
result = compile_and_solve(
preset="knapsack",
data='{"values":[60,100,120],"weights":[10,20,30],"capacity":50}',
)
# Specify SA solver parameters
result = solve_qubo(
'[[1, 0], [0, 1]]',
sa_params={"initial_temperature": 1000, "alpha": 0.995, "size_limit": 50},
)
# Compile problem (no solution), output QUBO matrix
result = compile_problem(preset="maxcut", data='[[0,1,0],[1,0,1],[0,1,0]]')
if result["success"]:
print(result["qubo_matrix"]) # QUBO matrix in JSON format
print(result["var_map"]) # Variable mapping
# Matrix conversion
result = convert_qubo_to_ising('[[1, 2], [0, 3]]')
# result["output"] contains {"ising_matrix": ..., "bias": ...}
# Check container status
result = container_status()
```
### Function Return Value Convention
All functions return a unified dict structure:
```python
# Success
{"success": True, "message": "...", "output": "..."}
# Failure
{"success": False, "message": "...", "output": "..."}
```
### Docker Dependency Description
| Function | Requires Docker | Description |
|------|------------|------|
| `build_image` | Yes | Build Kaiwu SDK image |
| `init_license` | Yes | Execute Kaiwu SDK in container |
| `check_license` | Yes | Check license file in container |
| `run_script` | Yes | Execute user script in container |
| `solve_qubo` | Yes | Call Kaiwu SDK to solve in container |
| `solve_ising` | Yes | Call Kaiwu SDK to solve in container |
| `compile_and_solve` | Yes | Compile QUBO on host → solve in container |
| `compile_problem` | No | Pure Python, compile QUBO on host (requires `qubify`) |
| `convert_qubo_to_ising` | Yes | Convert in container with Kaiwu SDK |
| `convert_ising_to_qubo` | Yes | Convert in container with Kaiwu SDK |
| `container_status` | Yes | docker compose ps |
---
## MCP Server Usage Guide
MCP (Model Context Protocol) mode allows AI Agent to directly call Kaiwu SDK.
Supports MCP configuration for the following AI coding tools: **Hermes Agent**, **Claude Code**, **OpenAI Codex**, **OpenCode**.
### Start MCP Server
```bash
cd /root/kaiwu-cli-mcp
pip install -r requirements.txt # Install fastmcp dependencies
python mcp_server.py # Start MCP Server (stdio mode)
```
---
### MCP Configuration Methods for Each Tool
#### Hermes Agent
Edit `~/.hermes/config.yaml`:
```yaml
mcpServers:
kaiwu-sdk-tools:
command: python
args: ["/root/kaiwu-cli-mcp/mcp_server.py"]
```
#### Claude Code
**Method 1: CLI Command** (recommended)
```bash
claude mcp add --transport stdio kaiwu-sdk-tools -- python /root/kaiwu-cli-mcp/mcp_server.py
```
**Method 2: `.mcp.json` file** (project-level, git-trackable)
Create `.mcp.json` in project root:
```json
{
"mcpServers": {
"kaiwu-sdk-tools": {
"command": "python",
"args": ["/root/kaiwu-cli-mcp/mcp_server.py"]
}
}
}
```
- **Local scope** (only current project, gitignored): `claude mcp add --scope local ...`
- **Project scope** (team-shared): `claude mcp add --scope project ...`
- **User scope** (global for all projects, `~/.claude.json`): `claude mcp add --scope user ...`
Use `/mcp` in Claude Code TUI to view and manage all MCP servers.
#### OpenAI Codex
Edit `~/.codex/config.toml`:
```toml
[mcp_servers.kaiwu-sdk-tools]
command = "python"
args = ["/root/kaiwu-cli-mcp/mcp_server.py"]
```
> Refer to [Codex configuration documentation](https://github.com/openai/codex/blob/main/docs/config.md) for detailed configuration parameters.
#### OpenCode
Create `opencode.json` (or `opencode.jsonc` for comments) in project root:
```json
{
"mcp": {
"kaiwu-sdk-tools": {
"type": "local",
"command": ["python", "/root/kaiwu-cli-mcp/mcp_server.py"]
}
}
}
```
> Refer to [OpenCode configuration documentation](https://opencode.ai/docs/) for detailed configuration parameters.
Use `/mcps` in OpenCode TUI to manage MCP servers.
---
### Available MCP Tools
After configuration, AI Agent can automatically discover the following tools:
| Tool Name | Description |
|--------|------|
| `kaiwu_build_image` | Build Kaiwu SDK Docker image |
| `kaiwu_init_license` | Generate SDK License (specify user_id/sdk_code) |
| `kaiwu_check_license` | Check License status |
| `kaiwu_run_script` | Run Python script (support arbitrary host path, auto-mount to Docker) |
| `kaiwu_solve_qubo` | Solve QUBO matrix (auto-convert to Ising + precision adjustment) |
| `kaiwu_solve_ising` | Solve Ising matrix (auto-precision adjustment) |
| `kaiwu_solve_preset` | **Automatically compile + solve (tsp/maxcut/knapsack)** via qubify |
| `kaiwu_solve_dsl` | **Automatically compile + solve (custom DSL)** via qubify |
| `kaiwu_compile_problem` | Compile problem → QUBO matrix (no solution) via qubify |
| `kaiwu_convert_qubo_to_ising` | QUBO matrix → Ising matrix |
| `kaiwu_convert_ising_to_qubo` | Ising matrix → QUBO matrix |
| `kaiwu_container_status` | View Docker container status |
All solving tools support `sa_params` and `cim_params` parameters (JSON format) to adjust optimizer behavior.
---
## Project Structure
```
kaiwu-cli-mcp/
├── cli.py # CLI entry (argparse)
├── mcp_server.py # MCP Server entry (FastMCP)
├── core.py # Pure business logic layer (importable)
├── config.py # Shared configuration reading
├── converters.py # qubify converter encapsulation
├── __init__.py # Python package entry
├── pyproject.toml # Python package configuration
├── user_config.yaml # User credential configuration ★edit this file★
├── Dockerfile # Kaiwu SDK Docker environment
├── docker-compose.yml # Docker orchestration (map user_script/ + license persistence)
├── requirements.txt # Python dependencies
├── README.md # This file
├── sdk/ # Place Kaiwu SDK .whl/.zip files
│ └── .gitkeep
└── user_script/ # User script directory ★write scripts here★
└── example_tsp.py # TSP example script
```
---
## Frequently Asked Questions
### Q: Where to download SDK .whl?
Log in to [https://platform.qboson.com/](https://platform.qboson.com/), select Linux version on the download page. File name example: `kaiwu-1.3.1-cp310-cp310-linux_x86_64.whl`.
### Q: How to confirm License generation success?
```bash
python cli.py license check
```
License persists through Docker named volume, will not be lost due to container restart.
### Q: How to directly enter Docker container for debugging?
```bash
docker compose run --rm kaiwu bash
```
Enter and directly use `python3` for interactive Kaiwu SDK usage.
### Q: Which solvers are supported?
- **SimulatedAnnealingOptimizer** (`kw.classical`) — Classical simulated annealing, no internet required
- **CIMOptimizer** (`kw.cim`) — Coherent Ising Machine real machine, requires cloud platform quota
Adjust solver parameters with CLI options `--sa-*` and `--cim-*`.
### Q: Python version requirements?
Kaiwu SDK v1.3.1 only supports **Python 3.10** (no minor version distinction). Docker image uses `python:3.10-slim`.
### Q: How is License persistence implemented?
Through Docker Compose's named volume `kaiwu-license`, mounted to SDK's license directory in container. Even if `docker compose run --rm` removes the container, license files remain in named volume. To clear license, run `docker volume rm kaiwu-cli-mcp_kaiwu-license`.
---
## Reference Links
- [Kaiwu SDK Official Documentation](https://kaiwu-sdk-docs.qboson.com/zh/latest/index.html)
- [Qboson Quantum Platform](https://platform.qboson.com/)
- [Kaiwu SDK Module Manual](https://kaiwu-sdk-docs.qboson.com/zh/latest/source/modules/index.html) — kaiwu.cim / kaiwu.qubo / kaiwu.license / kaiwu.conversion etc.
- [Kaiwu SDK Installation Instructions](https://kaiwu-sdk-docs.qboson.com/zh/latest/source/getting_started/sdk_installation_instructions.html)
- [Kaiwu SDK QUBO Modeling Tutorial (TSP)](https://kaiwu-sdk-docs.qboson.com/zh/latest/source/getting_started/tutorial_tsp.html)
---
## License
This tool is an open-source project. Kaiwu SDK copyright belongs to [Beijing Qboson Quantum Technology Co., Ltd.](https://www.qboson.com/).
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
No recommendations available