codegraph-network 0.1.0__py3-none-any.whl

codegraph/rank.py

@@ -0,0 +1,121 @@
+"""Graph ranking: global PageRank (stored at index time) and local personalized PageRank (per query)."""
+from __future__ import annotations
+
+from collections import defaultdict, deque
+from collections.abc import Callable, Iterable
+
+
+def pagerank(nodes: Iterable[int], edges: Iterable[tuple[int, int]],
+             damping: float = 0.85, iters: int = 60, tol: float = 1e-7,
+             stats: dict | None = None, init: dict[int, float] | None = None) -> dict[int, float]:
+    """Classic directed PageRank. Importance flows src -> dst, so widely depended-upon code ranks high.
+
+    `tol` is the L1 change per iteration. Power iteration with dangling nodes sheds mass at only
+    ~`damping` per step, so a tolerance far below that needs hundreds of passes for little gain;
+    1e-7 is the point where the ranking stops visibly changing. Pass a dict as `stats` to find out
+    whether the run converged inside the budget rather than assuming it.
+    """
+    nodes = list(nodes)
+    n = len(nodes)
+    if n == 0:
+        if stats is not None:
+            stats.update(iterations=0, converged=True, delta=0.0, nodes=0)
+        return {}
+    pos = {v: i for i, v in enumerate(nodes)}
+    out: list[list[int]] = [[] for _ in range(n)]
+    for s, d in edges:  # ignore edges pointing at symbols that are no longer in the graph
+        si, di = pos.get(s), pos.get(d)
+        if si is not None and di is not None:
+            out[si].append(di)
+    # dense lists beat dicts here: this loop runs iters x edges times and is the one full pass
+    sources = [(i, o, damping / len(o)) for i, o in enumerate(out) if o]
+    dangling = [i for i, o in enumerate(out) if not o]
+    rank = [1.0 / n] * n
+    if init:
+        # warm start from the previous run: an incremental reindex then converges in a few passes.
+        # Nodes without a prior score (new symbols) start at the uniform value.
+        rank = [init.get(v) or 1.0 / n for v in nodes]
+        total = sum(rank)
+        rank = [r / total for r in rank]
+    delta, it = 0.0, 0
+    for _step in range(1, iters + 1):
+        it = _step
+        base = (1 - damping) / n + damping * sum(rank[i] for i in dangling) / n
+        new = [base] * n
+        for i, ds, w in sources:
+            c = rank[i] * w
+            for d in ds:
+                new[d] += c
+        delta = sum(map(abs, map(float.__sub__, new, rank)))
+        rank = new
+        if delta < tol:
+            break
+    if stats is not None:
+        stats.update(iterations=it, converged=delta < tol, delta=delta, nodes=n)
+    return dict(zip(nodes, rank, strict=True))
+
+
+def personalized_pagerank(nbrs: Callable[[int], list[tuple[int, float]]], seeds: dict[int, float],
+                          alpha: float = 0.15, eps: float = 1e-5,
+                          max_nodes: int = 20_000) -> dict[int, float]:
+    """Local push approximation of random-walk-with-restart from `seeds`.
+
+    Only nodes near the seeds are visited, so cost does not grow with repo size -- except for hub
+    seeds, which is why the walk is hard-capped. `nbrs(u)` returns [(neighbour, weight)]; weights
+    let callers down-weight hub nodes.
+
+    Mass handling: a node whose residual falls below the threshold keeps it and stops. When the
+    `max_nodes` cap is reached the walk stops expanding and the leftover is banked onto the nodes
+    it belonged to, so scores stay comparable; any residue from nodes past the cap is added to the
+    highest-scoring node rather than dropped, so total mass is preserved.
+    """
+    p: dict[int, float] = defaultdict(float)
+    r: dict[int, float] = defaultdict(float)
+    for s, m in seeds.items():
+        r[s] += m
+    queue = deque(seeds)
+    queued = set(seeds)
+    seen = set(seeds)
+    overflow = 0.0
+
+    def reachable(u: int) -> bool:
+        """True while the result may still grow by one node."""
+        return len(seen) < max_nodes
+
+    while queue:
+        u = queue.popleft()
+        queued.discard(u)
+        ru = r[u]
+        nb = nbrs(u)
+        if not nb:
+            p[u] += ru
+            r[u] = 0.0
+            continue
+        if ru < eps * len(nb):
+            p[u] += ru  # below threshold: stop here, but keep the mass
+            r[u] = 0.0
+            continue
+        total_w = sum(w for _, w in nb)
+        p[u] += alpha * ru
+        spread = (1 - alpha) * ru
+        r[u] = 0.0
+        for v, w in nb:
+            r[v] += spread * w / total_w
+            if v in queued or r[v] < eps * max(1, len(nbrs(v))):
+                continue
+            if not reachable(v):
+                overflow += r[v]
+                r[v] = 0.0
+                continue
+            seen.add(v)
+            queue.append(v)
+            queued.add(v)
+    for v, rv in r.items():  # anything still pending when the queue drains
+        if rv:
+            if len(seen) >= max_nodes:
+                overflow += rv
+            else:
+                p[v] += rv
+    if overflow and p:
+        p[max(p, key=p.get)] += overflow
+    return p

