opencode-reasonix-mcp

MCP server that lets OpenCode drive Reasonix (DeepSeek V4) sub-tasks — ~$0.00004/task, ~95% prefix-cache hit rate, ~99% cheaper than running every sub-task on Claude or GPT.

中文文档

Table of contents

• Quick start
• What it does
• Configuration
• Tools
• OpenCode vs oh-my-opencode
• Why prefix cache saves tokens
• Architecture
• Development
• License

Quick start

Requirements: Node.js ≥ 18 · Reasonix CLI or desktop app · DeepSeek API key

1. Install Reasonix and set your API key:

npm install -g reasonix
export DEEPSEEK_API_KEY=sk-...   # or: reasonix setup

2. Choose install method:

   Global install (recommended for daily use — faster startup):

   npm install -g git+https://github.com/WHAT-BUG/opencode-reasonix-mcp.git

   Then in opencode.json:

   {
     "mcp": {
       "opencode-reasonix": {
         "command": ["opencode-reasonix-mcp"],
         "enabled": true,
         "type": "local"
       }
     }
   }

   npx (quick trial — may be slow on first run):

   {
     "command": ["npx", "-y", "github:WHAT-BUG/opencode-reasonix-mcp"]
   }

3. Restart OpenCode — the agent should see reasonix_execute, reasonix_decide, and reasonix_stats.

Full sample: examples/opencode.json

Not on npm yet — install via GitHub as above. Pin a release: github:WHAT-BUG/opencode-reasonix-mcp#v1.0.0

What it does

OpenCode owns the workspace (files, LSP, Git, task decomposition). This MCP offloads stateless sub-tasks — code generation, review, analysis — to Reasonix via reasonix run. Code must be inlined in the prompt; Reasonix does not read your repo.

OpenCode main agent  ──MCP──►  Reasonix CLI  ──►  DeepSeek API
  (orchestration + I/O)         (sub-task worker)    (prefix cache)

Tool	Purpose
reasonix_execute	Run a sub-task (auto / flash / pro, effort level)
reasonix_decide	Advise: handle locally vs route to Reasonix
reasonix_stats	Cost and cache stats from a JSONL transcript

Configuration

API key detection

Checked in order: --api-key → DEEPSEEK_API_KEY → desktop credentials file → ~/.reasonix/config.json

OS	Desktop credentials path
macOS	~/Library/Application Support/reasonix/credentials
Windows	%APPDATA%\reasonix\credentials
Linux	~/.config/reasonix/credentials

CLI options

All optional — zero-config works in most setups.

opencode-reasonix-mcp [options]

  --api-key <key>          DeepSeek API key
  --reasonix-path <path>   Path to reasonix binary
  --sandbox-dir <dir>      Working directory (default: /tmp)
  --timeout <seconds>      Child timeout (default: auto by preset×effort, 0=off)
  --version / --help

Pass options in opencode.json:

{
  "command": ["opencode-reasonix-mcp", "--sandbox-dir", "/my/workdir"]
}

Tools

reasonix_execute

One-shot code gen / review / analysis.

Parameter	Default	Description
task	—	Required. Prompt with all relevant code inline
preset	auto	auto · flash (deepseek-v4-flash) · pro (deepseek-v4-pro)
effort	medium	low · medium · high · max

preset=auto uses word-boundary keywords: pro for architecture, refactor, security… · flash for typo, rename, comment… · default flash.

reasonix_decide

Heuristic routing advice. The agent must call this explicitly — it never auto-intercepts reasonix_execute. Do not blindly trust decision: "skip".

Parameter	Default	Description
task	—	Required. Task description
model_context	paid	free = orchestrator on free model · paid = always route
context_requirement	small	small · large (needs 1M window)

Returns { decision: "skip" \| "route", preset, reason }.

reasonix_stats

Cost and cache statistics from a Reasonix JSONL transcript path.

OpenCode vs oh-my-opencode

Does not require oh-my-opencode. Sisyphus-style orchestration is a typical pattern, not a dependency.

	Vanilla OpenCode	+ oh-my-opencode (Sisyphus)
Setup	mcp.opencode-reasonix in opencode.json	Same + plugin
Scheduling	Agent decides when to call tools	Workflow may call reasonix_decide first
Best for	Ad-hoc sub-task delegation	High-volume automated dispatch

Why prefix cache saves tokens

Each reasonix run shares the same system prompt prefix → DeepSeek prefix cache hits on ~90% of tokens (94–95% measured). Stateless one-shot calls are enough; savings come from prefix reuse, not long sessions.

Metric	Typical value
Cost per sub-task	~$0.00004
Cache hit rate	94–95%
vs Claude / GPT sub-tasks	~99% savings

Provider	Avg task cost
DeepSeek V4-Flash (via Reasonix)	$0.00004
Direct DeepSeek API (no cache)	~$0.0007
Claude Sonnet / GPT-5	$0.01–0.10

When to use what: this MCP for stateless, cost-sensitive sub-tasks · direct DeepSeek API for custom streaming/batch · Claude/GPT MCP for frontier reasoning that cheaper models cannot handle.

Architecture

OpenCode (optional: Sisyphus)
  ├─ MCP ──► opencode-reasonix-mcp ──► reasonix run ──► DeepSeek
  ├─ File I/O / LSP / Git / AST-grep
  └─ Code gen / review / analysis (via MCP)

Development

git clone https://github.com/WHAT-BUG/opencode-reasonix-mcp
cd opencode-reasonix-mcp
npm link

Run tests (clone only — npm install -g skips test files):

node --test test/*.test.js

Debug MCP:

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | node index.js

Local OpenCode config after npm link: "command": ["opencode-reasonix-mcp"]

Path	Description
index.js	MCP server + CLI
bin/opencode-reasonix-mcp	Entry point
test/	Unit tests
examples/	Sample configs

License

MIT