Contour MCP
Everything Contour
does endpoint↔consumer mapping, full chain tracing (UI → API → service → database),
drift detection, test coverage overlay, scheduled-task / service-to-service /
event-driven flow tracking, use-case tagging with Jira linkage, and the shareable visual
report plus a bundled local, read-only MCP server that exposes the same trace
index to Claude Code, Claude Desktop, and other MCP clients.
This extension installs side by side with plain Contour you don't need to choose one. If you don't
need the MCP server, install
Contour
instead; this is a superset of it.
How this differs from vanilla Contour
- Same trace engine. The indexing, matching, drift detection, coverage overlay, and
use-case tagging are consumed as a versioned package
(
@contour/trace-engine-mcp, synced from the original repo see
tools/sync-trace-engine/sync.js), not a hand-maintained fork. A version bump on that
dependency is enough to pick up an upstream fix.
- Plus an MCP server. On first activation this extension writes a local, git-ignored
MCP server registration (
.mcp.json for Claude Code, .vscode/mcp.json for VS Code's
own MCP support) pointing at a bundled Node script no separate install step, and each
client's own trust prompt still applies (this extension never auto-approves itself).
- The trace index becomes a cache file, not just in-memory extension state. Every
time Contour finishes a reindex (full or incremental never a separate timer), it
atomically rewrites
.contour-mcp/cache.json in your workspace. The MCP server reads
that file fresh on every tool call, so an agent's answer always reflects your latest
edit, or clearly tells you to wait for Contour to finish reindexing rather than
guessing.
Install
Install from the Marketplace (search "Contour MCP"), or build and install a .vsix
locally:
npm install
npm run compile
npx vsce package
code --install-extension api-contract-tracer-mcp-*.vsix
Open a workspace with at least one backend (Java/Spring) and one frontend (React/JS)
folder. Contour MCP indexes automatically on activation; watch the "Contour MCP" output
channel for progress. Once the first index completes, the bundled MCP server is
registered automatically Claude Code or VS Code will prompt you to trust it the first
time it's discovered, same as adding any other MCP server by hand.
All read-only. None writes a file, runs a command, or calls any external API including
Jira: if a flow is tagged with a Jira key, only what's already stored locally is
surfaced, never a live lookup.
| Tool |
Input |
Returns |
list_flows |
entity |
Flow summaries (endpoints, scheduled tasks, service calls, events) touching a file, service, or table |
get_trace |
file, symbol? |
The scoped call chain for a file UI/consumer → API → service → database |
get_flow |
jira_key |
The flow tagged to that ticket description, tags, test coverage, as stored locally |
get_drift |
scope? |
Where the traced architecture and the real code have diverged, optionally scoped |
export_context |
scope, task |
A minimal, packaged context bundle sized for a specific task |
Example prompts, once the server is connected:
list_flows "What flows touch OrderController?"get_trace "Trace OrderController.java end to end, from the API down to the
database."get_flow "What's the flow tagged to ORD-123, and is it tested?"get_drift "Has anything drifted between the frontend and backend in the
orders service?"export_context "I need to add a cancel-order endpoint give me the minimal
context for that."
Staleness
The MCP server never trusts an in-memory copy it re-reads .contour-mcp/cache.json
from disk on every call. If the cache is missing, or a file your query touches was
edited after the cache was last built, or the cache itself has passed its backstop max
age (contourMCP.cacheStalenessThresholdMinutes, default 360 minutes), you get a clear
message to let Contour finish reindexing never stale or fabricated data.