codegraph/report.py

@@ -0,0 +1,199 @@
+"""Human-readable views of the whole graph: GRAPH_REPORT.md and a self-contained graph.html.
+
+Both are written next to the index (`.codegraph/`) and need nothing but a browser or a markdown viewer.
+"""
+from __future__ import annotations
+
+import json
+import posixpath
+from collections import Counter, defaultdict
+from pathlib import Path
+
+HTML_NODES = 400  # a force layout stays readable and smooth up to roughly this many nodes
+GOD_NODES = 10
+COMMUNITIES = 12
+SURPRISES = 8
+NON_TARGET = ("module", "impl", "namespace")
+
+
+def _area(file: str) -> str:
+    parts = file.split("/")
+    return "/".join(parts[:2]) if len(parts) > 2 else parts[0]
+
+
+def _gather(db):
+    syms = {r["id"]: r for r in db.execute(
+        f"SELECT id, file, qualname, kind, rank, community FROM symbols WHERE kind NOT IN {NON_TARGET!r}")}
+    edges = [(r["src"], r["dst"], r["kind"], r["conf"]) for r in db.execute("SELECT src, dst, kind, conf FROM edges")
+             if r["src"] in syms and r["dst"] in syms]
+    deg: Counter = Counter()
+    for s, d, _, _ in edges:
+        deg[s] += 1
+        deg[d] += 1
+    return syms, edges, deg
+
+
+def _communities(syms, edges, deg):
+    members: dict[int, list[int]] = defaultdict(list)
+    for i, r in syms.items():
+        if r["community"] >= 0:
+            members[r["community"]].append(i)
+    inside: Counter = Counter()
+    touching: Counter = Counter()
+    for s, d, _, _ in edges:
+        cs, cd = syms[s]["community"], syms[d]["community"]
+        touching[cs] += 1
+        if cs != cd:
+            touching[cd] += 1
+        else:
+            inside[cs] += 1
+    out = []
+    for c, ids in sorted(members.items(), key=lambda kv: (-len(kv[1]), kv[0])):
+        ids.sort(key=lambda i: -syms[i]["rank"])
+        areas = Counter(_area(syms[i]["file"]) for i in ids)
+        out.append({"id": c, "size": len(ids), "area": areas.most_common(1)[0][0],
+                    "files": len({syms[i]["file"] for i in ids}),
+                    "top": [syms[i]["qualname"] for i in ids[:4]],
+                    "cohesion": inside[c] / touching[c] if touching[c] else 1.0})
+    return out
+
+
+def _surprises(syms, edges, deg):
+    """Certain edges that join different communities *and* different areas of the tree, between
+    symbols that are not hubs: the links a reader would not have guessed from the file layout."""
+    scored = []
+    for s, d, kind, conf in edges:
+        a, b = syms[s], syms[d]
+        if conf != "extracted" or a["community"] == b["community"] or _area(a["file"]) == _area(b["file"]):
+            continue
+        if a["community"] < 0 or b["community"] < 0:
+            continue
+        scored.append((deg[s] + deg[d], a["qualname"], b["qualname"], kind, a["file"], b["file"]))
+    scored.sort()
+    return scored[:SURPRISES]
+
+
+def build_report(db) -> tuple[str, dict]:
+    syms, edges, deg = _gather(db)
+    conf = Counter(c for *_, c in edges)
+    comms = _communities(syms, edges, deg)
+    files = db.execute("SELECT COUNT(*) FROM files").fetchone()[0]
+    kinds = Counter(r["kind"] for r in syms.values())
+    out = ["# Codegraph report", "",
+           f"{files} files, {len(syms)} symbols, {len(edges)} edges "
+           f"({conf['extracted']} extracted, {conf['inferred']} inferred, {conf['ambiguous']} ambiguous), "
+           f"{len(comms)} communities.", ""]
+    docs = [k for k in ("section", "table", "view", "procedure") if kinds.get(k)]
+    if docs:
+        out += ["Beyond code: " + ", ".join(f"{kinds[k]} {k}s" for k in docs) + ".", ""]
+
+    out += ["## Key symbols", "", "Highest PageRank: the code everything else leans on.", ""]
+    top = sorted(syms, key=lambda i: -syms[i]["rank"])[:GOD_NODES]
+    for i in top:
+        r = syms[i]
+        out.append(f"- `{r['qualname']}` ({r['kind']}, {r['file']}) rank {r['rank']:.4f}, {deg[i]} links")
+
+    out += ["", "## Communities", "", "Groups of symbols that call each other more than they call out. "
+            "Cohesion is the share of their edges that stay inside.", ""]
+    for c in comms[:COMMUNITIES]:
+        out.append(f"- **#{c['id']} {c['area']}** — {c['size']} symbols in {c['files']} files, "
+                   f"cohesion {c['cohesion']:.0%}: " + ", ".join(f"`{q}`" for q in c["top"]))
+    if len(comms) > COMMUNITIES:
+        out.append(f"- ... and {len(comms) - COMMUNITIES} smaller")
+
+    sur = _surprises(syms, edges, deg)
+    if sur:
+        out += ["", "## Surprising connections", "",
+                "Certain links between different communities *and* different directories, between "
+                "non-hub symbols.", ""]
+        out += [f"- `{a}` ({fa}) -{k}-> `{b}` ({fb})" for _, a, b, k, fa, fb in sur]
+
+    out += ["", "## Questions worth asking", ""]
+    if top:
+        q0 = syms[top[0]]["qualname"]
+        out += [f"- What breaks if `{q0}` changes? -> `codegraph impact {q0}`",
+                f"- What is `{q0}` closest to? -> `codegraph related {q0}`"]
+    if conf["ambiguous"]:
+        out.append(f"- {conf['ambiguous']} edges are ambiguous (several plausible targets). "
+                   "Treat their callers/impact as upper bounds.")
+    if comms:
+        out.append(f"- Why is the biggest area ({comms[0]['area']}, {comms[0]['size']} symbols) one community?")
+    meta = {"symbols": len(syms), "edges": len(edges), "communities": len(comms),
+            "confidence": dict(conf)}
+    return "\n".join(out) + "\n", meta
+
+
+def build_html(db) -> str:
+    syms, edges, deg = _gather(db)
+    keep = sorted(syms, key=lambda i: -syms[i]["rank"])[:HTML_NODES]
+    ix = {sid: n for n, sid in enumerate(keep)}
+    nodes = [{"n": syms[i]["qualname"], "f": syms[i]["file"], "c": syms[i]["community"],
+              "r": syms[i]["rank"], "k": syms[i]["kind"]} for i in keep]
+    links = [{"s": ix[s], "t": ix[d], "q": c} for s, d, _, c in edges if s in ix and d in ix]
+    data = json.dumps({"nodes": nodes, "links": links}).replace("</", "<\\/")
+    return _HTML.replace("__DATA__", data).replace("__TOTAL__", str(len(syms))).replace("__SHOWN__", str(len(keep)))
+
+
+def write_all(db, root: Path) -> tuple[str, list[Path]]:
+    out_dir = root / ".codegraph"
+    out_dir.mkdir(exist_ok=True)
+    text, _ = build_report(db)
+    md, html = out_dir / "GRAPH_REPORT.md", out_dir / "graph.html"
+    md.write_text(text)
+    html.write_text(build_html(db))
+    return text, [md, html]
+
+
+def short(path: Path, root: Path) -> str:
+    return posixpath.normpath(path.relative_to(root).as_posix())
+
+
+_HTML = """<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Codegraph</title>
+<style>
+:root{--bg:#fafafa;--fg:#1a1a1a;--mute:#6b7280;--edge:#9ca3af}
+@media (prefers-color-scheme:dark){:root{--bg:#111318;--fg:#e5e7eb;--mute:#9ca3af;--edge:#4b5563}}
+html,body{margin:0;height:100%;background:var(--bg);color:var(--fg);font:14px system-ui,sans-serif}
+canvas{display:block;width:100%;height:100%}
+#tip{position:fixed;pointer-events:none;background:var(--bg);border:1px solid var(--edge);padding:4px 8px;
+border-radius:4px;display:none;max-width:60ch;word-break:break-all}
+#hud{position:fixed;left:12px;top:10px;color:var(--mute)}
+</style></head><body>
+<canvas id="c"></canvas><div id="tip"></div>
+<div id="hud">Top __SHOWN__ of __TOTAL__ symbols by PageRank. Colour = community. Dashed = inferred/ambiguous link. Hover to read, click to pin a neighbourhood.</div>
+<script>
+const D=__DATA__, N=D.nodes, L=D.links, cv=document.getElementById('c'), cx=cv.getContext('2d'), tip=document.getElementById('tip');
+const dpr=devicePixelRatio||1; let W,H;
+function size(){W=innerWidth;H=innerHeight;cv.width=W*dpr;cv.height=H*dpr;cx.setTransform(dpr,0,0,dpr,0,0)}
+addEventListener('resize',size);size();
+const col=c=>c<0?'#9ca3af':`hsl(${(c*137.5)%360},65%,52%)`;
+N.forEach((n,i)=>{n.x=W/2+Math.cos(i)*W/4*Math.random();n.y=H/2+Math.sin(i)*H/4*Math.random();n.vx=n.vy=0;n.d=0;n.rad=3+Math.sqrt(n.r*4000)});
+L.forEach(l=>{N[l.s].d++;N[l.t].d++});
+let alpha=1, pin=null, hov=null;
+function step(){
+ for(let i=0;i<N.length;i++){const a=N[i];
+  for(let j=i+1;j<N.length;j++){const b=N[j];let dx=a.x-b.x,dy=a.y-b.y,d2=dx*dx+dy*dy+.01;
+   if(d2<40000){const f=900/d2;dx*=f;dy*=f;a.vx+=dx;a.vy+=dy;b.vx-=dx;b.vy-=dy}}
+  a.vx+=(W/2-a.x)*.002;a.vy+=(H/2-a.y)*.002}
+ for(const l of L){const a=N[l.s],b=N[l.t];let dx=b.x-a.x,dy=b.y-a.y,d=Math.hypot(dx,dy)||1;
+  const same=a.c===b.c,f=(d-(same?40:90))*.012*(l.q==='extracted'?1:.5);dx*=f/d;dy*=f/d;a.vx+=dx;a.vy+=dy;b.vx-=dx;b.vy-=dy}
+ for(const n of N){n.vx*=.82;n.vy*=.82;n.x+=n.vx*alpha;n.y+=n.vy*alpha}
+ alpha=Math.max(.02,alpha*.992)}
+const near=i=>{const s=new Set([i]);L.forEach(l=>{if(l.s===i)s.add(l.t);if(l.t===i)s.add(l.s)});return s};
+function draw(){
+ cx.clearRect(0,0,W,H);const focus=pin!==null?near(pin):null;
+ cx.lineWidth=1;
+ for(const l of L){const a=N[l.s],b=N[l.t],on=!focus||(focus.has(l.s)&&focus.has(l.t));
+  cx.globalAlpha=on?.55:.06;cx.strokeStyle=getComputedStyle(document.documentElement).getPropertyValue('--edge');
+  cx.setLineDash(l.q==='extracted'?[]:[3,3]);cx.beginPath();cx.moveTo(a.x,a.y);cx.lineTo(b.x,b.y);cx.stroke()}
+ cx.setLineDash([]);
+ N.forEach((n,i)=>{cx.globalAlpha=!focus||focus.has(i)?1:.12;cx.fillStyle=col(n.c);cx.beginPath();cx.arc(n.x,n.y,n.rad,0,6.3);cx.fill()});
+ cx.globalAlpha=1}
+(function loop(){step();draw();requestAnimationFrame(loop)})();
+function pick(e){let best=null,bd=1e9;N.forEach((n,i)=>{const d=Math.hypot(n.x-e.clientX,n.y-e.clientY);if(d<n.rad+4&&d<bd){bd=d;best=i}});return best}
+cv.addEventListener('mousemove',e=>{hov=pick(e);if(hov===null){tip.style.display='none';return}
+ const n=N[hov];tip.textContent=`${n.k} ${n.n}  ${n.f}  (${n.d} links)`;tip.style.display='block';tip.style.left=e.clientX+12+'px';tip.style.top=e.clientY+12+'px'});
+cv.addEventListener('click',e=>{const p=pick(e);pin=p===pin?null:p;alpha=.3});
+</script></body></html>
+"""

