[Superagentic-AI]

Summary

Adds a Model Context Protocol (MCP) server so AI assistants (Claude Desktop, Cursor, any MCP client) can drive SuperQuantX across backends.

• New [mcp] extra using the official mcp SDK (mcp>=2.3,<3, verified with 2.3.0)
• Entry points over stdio: superquantx-mcp and python -m superquantx.mcp
• Tools (all read-only, structured JSON, never raise):
  • list_backends: install status, init, and a Bell smoke test per backend (working, not_installed, init_failed, execution_failed, wrong_results)
  • backend_versions: SDK and backend version info
  • run_circuit: OpenQASM 2, OpenQASM 3 (safe subset) or JSON gate list; counts, probabilities, gate counts, timing
  • bell_state_demo: same Bell circuit on several backends, per-backend errors isolated
  • qsvm_classify: SuperQuantX QuantumSVM with an exact fidelity kernel from each SDK's statevectors, kernel diagnostics, and an RBF SVM baseline
  • qaoa_maxcut: QAOA on the unified circuit API with grid search plus COBYLA, checked against brute force
• Safety: input validation, caps on qubits, shots, gates, QASM size, samples, features, QAOA size (env overridable below hard ceilings). Simulators only by default; a device needs SUPERQUANTX_MCP_ALLOW_HARDWARE=1. Logs go to stderr.
• docs/mcp.md (added to mkdocs nav): install, tools, limits, Claude Desktop and Cursor mcp.json snippets, comparison with the IBM Qiskit MCP servers (Qiskit stack only), and real captured output
• examples/mcp_client_demo.py: stdio client that calls every tool
• skills/superquantx/SKILL.md: agent skill for using the server honestly

Why the server computes its own QSVM kernel and QAOA

On 0.2.0 the backend kernels are not usable for a demo: simulator.compute_kernel_matrix is a classical Gaussian placeholder, the Qiskit kernel returns a zero diagonal, and the PennyLane kernel ignores the feature map. superquantx.algorithms.QAOA has random placeholder fallbacks. The server therefore builds the feature map and QAOA circuits itself and executes them through each backend, so all three backends return identical kernels and correct MaxCut results. kernel="backend" is still available and reports looks_valid: false when the backend kernel is wrong. Also, QuantumSVM train accuracy is computed from the precomputed kernel to avoid a double scaling issue in fit.

Verification

• Fresh uv venv on Python 3.11.16, uv pip install ".[mcp,qiskit,pennylane]" (mcp 2.3.0, qiskit 2.6.1, qiskit-aer 0.18.2, pennylane 0.45.1). examples/mcp_client_demo.py launched the server over stdio both as superquantx-mcp and python -m superquantx.mcp and called every tool on simulator, qiskit and pennylane. All calls succeeded except the intentional 64 qubit validation check.
  • Bell and GHZ: only correlated outcomes on all three backends
  • QSVM moons (40 samples): 0.833 test accuracy on all three backends, RBF baseline 0.833; iris: quantum 0.667 vs RBF 0.917 (reported honestly)
  • QAOA MaxCut on a 4 node graph: optimum 4 found on all three backends, approximation ratio about 0.80
• tests/unit/test_mcp_server.py: 44 passed with qiskit, pennylane and mcp installed; 41 passed and 3 skipped with only .[dev] (no mcp, qiskit or pennylane)
• Full unit suite: the same 14 pre-existing failures as main (braket, ocean, circuits repr, client tests), none in new code
• ruff check clean on the new files
• mkdocs build --strict has the same 104 pre-existing warnings as main; docs/mcp.md adds none

Limitations

• Noiseless local simulators at toy scale; no quantum advantage is claimed and the tools say so in their output
• Cirq, Braket and TKET use the same code path but were not installed in the verification run
• Qiskit Aer is slower for QAOA (about 5.5 s vs 0.4 s) because each optimizer step submits a new job
• uv.lock is not updated in this PR