Consider converting opencode/* Codescribe integration into an MCP server

[akashdhruv]

Context

Today opencode/* provides an OpenCode plugin + skills/agents wrapper around the code-scribe CLI:

• opencode/plugins/csb_plugin_codescribe.ts defines tools (csb_tool_codescribe, provider/model listing) and shells out to code-scribe.
• opencode/skills/* and opencode/agents/* provide a planner/executor workflow and validation/bundling, but are OpenCode-runtime specific.

We want to evaluate (and potentially implement) a standalone MCP (Model Context Protocol) server so these capabilities can be used from any MCP-capable client (Claude Desktop/Cursor/Continue/etc.), not just OpenCode.

Goal

Create a standalone MCP server exposing Codescribe capabilities as MCP tools, with a clear config/auth story and parity with current command behavior.

Non-goals (recommended)

• Don't attempt to "run OpenCode skills" inside MCP; treat opencode/agents/*.md + opencode/skills/*.md as orchestration recipes/templates.
• Don't depend on OpenCode's client.config.get(); replace it with an explicit MCP server config format.

Proposed MCP Tools (MVP)

codescribe.run

• Input: { command, args: string[], cwd?, provider?, model? }
• Behavior: validate rules, normalize args, enforce -m opencode-env where required, spawn code-scribe, return structured result.

codescribe.providers

• Return configured provider IDs.

codescribe.models

• Input: { provider }
• Return configured model IDs for that provider.

Nice-to-have

• codescribe.validate (dry-run validation + returns normalized invocation)
• codescribe.translateBundle (optional bundle execution if multi-step orchestration is needed server-side)

Config/Auth (key decision)

Replace client.config.get() with explicit server configuration:

• Config file (e.g. codescribe-mcp.config.json or .toml)
  • providers: { [providerId]: { baseURL?, models: string[] } }
• Env overrides (optional):
  • CODESCRIBE_MCP_CONFIG=/path/to/config
  • Possibly reuse existing OPENCODE_CODESCRIBE_PROVIDER|MODEL|BASEURL as overrides

Security notes:

• Avoid allowing user-provided baseURL in tool inputs (prefer config-only).
• Never echo secrets in tool output.

Runtime/Implementation Outline

• New mcp/ package (TypeScript):
  • src/server.ts MCP entrypoint
  • src/config.ts config loader + schema validation
  • src/codescribe.ts spawn wrapper + arg normalization
  • src/tools/* tool implementations
• Use a standard MCP server SDK (Node). Prefer @modelcontextprotocol/sdk.
• Prefer spawn over spawnSync for better streaming and timeouts.

Behavior Parity Requirements (from existing plugin)

Port the existing command rules/constraints:

Command	Requirements
translate	requires -p <prompt.toml>, forbids -r, Fortran files only, force -m opencode-env
inspect	requires -q \"<query>\", force -m opencode-env
update	requires at least one of -p or -q, optional repeatable -r, force -m opencode-env
generate	prompt positional, optional repeatable -r, force -m opencode-env
draft	single Fortran file only
index	single directory
format	TOML files

For {inspect, generate, update, translate}:

• Require provider + model
• Strip any user -m/--model args and append -m opencode-env

Output Contract

Return structured tool results (JSON-ish) rather than markdown:

{
  "ok": true,
  "exitCode": 0,
  "durationMs": 1234,
  "stdout": "...",
  "stderr": "...",
  "normalizedArgs": ["translate", "src/foo.F90", "-p", "prompts/code_translation.toml", "-m", "opencode-env"],
  "envApplied": { "provider": "argo", "model": "claude-sonnet-4", "baseURL": "..." }
}

Optional: summary string for humans.

Testing Plan

• Unit tests:
  • arg normalization (-m, --model, --model=...)
  • per-command validation rules
  • config loading + schema validation
• Integration tests (optional):
  • run codescribe.providers/codescribe.models
  • run codescribe.run format on a temp TOML
  • mock code-scribe binary if needed

Migration / Compatibility Plan

1. Keep the existing OpenCode plugin initially.
2. Optionally later: have the OpenCode plugin call the MCP server instead of spawning code-scribe directly.
3. Port opencode/agents/*.md into "client prompt templates" instructing how to use MCP tools.

Acceptance Criteria

• MCP server starts via stdio transport and is usable by a generic MCP client.
• codescribe.run reproduces existing rules and output is structured.
• Providers/models are configurable without OpenCode runtime.
• No secrets leak in tool outputs.

Open Question

Which MCP client(s) should be the initial target (affects packaging + transport defaults)?

• Claude Desktop / Cursor / Continue / any MCP client
• Recommended default: "any MCP client" via stdio + canonical SDK