@oriro/orirocli 0.1.9 → 0.1.12

package/skills/graphify/serve.py

@@ -1,1309 +0,0 @@
-# MCP stdio server - exposes graph query tools to Claude and other agents
-from __future__ import annotations
-import json
-import math
-import re
-import sys
-from pathlib import Path
-import networkx as nx
-from networkx.readwrite import json_graph
-from graphify.security import sanitize_label, check_graph_file_size_cap
-from graphify.build import edge_data
-
-try:
-    import jieba as _jieba  # type: ignore[import-untyped]
-except ImportError:
-    _jieba = None
-
-
-def _load_graph(graph_path: str) -> nx.Graph:
-    try:
-        resolved = Path(graph_path).resolve()
-        if resolved.suffix != ".json":
-            raise ValueError(f"Graph path must be a .json file, got: {graph_path!r}")
-        if not resolved.exists():
-            raise FileNotFoundError(f"Graph file not found: {resolved}")
-        check_graph_file_size_cap(resolved)
-        safe = resolved
-        data = json.loads(safe.read_text(encoding="utf-8"))
-        if "links" not in data and "edges" in data:
-            data = dict(data, links=data["edges"])
-        data = {**data, "directed": True}
-        try:
-            return json_graph.node_link_graph(data, edges="links")
-        except TypeError:
-            return json_graph.node_link_graph(data)
-    except (ValueError, FileNotFoundError) as exc:
-        print(f"error: {exc}", file=sys.stderr)
-        sys.exit(1)
-    except json.JSONDecodeError as exc:
-        print(f"error: graph.json is corrupted ({exc}). Re-run /graphify to rebuild.", file=sys.stderr)
-        sys.exit(1)
-
-
-def _communities_from_graph(G: nx.Graph) -> dict[int, list[str]]:
-    """Reconstruct community dict from community property stored on nodes."""
-    communities: dict[int, list[str]] = {}
-    for node_id, data in G.nodes(data=True):
-        cid = data.get("community")
-        if cid is not None:
-            communities.setdefault(int(cid), []).append(node_id)
-    return communities
-
-
-def _strip_diacritics(text: str) -> str:
-    import unicodedata
-    nfkd = unicodedata.normalize("NFKD", text)
-    return "".join(c for c in nfkd if not unicodedata.combining(c))
-
-
-def _search_tokens(text: str) -> list[str]:
-    """Split text into word tokens, stripping punctuation and diacritics."""
-    return re.findall(r"\w+", _strip_diacritics(str(text)).lower())
-
-
-def _has_chinese(text: str) -> bool:
-    return any("一" <= ch <= "鿿" for ch in text)
-
-
-def _segment_chinese(text: str) -> list[str]:
-    """Segment Chinese text and keep the original term for exact matching."""
-    if _jieba is not None:
-        segments = [w for w in _jieba.cut(text) if len(w.strip()) > 0]
-    else:
-        segments = [text[i:i + 2] for i in range(len(text) - 1)] or [text]
-    if len(text) > 1 and text not in segments:
-        segments.append(text)
-    return segments
-
-
-def _is_searchable(term: str) -> bool:
-    """True if term is Chinese, non-English, or an English word longer than 2 chars."""
-    if all("a" <= ch <= "z" for ch in term):
-        return len(term) > 2
-    return True
-
-
-def _query_terms(question: str) -> list[str]:
-    """Split a query into searchable terms, segmenting Chinese text."""
-    terms: list[str] = []
-    for raw in question.split():
-        if _has_chinese(raw):
-            for seg in _segment_chinese(raw.lower().strip()):
-                seg = seg.strip()
-                if seg and _is_searchable(seg):
-                    terms.append(seg)
-        else:
-            # Strip punctuation without touching Unicode characters (avoid NFKD mangling non-Latin scripts)
-            for tok in re.findall(r"\w+", raw.lower()):
-                if _is_searchable(tok):
-                    terms.append(tok)
-    return terms
-
-
-_EXACT_MATCH_BONUS = 1000.0
-_PREFIX_MATCH_BONUS = 100.0
-_SUBSTRING_MATCH_BONUS = 1.0
-_SOURCE_MATCH_BONUS = 0.5
-
-
-def _compute_idf(G: nx.Graph, terms: list[str]) -> dict[str, float]:
-    """IDF weights for query terms, cached in G.graph['_idf_cache'].
-
-    Common terms like 'error' or 'exception' that match hundreds of nodes get
-    low weights; rare identifiers like 'FooBarService' get high weights.
-    Cache is stored on the graph object itself so it auto-invalidates when
-    _maybe_reload() replaces G with a new object.
-    """
-    cache: dict[str, float] = G.graph.setdefault("_idf_cache", {})
-    N = G.number_of_nodes() or 1
-    uncached = [t for t in terms if t not in cache]
-    if uncached:
-        df: dict[str, int] = {t: 0 for t in uncached}
-        for _, data in G.nodes(data=True):
-            norm_label = (
-                data.get("norm_label") or _strip_diacritics(data.get("label") or "")
-            ).lower()
-            for t in uncached:
-                if t in norm_label:
-                    df[t] += 1
-        for t in uncached:
-            cache[t] = math.log(1 + N / (1 + df[t]))
-    return {t: cache.get(t, math.log(1 + N)) for t in terms}
-
-
-def _score_nodes(G: nx.Graph, terms: list[str]) -> list[tuple[float, str]]:
-    scored = []
-    norm_terms = [tok for t in terms for tok in _search_tokens(t)]
-    idf = _compute_idf(G, norm_terms)
-    # Whole-query string for full-label matching (mirrors _find_node's `term`).
-    joined = " ".join(norm_terms)
-    # Weight the full-query bonus by the rarest constituent term so a specific
-    # multi-word label still outweighs common-token noise; floor at 1.0.
-    joined_w = max((idf.get(t, 1.0) for t in norm_terms), default=1.0)
-    for nid, data in G.nodes(data=True):
-        norm_label = data.get("norm_label") or _strip_diacritics(data.get("label") or "").lower()
-        bare_label = norm_label.rstrip("()")
-        # Tokenized form of the label (punctuation stripped, same transform as the
-        # query). norm_label may still carry punctuation like ':' or '-', which a
-        # tokenized query can never equal; comparing token-joined forms on both
-        # sides makes "uoce: dehumidifier driver" match query "uoce dehumidifier
-        # driver".
-        label_tokens = " ".join(_search_tokens(data.get("label") or ""))
-        source = (data.get("source_file") or "").lower()
-        score = 0.0
-        # Full-query tier: a multi-word query that equals (or prefixes) the whole
-        # label must dominate the per-token bag-of-words sums below, so `path`/
-        # `query` resolve the same node `explain` does (via _find_node). Without
-        # this, no single token equals a multi-word label, the per-token exact
-        # tier never fires, and every node sharing the token set ties -> arbitrary
-        # node-id sort -> wrong/disconnected endpoint -> false "No path found".
-        if joined:
-            nid_lower = nid.lower()
-            if joined in (norm_label, bare_label, label_tokens, nid_lower):
-                score += _EXACT_MATCH_BONUS * 10 * joined_w
-            elif (
-                norm_label.startswith(joined)
-                or bare_label.startswith(joined)
-                or label_tokens.startswith(joined)
-            ):
-                score += _PREFIX_MATCH_BONUS * 10 * joined_w
-        for t in norm_terms:
-            w = idf.get(t, 1.0)
-            # Three-tier precedence: exact > prefix > substring (take the
-            # strongest tier per term so a single term cannot double-count).
-            if t == norm_label or t == bare_label:
-                score += _EXACT_MATCH_BONUS * w
-            elif norm_label.startswith(t) or bare_label.startswith(t):
-                score += _PREFIX_MATCH_BONUS * w
-            elif t in norm_label:
-                score += _SUBSTRING_MATCH_BONUS * w
-            if t in source:
-                score += _SOURCE_MATCH_BONUS * w
-        if score > 0:
-            scored.append((score, nid))
-    # Sort by score desc; break ties toward the shorter label so a concise exact
-    # match beats a longer superset that happens to share the same score.
-    scored.sort(key=lambda s: (-s[0], len(G.nodes[s[1]].get("label") or s[1]), s[1]))
-    return scored
-
-
-def _pick_seeds(scored: list[tuple[float, str]], max_k: int = 3, gap_ratio: float = 0.2) -> list[str]:
-    """Select BFS seed nodes, stopping when score drops too far below the top.
-
-    Prevents high-frequency noise terms (error, exception) from stealing seed
-    slots from a dominant identifier match. When FooBarService scores 1000 and
-    error nodes score 1.0, only FooBarService is seeded — the score gap is 99.9%
-    which is well above the 20% threshold that would allow additional seeds.
-    """
-    if not scored:
-        return []
-    top_score = scored[0][0]
-    seeds = []
-    for score, nid in scored[:max_k]:
-        if seeds and score < top_score * gap_ratio:
-            break
-        seeds.append(nid)
-    return seeds
-
-
-_CONTEXT_HINTS: tuple[tuple[str, tuple[str, ...]], ...] = (
-    ("call", ("call", "calls", "called", "invoke", "invokes", "invoked")),
-    ("import", ("import", "imports", "imported", "module", "modules")),
-    ("field", ("field", "fields", "member", "members", "property", "properties")),
-    ("parameter_type", ("parameter", "parameters", "param", "params", "argument", "arguments")),
-    ("return_type", ("return", "returns", "returned")),
-    ("generic_arg", ("generic", "generics", "template", "templates")),
-)
-
-
-_CONTEXT_FILTER_ALIASES: dict[str, str] = {
-    "param": "parameter_type",
-    "params": "parameter_type",
-    "parameter": "parameter_type",
-    "parameters": "parameter_type",
-    "argument": "parameter_type",
-    "arguments": "parameter_type",
-    "arg": "parameter_type",
-    "args": "parameter_type",
-    "return": "return_type",
-    "returns": "return_type",
-    "returned": "return_type",
-    "generic": "generic_arg",
-    "generics": "generic_arg",
-    "template": "generic_arg",
-    "templates": "generic_arg",
-    "annotation": "attribute",
-    "annotations": "attribute",
-    "decorator": "attribute",
-    "decorators": "attribute",
-    "calls": "call",
-    "called": "call",
-    "invoke": "call",
-    "invocation": "call",
-    "fields": "field",
-    "property": "field",
-    "properties": "field",
-    "member": "field",
-    "members": "field",
-    "imports": "import",
-    "imported": "import",
-    "module": "import",
-    "modules": "import",
-    "exports": "export",
-    "exported": "export",
-}
-
-
-def _normalize_context_filters(filters: list[str] | None) -> list[str]:
-    if not filters:
-        return []
-    normalized: list[str] = []
-    seen: set[str] = set()
-    for value in filters:
-        key = _strip_diacritics(str(value)).strip().lower()
-        if not key:
-            continue
-        key = _CONTEXT_FILTER_ALIASES.get(key, key)
-        if key not in seen:
-            seen.add(key)
-            normalized.append(key)
-    return normalized
-
-
-def _infer_context_filters(question: str) -> list[str]:
-    lowered = {
-        _strip_diacritics(token).lower()
-        for token in question.replace("?", " ").replace(",", " ").split()
-    }
-    inferred: list[str] = []
-    for context, hints in _CONTEXT_HINTS:
-        if any(hint in lowered for hint in hints):
-            inferred.append(context)
-    return inferred
-
-
-def _resolve_context_filters(question: str, explicit_filters: list[str] | None = None) -> tuple[list[str], str | None]:
-    normalized = _normalize_context_filters(explicit_filters)
-    if normalized:
-        return normalized, "explicit"
-    inferred = _infer_context_filters(question)
-    if inferred:
-        return inferred, "heuristic"
-    return [], None
-
-
-def _filter_graph_by_context(G: nx.Graph, context_filters: list[str] | None) -> nx.Graph:
-    filters = set(_normalize_context_filters(context_filters))
-    if not filters:
-        return G
-    H = G.__class__()
-    H.add_nodes_from(G.nodes(data=True))
-    if isinstance(G, (nx.MultiGraph, nx.MultiDiGraph)):
-        for u, v, key, data in G.edges(keys=True, data=True):
-            if data.get("context") in filters:
-                H.add_edge(u, v, key=key, **data)
-    else:
-        for u, v, data in G.edges(data=True):
-            if data.get("context") in filters:
-                H.add_edge(u, v, **data)
-    return H
-
-
-def _bfs(G: nx.Graph, start_nodes: list[str], depth: int) -> tuple[set[str], list[tuple]]:
-    # Compute hub threshold: nodes above this degree are not expanded as transit.
-    # p99 of degree distribution, floored at 50 to avoid over-blocking small graphs.
-    degrees = [G.degree(n) for n in G.nodes()]
-    if degrees:
-        degrees_sorted = sorted(degrees)
-        p99_idx = int(len(degrees_sorted) * 0.99)
-        hub_threshold = max(50, degrees_sorted[p99_idx])
-    else:
-        hub_threshold = 50
-    seed_set = set(start_nodes)
-    visited: set[str] = set(start_nodes)
-    frontier = set(start_nodes)
-    edges_seen: list[tuple] = []
-    for _ in range(depth):
-        next_frontier: set[str] = set()
-        for n in frontier:
-            # Don't expand through high-degree hubs (except seeds - a hub that
-            # is the starting node should still be explored).
-            if n not in seed_set and G.degree(n) >= hub_threshold:
-                continue
-            for neighbor in G.neighbors(n):
-                if neighbor not in visited:
-                    next_frontier.add(neighbor)
-                    edges_seen.append((n, neighbor))
-        visited.update(next_frontier)
-        frontier = next_frontier
-    return visited, edges_seen
-
-
-def _dfs(G: nx.Graph, start_nodes: list[str], depth: int) -> tuple[set[str], list[tuple]]:
-    degrees = [G.degree(n) for n in G.nodes()]
-    if degrees:
-        degrees_sorted = sorted(degrees)
-        p99_idx = int(len(degrees_sorted) * 0.99)
-        hub_threshold = max(50, degrees_sorted[p99_idx])
-    else:
-        hub_threshold = 50
-    seed_set = set(start_nodes)
-    visited: set[str] = set()
-    edges_seen: list[tuple] = []
-    stack = [(n, 0) for n in reversed(start_nodes)]
-    while stack:
-        node, d = stack.pop()
-        if node in visited or d > depth:
-            continue
-        visited.add(node)
-        if node not in seed_set and G.degree(node) >= hub_threshold:
-            continue
-        for neighbor in G.neighbors(node):
-            if neighbor not in visited:
-                stack.append((neighbor, d + 1))
-                edges_seen.append((node, neighbor))
-    return visited, edges_seen
-
-
-def _subgraph_to_text(G: nx.Graph, nodes: set[str], edges: list[tuple], token_budget: int = 2000, *, seeds: list[str] | None = None) -> str:
-    """Render subgraph as text, cutting at token_budget (approx 3 chars/token).
-
-    seeds: exact-match nodes rendered first before the degree-sorted expansion,
-    so the queried symbol always appears at the top of the output.
-    """
-    char_budget = token_budget * 3
-    lines = []
-    seed_set = set(seeds or [])
-    ordered = [n for n in (seeds or []) if n in nodes] + \
-              sorted(nodes - seed_set, key=lambda n: G.degree(n), reverse=True)
-    for nid in ordered:
-        d = G.nodes[nid]
-        # Every LLM-derived field passes through sanitize_label before being
-        # concatenated into MCP tool output (F-010): an attacker who controls a
-        # corpus document can otherwise inject ANSI escapes, fake graphify-out
-        # log lines, or prompt-injection markup into the model's context via
-        # source_file / source_location / community.
-        line = (
-            f"NODE {sanitize_label(d.get('label', nid))} "
-            f"[src={sanitize_label(str(d.get('source_file', '')))} "
-            f"loc={sanitize_label(str(d.get('source_location', '')))} "
-            f"community={sanitize_label(str(d.get('community', '')))}]"
-        )
-        lines.append(line)
-    for u, v in edges:
-        if u in nodes and v in nodes:
-            raw = G[u][v]
-            d = next(iter(raw.values()), {}) if isinstance(G, (nx.MultiGraph, nx.MultiDiGraph)) else raw
-            context = d.get("context")
-            context_suffix = f" context={sanitize_label(str(context))}" if context else ""
-            line = (
-                f"EDGE {sanitize_label(G.nodes[u].get('label', u))} "
-                f"--{sanitize_label(str(d.get('relation', '')))} "
-                f"[{sanitize_label(str(d.get('confidence', '')))}{context_suffix}]--> "
-                f"{sanitize_label(G.nodes[v].get('label', v))}"
-            )
-            lines.append(line)
-    output = "\n".join(lines)
-    if len(output) > char_budget:
-        cut_at = output[:char_budget].rfind("\n")
-        cut_at = cut_at if cut_at > 0 else char_budget
-        total_nodes = sum(1 for l in lines if l.startswith("NODE "))
-        shown_nodes = output[:cut_at].count("\nNODE ") + (1 if output.startswith("NODE ") else 0)
-        cut_count = total_nodes - shown_nodes
-        output = (
-            output[:cut_at]
-            + f"\n... (truncated — {cut_count} more nodes cut by ~{token_budget}-token budget."
-            f" Narrow with context_filter=['call'] or use get_node for a specific symbol)"
-        )
-    return output
-
-
-def _query_graph_text(
-    G: nx.Graph,
-    question: str,
-    *,
-    mode: str = "bfs",
-    depth: int = 3,
-    token_budget: int = 2000,
-    context_filters: list[str] | None = None,
-) -> str:
-    terms = _query_terms(question)
-    scored = _score_nodes(G, terms)
-    start_nodes = _pick_seeds(scored)
-    if not start_nodes:
-        return "No matching nodes found."
-    resolved_filters, filter_source = _resolve_context_filters(question, context_filters)
-    traversal_graph = _filter_graph_by_context(G, resolved_filters)
-    nodes, edges = _dfs(traversal_graph, start_nodes, depth) if mode == "dfs" else _bfs(traversal_graph, start_nodes, depth)
-    header_parts = [
-        f"Traversal: {mode.upper()} depth={depth}",
-        f"Start: {[G.nodes[n].get('label', n) for n in start_nodes]}",
-    ]
-    if resolved_filters:
-        header_parts.append(f"Context: {', '.join(resolved_filters)} ({filter_source})")
-    header_parts.append(f"{len(nodes)} nodes found")
-    header = " | ".join(header_parts) + "\n\n"
-    return header + _subgraph_to_text(traversal_graph, nodes, edges, token_budget)
-
-
-def _find_node(G: nx.Graph, label: str) -> list[str]:
-    """Return node IDs whose label or ID matches the search term (diacritic-insensitive).
-
-    Results are ordered by three-tier precedence: exact match, then prefix match,
-    then substring match. Node-ID exact matches are grouped with label exact matches.
-    """
-    term = " ".join(_search_tokens(label))
-    if not term:
-        return []
-    exact: list[str] = []
-    prefix: list[str] = []
-    substring: list[str] = []
-    for nid, d in G.nodes(data=True):
-        norm_label = d.get("norm_label") or _strip_diacritics(d.get("label") or "").lower()
-        bare_label = norm_label.rstrip("()")
-        nid_lower = nid.lower()
-        if term == norm_label or term == bare_label or term == nid_lower:
-            exact.append(nid)
-        elif norm_label.startswith(term) or bare_label.startswith(term) or nid_lower.startswith(term):
-            prefix.append(nid)
-        elif term in norm_label:
-            substring.append(nid)
-    return exact + prefix + substring
-
-
-def _filter_blank_stdin() -> None:
-    """Filter blank lines from stdin before MCP reads it.
-
-    Some MCP clients (Claude Desktop, etc.) send blank lines between JSON
-    messages. The MCP stdio transport tries to parse every line as a
-    JSONRPCMessage, so a bare newline triggers a Pydantic ValidationError.
-    This installs an OS-level pipe that relays stdin while dropping blanks.
-    """
-    import os
-    import threading
-
-    r_fd, w_fd = os.pipe()
-    saved_fd = os.dup(sys.stdin.fileno())
-
-    def _relay() -> None:
-        try:
-            with open(saved_fd, "rb") as src, open(w_fd, "wb") as dst:
-                for line in src:
-                    if line.strip():
-                        dst.write(line)
-                        dst.flush()
-        except Exception:
-            pass
-
-    threading.Thread(target=_relay, daemon=True).start()
-    os.dup2(r_fd, sys.stdin.fileno())
-    os.close(r_fd)
-    sys.stdin = open(0, "r", closefd=False)
-
-
-def _build_server(graph_path: str):
-    """Build the configured low-level MCP Server (shared by every transport).
-
-    All graph query tools and resources are registered here over a single
-    ``mcp.server.Server`` instance; the caller picks the transport (stdio or
-    Streamable HTTP) and runs it. Hot-reload of graph.json works the same way
-    regardless of transport, since reloads happen inside the tool handlers.
-    """
-    import threading
-
-    try:
-        from mcp.server import Server
-        from mcp import types
-        from mcp.types import AnyUrl
-    except ImportError as e:
-        raise ImportError('mcp not installed. Run: pip install "graphifyy[mcp]"') from e
-
-    G = _load_graph(graph_path)
-    communities = _communities_from_graph(G)
-
-    # Hot-reload state: mtime+size key lets us detect graph.json changes without
-    # polling. Initialised from the file stat at startup so the first tool call
-    # never triggers a redundant reload.
-    _reload_lock = threading.Lock()
-    try:
-        _s = Path(graph_path).stat()
-        _reload_state: dict = {"mtime_ns": _s.st_mtime_ns, "size": _s.st_size}
-    except FileNotFoundError:
-        _reload_state = {"mtime_ns": 0, "size": -1}
-
-    def _maybe_reload() -> None:
-        nonlocal G, communities
-        try:
-            s = Path(graph_path).stat()
-            key = (s.st_mtime_ns, s.st_size)
-        except FileNotFoundError:
-            return
-        if key == (_reload_state["mtime_ns"], _reload_state["size"]):
-            return
-        with _reload_lock:
-            try:
-                s = Path(graph_path).stat()
-                key = (s.st_mtime_ns, s.st_size)
-            except FileNotFoundError:
-                return
-            if key == (_reload_state["mtime_ns"], _reload_state["size"]):
-                return  # another thread already reloaded
-            try:
-                new_G = _load_graph(graph_path)
-            except SystemExit:
-                return  # keep serving stale graph on transient read error
-            G = new_G
-            communities = _communities_from_graph(new_G)
-            _reload_state["mtime_ns"], _reload_state["size"] = key
-
-    server = Server("graphify")
-
-    @server.list_tools()
-    async def list_tools() -> list[types.Tool]:
-        return [
-            types.Tool(
-                name="query_graph",
-                description="Search the knowledge graph using BFS or DFS. Returns relevant nodes and edges as text context.",
-                inputSchema={
-                    "type": "object",
-                    "properties": {
-                        "question": {"type": "string", "description": "Natural language question or keyword search"},
-                        "mode": {"type": "string", "enum": ["bfs", "dfs"], "default": "bfs",
-                                 "description": "bfs=broad context, dfs=trace a specific path"},
-                        "depth": {"type": "integer", "default": 3, "description": "Traversal depth (1-6)"},
-                        "token_budget": {"type": "integer", "default": 2000, "description": "Max output tokens"},
-                        "context_filter": {
-                            "type": "array",
-                            "items": {"type": "string"},
-                            "description": "Optional explicit edge-context filter, e.g. ['call', 'field']",
-                        },
-                    },
-                    "required": ["question"],
-                },
-            ),
-            types.Tool(
-                name="get_node",
-                description="Get full details for a specific node by label or ID.",
-                inputSchema={
-                    "type": "object",
-                    "properties": {"label": {"type": "string", "description": "Node label or ID to look up"}},
-                    "required": ["label"],
-                },
-            ),
-            types.Tool(
-                name="get_neighbors",
-                description="Get all direct neighbors of a node with edge details.",
-                inputSchema={
-                    "type": "object",
-                    "properties": {
-                        "label": {"type": "string"},
-                        "relation_filter": {"type": "string", "description": "Optional: filter by relation type"},
-                    },
-                    "required": ["label"],
-                },
-            ),
-            types.Tool(
-                name="get_community",
-                description="Get all nodes in a community by community ID.",
-                inputSchema={
-                    "type": "object",
-                    "properties": {"community_id": {"type": "integer", "description": "Community ID (0-indexed by size)"}},
-                    "required": ["community_id"],
-                },
-            ),
-            types.Tool(
-                name="god_nodes",
-                description="Return the most connected nodes - the core abstractions of the knowledge graph.",
-                inputSchema={"type": "object", "properties": {"top_n": {"type": "integer", "default": 10}}},
-            ),
-            types.Tool(
-                name="graph_stats",
-                description="Return summary statistics: node count, edge count, communities, confidence breakdown.",
-                inputSchema={"type": "object", "properties": {}},
-            ),
-            types.Tool(
-                name="shortest_path",
-                description="Find the shortest path between two concepts in the knowledge graph.",
-                inputSchema={
-                    "type": "object",
-                    "properties": {
-                        "source": {"type": "string", "description": "Source concept label or keyword"},
-                        "target": {"type": "string", "description": "Target concept label or keyword"},
-                        "max_hops": {"type": "integer", "default": 8, "description": "Maximum hops to consider"},
-                    },
-                    "required": ["source", "target"],
-                },
-            ),
-            types.Tool(
-                name="list_prs",
-                description=(
-                    "List open GitHub PRs with CI status, review state, and graph impact "
-                    "(which communities each PR touches, blast radius). Use this before starting "
-                    "work to check if a PR already covers the area you're about to change."
-                ),
-                inputSchema={
-                    "type": "object",
-                    "properties": {
-                        "base": {"type": "string", "description": "Base branch to filter PRs by (auto-detected if omitted)"},
-                        "repo": {"type": "string", "description": "GitHub repo (owner/repo). Defaults to current repo."},
-                    },
-                },
-            ),
-            types.Tool(
-                name="get_pr_impact",
-                description=(
-                    "Get detailed graph impact for a specific PR: which files it changes, "
-                    "which knowledge-graph communities are affected, and how many nodes are touched. "
-                    "Use this to assess merge risk or check for overlap with your current work."
-                ),
-                inputSchema={
-                    "type": "object",
-                    "properties": {
-                        "pr_number": {"type": "integer", "description": "PR number to analyse"},
-                        "repo": {"type": "string", "description": "GitHub repo (owner/repo). Defaults to current repo."},
-                    },
-                    "required": ["pr_number"],
-                },
-            ),
-            types.Tool(
-                name="triage_prs",
-                description=(
-                    "Return all actionable open PRs (correct base, not stale) with full graph impact data "
-                    "so you can reason about review priority, merge order, and conflict risk. "
-                    "Call this when the user asks 'what PRs should I review?' or 'what's ready to merge?'"
-                ),
-                inputSchema={
-                    "type": "object",
-                    "properties": {
-                        "base": {"type": "string", "description": "Base branch to filter PRs by (auto-detected if omitted)"},
-                        "repo": {"type": "string", "description": "GitHub repo (owner/repo). Defaults to current repo."},
-                    },
-                },
-            ),
-        ]
-
-    def _tool_query_graph(arguments: dict) -> str:
-        import time as _time
-        from graphify import querylog
-        question = arguments["question"]
-        mode = arguments.get("mode", "bfs")
-        depth = min(int(arguments.get("depth", 3)), 6)
-        budget = int(arguments.get("token_budget", 2000))
-        context_filter = arguments.get("context_filter")
-        _t0 = _time.perf_counter()
-        result = _query_graph_text(
-            G,
-            question,
-            mode=mode,
-            depth=depth,
-            token_budget=budget,
-            context_filters=context_filter,
-        )
-        querylog.log_query(
-            kind="mcp_query",
-            question=question,
-            corpus=str(graph_path),
-            result=result,
-            mode=mode,
-            depth=depth,
-            token_budget=budget,
-            duration_ms=(_time.perf_counter() - _t0) * 1000,
-        )
-        return result
-
-    def _tool_get_node(arguments: dict) -> str:
-        label = arguments["label"].lower()
-        matches = [(nid, d) for nid, d in G.nodes(data=True)
-                   if label in (d.get("label") or "").lower() or label == nid.lower()]
-        if not matches:
-            return f"No node matching '{label}' found."
-        nid, d = matches[0]
-        # Sanitise every LLM-derived field before concatenation (F-010).
-        return "\n".join([
-            f"Node: {sanitize_label(d.get('label', nid))}",
-            f"  ID: {sanitize_label(nid)}",
-            f"  Source: {sanitize_label(str(d.get('source_file', '')))} {sanitize_label(str(d.get('source_location', '')))}",
-            f"  Type: {sanitize_label(str(d.get('file_type', '')))}",
-            f"  Community: {sanitize_label(str(d.get('community', '')))}",
-            f"  Degree: {G.degree(nid)}",
-        ])
-
-    def _tool_get_neighbors(arguments: dict) -> str:
-        label = arguments["label"].lower()
-        rel_filter = arguments.get("relation_filter", "").lower()
-        matches = _find_node(G, label)
-        if not matches:
-            return f"No node matching '{label}' found."
-        nid = matches[0]
-        lines = [f"Neighbors of {sanitize_label(G.nodes[nid].get('label', nid))}:"]
-        for nb in G.successors(nid):
-            d = edge_data(G, nid, nb)
-            rel = d.get("relation", "")
-            if rel_filter and rel_filter not in rel.lower():
-                continue
-            lines.append(
-                f"  --> {sanitize_label(G.nodes[nb].get('label', nb))} "
-                f"[{sanitize_label(str(rel))}] [{sanitize_label(str(d.get('confidence', '')))}]"
-            )
-        for nb in G.predecessors(nid):
-            d = edge_data(G, nb, nid)
-            rel = d.get("relation", "")
-            if rel_filter and rel_filter not in rel.lower():
-                continue
-            lines.append(
-                f"  <-- {sanitize_label(G.nodes[nb].get('label', nb))} "
-                f"[{sanitize_label(str(rel))}] [{sanitize_label(str(d.get('confidence', '')))}]"
-            )
-        return "\n".join(lines)
-
-    def _tool_get_community(arguments: dict) -> str:
-        cid = int(arguments["community_id"])
-        nodes = communities.get(cid, [])
-        if not nodes:
-            return f"Community {cid} not found."
-        lines = [f"Community {cid} ({len(nodes)} nodes):"]
-        for n in nodes:
-            d = G.nodes[n]
-            # Sanitise label and source_file (F-010).
-            lines.append(
-                f"  {sanitize_label(d.get('label', n))} "
-                f"[{sanitize_label(str(d.get('source_file', '')))}]"
-            )
-        return "\n".join(lines)
-
-    def _tool_god_nodes(arguments: dict) -> str:
-        from graphify.analyze import god_nodes as _god_nodes
-        nodes = _god_nodes(G, top_n=int(arguments.get("top_n", 10)))
-        lines = ["God nodes (most connected):"]
-        lines += [f"  {i}. {n['label']} - {n['degree']} edges" for i, n in enumerate(nodes, 1)]
-        return "\n".join(lines)
-
-    def _tool_graph_stats(_: dict) -> str:
-        confs = [d.get("confidence", "EXTRACTED") for _, _, d in G.edges(data=True)]
-        total = len(confs) or 1
-        return (
-            f"Nodes: {G.number_of_nodes()}\n"
-            f"Edges: {G.number_of_edges()}\n"
-            f"Communities: {len(communities)}\n"
-            f"EXTRACTED: {round(confs.count('EXTRACTED')/total*100)}%\n"
-            f"INFERRED: {round(confs.count('INFERRED')/total*100)}%\n"
-            f"AMBIGUOUS: {round(confs.count('AMBIGUOUS')/total*100)}%\n"
-        )
-
-    def _tool_shortest_path(arguments: dict) -> str:
-        src_scored = _score_nodes(G, [t.lower() for t in arguments["source"].split()])
-        tgt_scored = _score_nodes(G, [t.lower() for t in arguments["target"].split()])
-        if not src_scored:
-            return f"No node matching source '{arguments['source']}' found."
-        if not tgt_scored:
-            return f"No node matching target '{arguments['target']}' found."
-        src_nid, tgt_nid = src_scored[0][1], tgt_scored[0][1]
-        # Ambiguity guard: when both queries resolve to the same node, the
-        # shortest path is trivially zero hops, which is almost never what the
-        # caller wanted (see bug #828).
-        if src_nid == tgt_nid:
-            return (
-                f"'{arguments['source']}' and '{arguments['target']}' both resolved to "
-                f"the same node '{src_nid}'. Use a more specific label or the exact node ID."
-            )
-        warnings: list[str] = []
-        for name, scored in (("source", src_scored), ("target", tgt_scored)):
-            if len(scored) >= 2:
-                top, runner = scored[0][0], scored[1][0]
-                if top > 0 and (top - runner) / top < 0.10:
-                    warnings.append(
-                        f"warning: {name} match was ambiguous "
-                        f"(top score {top:g}, runner-up {runner:g})"
-                    )
-        max_hops = int(arguments.get("max_hops", 8))
-        try:
-            # Use undirected view for path-finding (works regardless of query src/tgt order)
-            path_nodes = nx.shortest_path(G.to_undirected(as_view=True), src_nid, tgt_nid)
-        except (nx.NetworkXNoPath, nx.NodeNotFound):
-            return f"No path found between '{G.nodes[src_nid].get('label', src_nid)}' and '{G.nodes[tgt_nid].get('label', tgt_nid)}'."
-        hops = len(path_nodes) - 1
-        if hops > max_hops:
-            return f"Path exceeds max_hops={max_hops} ({hops} hops found)."
-        segments = []
-        for i in range(len(path_nodes) - 1):
-            u, v = path_nodes[i], path_nodes[i + 1]
-            if G.has_edge(u, v):
-                edata = edge_data(G, u, v)
-                forward = True
-            else:
-                edata = edge_data(G, v, u)
-                forward = False
-            rel = edata.get("relation", "")
-            conf = edata.get("confidence", "")
-            conf_str = f" [{conf}]" if conf else ""
-            if i == 0:
-                segments.append(G.nodes[u].get("label", u))
-            if forward:
-                segments.append(f"--{rel}{conf_str}--> {G.nodes[v].get('label', v)}")
-            else:
-                segments.append(f"<--{rel}{conf_str}-- {G.nodes[v].get('label', v)}")
-        prefix = ("\n".join(warnings) + "\n") if warnings else ""
-        return prefix + f"Shortest path ({hops} hops):\n  " + " ".join(segments)
-
-    def _tool_list_prs(arguments: dict) -> str:
-        from graphify.prs import fetch_prs, fetch_worktrees, format_prs_text, _detect_default_branch
-        repo = arguments.get("repo") or None
-        base = arguments.get("base") or _detect_default_branch(repo)
-        try:
-            prs = fetch_prs(repo=repo, base=base)
-        except RuntimeError as e:
-            return f"Error: {e}"
-        worktrees = fetch_worktrees()
-        for pr in prs:
-            pr.worktree_path = worktrees.get(pr.branch)
-        return format_prs_text(prs, base)
-
-    def _tool_get_pr_impact(arguments: dict) -> str:
-        from graphify.prs import fetch_pr_files, compute_pr_impact, _gh, _parse_ci
-        number = int(arguments["pr_number"])
-        repo = arguments.get("repo") or None
-        # Use gh pr view directly — works for any base branch, not just the default
-        view_args = ["pr", "view", str(number), "--json",
-                     "title,headRefName,baseRefName,author,isDraft,reviewDecision,statusCheckRollup,updatedAt"]
-        if repo:
-            view_args += ["--repo", repo]
-        pr_data = _gh(*view_args)
-        if pr_data is None:
-            return f"PR #{number} not found or gh not authenticated."
-        files = fetch_pr_files(number, repo)
-        if not files:
-            return f"PR #{number}: no changed files found (may require gh auth)."
-        comms, nodes = compute_pr_impact(files, G)
-        ci = _parse_ci(pr_data.get("statusCheckRollup") or [])
-        lines = [
-            f"PR #{number}: {pr_data['title']}",
-            f"CI: {ci}  Review: {pr_data.get('reviewDecision') or 'none'}",
-            f"Base: {pr_data['baseRefName']}  Author: {(pr_data.get('author') or {}).get('login', '?')}",
-            f"\nGraph impact: {nodes} nodes across {len(comms)} communities",
-            f"Communities touched: {comms}",
-            f"Files changed ({len(files)}):",
-        ]
-        lines += [f"  {f}" for f in files[:20]]
-        if len(files) > 20:
-            lines.append(f"  … and {len(files) - 20} more")
-        return "\n".join(lines)
-
-    def _tool_triage_prs(arguments: dict) -> str:
-        from concurrent.futures import ThreadPoolExecutor, as_completed
-        from graphify.prs import fetch_prs, fetch_worktrees, fetch_pr_files, compute_pr_impact, _STATUS_ORDER, _detect_default_branch
-        repo = arguments.get("repo") or None
-        base = arguments.get("base") or _detect_default_branch(repo)
-        try:
-            prs = fetch_prs(repo=repo, base=base)
-        except RuntimeError as e:
-            return f"Error: {e}"
-        worktrees = fetch_worktrees()
-        for pr in prs:
-            pr.worktree_path = worktrees.get(pr.branch)
-        actionable = [p for p in prs if p.base_branch == base and p.status not in ("WRONG-BASE", "STALE")]
-        if not actionable:
-            return f"No actionable PRs targeting {base}."
-        # Fetch diffs concurrently then compute graph impact using in-memory G
-        workers = min(8, len(actionable))
-        with ThreadPoolExecutor(max_workers=workers) as pool:
-            future_to_pr = {pool.submit(fetch_pr_files, pr.number, repo): pr for pr in actionable}
-            for fut in as_completed(future_to_pr):
-                pr = future_to_pr[fut]
-                try:
-                    files = fut.result()
-                except Exception:
-                    files = []
-                if files:
-                    pr.files_changed = files
-                    pr.communities_touched, pr.nodes_affected = compute_pr_impact(files, G)
-        header = (
-            f"Actionable PRs targeting {base}: {len(actionable)}\n"
-            "Rank these by review priority. Higher blast_radius = more graph communities affected = higher merge risk.\n"
-        )
-        lines = [header]
-        for p in sorted(actionable, key=lambda x: (_STATUS_ORDER.index(x.status) if x.status in _STATUS_ORDER else 99)):
-            impact = f"  blast_radius={p.blast_radius}" if p.blast_radius else ""
-            wt = f"  worktree={p.worktree_path}" if p.worktree_path else ""
-            lines.append(
-                f"PR #{p.number} [{p.status}] CI={p.ci_status} review={p.review_decision or 'none'} "
-                f"age={p.days_old}d author={p.author}{impact}{wt}\n  title: {p.title}"
-            )
-        return "\n\n".join(lines)
-
-    _handlers = {
-        "query_graph": _tool_query_graph,
-        "get_node": _tool_get_node,
-        "get_neighbors": _tool_get_neighbors,
-        "get_community": _tool_get_community,
-        "god_nodes": _tool_god_nodes,
-        "graph_stats": _tool_graph_stats,
-        "shortest_path": _tool_shortest_path,
-        "list_prs": _tool_list_prs,
-        "get_pr_impact": _tool_get_pr_impact,
-        "triage_prs": _tool_triage_prs,
-    }
-
-    def _load_community_labels() -> dict[int, str]:
-        labels_path = Path(graph_path).parent / ".graphify_labels.json"
-        if labels_path.exists():
-            try:
-                return {int(k): v for k, v in json.loads(labels_path.read_text(encoding="utf-8")).items()}
-            except Exception:
-                pass
-        return {cid: f"Community {cid}" for cid in communities}
-
-    @server.list_resources()
-    async def list_resources() -> list[types.Resource]:
-        return [
-            types.Resource(uri=AnyUrl("graphify://report"), name="Graph Report", description="Full GRAPH_REPORT.md", mimeType="text/markdown"),
-            types.Resource(uri=AnyUrl("graphify://stats"), name="Graph Stats", description="Node/edge/community counts and confidence breakdown", mimeType="text/plain"),
-            types.Resource(uri=AnyUrl("graphify://god-nodes"), name="God Nodes", description="Top 10 most-connected nodes", mimeType="text/plain"),
-            types.Resource(uri=AnyUrl("graphify://surprises"), name="Surprising Connections", description="Cross-community surprising connections", mimeType="text/plain"),
-            types.Resource(uri=AnyUrl("graphify://audit"), name="Confidence Audit", description="EXTRACTED/INFERRED/AMBIGUOUS edge breakdown", mimeType="text/plain"),
-            types.Resource(uri=AnyUrl("graphify://questions"), name="Suggested Questions", description="Suggested questions for this codebase", mimeType="text/plain"),
-        ]
-
-    @server.read_resource()
-    async def read_resource(uri: AnyUrl) -> str:
-        _maybe_reload()
-        uri_str = str(uri)
-        if uri_str == "graphify://report":
-            report_path = Path(graph_path).parent / "GRAPH_REPORT.md"
-            if report_path.exists():
-                return report_path.read_text(encoding="utf-8")
-            return "GRAPH_REPORT.md not found. Run graphify extract first."
-        if uri_str == "graphify://stats":
-            return _tool_graph_stats({})
-        if uri_str == "graphify://god-nodes":
-            return _tool_god_nodes({"top_n": 10})
-        if uri_str == "graphify://surprises":
-            try:
-                from graphify.analyze import surprising_connections
-                surprises = surprising_connections(G, communities, top_n=10)
-                if not surprises:
-                    return "No surprising connections found."
-                lines = ["Surprising cross-community connections:"]
-                for s in surprises:
-                    lines.append(f"  {s.get('source', '')} <-> {s.get('target', '')} [{s.get('relation', '')}]")
-                return "\n".join(lines)
-            except Exception as exc:
-                return f"Could not compute surprising connections: {exc}"
-        if uri_str == "graphify://audit":
-            confs = [d.get("confidence", "EXTRACTED") for _, _, d in G.edges(data=True)]
-            total = len(confs) or 1
-            return (
-                f"Total edges: {total}\n"
-                f"EXTRACTED: {confs.count('EXTRACTED')} ({round(confs.count('EXTRACTED')/total*100)}%)\n"
-                f"INFERRED: {confs.count('INFERRED')} ({round(confs.count('INFERRED')/total*100)}%)\n"
-                f"AMBIGUOUS: {confs.count('AMBIGUOUS')} ({round(confs.count('AMBIGUOUS')/total*100)}%)\n"
-            )
-        if uri_str == "graphify://questions":
-            try:
-                from graphify.analyze import suggest_questions
-                community_labels = _load_community_labels()
-                questions = suggest_questions(G, communities, community_labels, top_n=10)
-                if not questions:
-                    return "No suggested questions available."
-                lines = ["Suggested questions:"]
-                for q in questions:
-                    if isinstance(q, dict):
-                        lines.append(f"  - {q.get('question', '')}")
-                    else:
-                        lines.append(f"  - {q}")
-                return "\n".join(lines)
-            except Exception as exc:
-                return f"Could not generate questions: {exc}"
-        raise ValueError(f"Unknown resource: {uri_str}")
-
-    @server.call_tool()
-    async def call_tool(name: str, arguments: dict) -> list[types.TextContent]:
-        _maybe_reload()
-        handler = _handlers.get(name)
-        if not handler:
-            return [types.TextContent(type="text", text=f"Unknown tool: {name}")]
-        try:
-            return [types.TextContent(type="text", text=handler(arguments))]
-        except Exception as exc:
-            return [types.TextContent(type="text", text=f"Error executing {name}: {exc}")]
-
-    return server
-
-
-def serve(graph_path: str = "graphify-out/graph.json") -> None:
-    """Start the MCP server over stdio (the default, per-developer transport)."""
-    try:
-        from mcp.server.stdio import stdio_server
-    except ImportError as e:
-        raise ImportError('mcp not installed. Run: pip install "graphifyy[mcp]"') from e
-    import asyncio
-
-    server = _build_server(graph_path)
-
-    async def main() -> None:
-        async with stdio_server() as streams:
-            await server.run(streams[0], streams[1], server.create_initialization_options())
-
-    _filter_blank_stdin()
-    asyncio.run(main())
-
-
-class _MCPASGIApp:
-    """Raw-ASGI wrapper around the Streamable HTTP session manager.
-
-    Passed to a Starlette ``Route`` as a class instance (not a function) so
-    Starlette treats it as an ASGI app: it serves the exact mount path for all
-    methods (GET/POST/DELETE) with no request/response wrapping and no
-    trailing-slash redirect — mirroring how FastMCP mounts the same manager.
-    """
-
-    def __init__(self, manager) -> None:
-        self._manager = manager
-
-    async def __call__(self, scope, receive, send) -> None:
-        await self._manager.handle_request(scope, receive, send)
-
-
-class _ApiKeyMiddleware:
-    """Pure-ASGI API-key gate for the HTTP transport.
-
-    Implemented as raw ASGI (not Starlette's BaseHTTPMiddleware) on purpose:
-    BaseHTTPMiddleware buffers responses and breaks the Streamable HTTP SSE
-    stream. This short-circuits with 401 before the request ever reaches the
-    session manager, leaving the streaming path untouched for authorized calls.
-    """
-
-    def __init__(self, app, api_key: str) -> None:
-        self.app = app
-        self._expected = api_key.encode("utf-8")
-
-    async def __call__(self, scope, receive, send) -> None:
-        if scope["type"] != "http":
-            await self.app(scope, receive, send)
-            return
-        import hmac
-        headers = dict(scope.get("headers") or [])
-        provided = headers.get(b"x-api-key")
-        if provided is None:
-            # RFC 6750: the auth scheme token is case-insensitive.
-            scheme, _, token = headers.get(b"authorization", b"").partition(b" ")
-            if scheme.lower() == b"bearer" and token:
-                provided = token.strip()
-        # Constant-time compare; reject when no key was supplied at all.
-        if provided is None or not hmac.compare_digest(provided, self._expected):
-            body = b'{"error": "unauthorized"}'
-            await send({
-                "type": "http.response.start",
-                "status": 401,
-                "headers": [
-                    (b"content-type", b"application/json"),
-                    (b"content-length", str(len(body)).encode("ascii")),
-                ],
-            })
-            await send({"type": "http.response.body", "body": body})
-            return
-        await self.app(scope, receive, send)
-
-
-def _build_http_app(
-    graph_path: str,
-    *,
-    host: str = "127.0.0.1",
-    port: int = 8080,
-    api_key: str | None = None,
-    path: str = "/mcp",
-    json_response: bool = False,
-    stateless: bool = False,
-    session_timeout: float | None = 3600.0,
-):
-    """Build the Starlette ASGI app for the Streamable HTTP transport.
-
-    Split out from :func:`serve_http` (which blocks on uvicorn) so the wiring
-    can be exercised with an in-process ASGI test client.
-
-    ``session_timeout`` reaps stateful sessions idle for that many seconds so a
-    long-running shared server does not leak memory when IDE clients disconnect
-    without sending a DELETE. ``None`` (or <= 0) disables reaping; it is forced
-    to ``None`` in stateless mode, which has no sessions to reap.
-    """
-    try:
-        import contextlib
-
-        from starlette.applications import Starlette
-        from starlette.middleware import Middleware
-        from starlette.routing import Route
-
-        from mcp.server.streamable_http_manager import StreamableHTTPSessionManager
-        from mcp.server.transport_security import TransportSecuritySettings
-    except ImportError as e:
-        raise ImportError(
-            'HTTP transport needs the mcp extra (mcp + starlette + uvicorn). '
-            'Run: pip install "graphifyy[mcp]"'
-        ) from e
-
-    # A blank key (e.g. --api-key "" or an empty GRAPHIFY_API_KEY) must not be
-    # mistaken for "auth on" — normalize it to None so the gate is unambiguous.
-    api_key = (api_key or "").strip() or None
-
-    server = _build_server(graph_path)
-
-    # DNS-rebinding protection. When the operator binds a wildcard address they
-    # are intentionally exposing the server, so accept any Host header; for a
-    # loopback/specific bind, restrict Host to that address (with and without
-    # the port) plus the localhost aliases.
-    if host in ("0.0.0.0", "::", ""):
-        security = TransportSecuritySettings(enable_dns_rebinding_protection=False)
-    else:
-        allowed = {host, "localhost", "127.0.0.1"}
-        allowed |= {f"{h}:{port}" for h in list(allowed)}
-        security = TransportSecuritySettings(allowed_hosts=sorted(allowed))
-
-    # The SDK rejects a non-positive timeout and forbids one in stateless mode.
-    idle_timeout = None if (stateless or not session_timeout or session_timeout <= 0) else session_timeout
-
-    manager = StreamableHTTPSessionManager(
-        app=server,
-        json_response=json_response,
-        stateless=stateless,
-        security_settings=security,
-        session_idle_timeout=idle_timeout,
-    )
-
-    @contextlib.asynccontextmanager
-    async def lifespan(_app):
-        # The session manager owns an anyio task group that must wrap the whole
-        # server lifetime, so enter it here rather than per-request.
-        async with manager.run():
-            yield
-
-    middleware = []
-    if api_key:
-        middleware.append(Middleware(_ApiKeyMiddleware, api_key=api_key))
-
-    return Starlette(
-        routes=[Route(path, endpoint=_MCPASGIApp(manager))],
-        middleware=middleware,
-        lifespan=lifespan,
-    )
-
-
-def serve_http(
-    graph_path: str = "graphify-out/graph.json",
-    *,
-    host: str = "127.0.0.1",
-    port: int = 8080,
-    api_key: str | None = None,
-    path: str = "/mcp",
-    json_response: bool = False,
-    stateless: bool = False,
-    session_timeout: float | None = 3600.0,
-) -> None:
-    """Start the MCP server over Streamable HTTP (MCP spec 2025-03-26).
-
-    Serves the same tools/resources as the stdio transport, so a single shared
-    process can host the graph for a whole team. Clients point their IDE MCP
-    config at ``http://<host>:<port><path>`` (default ``/mcp``).
-
-    ``api_key`` (or the ``GRAPHIFY_API_KEY`` env var) enables a simple header
-    check (``Authorization: Bearer <key>`` or ``X-API-Key: <key>``). OAuth is a
-    deliberate follow-up. Binding ``0.0.0.0`` exposes the server beyond
-    localhost — set an api_key when you do.
-    """
-    try:
-        import uvicorn
-    except ImportError as e:
-        raise ImportError(
-            'HTTP transport needs the mcp extra (mcp + starlette + uvicorn). '
-            'Run: pip install "graphifyy[mcp]"'
-        ) from e
-
-    api_key = (api_key or "").strip() or None
-
-    app = _build_http_app(
-        graph_path,
-        host=host,
-        port=port,
-        api_key=api_key,
-        path=path,
-        json_response=json_response,
-        stateless=stateless,
-        session_timeout=session_timeout,
-    )
-
-    auth_note = "api-key required" if api_key else "no auth (set --api-key to require one)"
-    print(
-        f"graphify MCP server (streamable-http) on http://{host}:{port}{path} - {auth_note}",
-        file=sys.stderr,
-    )
-    if host in ("0.0.0.0", "::", "") and not api_key:
-        print(
-            f"WARNING: binding {host or '0.0.0.0'} with no api-key exposes the graph "
-            "unauthenticated on the network. Set --api-key (or GRAPHIFY_API_KEY).",
-            file=sys.stderr,
-        )
-    uvicorn.run(app, host=host, port=port)
-
-
-def _main(argv: list[str] | None = None) -> None:
-    import argparse
-    import os
-
-    parser = argparse.ArgumentParser(
-        prog="python -m graphify.serve",
-        description="Serve a graphify knowledge graph over MCP (stdio or Streamable HTTP).",
-    )
-    parser.add_argument(
-        "graph_path",
-        nargs="?",
-        default="graphify-out/graph.json",
-        help="Path to graph.json (default: graphify-out/graph.json)",
-    )
-    parser.add_argument(
-        "--transport",
-        choices=["stdio", "http"],
-        default="stdio",
-        help="Transport to serve on (default: stdio)",
-    )
-    parser.add_argument("--host", default="127.0.0.1", help="HTTP bind host (default: 127.0.0.1)")
-    parser.add_argument("--port", type=int, default=8080, help="HTTP bind port (default: 8080)")
-    parser.add_argument(
-        "--api-key",
-        default=os.environ.get("GRAPHIFY_API_KEY"),
-        help="Require this key on the HTTP transport (env: GRAPHIFY_API_KEY)",
-    )
-    parser.add_argument("--path", default="/mcp", help="HTTP mount path (default: /mcp)")
-    parser.add_argument(
-        "--json-response",
-        action="store_true",
-        help="Return plain JSON responses instead of SSE streams",
-    )
-    parser.add_argument(
-        "--stateless",
-        action="store_true",
-        help="Run without per-session state (for load-balanced / CI deployments)",
-    )
-    parser.add_argument(
-        "--session-timeout",
-        type=float,
-        default=3600.0,
-        help="Reap stateful sessions idle this many seconds (default: 3600; 0 disables)",
-    )
-    args = parser.parse_args(argv)
-
-    if args.transport == "http":
-        serve_http(
-            args.graph_path,
-            host=args.host,
-            port=args.port,
-            api_key=args.api_key,
-            path=args.path,
-            json_response=args.json_response,
-            stateless=args.stateless,
-            session_timeout=args.session_timeout,
-        )
-    else:
-        serve(args.graph_path)
-
-
-if __name__ == "__main__":
-    _main()