Ladder_mcp

Windows-first MCP server and local web UI for agentic code work. Ladder_mcp exposes provider-neutral tools over Kimi Code and the local MiniMax mmx CLI, plus a visual workflow builder for configuring coder/reviewer development loops on localhost.

The original kimi_* tools remain available and stable, but new orchestration work should usually use the provider-neutral agent_* tools or --web mode.

Published on npm (version badge above). Supported platform is Windows 11 only.

Highlights

• Provider-neutral agents — agent_ask, agent_code, and agent_cycle run against Kimi or MiniMax with one MCP-facing interface.
• Visual workflow builder — ladder-mcp --web starts a localhost UI for composing task, caller model, coder, reviewer, verification, approval, and output blocks.
• Agentic codegen & analysis — point an agent at a repo to read or edit files.
• Kimi ACP transport — kimi_code drives Kimi over the ACP JSON-RPC protocol (one kimi acp process per call; continuity via session_id), with granular watchable live progress and interactive permission prompts.
• Background tasks — run several agent tasks in parallel and wait for each with a single blocking agent_tasks action=wait or kimi_tasks action=wait call (no polling loop), with a live TODO checklist surfaced as work proceeds.
• Dev cycle — agent_cycle runs an automated coder→reviewer loop (two independent agent sessions) until the reviewer approves or the caller's max_iterations budget is spent. This is the recommended way to write code with provider=minimax.
• Independent review — kimi_ask runs stateless questions or a skeptical second-opinion review of supplied material (no repo access, no edits).
• Session-aware — list, inspect, and resume Kimi sessions and Ladder-managed MiniMax sessions.
• Diagnostics & setup — one call to check provider install/auth/health, one to emit the MCP config for a Kimi-hosted server.
• Windows-native — resolves kimi.exe, ~/.kimi-code, and PATH correctly; no POSIX assumptions.

Requirements

• Windows 11
• Node.js ≥ 18
• Kimi Code CLI installed (kimi.exe on PATH or at ~/.kimi-code/bin/kimi.exe) and authenticated (~/.kimi-code/) for Kimi-backed tools
• MiniMax CLI (mmx on PATH) for agent_ask, agent_code, and agent_cycle with provider=minimax

Quick start (from npm)

You don't need to clone or build — the package is published on npm and your MCP client launches it via npx, or you can install the package directly.

Claude Code (one command):

claude mcp add ladder-mcp -- npx -y ladder-mcp

Or add it manually to your MCP config:

{
  "mcpServers": {
    "ladder-mcp": {
      "command": "npx",
      "args": ["-y", "ladder-mcp"]
    }
  }
}

Then in Claude Code run /mcp (should show ladder-mcp: connected) and call agent_status to confirm provider availability. kimi_status remains available for Kimi-specific diagnostics.

The server speaks MCP over stdio: it is launched and managed by the client, not run by hand. Running npx ladder-mcp directly will appear to "hang" — that is the server correctly waiting for a client. Exit with Ctrl+C.

Prefer a global install? npm install -g ladder-mcp, then use ladder-mcp as the command instead of npx -y ladder-mcp.

Or install locally into your project:

npm install ladder-mcp

Then point your MCP config at ./node_modules/.bin/ladder-mcp (or use npx -y ladder-mcp, which resolves the locally installed copy when available).

To let Kimi Code itself host this server, use the kimi_setup tool to produce/merge a .kimi-code/mcp.json entry.

Tools

Core (always on)

| Tool | Purpose | Key parameters | |------|---------|----------------| | kimi_code | Agentic work in a repository — analyze and (optionally) edit files. | prompt, work_dir, edit (default false = analysis-only), background, session_id (continue a session), timeout_ms (floor 30 min) | | kimi_ask | Stateless question, or independent review when context is supplied. Text only — no repo, no edits. | prompt, context (switches to verify mode), role (reviewer persona), timeout_ms | | kimi_sessions | List/inspect Kimi sessions from the CLI catalog, ACP, or both. | source (cli|acp|all, default all), work_dir, limit (default 20) | | kimi_tasks | Manage background work. | action (wait|status|output|cancel), task_id, session_id (cancel an ACP session), mode (final|full), offset, limit, timeout_ms (wait) | | kimi_status | Installation, auth, and diagnostics. | detail (basic|full), doctor_target (config|tui), doctor_path | | kimi_setup | Generate/merge the Kimi-hosted MCP config entry for this server. | scope (project|user), write (default false = preview only), project_dir, server_name | | agent_ask | Provider-neutral stateless question/review. | prompt, provider (kimi|minimax, default kimi), context, role, timeout_ms | | agent_code | Provider-neutral agentic code work — analyze and (optionally) edit files. For MiniMax codegen prefer agent_cycle. | prompt, work_dir, provider (kimi|minimax, default kimi), edit, background, session_id, timeout_ms | | agent_cycle | Iterative dev cycle: coder agent implements, independent reviewer agent reviews the diff, loop repeats until VERDICT: APPROVED or the iteration budget runs out. Recommended for codegen with provider=minimax. | prompt, work_dir, max_iterations (1–10), provider (both roles, default kimi), coder_provider, reviewer_provider, edit (default true), background, timeout_ms (per agent run) | | agent_sessions | List sessions across providers: Kimi (CLI catalog + ACP) and MiniMax (Ladder session store). | provider (kimi|minimax|all, default all), work_dir, limit | | agent_status | Installation/auth diagnostics for Kimi and MiniMax together. | detail (basic|full) | | agent_tasks | Provider-neutral background-task management (same store as kimi_tasks). | action (wait|status|output|cancel)*, task_id, session_id, mode, offset, limit, timeout_ms |

