QCA OpenCode Plugin

This package adds the QCA quantum-calibration toolset to an unmodified official OpenCode installation. It replaces the previous approach that patched and rebuilt OpenCode Desktop.

What it provides

• Eight OpenCode tools: backend status, experiment discovery, schema lookup, parameter validation, dry-run, history lookup, array listing, and array read.
• A standards-based MCP stdio server exposing the same eight QCA tools for other MCP-compatible agents.
• A dependency-free Python QCA mini backend that the plugin starts and stops.
• A remote mode for connecting the same tools to another QCA implementation that exposes the compatible HTTP contract.
• Global and project-local installation scripts for Windows, macOS, and Linux.

The bundled backend is still a deterministic dry-run simulator. It does not connect to quantum hardware.

Requirements

• OpenCode 1.17.18 or later.
• Python 3.10 or later available as python3, python, or Windows py -3.

No Docker, FastAPI, Uvicorn, or OpenCode source build is required.

Install

Windows

cd qca-opencode-plugin
powershell -ExecutionPolicy Bypass -File .\scripts\install.ps1

For only the current project:

powershell -ExecutionPolicy Bypass -File .\scripts\install.ps1 -Scope Project

macOS or Linux

cd qca-opencode-plugin
chmod +x scripts/install.sh
./scripts/install.sh global

Use project instead of global to install into the current project's .opencode directory.

Restart OpenCode after installation and ask:

Call qca_backend_status, then list all QCA experiments.

Other Agents via MCP

The OpenCode plugin is still the best path for OpenCode itself. For other agents, use the MCP entry point:

bun ./mcp-server.ts

MCP clients should configure this package as a stdio server. Use the absolute path on your machine:

{
  "mcpServers": {
    "qca": {
      "command": "bun",
      "args": [
        "D:/StudyFiles/w/Intern/gitee-publish/qca-opencode-plugin/mcp-server.ts"
      ],
      "env": {
        "QCA_PYTHON": "python"
      }
    }
  }
}

After connecting, the client will see the same tools:

• qca_backend_status
• qca_list_experiments
• qca_get_schema
• qca_validate_params
• qca_run_dry_run
• qca_history_show
• qca_list_arrays
• qca_get_array

For production or a real lab backend, set QCA_BASE_URL and the MCP server will call that external service instead of starting the bundled Python dry-run backend:

{
  "mcpServers": {
    "qca": {
      "command": "bun",
      "args": [
        "D:/StudyFiles/w/Intern/gitee-publish/qca-opencode-plugin/mcp-server.ts"
      ],
      "env": {
        "QCA_BASE_URL": "http://127.0.0.1:8000"
      }
    }
  }
}

Uninstall

Windows:

powershell -ExecutionPolicy Bypass -File .\scripts\uninstall.ps1

macOS or Linux:

./scripts/uninstall.sh global

Use Project or project to remove a project-local installation. Experiment history is intentionally left in the data directory, so uninstalling or upgrading the plugin does not delete results.

Runtime modes

Managed local backend

This is the default. The plugin finds Python, starts the bundled server on 127.0.0.1 with a dynamic port, waits for /health, and terminates the child process through the OpenCode plugin dispose() hook.

Data is stored outside the OpenCode installation:

• Windows: %LOCALAPPDATA%\qca-opencode-plugin\data
• macOS: ~/Library/Application Support/qca-opencode-plugin/data
• Linux: ${XDG_DATA_HOME:-~/.local/share}/qca-opencode-plugin/data

QCA_DATA_DIR overrides all defaults. XDG_DATA_HOME is also honored on every platform. Set QCA_PYTHON to an absolute Python executable when automatic discovery is not appropriate.

External QCA backend

Set QCA_BASE_URL before starting OpenCode:

QCA_BASE_URL=http://127.0.0.1:8000 opencode

In this mode, the plugin does not start Python. This is the migration point for the real QCA backend, a remote lab service, or a containerized deployment.

Configured plugin options can also be used when the package is published:

{
  "plugin": [
    [
      "@black-jony/qca-opencode-plugin",
      {
        "baseUrl": "http://127.0.0.1:8000"
      }
    ]
  ]
}

Test

bun install
bun test ./tests/plugin.test.ts ./tests/mcp.test.ts
python tests\test_backend.py

The automated tests exercise all eight tools through both the OpenCode plugin entry point and the MCP stdio entry point, then repeat the backend contract against the installed directory layout.

Then run the OpenCode acceptance flow:

1. qca_backend_status
2. qca_list_experiments
3. qca_get_schema for qubit_spectroscopy
4. Validate {"qubit":"Q0","center_freq":9.0}
5. Dry-run qubit_spectroscopy for Q0
6. List arrays using the returned experiment ID
7. Read the frequencies array
8. Read the complete history result

Security boundary

The plugin improves modularity, dependency isolation, and API capability boundaries. It is not an operating-system sandbox. The plugin and its Python child process run with the current user's permissions. For real hardware, authentication, explicit execution approval, audit logging, and a dedicated worker sandbox remain required.