contextai-mcp 0.1.0

MCP server exposing ContextAI's static code-graph API to LLM agents

ConnectContext

An MCP server that exposes ContextAI's code-graph engine as tools an LLM agent can call: build a knowledge graph of a Python project (functions/classes as nodes, calls/relationships as edges), query it, and confirm it against real runtime behavior.

Stability

Tier	Tools	Notes
Stable	build_graph, load_graph, find_node, get_context, get_edge_path, list_gaps	Read-only static analysis. Never executes code. Tested against real multi-thousand-node codebases.
Experimental	run_trace, merge_trace	run_trace executes the target's code (in a subprocess, in a chosen interpreter). Tested on synchronous, dependency-light Python. Async/threaded/network-dependent targets, and cross-platform/cross-version behavior, are not yet validated. Use on trusted code only.

Tools

Tool	What it does
build_graph(project_root, output="graph.json")	Statically analyze a project; save the graph. Run this first.
load_graph(graph_path)	Load/validate a graph; report node/edge counts.
find_node(graph_path, query)	Substring search for nodes; returns slim records with ids.
get_context(graph_path, node_id, depth=2, direction="in", include_code=True)	Focal node + neighbors + edges. Focal and (by default) each neighbor include their source code, so an agent can read the whole neighborhood in one call; pass include_code=false for a slim response.
get_edge_path(graph_path, from_id, to_id)	Direct edges between two nodes.
list_gaps(graph_path, node_id)	Unresolved calls / dynamic-dispatch gaps for a node.
run_trace(project_root, target, static_graph, entry=None, python=None, timeout_seconds=120, ...)	Execute a target under the tracer in a subprocess and return the ordered execution path with each step's source code, mapped onto the graph. On a crash it returns the path up to the failure plus the error and traceback — trace-to-context debugging in one call. Pass python=".venv/bin/python" to trace a project in its own venv (that interpreter must have contextai installed). Pass entry=<function> to get an exact, lossless split between import-time setup and real execution — without it, a long path falls back to a head/tail approximation. Always merges onto a fresh static graph; refuses a static_graph that already carries runtime data, so traced actions never silently accumulate.
merge_trace(base_graph, call_log, project_root, ...)	Fold a previously captured call log onto a pristine graph (no code execution). Same no-accumulation guarantee as run_trace.

The long-running-session tracers (start_trace / stop_trace) are intentionally not exposed: they hook the process they're called in, so driven across separate MCP tool calls they capture nothing useful — they're meant to be embedded inside a long-running app (e.g. a FastAPI startup/shutdown hook), not called remotely.

Setup

pip install -r requirements.txt   # mcp[cli]<2 + contextai

Run

contextai-mcp   # or: python server.py   — stdio transport

For interactive inspection: mcp dev server.py.

Using with an MCP client

The server is the same regardless of client — only where each client looks for its config differs.

Once published to PyPI, any client can run it with zero manual install via uvx:

Client	Config file	Format
Claude Code	.mcp.json (project)	JSON
Claude Desktop	claude_desktop_config.json	JSON
Cursor	.cursor/mcp.json (project) or ~/.cursor/mcp.json (global)	JSON, same shape as Claude
Codex CLI	.codex/config.toml (project) or ~/.codex/config.toml (global)	TOML

Claude Code / Claude Desktop / Cursor (JSON):

{ "mcpServers": { "contextai-graph": { "command": "uvx", "args": ["contextai-mcp"] } } }

Codex CLI (TOML):

[mcp_servers.contextai-graph]
command = "uvx"
args = ["contextai-mcp"]

Before publishing (local development), point at the installed console script directly instead — see .mcp.json, .cursor/mcp.json, and .codex/config.toml in this repo for working examples against this workspace's interpreter.

Typical flow

1. build_graph("/path/to/project") → writes graph.json.
2. find_node("graph.json", "process_data") → grab a node id.
3. get_context("graph.json", "<id>") → see callers/callees.
4. list_gaps / get_edge_path for deeper inspection.
5. run_trace(..., entry="the_function") → confirm what actually executes, or get the exact path to a bug.

Layout

server.py                     # entrypoint: create_server().run()
contextai_mcp/
├── app.py                    # create_server() factory
├── _helpers.py               # GraphStore cache, JSON coercion, no-accumulation guard
└── tools/                    # one file per tool, each with register(mcp)
    ├── __init__.py           # register_all(mcp)
    ├── build_graph.py  load_graph.py  find_node.py
    ├── get_context.py  get_edge_path.py  list_gaps.py
    └── run_trace.py    merge_trace.py
.mcp.json  .cursor/mcp.json  .codex/config.toml   # client configs for this workspace

See docs/PROBLEMS_AND_SOLUTIONS.md for the full build log: every issue hit, why, and how it was fixed.