MCP Tools

CodeRecon exposes 15 MCP tools across 5 groups (plus 1 dev-mode tool). Call describe(action="tool", name="<tool>") at any time to get full parameter documentation inline.

Orientation¶

Dev-mode only (enabled with recon up --dev-mode):

Introspection¶

describe¶

Get parameter documentation for any tool, or decode an error code.

{
  "action": "tool",
  "name": "recon"
}

{
  "action": "error",
  "code": "E_INDEX_NOT_READY"
}

Discovery¶

recon_scout¶

Codebase orientation — structure, graph analysis, health signals. Call this first on an unfamiliar repo to understand what you're working with.

{
  "scope": "src/coderecon/mcp"
}

Returns:

• tree — progressively compressed directory tree
• languages — language distribution
• entry_points — detected entry points
• top_files — PageRank-ranked most-imported files
• top_symbols — PageRank-ranked most-referenced symbols
• communities — Louvain module clusters
• cycles — circular dependency chains (Tarjan)
• coverage — test coverage rate
• lint — lint health summary
• context — one-sentence terrain summary
• warning — structural trap alert (only when a real hazard exists)
• zoom_targets — dirs collapsed during compression (use as scope for follow-up)

recon¶

Task-aware context retrieval. Given a natural language task description, returns ranked semantic spans with code snippets from the most relevant definitions.

Pipeline: retrieve → gate → rank → cutoff → snippet extraction. Top half of results include full code snippets. Bottom half include signature + docstring only.

{
  "task": "Add retry logic to the HTTP client when rate-limited",
  "seeds": ["HttpClient", "send_request"],
  "pins": ["src/http/client.py"],
  "read_only": true
}

Response fields:

recon_impact¶

Read-only reference analysis — find every place a symbol or file is referenced. Use this before deciding whether a rename/move is worth doing.

{
  "target": "HttpClient",
  "justification": "Planning to rename before refactoring"
}

Returns references list with path, line, match_text, and certainty. No refactor ID is created — this is always read-only.

Analysis¶

semantic_diff¶

Structural change summary from index facts. Diff the index between two Git refs, showing which definitions changed.

{
  "base": "HEAD",
  "target": "feature-branch",
  "paths": ["src/http/"]
}

graph_cycles¶

Detect dependency cycles in the codebase. Returns all strongly connected components (size > 1) with graph metadata. Unlike recon_scout, returns complete untruncated cycle data.

{
  "level": "file"
}

graph_communities¶

Detect module communities via Louvain community detection. Returns all communities with full member lists and graph metadata. Unlike recon_scout, returns complete untruncated community data.

{
  "level": "file",
  "resolution": 1.5
}

Test Impact¶

blast_radius¶

Compute blast radius for changed files. Resolves changed files to their definitions, then uses coverage data and call-graph reachability to identify affected tests with confidence scores.

{
  "changed_files": ["src/http/client.py", "src/http/retry.py"],
  "max_hops": 2
}

Returns ranked test candidates with distance and confidence scores.

covering_tests¶

Get covering tests for each definition in a file. Returns a mapping from def_uid to the test candidates that cover it. Useful for per-function test annotation in diff viewers.

{
  "file_path": "src/http/client.py"
}

recon_line_coverage¶

Get per-line coverage for a file. Returns covered/uncovered line numbers and optionally which tests hit each line in the specified range.

{
  "file_path": "src/http/client.py",
  "line_start": 50,
  "line_end": 100,
  "include_tests": true
}

Refactor¶

Structural refactors follow a preview → commit/cancel flow. No changes are written until you call refactor_commit.

refactor_rename  ──→  refactor_commit   (applies changes)
refactor_move    ──→  refactor_cancel   (discards preview)

refactor_rename¶

Rename a symbol across the entire codebase. Produces a preview with per-hunk certainty ratings.

{
  "symbol": "HttpClient",
  "new_name": "RestClient",
  "justification": "Aligning with REST naming conventions",
  "include_comments": true
}

Preview response includes:

• refactor_id — pass to refactor_commit or refactor_cancel
• preview.edits — per-file hunks with old, new, line, certainty
• preview.verification_required — true if any low-certainty matches need review
• display_to_user — human-readable summary to show the user

refactor_move¶

Move a file/module and automatically update all imports that reference it.

{
  "from_path": "src/http/client.py",
  "to_path": "src/rest/client.py",
  "justification": "Relocating to new module structure"
}

refactor_commit¶

Apply a previewed refactoring, or inspect low-certainty matches before committing.

Apply mode (no inspect_path):

{
  "refactor_id": "abc123"
}

Inspect mode (review low-certainty matches in a file before committing):

{
  "refactor_id": "abc123",
  "inspect_path": "src/utils/helpers.py",
  "context_lines": 3
}

refactor_cancel¶

Discard a pending refactoring preview without making any changes.

{
  "refactor_id": "abc123"
}

Commit¶

checkpoint¶

All-in-one lint → test → commit → (optional push) workflow. Designed to be the last step in a coding task.

{
  "changed_files": ["src/http/client.py", "tests/test_client.py"],
  "commit_message": "refactor: rename HttpClient to RestClient",
  "push": false
}

What checkpoint does:

1. Runs lint on the full repo (with auto-fix by default)
2. Checks for cached background test results from the daemon's test scheduler
3. If no cached results, falls back to live test discovery via import graph from changed_files
4. If commit_message is set and all checks pass: stage → pre-commit hooks → commit
5. If push is set: push to origin

Dev-Mode Tools¶

recon_raw_signals¶

Raw retrieval signals for ranking model training. Runs all retrievers (lexical, term match, graph, symbol) against the current index and returns the unfiltered candidate pool with per-retriever scores and ranks per DefFact. Does not run any model (ranker, cutoff, gate). Does not filter, sort, or truncate. Only available when the daemon is started with --dev-mode.

{
  "query": "HTTP retry logic",
  "seeds": ["HttpClient"],
  "pins": ["src/http/client.py"]
}

Typical Agent Workflow¶

1. recon_scout            → understand repo structure
2. recon(task=...)        → find relevant code
3. [read files, make edits]
4. recon_impact(...)      → verify nothing unexpected breaks
5. checkpoint(...)        → lint, test, commit

For structural renames / moves:

1. recon(task=...)
2. recon_impact(target=...)        → see scope
3. refactor_rename / refactor_move → preview
4. refactor_commit                 → apply
5. checkpoint(...)                 → verify & commit