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

Tools

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 -m contextai_mcp   or: python server.py   — stdio transport

For interactive inspection: mcp dev server.py.

contextai-mcp --help / --version work and exit immediately. Running it directly in an interactive terminal (no real MCP client attached) prints the tool list and exits instead of hanging — it's designed to be launched by a client over a pipe, not run by a human directly.

Using with an MCP client

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

Published on PyPI as contextai-mcp, so any client can run it with zero manual install via uvx — this is the recommended way to configure it, since it also sidesteps a common pip install gotcha: the contextai-mcp console script can land somewhere not on your shell's PATH (e.g. ~/.local/bin on a --user install), which makes a bare "command": "contextai-mcp" config fail with "command not found." uvx manages its own isolated environment and invocation, so this never comes up. If you do use a plain pip install, either put the script's directory on PATH or use an absolute path in your config (see the local examples below) — python -m contextai_mcp also works as a command/args alternative that doesn't depend on the console script at all.

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/
├── __main__.py               # python -m contextai_mcp
├── app.py                    # create_server() factory + --help/--version/main()
├── _helpers.py               # GraphStore cache, JSON coercion, stdout guard, 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.