Opencode AST MCP Server

Turn any MCP-aware IDE (OpenCode, Claude Desktop, etc.) into an agentic coding system backed by tree-sitter, a local Qwen 3 VL 4B, OpenRouter (Claude Haiku by default), and Podman.

Why this project

A drop-in MCP server that gives your coding agent 13 specialised tools — AST extraction without reading whole files, project-wide codebase awareness, local code analysis via Qwen, cloud SDD planning via DeepSeek (or any OpenAI-compatible endpoint), and isolated test execution in Podman — so the agent spends its context window on code, not on boilerplate.

Related MCP server: agent-lsp

Features

• 13 MCP tools in a single Python server (FastMCP + stdio)

• tree-sitter AST extraction for Python, JavaScript, TypeScript, TSX, Go, Rust, Java, C/C++, Ruby, PHP, LaTeX

• Project-wide codebase awareness — recursive file listing, overview with skeletons, cross-file symbol search, AST-aware reference finder (mtime-cached)

• Local LLM analysis via LM Studio + Qwen 3 VL 4B (no cloud for code review)

• Cloud planning via any OpenAI-compatible endpoint (default: DeepSeek, works with OpenRouter, OpenAI, ollama)

• Podman sandbox for test execution with hardened mount validation

• Autonomous code→test→fix loop with a 5-iteration circuit breaker

• 75 pytest tests, all runnable in the sandbox

Table of contents

• Quick start

• Tools at a glance

• How it works with OpenCode plan/build mode

• Project status

• Project layout

• Documentation

• Contributing

• License

• Acknowledgments

Quick start

# 1. Clone & enter
git clone <repo-url> opencode-ast-mcp
cd opencode-ast-mcp

# 2. Create a virtualenv & install
python3.13 -m venv venv
./venv/bin/pip install -r requirements.txt

# 3. Configure secrets
cp .env.example .env
# Edit .env — set MINIMAX_API_KEY to your OpenRouter/OpenAI key
$EDITOR .env

# 4. Build the Podman sandbox image (one time)
podman compose -f sandbox/compose.yaml build

# 5. (Optional) Start LM Studio and load the Qwen model
lms server start
lms load qwen3-vl-4b-instruct-c_abliterated-v2-mlx --gpu max -c 16384 --yes

# 6. Register the MCP server in OpenCode
#    Edit ~/.config/opencode/opencode.json and add:
#    "opencode-ast": {
#      "type": "local",
#      "command": ["/absolute/path/to/opencode-ast-mcp/start.sh"]
#    }

Full setup walkthrough (with all 9 env vars and Podman machine init): docs/SETUP.md. Something broken? docs/TROUBLESHOOTING.md.

Tools at a glance

Full per-tool reference (params, returns, gotchas, decision tree): docs/TOOLS.md

How it works with OpenCode plan/build mode

OpenCode itself has a plan mode (read-only) and a build mode (full write access). The MCP tools map onto those modes as follows:

generate_sdd is the bridge between the two modes: it runs entirely in plan mode (no file writes), produces the SDD artifacts the user reviews, and the user then flips to build mode for execute_autonomous_loop_tool to walk through plan.md step by step. The 4 codebase-awareness tools (list_files, get_project_overview, search_symbol, find_references) are also read-only and can be used freely in plan mode to scope the investigation. See docs/ARCHITECTURE.md for the full request lifecycle and the four "Gotchas" (A: os.sync(), B: circuit breaker, C: thermal cooldown, D: mount validation) that make the system safe.

Project status

All 13 tools validated end-to-end as of v0.2.0:

As of v0.1.1, execute_autonomous_loop_tool actually applies M3's generated patches between iterations via git apply (with patch -p1 as fallback). See docs/TOOLS.md §7 for the full apply-failure flow.

Project layout

opencode-ast-mcp/
├── server.py              # FastMCP entry point — registers 13 tools
├── start.sh               # Boot script: starts LM Studio, runs server.py
├── config.py              # Centralised env-var configuration
├── ast_extractor.py       # tree-sitter powered skeleton/JSON/extract
├── codebase_index.py      # Mtime-cached recursive project index (v0.2.0)
├── lm_client.py           # LM Studio HTTP client (Qwen 3 VL 4B)
├── m3_client.py           # LLM brain client (OpenAI-compatible)
├── sandbox_runner.py      # Podman container execution + safety checks
├── autonomous_loop.py     # Code→test→fix loop with circuit breaker
├── dummy_auth.py          # Test fixture for the AST extractor
├── requirements.txt       # Python dependencies
├── LICENSE                # MIT
├── .env.example           # Template for .env
├── .github/
│   ├── workflows/test.yml # CI: 75 pytest in Podman on every push/PR
│   └── dependabot.yml     # Dependabot for pip
├── sandbox/
│   ├── Containerfile      # python:3.13-slim + pytest + git + patch
│   └── compose.yaml       # Podman compose for the sandbox
├── sdd/                   # Project's own SDD (product/tech/plan.md)
├── prompts/
│   └── system_prompt.md   # Brain orchestrator system prompt
├── tests/                 # pytest suite (75 tests)
├── docs/                  # ARCHITECTURE / TOOLS / SETUP / TROUBLESHOOTING
├── AGENTS.md              # Guidance for AI coding agents
├── CHANGELOG.md           # Release history
├── CONTRIBUTING.md        # How to contribute
├── SECURITY.md            # How to report security issues
└── venv/                  # Local virtualenv (gitignored)

Documentation

• docs/ARCHITECTURE.md — component diagram, request lifecycle, Gotchas A–D

• docs/TOOLS.md — full per-tool reference + decision tree

• docs/SETUP.md — 9-step setup with provider-swap matrix

• docs/TROUBLESHOOTING.md — 6 grouped failure modes with fixes

• sdd/ — the project's own software design docs

• AGENTS.md — guidance for AI agents (OpenCode-using and contributor)

• prompts/system_prompt.md — the brain's own system prompt

Contributing

PRs welcome. The dev loop is:

./venv/bin/pip install -r requirements.txt
./venv/bin/python -m pytest tests/ -v        # host, fast
# or
podman compose -f sandbox/compose.yaml run --rm opencode-sandbox \
  bash -c "cd /workspace && pip install -q -r requirements.txt && python -m pytest tests/ -v"
# sandbox, matches CI

# Add a tool → see AGENTS.md "Adding a new MCP tool"
# Add a language → see AGENTS.md "Adding a new language to the AST extractor"

Please read AGENTS.md before changing code — it documents the module boundaries, safety constraints, and plan-mode etiquette that all contributors (human or AI) are expected to follow.

See CONTRIBUTING.md for the full contributor checklist and SECURITY.md for private disclosure.

License

MIT — © 2026 Tim

Acknowledgments

• tree-sitter — the AST parser that makes deterministic code analysis possible

• LM Studio + Qwen 3 VL 4B — local inference for per-function code review

• Anthropic Claude via OpenRouter — cloud-side SDD planning

• DeepSeek — default brain provider (open-source, OpenAI-compatible, strong structured output)

• Podman — rootless container isolation

• FastMCP — the Python MCP server SDK