MCP Tools Reference

Complete reference for all 14 dkod MCP tools. These tools use the dk_ prefix and are the primary interface for IDE-integrated agents (Claude Code, Cursor, Cline, Windsurf, etc.).

Workflow Overview

The typical agent workflow follows this sequence:

1. dk_connect — establish an isolated session
2. dk_context — query the codebase semantically
3. dk_file_read / dk_file_write / dk_file_list — workspace file I/O
4. dk_submit — submit a changeset (returns inline review summary)
5. dk_verify — run the verification pipeline
6. dk_review — get full code review findings
7. dk_approve — approve the changeset
8. dk_merge — integrate into dkod's semantic graph
9. dk_push — push to GitHub as a branch or PR

Use dk_status and dk_watch at any time to inspect state and monitor events.

dk_connect

Establish an isolated session workspace for an agent.

Parameters:

Response:

{
  "session_id": "sess_a1b2c3",
  "changeset_id": "cs_abc123",
  "workspace_id": "ws_x1y2z3",
  "codebase_version": "v1847",
  "summary": {
    "languages": ["rust", "typescript"],
    "total_symbols": 2847,
    "total_files": 156
  },
  "concurrency": {
    "active_sessions": 3,
    "other_sessions": [
      { "agent_id": "claude-code-v3", "intent": "Refactor auth", "active_files": ["src/auth.rs"] }
    ]
  }
}

When to call: At the start of every agent workflow. Each agent (or sub-agent) needs its own session.

dk_context

Query semantic context — symbols, call graphs, tests, and dependencies.

Parameters:

Response:

{
  "symbols": [
    {
      "symbol_name": "authenticate_user",
      "file_path": "src/auth/handler.rs",
      "signature": "fn authenticate_user(req: &Request) -> Result<User>",
      "test_symbol_ids": ["sym_t1a2b3"]
    }
  ],
  "estimated_tokens": 4521
}

When to call: Before making changes — to understand the code you're about to modify.

dk_file_read

Read a file from the session's workspace (includes overlay changes).

Parameters:

Response:

{
  "path": "src/auth/handler.rs",
  "content": "use crate::models::User;\n\nfn authenticate_user...",
  "hash": "a3f8c2..."
}

When to call: To read file contents before or after modifications.

dk_file_write

Write a file to the session's overlay. Returns soft conflict warnings if another session modified the same symbol.

Parameters:

Response:

{
  "new_hash": "b4e9d1...",
  "detected_changes": [
    { "symbol_name": "authenticate_user", "change_type": "modified" }
  ],
  "conflict_warnings": []
}

When conflict_warnings is non-empty, another active session has modified the same symbol. The write still succeeds — the warning is an early signal to adapt before submitting.

When to call: After reading a file and preparing changes.

dk_file_list

List files in the session's workspace.

Parameters:

Response:

{
  "files": [
    { "path": "src/auth/handler.rs", "size": 2847, "modified": true },
    { "path": "src/auth/oauth.rs", "size": 1204, "modified": false }
  ]
}

When to call: To discover files before reading or to check which files have been modified in the overlay.

dk_submit

Submit the session's changes as a changeset. Returns an inline review summary (local tier) — no separate call needed for the summary.

Parameters:

Response (accepted):

{
  "status": "accepted",
  "changeset_id": "cs_abc123",
  "review_summary": {
    "tier": "local",
    "score": 4,
    "findings_count": 1,
    "top_severity": "warning"
  }
}

Response (conflict):

{
  "status": "conflict",
  "conflicting_symbols": [
    {
      "symbol": "authenticate_user",
      "file": "src/auth/handler.rs",
      "base_version": "fn authenticate_user(req: &Request) -> Result<User>",
      "their_change": { "description": "Added rate_limit parameter", "change_type": "modified" },
      "your_change": { "description": "Changed return type to Result<AuthToken>", "change_type": "modified" }
    }
  ],
  "suggested_action": "proceed",
  "available_actions": ["proceed", "keep_yours", "keep_theirs", "manual"]
}

When to call: After making all file changes. The changeset is atomic — all changes are submitted together.

dk_verify

Run the verification pipeline (lint, typecheck, tests) on a submitted changeset.

Parameters:

Response:

{
  "status": "passed",
  "gates": [
    { "name": "typecheck", "status": "passed", "duration_ms": 1200 },
    { "name": "lint", "status": "passed", "duration_ms": 400 },
    { "name": "affected_tests", "status": "passed", "duration_ms": 8500 }
  ]
}

