Skip to main content

MCP Tools Server

The tools-mcp subcommand boots a stdio Model Context Protocol (MCP) server that exposes muonroi-cli's native developer tools — self-verification runs, Experience-Engine recall, per-session cost forensics, and LSP-backed code intelligence — to external agents (Claude Code, Cursor, Codex, custom MCP clients).

Where the MCP Harness Driver lets an agent drive the TUI, the Tools Server lets an agent call the CLI's analysis capabilities directly as structured JSON-RPC tools.

The implementation lives in src/mcp/tools-server.ts:156 (server registration) and is wired into the CLI at src/index.ts:1585 (tools-mcp command).

Overview​

  • Transport: stdio JSON-RPC (MCP SDK StdioServerTransport, src/mcp/tools-server.ts:169).
  • Server name / version: muonroi-tools / 0.1.0 (src/mcp/tools-server.ts:156).
  • Tool count: 9 (see Tool Catalogue).
  • Output envelope: every tool returns { content: [{ type: "text", text: <json> }] }; errors return the same envelope with isError: true and a { error, message } payload.

Launching the server​

muonroi-cli tools-mcp
# short alias:
mu tools-mcp
# or, from a checkout of this repo:
bun run src/index.ts tools-mcp

The process reads JSON-RPC over stdin and writes responses over stdout. Logs go to stderr.

Installation​

tools-mcp ships with the muonroi-cli binary. Install the CLI first:

# Linux / macOS (prebuilt binary, zero runtime deps)
curl -fsSL https://raw.githubusercontent.com/muonroi/muonroi-cli/master/install.sh | bash

# Windows PowerShell
irm https://raw.githubusercontent.com/muonroi/muonroi-cli/master/install.ps1 | iex

# or via Bun (requires Bun >= 1.3)
bun add -g muonroi-cli
note

Install with the prebuilt binary or bun add -g — not npm install -g. The TUI uses Bun-only import ... with { type: "file" } syntax that the Node ESM loader cannot parse. The standalone binary bundles its own runtime; bun add -g requires Bun on PATH. The binary exposes both muonroi-cli and mu.

MCP client configuration​

Add the following to your MCP client config (Claude Code, Cursor, or any SDK-compatible client). If the CLI is installed globally:

{
  "mcpServers": {
    "muonroi-tools": {
      "command": "muonroi-cli",
      "args": ["tools-mcp"]
    }
  }
}

From a repo checkout, point at the entrypoint via Bun:

{
  "mcpServers": {
    "muonroi-tools": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/muonroi-cli/src/index.ts", "tools-mcp"]
    }
  }
}

After restart, the client advertises 9 tools across the selfverify.*, ee.*, usage.*, and lsp.* namespaces.

Prerequisites​

Each tool group has its own dependency. The server starts regardless; a tool returns an error envelope if its backing service is unreachable.

GroupRequiresConfigured via
selfverify.*A muonroi-cli workspace (runs in-process). LLM-driven agentic mode needs a provider configured.CLI settings / provider config
ee.*A reachable Experience-Engine server.~/.experience/config.json → serverBaseUrl, serverAuthToken
usage.forensicsA session activity log.EXPERIENCE_ACTIVITY_LOG (default ~/.experience/activity.jsonl)
lsp.queryA running language server for the target file.CLI settings lsp.enabled, lsp.tool

Environment variables​

VariableDefaultPurpose
EXPERIENCE_ACTIVITY_LOG~/.experience/activity.jsonlPath to the JSONL activity log read by usage.forensics (src/ee/search.ts:49).
EXP_SESSION(unset)Optional source session id used to scope ee.query recall context (src/ee/search.ts:89).

Tool catalogue​

Inputs are validated with Zod; violations surface as MCP protocol errors before reaching tool code.

Self-verification​

Run and poll the CLI's self-verify pipeline (heuristic tier1 or LLM-driven agentic). selfverify.start returns immediately with a runId; poll selfverify.status / fetch selfverify.result.

ToolInputOutputSourcePurpose
selfverify.startmode: "tier1" | "agentic", since?: string, max?: 1..50, emit?: boolean, out?: string, goal?: string, llm?: string, turns?: 1..50{ runId }src/mcp/tools-server.ts:63Start a self-verify run; returns the run id for polling.
selfverify.statusrunId: string{ status, logTail, elapsedMs }src/mcp/tools-server.ts:102Status, log tail, and elapsed time of a running job.
selfverify.resultrunId: stringfull reportsrc/mcp/tools-server.ts:122Full report of a completed run (when status = "done").
selfverify.listnonerun summariessrc/mcp/tools-server.ts:137List recent self-verify runs with status + elapsed time.
selfverify.cancelrunId: string{ cancelled }src/mcp/tools-server.ts:148Best-effort cancel of a running job.

Experience Engine​

Active recall over the Experience-Engine brain (prior decisions, gotchas, task checkpoints).

ToolInputOutputSourcePurpose
ee.queryquery: string (1–1000), project?: string (≤200)ranked index with [id col] handlessrc/mcp/ee-tools.ts:42Scope-filtered retrieval across all experience tiers (T0 principles → T1 behavioral → T2 seeds → self-QA).
ee.healthnone{ ok, ... }src/mcp/ee-tools.ts:72Check Experience-Engine server reachability.

Cost forensics​

ToolInputOutputSourcePurpose
usage.forensicsprefix: string (1–100)per-session cost reportsrc/mcp/forensics-tools.ts:40Token-cost forensics by session-id prefix — peak input tokens, cache-hit ratio, per-event breakdown.

Code intelligence​

ToolInputOutputSourcePurpose
lsp.queryoperation: <LSP op>, filePath: string (1–1000), line?: number, character?: number, query?: string (≤1000)LSP resultsrc/mcp/lsp-tools.ts:43Semantic code intelligence via a language server.

Supported operation values: goToDefinition, findReferences, hover, documentSymbol, workspaceSymbol, goToImplementation, prepareCallHierarchy, incomingCalls, outgoingCalls.

Example: active recall before a risky step​

→ {"jsonrpc":"2.0","id":1,"method":"tools/call",
   "params":{"name":"ee.query",
   "arguments":{"query":"how is JWT auth toggled in control-plane",
   "project":"muonroi-control-plane"}}}
← {"jsonrpc":"2.0","id":1,"result":{"content":[{"type":"text",
   "text":"[id col] ... ranked recall lines ..."}]}}

After acting on a recalled hint, report the verdict with exp-feedback followed|ignored|noise <id> <col> so the brain learns — see the Experience Engine guide.

See also​