MCP server

kdo ships an MCP server as a first-class command. It speaks JSON-RPC 2.0 over stdio and exposes every workspace query an AI coding agent needs: orientation, context, symbol lookup, dep graph, affected-set, cross-workspace search, and task execution.

Start the server

kdo serve --transport stdio
kdo serve --transport stdio --agent claude
kdo serve --transport stdio --agent openclaw

Runs in the foreground, reads JSON-RPC messages on stdin, writes responses on stdout. Logs go to stderr. Intended to be started by an MCP client, not directly by a human.

Smoke-test manually:

echo '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"t","version":"1"}},"id":1}' \
  | kdo serve --transport stdio

You should see a JSON response with "serverInfo":{"name":"kdo",...}.

Agent profiles

The --agent flag tunes the server to the target agent’s characteristics. Each profile shifts token budgets, loop-detection thresholds, and tool-description verbosity. generic (default) works for anything MCP-spec-compliant.

Loop guard. Every tools/call passes through a sliding-window detector. N identical (tool, args) pairs in a row return a "loop detected" error instead of silently re-running. OpenClaw’s window is 3, Claude and generic are 5. A second detector catches thrash (many distinct calls in a very short window) using profile-tunable thresholds.

kdo setup <agent> writes the correct --agent flag into the client config automatically. If you’re wiring it manually, pick the profile that matches your agent.

Register with an agent

Claude Code

Preferred, one command:

kdo setup claude --global

Shells out to claude mcp add --scope user, updates ~/.claude/CLAUDE.md, seeds shared agent memory. Idempotent.

Manual equivalent:

claude mcp add --scope user kdo -- kdo serve --transport stdio --agent claude

Verify:

claude mcp list
# kdo: kdo serve --transport stdio --agent claude - ✓ Connected

Status: tested end-to-end. initialize, tools/list, tools/call all round-trip cleanly. Loop guard observed tripping on the 3rd duplicate call under the openclaw profile.

OpenClaw

Preferred, one command:

kdo setup openclaw --global

Writes an AgentSkills-spec SKILL.md under ~/.openclaw/skills/kdo/ and merges the MCP server into ~/.openclaw/openclaw.json at /mcpServers/kdo. Plain JSON, siblings preserved.

Manual equivalent - edit ~/.openclaw/openclaw.json:

{
  "mcpServers": {
    "kdo": {
      "command": "kdo",
      "args": ["serve", "--transport", "stdio", "--agent", "openclaw"]
    }
  }
}

Status: MCP server is spec-compliant and the registration schema matches OpenClaw’s documented format, but end-to-end verification against a live OpenClaw gateway is still pending.

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "kdo": {
      "command": "kdo",
      "args": ["serve", "--transport", "stdio"]
    }
  }
}

Zed, Cline, Continue, any other MCP-capable client

Point them at the same command: kdo serve --transport stdio. The specifics vary by client; check their MCP docs for the exact config file.

Tools

Seven tools/call methods. Every tool returns JSON and respects the workspace rooted at the CWD where kdo serve was started.

kdo_list_projects

List every project with a one-line summary. Start here: cheap orientation (~200 tokens).

Input: none Output: array of { name, path, language, summary, dep_count }

{
  "method": "tools/call",
  "params": {
    "name": "kdo_list_projects",
    "arguments": {}
  }
}

kdo_get_context

Token-budgeted context bundle for one project. Summary + public API signatures + dependency list, truncated with a visible marker if it would exceed the budget.

Input:

Output: markdown string

Typical use: after kdo_list_projects tells the agent what exists, this gives it just enough to make a change without running out of context.

kdo_read_symbol

Read a specific symbol body (function, struct, trait, class) via tree-sitter. Use when kdo_get_context shows only the signature and the agent needs the implementation.

Input:

Output: { file, line, body } or an error if the symbol wasn’t found.

kdo_dep_graph

Query the dependency graph: either what this project depends on, or what depends on it.

Input:

Output: array of project names.

kdo_affected

Which projects are affected by changes since a git ref. Uses the workspace dep graph: touching a leaf marks every dependent.

Input:

Output: array of project names.

Use at the start of a task to scope changes: “what could be broken by this PR?”

kdo_search_code

ripgrep-powered pattern search across every workspace source file. Respects .gitignore and .kdoignore.

Input:

Output: array of { file, line, match } hits.

kdo_run_task

Execute a task in one project from inside an agent conversation. Resolves the same way as kdo run on the CLI.

Input:

Output: { exit_code, stdout, stderr }.

Use with care: the task actually runs.

Resources

kdo also exposes pre-generated context files under .kdo/context/ as MCP resources. Clients that support resources/list + resources/read can attach them directly without calling kdo_get_context.

URI format: kdo://context/<project>

resources/list:

{
  "resources": [
    {
      "uri": "kdo://context/vault-sdk",
      "name": "vault-sdk context",
      "description": "Pre-generated context bundle for project `vault-sdk`.",
      "mimeType": "text/markdown"
    }
  ]
}

resources/read:

{
  "params": { "uri": "kdo://context/vault-sdk" }
}

Returns a contents[] array with the markdown body.

Recommended agent workflow

Order matters for token efficiency:

1. kdo_list_projects for orientation. One call, ~200 tokens.
2. kdo_get_context (or read the resource) for the specific project the agent is about to change.
3. kdo_dep_graph / kdo_affected to understand blast radius before editing.
4. kdo_read_symbol only when a specific function body is needed.
5. kdo_search_code for cross-project usage.
6. kdo_run_task to verify a change via test / build / lint.

Following this order typically cuts token consumption 5–10× versus letting the agent walk the filesystem.

Protocol version

Advertised protocol version: 2024-11-05. Capabilities declared in initialize:

{
  "capabilities": {
    "tools": {},
    "resources": { "listChanged": false, "subscribe": false }
  }
}

Keeping the context fresh

Context files are generated once during kdo init and cached under .kdo/context/. If you make big structural changes, re-run kdo init to regenerate. Incremental regeneration (only changed projects) is on the roadmap.

Troubleshooting

• “Connection failed” in Claude Code / other clients: run kdo serve --transport stdio manually and pipe in the initialize message above. If that works, the client’s config is pointing at the wrong binary path.
• Empty context / minimal signatures: make sure source files have public API markers (pub fn, export function, etc.). Check .kdoignore isn’t excluding source directories.
• Tool not found: confirm the version. Older versions didn’t ship kdo_run_task or resources. kdo --version should print 0.2.0-alpha.1 or later.

Roadmap

Planned but not yet shipped:

• SSE transport for remote/multi-agent setups
• Streaming context for oversized projects
• Incremental context regeneration via content hashes

Track status at TODO.md.