* = required.

kimi_code drives Kimi exclusively through the ACP JSON-RPC transport. Prefer the default foreground call: it blocks until Kimi finishes, streams live progress to clients that render it (Claude Code does), and costs the host model nothing while it waits. Set background: true only when you need several Kimi tasks running in parallel.

The MiniMax path runs a Ladder-owned agentic loop over per-iteration mmx chat calls. Since 1.11.1 the loop is hardened against two common MiniMax failure modes: a text-only turn without tool calls is auto-nudged to continue (at most 2 consecutive nudges, skipped on the last iteration), and an empty/truncated answer is retried up to 2 times per run with an instruction to split large file writes. Note the trade-off: a run that genuinely ends with a text answer incurs up to 2 extra confirmation round-trips before returning.

Experimental (off by default)

Enable with the environment variable LADDER_EXPERIMENTAL=1:

| Tool | Purpose | |------|---------| | kimi_export_session | Export a Kimi session ZIP (requires explicit output_path; excludes the global diagnostic log by default). | | kimi_visualize_session | Preview or launch the Kimi session visualizer on localhost (kimi vis --no-open). | | kimi_desktop_status | Read-only Kimi Desktop Work status probe. | | kimi_budget_probe | Guided budget-separation evidence workflow (does not submit Work tasks). |

Background tasks

Foreground (the default) is the right choice for a single task: the call blocks, live progress is visible, and no tokens are spent while waiting. Use background: true to run several Kimi tasks in parallel — each call returns immediately with a task id. Then wait with one blocking call instead of a polling loop (every status poll is a full model turn and costs tokens):

// 1. start two tasks in parallel
kimi_code { "prompt": "...", "work_dir": "C:\\repo1", "edit": true, "background": true }
kimi_code { "prompt": "...", "work_dir": "C:\\repo2", "edit": true, "background": true }
// 2. wait — blocks until the task finishes (or timeout_ms, default 20 min);
//    returns the status snapshot plus the last log lines
kimi_tasks { "action": "wait", "task_id": "task_1" }
// 3. read a paginated slice of the full transcript (TODO checklist + every action)
kimi_tasks { "action": "output", "task_id": "task_1", "mode": "full", "offset": 0, "limit": 100 }
// 4. quick non-blocking check — list all, or pass task_id; metadata only
kimi_tasks { "action": "status" }
// 5. stop early (kills the Kimi child process)
kimi_tasks { "action": "cancel", "task_id": "task_1" }

The task log keeps the full transcript — every progress event and each TODO snapshot as Kimi maintains its plan. The status action returns only metadata; the body is opt-in via output. On server shutdown all running background tasks are cancelled so no kimi acp child processes are orphaned.

Dev cycle (coder ↔ reviewer)

agent_cycle automates the "one agent codes, another reviews" loop inside a single tool call:

1. The coder session implements the task (edit: true).
2. The reviewer — a separate, always read-only session — inspects git diff plus the coder's report and must end with VERDICT: APPROVED or VERDICT: REVISE + a numbered fix list.
3. On REVISE the feedback goes back into the same coder session; the loop repeats until approval or max_iterations (set by the caller, 1–10).

Both roles default to one provider (different sessions/dialogues); override either role with coder_provider / reviewer_provider for cross-provider review. For MiniMax codegen this cycle is the recommended mode — it compensates for the single-shot quality gap without burning a second provider's quota by default.