codegraph/review.py

@@ -0,0 +1,145 @@
+"""`review` / `prs`: what does this change touch, and what depends on it?
+
+Maps a git diff onto graph symbols, then reports each changed symbol's blast radius, whether any test is
+linked to it, and files that usually change together with the diff but are missing from it.
+"""
+from __future__ import annotations
+
+import re
+import subprocess
+from collections import defaultdict
+from pathlib import Path
+
+from .links import is_test_path
+
+HUNK = re.compile(r"^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@")
+MAIN_BRANCHES = ("origin/main", "origin/master", "main", "master")
+COCHANGE_MIN = 0.3  # a partner file below this weight is coincidence, not a habit
+MAX_SYMBOLS = 15
+
+
+def _git(root: Path, *args: str) -> str | None:
+    try:
+        p = subprocess.run(["git", "-C", str(root), *args], capture_output=True, text=True, timeout=30)
+    except (OSError, subprocess.SubprocessError):
+        return None
+    return p.stdout if p.returncode == 0 else None
+
+
+def default_base(root: Path) -> str:
+    """The point the change started from: merge-base with the main branch, or HEAD (uncommitted work)
+    when already on it."""
+    for name in MAIN_BRANCHES:
+        out = _git(root, "merge-base", "HEAD", name)
+        if out and out.strip():
+            base = out.strip()
+            head = (_git(root, "rev-parse", "HEAD") or "").strip()
+            return base if base != head else "HEAD"
+    return "HEAD"
+
+
+def parse_diff(diff: str) -> tuple[dict[str, list[tuple[int, int]]], list[str]]:
+    """Unified diff (-U0) -> ({file: [(first, last) new-side line ranges]}, [deleted files])."""
+    changed: dict[str, list[tuple[int, int]]] = defaultdict(list)
+    deleted: list[str] = []
+    old = cur = None
+    for line in diff.splitlines():
+        if line.startswith("--- "):
+            old = line[6:] if line.startswith("--- a/") else None
+        elif line.startswith("+++ "):
+            cur = line[6:] if line.startswith("+++ b/") else None
+            if cur is None and old:
+                deleted.append(old)
+        elif cur and (m := HUNK.match(line)):
+            start, n = int(m.group(1)), int(m.group(2) if m.group(2) is not None else 1)
+            changed[cur].append((start, start + max(n, 1) - 1))  # n == 0: pure deletion at `start`
+    return dict(changed), deleted
+
+
+def _innermost(rows, ranges):
+    """Symbols overlapping any range, minus containers whose own child also overlaps."""
+    hit = [r for r in rows if any(r["line_start"] <= b and a <= r["line_end"] for a, b in ranges)]
+    ids = {r["parent"] for r in hit}
+    return [r for r in hit if r["id"] not in ids]
+
+
+def review(graph, base: str = "", max_tokens: int = 1500) -> str:
+    root = graph.root
+    if _git(root, "rev-parse", "--git-dir") is None:
+        return "Not a git repository: nothing to diff."
+    base = base.strip() or default_base(root)
+    diff = _git(root, "diff", "-U0", "--no-color", base, "--")
+    if diff is None:
+        return f"git could not diff against '{base}'. Pass a branch, tag or commit."
+    changed, deleted = parse_diff(diff)
+    if not changed and not deleted:
+        return f"No changes against {base}."
+
+    db = graph.db
+    rows_by_file = defaultdict(list)
+    for r in db.execute("SELECT * FROM symbols WHERE kind NOT IN ('module','impl','namespace')"):
+        if r["file"] in changed:
+            rows_by_file[r["file"]].append(r)
+    touched, unindexed = [], []
+    for f, ranges in sorted(changed.items()):
+        rows = rows_by_file.get(f)
+        if rows is None:
+            unindexed.append(f)
+            continue
+        touched += _innermost(rows, ranges)
+
+    report = []
+    for r in touched:
+        levels = graph._bfs(r, "in", 3, 10_000)
+        deps = [n for ns in levels.values() for n in ns]
+        report.append((r, len(deps), len({n["file"] for n in deps}),
+                       sum(1 for n in deps if n["conf"] != "extracted"), _tests_for(graph, r["id"])))
+    report.sort(key=lambda t: (-t[1], t[0]["qualname"]))
+
+    files = sorted(changed)
+    out = [f"review vs {base}: {len(files)} file(s), {len(touched)} symbol(s) changed"
+           + (f", {len(deleted)} file(s) deleted" if deleted else "")]
+    if report:
+        out.append("highest blast radius first:")
+    for r, n, nf, soft, tests in report[:MAX_SYMBOLS]:
+        what = f"{n} dependents in {nf} file(s)" + (f", {soft} via inferred/ambiguous" if soft else "") if n else "no dependents"
+        verdict = "" if is_test_path(r["file"]) else ("  tests: " + (", ".join(tests[:2]) if tests else "NONE linked"))
+        out.append(f"  {r['qualname']}  {r['file']}:{r['line_start']}  -> {what}{verdict}")
+    if len(report) > MAX_SYMBOLS:
+        out.append(f"  ... and {len(report) - MAX_SYMBOLS} more")
+    untested = [r["qualname"] for r, _, _, _, t in report if not t and not is_test_path(r["file"])]
+    if untested:
+        out.append("changed without a linked test: " + ", ".join(untested[:8])
+                   + (f" (+{len(untested) - 8})" if len(untested) > 8 else ""))
+    missing = _cochange_missing(graph, set(files))
+    if missing:
+        out.append("usually changes together with this diff, but untouched: "
+                   + ", ".join(f"{m} ({w:.2f})" for m, w in missing[:5]))
+    if deleted:
+        out.append("deleted: " + ", ".join(deleted[:8]))
+    if unindexed:
+        out.append(f"not indexed (unsupported type or ignored): {', '.join(unindexed[:6])}"
+                   + (f" (+{len(unindexed) - 6})" if len(unindexed) > 6 else ""))
+    text = "\n".join(out)
+    cap = max_tokens * 4
+    return text if len(text) <= cap else text[:cap].rsplit("\n", 1)[0] + "\n  ... truncated"
+
+
+def _tests_for(graph, sid: int) -> list[str]:
+    """Test symbols linked to `sid` (links of kind 'tests', in either direction)."""
+    names = []
+    for other, kind, _w, _note, _fwd in graph._lnk.get(sid, ()):
+        if kind == "tests":
+            row = graph.db.execute("SELECT qualname FROM symbols WHERE id=?", (other,)).fetchone()
+            if row:
+                names.append(row[0])
+    return names
+
+
+def _cochange_missing(graph, files: set[str]) -> list[tuple[str, float]]:
+    best: dict[str, float] = {}
+    for f in files:
+        for other, w in graph._fl.get(f, ()):
+            if other not in files and w >= COCHANGE_MIN:
+                best[other] = max(best.get(other, 0.0), w)
+    return sorted(best.items(), key=lambda kv: (-kv[1], kv[0]))

