Agent tools (MCP)

arcade-agent ships an MCP server (arcade-mcp) with 18 tools. Fourteen cover the full analysis pipeline — ingest, parse, recover an architecture, detect smells, compute metrics, compare versions, and report on the result; four are task-shaped context tools designed for the questions agents actually ask mid-edit.

Setup

Agents evaluating this tool can fetch the machine-readable docs index at https://arcade-agent.dev/llms.txt rather than crawling this site page by page.

All five clients below point at the same server: uvx fetches and runs arcade-agent with the mcp extra (required — arcade-mcp fails to start without it) on first launch, so there’s nothing to pre-install. Only the file path and the top-level JSON key differ per client.

Claude Code — .mcp.json

{
  "mcpServers": {
    "arcade-agent": {
      "command": "uvx",
      "args": ["--from", "arcade-agent[mcp]", "arcade-mcp"]
    }
  }
}

Cursor — ~/.cursor/mcp.json

{
  "mcpServers": {
    "arcade-agent": {
      "command": "uvx",
      "args": ["--from", "arcade-agent[mcp]", "arcade-mcp"]
    }
  }
}

Claude Desktop — claude_desktop_config.json

{
  "mcpServers": {
    "arcade-agent": {
      "command": "uvx",
      "args": ["--from", "arcade-agent[mcp]", "arcade-mcp"]
    }
  }
}

VS Code — .vscode/mcp.json

{
  "servers": {
    "arcade-agent": {
      "command": "uvx",
      "args": ["--from", "arcade-agent[mcp]", "arcade-mcp"]
    }
  }
}

Windsurf — ~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "arcade-agent": {
      "command": "uvx",
      "args": ["--from", "arcade-agent[mcp]", "arcade-mcp"]
    }
  }
}

The tools

Tool	What it answers	When the agent calls it
ingest	Where’s the source, and what’s actually in scope?	First — before anything else. Accepts a git URL or local path, auto-detects the source root, and filters out test/vendor/build directories.
parse	What are the entities and dependency edges in this codebase?	Right after ingest, before recover, summarize, or any tool that needs a dep_graph.
analyze	Run the whole pipeline — ingest, parse, recover, smells, metrics — in one call.	When starting fresh on a repo and one round-trip is worth more than stage-by-stage control; returns per-stage session IDs (even on partial failure).
recover	How do these entities group into components (pkg/wca/acdc/arc/limbo)?	After parse, before the smell/metric/query/explain tools that need an architecture.
detect_smells	Which components have a dependency cycle, concern overload, scattered functionality, or link overload?	After recover, when auditing architecture health.
compute_metrics	How cohesive and coupled is this architecture (RCI, TurboMQ, BasicMQ, connectivity, coupling ratios)?	After recover, to quantify what detect_smells flagged qualitatively.
compare	What changed between two recovered architectures — components added, removed, split, or merged?	Comparing two versions (e.g. two commits), matched via the Hungarian algorithm.
query	Ad hoc structural questions: component_of, dependencies, dependents, entities, most_coupled, summary, largest.	Mid-investigation, once an architecture and dep_graph exist, for one specific follow-up.
visualize	How do I get a shareable report or diagram (HTML, DOT, JSON, RSF, Mermaid) of this analysis?	End of a pipeline run, to hand a human-readable artifact to someone else.
summarize	What does this codebase — or one package — look like at a glance: structure, dependency hotspots, entry points?	First orientation pass on a repo, or drilling into one package via focus.
explain_component	What does this one component do: responsibility, entities, public API surface, dependencies, cohesion?	Drilling into a single component surfaced by recover, detect_smells, or query.
find_relevant	Which entities relate to this natural-language topic?	Searching code by concept or keyword rather than an exact name.
api_surface ★	What is safe to call on this component from outside?	When wiring into unfamiliar code.
diff_impact ★	What breaks if these files change?	Before and after editing — blast radius.
context_for_task ★	Which components, entities and edges matter for this task?	Before starting work it can’t scope.
dependency_cone ★	What does this component pull in, transitively?	When judging extraction or upgrade cost.
get_full_result	What’s the untruncated data behind a summarized or budget-truncated response?	After a summary was cut down by max_tokens, when the detail is actually needed.
list_sessions	What session IDs do I already have open, and what type is each?	Before referencing a dep_graph/architecture argument in another call, or resuming mid-session.

