opencode-cpp-refactory

中文文档

OpenCode plugin for AI-assisted C++ legacy code refactoring and new feature development with MCP-driven safety nets.

Architecture

┌─────────────────────────────────────────────────────────────┐
│  opencode                                                   │
│                                                             │
│  ┌───────────────────────────────────────────────────────┐  │
│  │  NPM Plugin: opencode-cpp-refactory                   │  │
 │  │  ├── 17 custom tools (bash scripts + TS modules)      │  │
│  │  ├── Event hooks (session / tool-guard / env-inject)  │  │
│  │  └── MCP client ─────────────────┐                    │  │
│  └───────────────────────────────────┼────────────────────┘  │
│                                      │ stdio (JSON-RPC 2.0) │
└──────────────────────────────────────┼──────────────────────┘
                                       │
                        ┌──────────────▼──────────────────┐
                        │  Docker Container (user-managed) │
                        │  └── clang-ast-mcp server        │
                        │      ├── ASTEngine (libclang-18) │
                        │      ├── list_functions          │
                        │      ├── globals_finder          │
                        │      ├── virtual_calls           │
                        │      └── macro_jungle            │
                        └──────────────────────────────────┘

Three components, each with its own role:

| Component | What | How | |---|---|---| | NPM Plugin | Entry point — tools, hooks, workflow enforcement | npm install opencode-cpp-refactory | | MCP | Communication protocol (JSON-RPC over stdio) | Configured in opencode.json | | Docker | clang-ast-mcp server runtime (user builds & runs) | docker build + docker run |

Prerequisites

OpenCode (Fork)

This plugin requires the OpenCode fork with plugin and MCP support. Install it first:

Linux:

curl -fsSL https://github.com/LeXwDeX/opencode/releases/latest/download/opencode-linux-x64.tar.gz | tar xz
sudo mv opencode /usr/local/bin/

macOS (Apple Silicon):

curl -fsSL -o opencode.zip https://github.com/LeXwDeX/opencode/releases/latest/download/opencode-darwin-arm64.zip
unzip opencode.zip && sudo mv opencode /usr/local/bin/

Windows:

Invoke-WebRequest -Uri "https://github.com/LeXwDeX/opencode/releases/latest/download/opencode-windows-x64.zip" -OutFile opencode.zip
Expand-Archive opencode.zip -DestinationPath .
# Move opencode.exe to a directory in your PATH

Verify installation:

opencode --version

Node.js

Node.js >= 18.0.0 is required (for the NPM plugin).

Docker

Docker Engine >= 20.10 is required (for the clang-ast-mcp server).

Installation

Step 1: Install the NPM Plugin

npm install opencode-cpp-refactory

Step 2: Build the Docker Image

The clang-ast-mcp server runs inside a Docker container with full LLVM/Clang 18 toolchain. Build it from this repo:

git clone https://github.com/LeXwDeX/Cpp_Refactory.git
cd Cpp_Refactory
docker build -t cpp-refactory -f docker/Dockerfile .

The build automatically runs the test suite (42 assertions + E2E refactor tests). Any failure aborts the build.

Step 3: Configure opencode.json

Add both the plugin and the MCP server to your project's opencode.json:

{
  "plugin": ["opencode-cpp-refactory"],
  "mcp": {
    "clang-ast": {
      "type": "local",
      "command": [
        "docker", "run", "--rm", "-i",
        "-v", "/path/to/your/cpp/project:/work:ro",
        "cpp-refactory"
      ],
      "enabled": true
    }
  }
}

Configuration breakdown:

| Field | Purpose | |---|---| | "plugin" | Registers the NPM plugin with opencode | | "mcp.clang-ast" | Tells opencode how to start the MCP server | | "-v ...:/work:ro" | Mounts your C++ project read-only into the container | | "docker run -i" | -i is required — MCP uses stdin/stdout for JSON-RPC |

Tip: Replace /path/to/your/cpp/project with your actual project path. The container only reads your source files; all analysis happens in-memory.

Step 4: Verify

Open opencode in your C++ project and call the cpp-bootstrap tool. If everything is wired correctly:

1. Plugin hooks fire (session.created logs appear)
2. MCP tools are available (clang_ast_load, clang_ast_list_functions, etc.)
3. cpp-bootstrap initializes .cpp_refactory/ workspace

Quick Start

1. Open a C++ project in OpenCode
2. Call cpp-bootstrap to initialize .cpp_refactory/ workspace
3. Call cpp-scan to scan the project
4. Follow the 6-phase pipeline: scan → analyze → plan → execute → verify → record

Plugin Tools

These 17 tools are registered by the NPM plugin and available immediately after installation:

