MCP tools: overview

Most MCP servers expose tools that mirror data entities: one file, one symbol, one diff. That forces the agent into long sequential chains. Repowise exposes a small, curated set of task-shaped tools instead. Pass multiple targets in one call. Get complete context (docs, ownership, metrics, history, decisions) back. Same answer, fewer round-trips, fewer tokens.

The core tools#

These ten tools are the documented core surface, available in both single-repo and workspace modes:

get_risk and get_change_risk are the pair people mix up. get_risk scores indexed files by path and can report blast radius. get_change_risk scores the shape of a live diff, so it catches risky small changes that a file-level view misses.

One more tool is on by default: list_repos enumerates the repos the server can reach. It is mostly useful in workspace mode, where it lists every workspace repo and the default. That makes 11 tools advertised by default in single-repo mode, though only the ten above are worth an agent's attention on a typical task.

In workspace mode, every tool accepts a repo parameter. Pass a specific repo name, or "all" to federate across the workspace.

Two more, on by default in workspace mode#

When the server runs over a workspace (several repos indexed together), two additional tools appear automatically. They answer cross-repo questions that have no single-repo equivalent.

They are documented in full on the Workspace MCP mode page.

A third workspace-scoped tool, get_conformance (declared dependency-rule violations and dependency cycles), is opt-in even inside a workspace: enable it with mcp.tools: ["+get_conformance"]. Its findings still surface automatically in get_risk's PR-mode directive (conformance_violations / dependency_cycles) without opting the tool itself in.

Three opt-in tools#

get_dependency_path (shortest dependency path between two files or modules), get_execution_flows (entry points + call traces), and generate_refactoring_code (turns a get_health(include=["refactoring"]) plan into code + a diff) are registered tools that ship with the server but are off by default in every mode. Turn them on per repo in .repowise/config.yaml:

mcp:
  tools: ["+get_execution_flows", "+get_dependency_path", "+generate_refactoring_code"]

or per launch with repowise mcp --tools "+get_execution_flows". See Configuring the tool surface for the full +/- delta syntax and the explicit-allowlist / all shapes.

generate_refactoring_code has a second gate on top of the tool-surface one: even opted in, it returns an error unless refactoring.llm.enabled is also set in .repowise/config.yaml.

Truncation is reversible. Responses are token-budgeted, but dropped content is no longer silently lost: a _meta.omitted envelope lists refs (repowise#<12-hex>) that resolve via get_symbol, or repowise expand <ref> from a shell, with no extra tool. See Distill for the full reversibility model.

Connecting#

repowise init automatically writes .mcp.json at the project root and (for Claude Code) registers the server in ~/.claude/settings.json. You don't need to do anything else.

To wire up another editor manually:

{
  "mcpServers": {
    "repowise": {
      "command": "repowise",
      "args": ["mcp", "/path/to/your/project"]
    }
  }
}

A real five-call task#

"Add rate limiting to all API endpoints." Without repowise, an agent greps and reads files for ~30 calls. With repowise, five:

get_overview()
get_context(targets=["middleware", "api/routes", "payments"])
get_risk(targets=["middleware/auth.ts"])
get_why(query="rate limiting")
search_codebase(query="rate limit OR throttle OR retry")

That's the design point. Each call returns a task-shaped slice of the codebase, not a single file or symbol, so the agent reaches a decision in one or two passes instead of ten.

How to compose these#

Most tasks aren't a single call. These are the hand-offs that come up most often: what a tool's output points you to next.

Why a curated surface#

Repowise's internal modules expose more graph navigation primitives (callers/callees, dependency paths, graph metrics, execution flows, community detection). Most of that surfaces as include options on the core tools rather than separate calls; two of the primitives (get_dependency_path, get_execution_flows) are real MCP tools but ship off by default, because every extra tool in the schema is overhead on tasks that don't need it.

The public tools are deliberately one level up. get_context absorbs callers, callees, metrics, and community into a single call via its include parameter. get_risk rolls up hotspot, dependents, co-changes, reviewers, and test gaps. get_why covers natural-language search, path lookup, and the global health dashboard. get_health rolls up the three-signal marker scores plus targeted findings.

If you're building on top of repowise programmatically, the packages/server Python API exposes the lower-level primitives. The MCP surface is what AI agents see, and AI agents do better with fewer, richer tools.