When to call: After dk_submit succeeds. Verification confirms structural correctness — tests pass, types check, lint rules satisfied.

dk_review

Get the full code review findings for a changeset. Returns both local and deep review results (if deep review is configured and complete).

Parameters:

Response (formatted markdown):

## LOCAL Review — Score: 3/5

- **WARNING** `TEST_GAP` rust/src/auth.rs (70% confidence)
  No test file covers rust/src/auth.rs.
  → Add or update tests alongside source changes.

- **INFO** `NAMING_CONVENTION` rust/src/auth.rs:42 (85% confidence)
  Function `doAuth` doesn't follow snake_case convention.
  → Rename to `do_auth`.

## DEEP Review — Score: 5/5

No findings.

Each finding includes severity (error, warning, info), category, file path and line number, confidence percentage, a message describing the issue, and a suggestion prefixed with →.

When to call: After dk_verify to check code quality before approving. Also useful for the orchestrator's review gate — score < 3 or error findings trigger a fix-and-resubmit loop.

dk_approve

Approve a submitted changeset, marking it ready for merge.

Parameters:

Response:

{
  "status": "approved",
  "changeset_id": "cs_abc123"
}

When to call: After both dk_verify and dk_review pass your quality gates.

dk_resolve

Resolve merge conflicts on a changeset.

Parameters:

Response:

{
  "status": "resolved",
  "changeset_id": "cs_abc123",
  "action_taken": "proceed"
}

proceed (recommended) — unblocks the merge. The agent should reconnect, re-read the updated code, and re-submit. keep_yours — this agent's changes take priority for conflicting symbols. keep_theirs — the other agent's changes take priority. manual — provide custom content for each conflicting symbol.

When to call: When dk_submit or dk_merge returns a conflict status.

dk_merge

Integrate an approved changeset into dkod's semantic code graph. This is an internal integration — not a GitHub merge.

Parameters:

Response (success):

{
  "status": "integrated",
  "merged_version": "v1848",
  "commit_hash": "e4f7a2b..."
}

Response (overwrite warning):

{
  "status": "overwrite_warning",
  "warnings": [
    {
      "file_path": "src/auth/handler.rs",
      "symbol_name": "authenticate_user",
      "other_agent": "claude-code-v3",
      "merged_at": "2026-03-21T10:30:00Z"
    }
  ],
  "available_actions": ["proceed", "review", "abort"]
}

When to call: After dk_approve. Use force: true to bypass overwrite warnings when you've reviewed the situation.

dk_push

Push integrated changes to a feature branch on GitHub and optionally create a pull request.

Parameters:

Response:

{
  "status": "pushed",
  "branch": "dkod/oauth2-refactor-a1b2c3",
  "pull_request_url": "https://github.com/org/repo/pull/42"
}

When to call: After dk_merge succeeds. This is the final step that makes changes visible on GitHub.

dk_status

Get the current session state, overlay info, and any active conflicts.

Parameters:

Response:

{
  "session_id": "sess_a1b2c3",
  "changeset_id": "cs_abc123",
  "status": "active",
  "modified_files": ["src/auth/handler.rs", "src/auth/oauth.rs"],
  "codebase_version": "v1847"
}

When to call: At any time to check the current state of a session.

dk_watch

Subscribe to real-time codebase events from other agents. Auto-started on dk_connect — returns buffered events since last call.

Parameters:

Response:

{
  "events": [
    {
      "event_type": "symbol.modified",
      "changeset_id": "cs_xyz789",
      "agent_id": "claude-code-v3",
      "session_id": "sess_d4e5f6",
      "affected_symbols": ["authenticate_user"],
      "affected_files": ["src/auth/handler.rs"],
      "details": "Agent modified authenticate_user"
    },
    {
      "event_type": "changeset.review.completed",
      "changeset_id": "cs_abc123",
      "data": {
        "tier": "deep",
        "score": 4,
        "findings_count": 2,
        "top_severity": "warning"
      }
    }
  ]
}

Review events (changeset.review.completed) include tier ("local" or "deep"), score, findings_count, and top_severity.

When to call: Periodically during long-running sessions to stay aware of other agents' changes and review completions.

Next Steps

• Code Review Intelligence — how review scores and findings work
• SDK Reference — Python and Rust SDK with programmatic tool calling
• Agent Protocol — the six protocol operations these tools implement
• Verification Pipeline — the quality gates behind dk_verify