MCP Server

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

Terminal

./gradlew :modules:cli:run --args="serve-mcp"

Claude Desktop

claude_desktop_config.json

{
  "mcpServers": {
    "contextgraph": {
      "command": "/absolute/path/to/context-graph/gradlew",
      "args": [
        "-p", "/absolute/path/to/context-graph",
        ":modules:cli:run",
        "--args=serve-mcp"
      ]
    }
  }
}

Tools

The server registers 10 tools that agents can call to query the knowledge graph.

contextgraph.index_project

Index a project directory into the graph.

Parameter	Type	Required	Description
`path`	string	yes	Absolute path to the project directory

contextgraph.search_nodes

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

Parameter	Type	Required	Description
`query`	string	yes	Search query
`types`	string	no	Comma-separated node types e.g. `Class,Function`
`minConfidence`	number	no	Minimum confidence 0–1 (default: 0.5)
`limit`	number	no	Max results (default: 20)

contextgraph.get_node

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

Parameter	Type	Required
`nodeId`	string	yes

contextgraph.expand_node

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

Parameter	Type	Default
`nodeId`	string	—
`depth`	number	2

contextgraph.find_path

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

Parameter	Type
`fromId`	string
`toId`	string

contextgraph.get_evidence

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

contextgraph.impact_analysis

Reverse dependency analysis: what nodes depend on this one? Useful before making changes to understand blast radius.

contextgraph.related_files

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

contextgraph.build_context

The most powerful tool for agents. Given a task description, it searches the graph, expands neighborhoods, and returns a ranked set of nodes and edges most relevant to the task.

Parameter	Type	Default
`task`	string	—
`depth`	number	2

contextgraph.generate_report

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

Resources

The server also exposes read-only MCP resources:

URI	Description
`contextgraph://project`	Artifact, node, and edge counts
`contextgraph://graph/nodes`	All nodes (up to 500, confidence ≥ 0.5)
`contextgraph://graph/edges`	All edges (up to 500, confidence ≥ 0.5)
`contextgraph://artifacts`	All indexed source files
`contextgraph://reports/summary`	Live Markdown report
`contextgraph://clusters`	Connected component summary

Prompts

Prompt	Description
`explain_codebase`	Guide the agent to explain the overall architecture
`find_context_for_task`	Find relevant graph context for a given task
`analyze_change_impact`	Analyze the impact of changing a specific node
`summarize_research`	Summarize a research document collection