MCP Server

ContextGraph exposes its knowledge graph to AI agents over the Model Context Protocol (MCP) via stdio. Start the server with:

./gradlew :modules:cli:installDist
modules/cli/build/install/contextgraph/bin/contextgraph serve-mcp

Claude Desktop

Point the client at the installed launcher rather than at Gradle — an MCP client starts the server on every session, and a Gradle daemon start on each call is pure latency.

{
  "mcpServers": {
    "contextgraph": {
      "command": "/absolute/path/to/context-graph/modules/cli/build/install/contextgraph/bin/contextgraph",
      "args": ["serve-mcp"]
    }
  }
}

Tools

The server registers 11 tools. One of them is the primary entry point; the other ten are secondary and mostly return pointers you then have to follow with a separate file read.

contextgraph.explore — primary

Answers a natural-language question about the codebase in one call. Returns the modules that matched with their descriptions, the relevant symbols with verbatim source, the resolved edges between them — each carrying its confidence and the resolution rung that produced it — and blast radius, meaning what depends on those symbols.

The response is capped at a token budget: the highest-ranked symbols carry full source, the rest carry signature and location only and are marked "elided": true. A question that matches nothing returns "empty": true rather than an error.

Prefer this over every tool below for most questions. It exists because agents choose badly among many similar tools and chaining thin calls costs more than one fat call.

contextgraph.index_project

Index a project directory into the graph.

contextgraph.search_nodes

Full-text search across all nodes, with optional type filtering.

contextgraph.get_node

Fetch a single node by ID, including its properties and provenance (source file + line numbers).

contextgraph.expand_node

BFS neighborhood expansion — returns all nodes reachable within depth hops.

contextgraph.find_path

Find the shortest explanation path between two nodes using Dijkstra's algorithm.

contextgraph.get_evidence

Return the full provenance chain for a node — every file and line number that contributed to it.

contextgraph.impact_analysis

Every node that points at this one — its direct dependents, and for a method its resolved call sites, each with its node ID and file:line location. This is the tool for "what calls X" and "what breaks if I change X" when you want that one answer without the rest of an explore response.

contextgraph.related_files

Return all source file paths associated with a node via provenance records.

contextgraph.build_context

Given a task description, searches the graph, expands neighborhoods, and returns a ranked set of nodes and edges relevant to the task — pointers rather than source. For a question you want answered, contextgraph.explore is the better call.

contextgraph.generate_report

Generate GRAPH_REPORT.md and graph.html in the specified output directory.

Resources

The server also exposes read-only MCP resources:

Prompts