# 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

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

For only the current project:

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

### macOS or Linux

```bash
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:

```text
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:

```bash
bun ./mcp-server.ts
```

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

```json
{
  "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:

```json
{
  "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
powershell -ExecutionPolicy Bypass -File .\scripts\uninstall.ps1
```

macOS or Linux:

```bash
./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:

```bash
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:

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

## Test

```powershell
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.