★ The four task-shaped context tools each get a dedicated page with worked examples: see the sidebar or the links above.

Token budgets

Every tool accepts an optional max_tokens argument, and responses that exceed it degrade rather than error. The MCP adapter picks one of two strategies depending on the response shape:

• Responses carrying a graph or architecture key (most pipeline tools) go through progressive, ordered reduction, stopping at the first level that fits the budget: return as-is if already within budget; cap each architecture component’s entity list to 10 (recording the original count as entities_truncated); collapse the graph’s entities map from full records to a bare FQN→kind mapping; drop the edges list in favor of an edge_summary relation-count dict; drop the entities map entirely, keeping only a kind-count entity_summary; reduce components to just name and num_entities; and finally drop the packages map, keeping only num_packages. A tight budget can mean losing entity or edge detail outright — this is per-level detail dropping, not smarter summarization.
• Everything else (session summaries, query/compare/explain results) goes through generic enforcement: it repeatedly finds and deletes the single largest top-level key — excluding the protected session_id, type, and _budget_truncated keys — until the payload fits or nothing droppable remains, and flags the result with _budget_truncated: true.

Either way, a truncated response still carries its session_id — call get_full_result to fetch the untruncated data behind it.

What this buys in practice

Measured 2026-07-21, arcade-agent 0.2.0, click@cfa01eeb78.

One real run, not a projection. Scenario: an agent is asked to change the signature of click.core.Context.invoke — what do I need to read? — against a shallow clone of pallets/click, the same repo used throughout this site’s worked examples.

After the one-time setup (ingest → parse → recover — three calls, amortized across a whole session, not counted below), a single context_for_task call returned a ranked 15-file slice with per-file reasons, in 16,169 tokens — over-broad on this repo due to a keyword-tokenizer quirk (short words like “the”/“of”/“to” survive context_for_task’s _tokenize step, which filters only on length and has no stopword list, so each picks up a file-path substring match; see methodology).

The comparison below is not against that 15-file list — it’s against a baseline derived independently from the dependency graph itself, per the methodology’s protocol: the file(s) that define the task’s target entities (click.core.Context, click.core.Context.invoke) plus any file whose entities carry a graph edge pointing at them. On this repo the parsed graph holds only 29 import/extends edges across 572 entities — no call edges — and none target Context at all, so the independent baseline collapses to the one file that defines it, read in full:

	With arcade-agent (context_for_task response)	Raw baseline (dep-graph-derived: click/core.py)
Tool calls / files read	1 call	1 file
Tokens (len(text)/4 estimate)	16,169	36,897
Reduction		56%

Both token counts use the same estimator, disclosed as an estimate, not a real tokenizer count. The file-count line above is exactly 1 vs. 1 because, on this scenario, the dependency graph has no edges pointing at either target entity — so the tool’s advantage here is entirely in token density, not file-count reduction: the tool’s response (which, per the tokenizer-quirk note above, actually covers matched entities across 15 files, more than this baseline) is still under half the size of reading the one relevant file in full. Full arithmetic, the edge query that derived the baseline, the raw JSON, and a diff_impact run disclosed separately (its blast-radius signal was weak on click’s edge-sparse graph — the same sparsity that collapses the baseline here to one file) are in the full methodology.

Reproduce this

uv venv .venv && source .venv/bin/activate
uv pip install "arcade-agent[languages,mcp]==0.2.0"
git clone --depth 1 https://github.com/pallets/click.git click-repo

Then drive arcade-mcp over stdio with the official mcp client SDK: ingest the clone, parse it, recover an architecture (algorithm="pkg", pkg_depth=1), then call context_for_task with task="change the signature of click.core.Context.invoke — what do I need to read?". Separately, call arcade_agent.tools.parse.parse(...) directly in Python to get the DependencyGraph object and query graph.edges for any edge targeting click.core.Context or click.core.Context.invoke — that query is what derives the raw baseline, not the MCP tool’s own output. The full scripts and raw output are in the methodology doc linked above.