codegraph/server.py

@@ -0,0 +1,81 @@
+"""MCP server exposing the code graph to LLM agents."""
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+from mcp.server.mcpserver import MCPServer
+
+from .indexer import index_repo
+from .queries import Graph
+from .tools import TOOLS
+
+try:  # mcp 1.x compatibility: FastMCP is the same object under its old name
+    from mcp.server.fastmcp import FastMCP
+except ImportError:  # pragma: no cover - mcp 2.x
+    FastMCP = MCPServer
+
+INSTRUCTIONS = (
+    "Code graph for this repository. Prefer these tools over reading whole files: "
+    "start with repo_map, find code with search, then call context(symbol) to get a symbol's source, "
+    "the signatures it uses and who uses it in one compact response. Use impact(symbol) before changing "
+    "a function, and similar(symbol) to find code that does the same thing under different names. "
+    "Fall back to reading files only for exact surrounding code."
+)
+
+
+def _log(msg: str):
+    """stderr only: stdout is the MCP transport."""
+    print(f"codegraph: {msg}", file=sys.stderr, flush=True)
+
+
+def build(root: str | Path, index: bool = True) -> MCPServer:
+    root = Path(root).resolve()
+    mcp = MCPServer("codegraph", instructions=INSTRUCTIONS)
+    if index:
+        _log(f"indexing {root} ...")
+        stats = index_repo(root, progress=lambda m: _log(m))
+        _log(f"indexed {stats['files']} files, {stats['symbols']} symbols, {stats['edges']} edges")
+    graph = Graph(root)  # one long-lived graph: adjacency lists stay in memory
+
+    for tool in TOOLS:
+        _register(mcp, tool, graph, root)
+
+    return mcp
+
+
+def _register(mcp, tool, graph: Graph, root: Path):
+    """Expose one Tool spec. The signature is generated from the spec, annotations included,
+    so the advertised schema cannot drift from what the tool actually accepts."""
+    if tool.name == "reindex":
+        def reindex(force: bool = False) -> str:
+            r = index_repo(root, force)
+            graph.reload()
+            return (f"{r['files']} files, {r['changed']} re-parsed, "
+                    f"{r['symbols']} symbols, {r['edges']} edges")
+        reindex.__doc__ = tool.summary
+        mcp.tool(name=tool.name)(reindex)
+        return
+
+    def dispatch(**kwargs):
+        return getattr(graph, tool.name)(**kwargs)
+
+    params = tool.params
+    args = []
+    for p in params:
+        args.append(f"{p.name}: {p.type}" if p.default is None
+                    else f"{p.name}: {p.type} = {p.default!r}")
+    # keyword forwarding: the MCP runtime calls tools with keyword arguments
+    src = (f"def _{tool.name}({', '.join(args)}) -> str:\n"
+           f"    return _dispatch({', '.join(f'{n}={n}' for n in [p.name for p in params])})")
+    ns: dict = {"_dispatch": dispatch}
+    exec(compile(src, f"<tool {tool.name}>", "exec"), ns)
+    fn = ns[f"_{tool.name}"]
+    fn.__name__ = tool.name  # the MCP tool name must not inherit the underscore
+    fn.__doc__ = tool.summary
+    mcp.tool(name=tool.name)(fn)
+
+
+def main(root: str | None = None):
+    build(root or os.environ.get("CODEGRAPH_ROOT") or os.getcwd()).run()