Metadata-Version: 2.4
Name: contextai-mcp
Version: 0.1.0
Summary: MCP server exposing ContextAI's static code-graph API to LLM agents
Author: Shobhit Goel
License: MIT
Project-URL: Homepage, https://github.com/shobhit0521/ConnectContext
Project-URL: Repository, https://github.com/shobhit0521/ConnectContext
Keywords: mcp,code-graph,llm,agents,static-analysis,contextai
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: contextai-graph>=0.2.0
Requires-Dist: mcp[cli]<2
Dynamic: license-file

# ConnectContext

An MCP server that exposes [ContextAI](https://github.com/shobhit0521/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

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

## Run

```bash
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`](https://docs.astral.sh/uv/guides/tools/):

| 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):
```json
{ "mcpServers": { "contextai-graph": { "command": "uvx", "args": ["contextai-mcp"] } } }
```

**Codex CLI** (TOML):
```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](.mcp.json), [.cursor/mcp.json](.cursor/mcp.json), and
[.codex/config.toml](.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](docs/PROBLEMS_AND_SOLUTIONS.md) for the full build log:
every issue hit, why, and how it was fixed.