agent_cycle {
  "prompt": "Add input validation to the /users endpoint",
  "work_dir": "C:\\repo",
  "provider": "minimax",
  "max_iterations": 3
}
// or in the background:
agent_cycle { ...same..., "background": true }
agent_tasks { "action": "wait", "task_id": "task_1" }

The result includes per-iteration verdicts, the final review, and both session ids (agent_code + session_id continues the coder session manually).

Configuration

Environment variables

| Variable | Effect | |----------|--------| | LADDER_EXPERIMENTAL=1 | Register the 4 experimental tools. | | KIMI_API_KEY | API key used by kimi_ask (alternatively set api_key in ~/.kimi-code/config.toml). KIMICODE_API_KEY is also accepted as a legacy name. |

Timeouts

Every tool that drives an agent accepts a timeout_ms override. Defaults: kimi_code over ACP has a 30 min (1 800 000 ms) floor — smaller values are raised to the floor; kimi_ask is 2 min (5 min in verify mode); agent_code / agent_cycle with provider=minimax default to 10 min (600 000 ms); API-backed calls default to 5 min; CLI admin calls default to 30 s.

Safety boundaries

• edit defaults to false (analysis-only intent). Read-only is enforced at the ACP proxy since 1.2.0: fs/write_text_file requests are rejected with a JSON-RPC error before touching disk, and mutating permission requests are denied (reads stay allowed), in addition to the read-only prompt guard. This is best-effort hardening within the protocol — an airtight guarantee would require OS-level sandboxing of the Kimi process.
• kimi_export_session requires an explicit output_path, stays within the working directory, and excludes the global diagnostic log by default.
• Desktop Work tools are experimental and read-only: they do not read the desktop token store, replay web auth, or submit desktop Work tasks.
• The vendored kimi-code-mcp/ is a read-only reference and is never edited or written to by the tools.

Web Mode

You can run ladder-mcp as a visual workflow builder UI instead of the MCP stdio server:

ladder-mcp --web [--host 127.0.0.1] [--port 58629] [--no-open]

This starts a lightweight Node.js HTTP server on localhost and prints the URL:

ladder-mcp web server running at http://127.0.0.1:58629/

If the default port is unavailable and --port was not specified, Ladder_mcp falls back to a free OS-assigned localhost port and prints that actual URL. Use --no-open when you want the URL printed but do not want the server to try to open a browser.

The web mode includes:

• Workflow Builder UI: graph block palette (task, agent, command, condition, approval, output), property panel, conditional routing, validation, save/load, run button
• Graph runtime: conditional edges (success, failure, approved, revise, always), bounded loops (maxSteps, maxNodeRuns), per-node state, and per-agent status with name/avatar metadata
• Agent controls: choose Kimi or MiniMax per agent, set role, detail level, timeout, role instructions, and explicit read-only/edit access (reviewers stay read-only)
• REST API: GET /api/status, GET /api/workflows, GET/PUT /api/workflows/:id, POST /api/workflows/validate, POST /api/runs, GET /api/runs/:id, GET /api/runs/:id/events (SSE), POST /api/runs/:id/cancel
• Workflow persistence: .ladder-mcp/workflows/*.json in the MCP server's project work directory. The server work directory is authoritative; browser-supplied workDir values are ignored.

Build from source (contributors)

npm install
npm run build      # compiles src/ -> dist/ (tests excluded)

Quick checks:

npm test           # vitest
npm run typecheck  # tsc --noEmit (incl. tests)
npm run dev        # run the server from source via tsx

Troubleshooting

• ladder-mcp not connected / tools missing — run agent_status for a provider overview, or kimi_status for Kimi-specific binary, catalog, credentials, config, and API diagnostics.
• Need the web UI address — when running ladder-mcp --web, read the printed ladder-mcp web server running at ... URL. If the default port is unavailable, the printed URL may use a different port.
• npx ladder-mcp seems to hang — expected; it is the stdio server waiting for a client. It is meant to be launched by your MCP client, not by hand.
• kimi_ask errors about a missing key — set KIMI_API_KEY (legacy KIMICODE_API_KEY is also accepted) or add api_key to ~/.kimi-code/config.toml. kimi_code does not need this key.
• kimi_code timed out — the Kimi process is stopped on timeout, but Kimi persists session state on disk and the response includes a session_id. Call kimi_code again with that session_id to continue the same Kimi session. Resume is best-effort and not guaranteed; do not start a new task or perform the work yourself.

Project layout

• src/ — the Ladder_mcp application (package ladder-mcp)
• kimi-code-mcp/ — upstream reference (read-only, MIT)

License

MIT. Ports logic from the MIT-licensed kimi-code-mcp reference.