| Tool | Description | |------|-------------| | cpp-scan | Project pre-scan: C++ standard, file hotspots, god functions, #ifdef jungle index | | cpp-seam-finder | Seam discovery via regex heuristics (fallback path, >30% false positive rate) | | cpp-bigfile-map | Large file navigation map: Section Map + Function Index + Cut Points | | cpp-verify-tools | Verify toolchain completeness (clang-tidy, cppcheck, bear, ccache) | | cpp-bootstrap | Initialize cpp_refactory workspace in target project | | cpp-characterize | Characterization test generation helper | | cpp-ast-cache | AST disk cache management (stats/clean/list) | | ledger-init | Initialize three-layer ledger (Wave/Batch/Partition) | | ledger-wave-add | Create Wave (campaign-level goal) | | ledger-batch-add | Create Batch (single-session goal) | | ledger-partition-add | Create Partition (minimum execution unit, ~4h) | | ledger-promote | Advance partition status (PLANNED→IN_PROGRESS→VERIFIED→DONE) | | ledger-status | View current ledger overview | | ledger-list | List all partition details | | cpp-diagnose | One-click environment diagnosis: checks 17 items including toolchain availability, compile_commands.json validity, Docker/MCP connectivity | | cpp-pipeline | Refactoring pipeline verification: runs compilation + tests + static analysis on changed files, returns structured pass/fail result | | cpp-quality-gate | Incremental quality gate: records baseline of current warnings/tests/errors, then compares and reports ONLY new issues (delta) |

MCP Tools (via Docker)

These tools are provided by the clang-ast-mcp server running in Docker. They require the MCP configuration from Step 3:

| Tool | Description | |---|---| | clang_ast_load | Pre-warm AST cache for a file | | clang_ast_list_functions | List functions with cyclomatic complexity and line boundaries | | clang_ast_globals | Global variable analysis (SIOF risk detection) | | clang_ast_virtual_calls | Virtual call sites + override candidates | | clang_ast_macro_jungle | Preprocessor complexity report |

Hooks

session.created

Automatically reads state/ files and injects them into conversation context. Warns if cpp_refactory is not initialized.

tool.execute.before

Blocks cpp-refactory tools (except cpp-bootstrap) if .cpp_refactory/ doesn't exist. Warns about open tool gaps.

shell.env

Injects CPP_REFACTORY_ROOT, CPP_REFACTORY_SCRIPTS, CPP_REFACTORY_RESOURCES into all shell sessions.

Docker Reference

The Docker image supports multiple run modes:

# MCP server mode (default — used by opencode.json)
docker run --rm -i -v /path/to/project:/work:ro cpp-refactory

# Interactive shell (debugging)
docker run --rm -it -v /path/to/project:/work cpp-refactory shell

# Run test suite
docker run --rm cpp-refactory test --all

# Full sandbox validation
docker run --rm cpp-refactory bash /opt/cpp_refactory/docker/validate-sandbox.sh

Docker Compose

export CPP_PROJECT_PATH=/path/to/your/cpp/repo

# Start MCP server
docker compose -f docker/docker-compose.yml run --rm -T mcp-server

# Run tests
docker compose -f docker/docker-compose.yml run --rm test

# Interactive shell
docker compose -f docker/docker-compose.yml run --rm shell

Security Isolation (docker-compose.yml)

| Measure | Description | |---|---| | read_only: true | Read-only root filesystem | | no-new-privileges | Prevent privilege escalation | | cap_drop: ALL | Remove all Linux capabilities | | cap_add: DAC_READ_SEARCH | Only allow reading mounted files | | networks: internal | No external network access | | memory: 4G / cpus: 4.0 | Resource limits | | /work:ro | Host project mounted read-only |

What's Inside the Image

| Component | Source | Purpose | |---|---|---| | LLVM/Clang 18 | Ubuntu 24.04 apt | C++ compilation + AST analysis | | libclang-18-dev | Ubuntu 24.04 apt | Python binding for AST | | clang-tidy / clang-format | Ubuntu 24.04 apt | Static analysis / formatting | | cppcheck | Ubuntu 24.04 apt | Complementary static analysis | | bear | Ubuntu 24.04 apt | Generate compile_commands.json | | clang-ast-mcp | This repo (mcp/) | MCP server with 7 AST tools |

Optional MCP Servers

The plugin also integrates with these optional MCP servers (configure separately in opencode.json):

• codegraph — Tree-sitter structural queries (impact analysis, call graph, symbol search)
• hindsight — Biomimetic agent memory with fact extraction, semantic/graph/temporal recall, and reflection

The plugin degrades gracefully when they're unavailable.

Development

# Plugin development
npm install
npm test          # 38 tests, node:test + tsx
npm run build     # tsup → dist/index.js
npm run typecheck # tsc --noEmit

# Docker image
docker build -t cpp-refactory -f docker/Dockerfile .
docker run --rm cpp-refactory test --all

License

AGPL-3.0-or-later. See LICENSE.