{
  "markdown": "# cgraphy – Code Knowledge Graph MCP Server\n\n[![PyPI version](https://img.shields.io/pypi/v/cgraphy.svg)](https://pypi.org/project/cgraphy/)\n[![Python versions](https://img.shields.io/pypi/pyversions/cgraphy.svg)](https://pypi.org/project/cgraphy/)\n[![License](https://img.shields.io/pypi/l/cgraphy.svg)](https://github.com/pmgarg/cgraphy/blob/master/LICENSE)\n[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.21422935.svg)](https://doi.org/10.5281/zenodo.21422935)\n\n**Paper (DOI):** [https://doi.org/10.5281/zenodo.21422935](https://doi.org/10.5281/zenodo.21422935)  \n**PyPI:** [https://pypi.org/project/cgraphy/](https://pypi.org/project/cgraphy/)  \n**GitHub:** [https://github.com/pmgarg/cgraphy](https://github.com/pmgarg/cgraphy)\n\n**cgraphy** is a Python code knowledge graph and Model Context Protocol (MCP) server for AI coding agents such as Claude Code, Codex CLI, Cursor, and Gemini CLI.\n\ncgraphy indexes any codebase into a knowledge graph — functions, classes and\nfiles as nodes; calls, imports, inheritance and git co-change history as\nedges — and serves compact, token-budgeted slices of it to AI assistants\nthrough the [Model Context Protocol](https://modelcontextprotocol.io). Instead\nof re-reading dozens of files to orient itself on every prompt, an agent asks\nthe graph and gets the relevant subgraph in a couple of thousand tokens.\n\n- **Any language.** Full-fidelity extraction (calls, imports, inheritance) for\n  Python, TypeScript/JavaScript, Java, Go, C, C++ and Rust; generic\n  definition-level extraction for 20+ more via tree-sitter; config and docs\n  files participate through summaries.\n- **Importance-ranked.** PageRank over the code graph puts load-bearing\n  symbols first in every answer.\n- **Token-budgeted.** `cgraphy_context` expands the graph greedily around a\n  symbol and stops exactly at your token budget — cost scales with the\n  question, not the repo.\n- **Git-aware.** `--git-history` mines commit history for files that change\n  together (logical coupling), an edge type static analysis can't see.\n- **No API key.** Semantic summaries are written by the host agent itself\n  through the enrich loop; summaries survive re-indexing via content hashing.\n- **Zero infrastructure.** One SQLite file in `.cgraphy/`. No services, no\n  daemons, no vector database.\n- **Proven end-to-end.** In 400+ controlled agent runs on SWE-bench Lite,\n  the deployed configuration resolved **14 vs 8** of 57 real GitHub issues\n  (official Docker harness). Indexes kubernetes (26K files, 219K nodes) in\n  **49s**, keeps it fresh in **1.6s** cycles, answers queries in 1–152ms.\n  All benchmarks and predictions are in this repo ([Research paper and benchmarks](https://github.com/pmgarg/cgraphy/tree/master/paper)).\n\n## Install\n\n```bash\npip install cgraphy        # or: uv tool install cgraphy\n```\n\n## Quick start\n\n```bash\ncd your-repo\ncgraphy init          # one command: MCP config + agent steering + index\n```\n\n`cgraphy init` does three things:\n\n1. Writes a project-scoped `.mcp.json` — picked up automatically by **Claude\n   Code** in all its forms: CLI, VSCode extension, and the desktop app.\n2. Appends a steering block to `CLAUDE.md` and `AGENTS.md` telling agents to\n   consult the graph (`cgraphy_overview` → `cgraphy_search` →\n   `cgraphy_context`) *before* reading files — this is what makes the graph\n   actually replace bulk file reading. (Agents can't be forced, only steered:\n   instruction files + persuasive tool descriptions + the tools being\n   genuinely faster is the mechanism, and it works.)\n3. Builds the index with git co-change history.\n\nOr register the MCP server manually with your assistant:\n\n**Claude Code**\n\n```bash\nclaude mcp add cgraphy -- uvx cgraphy serve /path/to/repo\n```\n\n**Codex CLI** (`~/.codex/config.toml`)\n\n```toml\n[mcp_servers.cgraphy]\ncommand = \"uvx\"\nargs = [\"cgraphy\", \"serve\", \"/path/to/repo\"]\n```\n\n**Gemini CLI** (`~/.gemini/settings.json`) / **Cursor** (`.cursor/mcp.json`)\n\n```json\n{\"mcpServers\": {\"cgraphy\": {\"command\": \"uvx\",\n                            \"args\": [\"cgraphy\", \"serve\", \"/path/to/repo\"]}}}\n```\n\n## The eight tools\n\nReading / orientation:\n\n| Tool | Returns | The agent uses it… |\n| --- | --- | --- |\n| `cgraphy_overview` | Repo map: subsystems, key symbols by importance, all files | first, instead of reading files to orient |\n| `cgraphy_search` | Ranked matches with `file:line` and summaries (hybrid lexical+semantic when the `[semantic]` extra is installed) | before grep / directory listing |\n| `cgraphy_context` | Subgraph around a symbol (callers, callees, imports, co-changes) within a token budget | instead of reading whole files |\n| `cgraphy_read` | Just one symbol's source, line-numbered, budgeted | instead of reading the whole file |\n\nEditing / reviewing — the tools that make the graph part of the change loop:\n\n| Tool | Returns | The agent uses it… |\n| --- | --- | --- |\n| `cgraphy_impact` | Blast radius: direct + transitive dependents, affected tests, historically co-changed files | before modifying shared code |\n| `cgraphy_diff_context` | The working git diff mapped to touched symbols, their users, and covering tests | before committing / when resuming work |\n\nEnrichment:\n\n| Tool | Returns | The agent uses it… |\n| --- | --- | --- |\n| `cgraphy_enrich` | Batch of symbols that still need one-line summaries | when asked to \"enrich the graph\" |\n| `cgraphy_store_summaries` | Confirmation + remaining count | to save the summaries it wrote |\n\nRetrieval is usage-aware: symbols an agent repeatedly asks about get a small,\ncapped boost in future context expansion (telemetry stays in the local\nSQLite file; nothing leaves your machine).\n\n### Semantic search (optional)\n\n```bash\npip install \"cgraphy[semantic]\"\n```\n\nAdds tiny static embeddings (model2vec, CPU-only, no torch) fused with FTS5\nby reciprocal-rank fusion — closes the vocabulary gap between issue-style\nprose (\"login broken\") and code identifiers (`validate_jwt`).\n\nThe graph self-heals: tools detect stale files and re-index incrementally\n(changed files only) before answering.\n\n## Enriching the graph\n\nStructure is extracted automatically; *meaning* comes from summaries. Tell\nyour agent once:\n\n> enrich the cgraphy graph\n\nIt will loop `cgraphy_enrich` → `cgraphy_store_summaries` until every symbol\nhas a one-line semantic summary. Summaries are keyed to a hash of each\nsymbol's source, so editing one function invalidates only that summary.\n\nFor CI, `cgraphy index --summarize` pre-bakes summaries with your own\nAnthropic API key (`pip install cgraphy[summarize]`, `ANTHROPIC_API_KEY` set).\n\n## Viewer\n\n```bash\ncgraphy view .        # http://localhost:8787\n```\n\nA dependency-free local page (bundled Cytoscape.js): search, color by kind,\nclick for details, double-click to expand neighbors; co-change edges shown\ndashed.\n\n## Measuring the savings\n\n```bash\npython scripts/benchmark.py /path/to/repo \"your question\"\n```\n\nPrints the tokens an agent spends orienting via cgraphy (overview + search +\ncontext) versus reading every code file, and the reduction factor.\n\n## Localization benchmark (research harness)\n\n```bash\npython scripts/eval_localization.py /path/to/repo 50\n```\n\nMines fix-like commits from the repo's history (subject = query, touched\nfiles = ground truth, co-change mining excludes evaluated commits), then\nscores an ablation ladder — FTS-only, +PageRank, +graph expansion, ±co-change\nedges — on hit@5/hit@10/MRR and token cost. No LLM calls, no human grading,\nfully reproducible. Results and a paper draft live in [paper/](paper/).\n\n## How it works\n\n1. `cgraphy index` walks the repo (respecting `.gitignore` +\n   `.cgraphyignore`), parses each file with tree-sitter, and stores nodes and\n   edges in `.cgraphy/graph.db` (SQLite + FTS5). Re-indexing is incremental by\n   content hash.\n2. A resolver links cross-file references (calls, imports, inheritance) by\n   qualified name, best-effort; unresolved names are kept, never dropped.\n3. PageRank runs over the edge graph; every query surfaces important symbols\n   first. Search blends FTS5 relevance with rank.\n4. `cgraphy serve` exposes the five MCP tools over stdio.\n5. Optional: `--git-history` adds weighted co-change edges mined from\n   `git log`.\n\nDesign details: [docs/superpowers/specs/2026-07-08-cgraphy-design.md](https://github.com/pmgarg/cgraphy/blob/master/docs/superpowers/specs/2026-07-08-cgraphy-design.md)\n\n## Citing cgraphy\n\nIf you use cgraphy in research or tooling, please cite the paper:\n\n```bibtex\n@misc{garg2026cgraphy,\n  author = {Garg, Prateek Mohan},\n  title  = {Which Graph Signals Pay for Their Tokens? cgraphy: A Token-Budgeted\n            Code Knowledge Graph as a Portable Context Layer for AI Coding Agents},\n  year   = {2026},\n  doi    = {10.5281/zenodo.21422935},\n  url    = {https://doi.org/10.5281/zenodo.21422935},\n  note   = {Preprint}\n}\n```\n\n## License\n\nMIT\n\nmcp-name: io.github.pmgarg/cgraphy\n",
  "bytes": 8868,
  "sha": "bb8799f322796d711a0169b7814eb23acfe6c679f94d0283cd119264da7318e5",
  "repo_slug": "pmgarg/cgraphy",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_pmgarg_cgraphy_2ec62ca7/readme"
}