@geml/geml 1.4.4 → 1.4.5

package/README.md

@@ -23,7 +23,7 @@ print("hi")
 
 - **Addressable** — every block has an `#id`; `geml get` / `geml set '#id'`
   read or patch one section without re-emitting the whole file (on this repo's
-  own spec, ~**31× less context** than shipping the whole document).
+  own spec, ~**66× less context** than shipping the whole document).
 - **Verifiable** — references are checked at build time (a dangling `#id` is an
   error, not a silent dead link), and the parser emits a document-model JSON
   with a `diagnostics` array, so agents and CI get a structured pass/fail signal.
@@ -159,6 +159,37 @@ attributes (caption, compute, …) without touching the body. Convention: keep
 the document title in `=== meta` (`title = "…"`), not an H1 — a lone top-level
 `#` section is the whole document, the telltale that it is really a title.
 
+## MCP Server
+
+This package includes a standard Model Context Protocol (MCP) server that exposes GEML document CRUD operations. It runs locally and supports Windows, macOS, and Linux.
+
+To connect it to an MCP-compatible client, provide the `npx` execution command and specify the `--root` argument (the directory containing your `.geml` files).
+
+### Claude Desktop
+Add to your `claude_desktop_config.json`:
+```json
+{
+  "mcpServers": {
+    "geml": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@geml/geml@latest",
+        "mcp",
+        "--root",
+        "/absolute/path/to/your/docs"
+      ]
+    }
+  }
+}
+```
+
+### Claude Code / CLI Clients
+Run the following command to add the server:
+```sh
+/mcp add npx -y @geml/geml@latest mcp --root /absolute/path/to/your/docs
+```
+
 ## Library
 
 ```js

package/codemap/find.mjs

@@ -6,11 +6,16 @@
 // document + block id to open, and the true source location. NO browser: pure
 // stdout, so it pipes/greps. `dir` defaults to ./.geml-code-graph.
 //
-// Same index the MCP `resolve_name` tool and the viewer search box use
+// Same index the MCP `geml_codemap_search` tool and the viewer search box use
 // (_index/name-lookup.json); a name with several rows is real ambiguity
 // (overloads / same short name across classes) — every candidate is printed.
-import { readFileSync, existsSync } from "node:fs";
+//
+// The matching rule and the src lookup are IMPORTED, not repeated here: this
+// command and `geml_codemap_search` answer the same question, and two copies of
+// "what counts as a match" would drift the moment one of them is tuned.
+import { existsSync } from "node:fs";
 import { join } from "node:path";
+import { searchNames, srcOf } from "./mcp-server.mjs";
 
 // `find x | head` closes stdout after a few lines — that is normal pipe
 // usage, not an error (POSIX would kill us silently with SIGPIPE; Windows
@@ -30,32 +35,13 @@ if (!existsSync(lookupPath)) {
   console.error(`no name-lookup at ${lookupPath} — build the codemap first (geml codemap build)`);
   process.exit(1);
 }
-const lookup = JSON.parse(readFileSync(lookupPath, "utf8"));
-const q = query.toLowerCase();
-const names = Object.keys(lookup).filter((n) => n.toLowerCase().includes(q)).sort();
+const { names, lookup } = searchNames(dir, query);
 if (!names.length) { console.error(`no symbol matching "${query}"`); process.exit(1); }
 
-// src= lives on the block header line in the doc; read each doc once, index by id.
-const docCache = new Map(); // doc -> Map(id -> src)
-const srcOf = (doc, id) => {
-  if (!docCache.has(doc)) {
-    const map = new Map();
-    try {
-      const text = readFileSync(join(dir, doc), "utf8");
-      // src= may be quoted or a bare token (path#Lx-y, no spaces).
-      const re = /\{#([A-Za-z0-9._-]+)\b[^}]*?\bsrc=(?:"([^"]+)"|([^\s}]+))/g;
-      let m;
-      while ((m = re.exec(text))) map.set(m[1], m[2] || m[3]);
-    } catch { /* doc unreadable — skip src */ }
-    docCache.set(doc, map);
-  }
-  return docCache.get(doc).get(id) || "";
-};
-
 let n = 0;
 for (const name of names) {
   for (const c of lookup[name]) {
-    const src = srcOf(c.doc, c.id);
+    const src = srcOf(dir, c.doc, c.id);
     process.stdout.write(`${name}\t${c.doc}#${c.id}${src ? `\t${src}` : ""}\n`);
     n++;
   }

package/codemap/mcp-server.mjs

@@ -1,24 +1,41 @@
 #!/usr/bin/env node
-// geml-code-graph MCP server — the thin consumption wrapper of DESIGN §8 (P2).
-// Three navigation tools over a built graph/ directory, each "give an
-// identifier, get readable text back" (the original proposal's 2.6):
-//   resolve_name   name -> candidate anchors (doc + block id)
-//   open_symbol    doc + id -> that symbol's block, verbatim
-//   get_backlinks  doc + id -> the symbol's backlink block (who calls it)
+// geml-code-graph MCP tools — the thin consumption wrapper of DESIGN §8 (P2).
+// Navigation over a built graph/ directory, each "give an identifier, get
+// readable text back" (the original proposal's 2.6). Every name mirrors its CLI
+// path — `geml codemap <sub>` -> `geml_codemap_<sub>` — so one vocabulary covers
+// both surfaces:
+//   geml_codemap_search     name or substring -> candidates (start here)
+//   geml_codemap_list       no arg -> modules; a module -> its symbols
+//   geml_codemap_node       doc + id -> that symbol's block, verbatim
+//   geml_codemap_callchain  doc + id -> several hops, either direction
 //
-// Zero dependencies: newline-delimited JSON-RPC 2.0 over stdio (the MCP stdio
-// transport). Register e.g.:
-//   claude mcp add geml-code-graph -e GEML_GRAPH_DIR=/abs/path/to/graph \
-//     -- geml codemap mcp
-// The graph dir comes from GEML_GRAPH_DIR or a per-call `graph_dir` argument.
+// The four cover reading the graph, not producing it: building and refreshing
+// stay CLI-only on purpose (both run indexers or recorded shell steps, which is
+// not something a model should trigger), and `codemap serve` renders HTML for a
+// human, which a model cannot consume. See DESIGN §8.
 //
-// The dispatch is exported (and the stdio wiring below is main-module guarded)
-// so the test suite can drive it in-process; the CLI dispatcher always runs
-// this file as a child's MAIN module, where nothing changes.
+// This file is a LIBRARY, not a server entry point. `geml codemap mcp` was
+// removed: `geml mcp --root <dir>` serves these three tools next to the
+// document tools, importing the TOOLS table below rather than duplicating it,
+// so a client registers one server instead of two.
+//
+//   claude mcp add geml -- geml mcp --root /abs/path/to/repo
+//
+// `graphDirOf` still honours GEML_GRAPH_DIR and a per-call `graph_dir`. Nothing
+// reaches those defaults through `geml mcp`, which resolves the directory
+// against its own --root before calling a tool — a client-chosen directory is
+// safe only on a process that cannot write, and that one can.
+//
+// Zero dependencies; the handlers speak newline-delimited JSON-RPC 2.0 (the MCP
+// stdio transport) and `handleLine` is exported so both `geml mcp` and the test
+// suite drive it in-process.
 import { readFileSync, existsSync, realpathSync } from "node:fs";
 import { join, resolve, dirname, sep } from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
-import { createInterface } from "node:readline";
+import { fileURLToPath } from "node:url";
+// Where the sources live is serve.mjs's rule (the recipe's `root`, else the
+// graph dir's parent). Imported, not restated: two copies would drift and the
+// source panel and this tool would disagree about which file a symbol is in.
+import { resolveSrcRoot } from "./serve.mjs";
 
 // blockSpans from the reference parser (its CLI entry is guarded, so importing
 // is side-effect free). Falls back with a clear error if the parser isn't built.
@@ -54,73 +71,315 @@ export const readBlock = (graphDir, doc, id) => {
   return splitLines(source).slice(span.start, span.end).join("");
 };
 
+// ---- CSV-table reading (profile §4) -----------------------------------------
+// Serves the edge tables — `#calls` is `from, to, kind, confidence`, `#called-by`
+// is `from, to, kind, site`, cells being `#id` (this document) or `doc.geml#id`
+// (a sibling) — and the index's `#modules`, which has the same shape: a fence
+// line, a header row, then data.
+const tableRows = (graphDir, doc, tableId) => {
+  let raw;
+  try { raw = readBlock(graphDir, doc, tableId); } catch { return []; }
+  // readBlock returns the whole block: fence line, header row, data, close.
+  return raw.split("\n").slice(2)
+    .filter((l) => l.trim() && !l.trimStart().startsWith("==="))
+    .map((l) => l.split(",").map((c) => c.trim()));
+};
+
+// A from/to cell as a target, or null when it is plain text (an `#unresolved`
+// target or a `file:line` site — profile §4 says those are unchecked).
+const refTarget = (cell, fromDoc) => {
+  const m = /^([^#]*)#(.+)$/.exec(cell ?? "");
+  return m ? { doc: m[1] || fromDoc, id: m[2] } : null;
+};
+
+// One hop. `callees` reads this document's out-edges; `callers` reads the
+// in-edge table, which the generator aggregates per document, so both
+// directions are a single read of the symbol's OWN document.
+const neighbours = (graphDir, doc, id, direction) => {
+  const table = direction === "callers" ? "called-by" : "calls";
+  const [self, other] = direction === "callers" ? [1, 0] : [0, 1];
+  const want = `#${id.replace(/^#/, "")}`;
+  const out = [];
+  const seen = new Set();
+  for (const row of tableRows(graphDir, doc, table)) {
+    if (row[self] !== want) continue;
+    const t = refTarget(row[other], doc);
+    // A symbol called from three sites yields three identical rows; the caller
+    // wants the shape of the graph, not the call count.
+    if (!t) continue;
+    const key = `${t.doc}#${t.id}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push({ ...t, kind: row[2] || "call" });
+  }
+  return out;
+};
+
+// The symbol index: name -> [{ anchor, doc, id }].
+const loadLookup = (graphDir) => {
+  const lookupPath = join(graphDir, "_index/name-lookup.json");
+  if (!existsSync(lookupPath)) throw new Error(`no name-lookup at ${lookupPath} — build the graph first`);
+  return JSON.parse(readFileSync(lookupPath, "utf8"));
+};
+
+// ---- name search (shared with `geml codemap find`) --------------------------
+// One definition of "matches", so the CLI and the tool cannot answer the same
+// query differently: case-insensitive substring over the name index, sorted.
+// `exact` narrows to the whole name — the former `resolve_name`, now a flag,
+// because two tools differing only in strictness is two chances to pick wrong.
+export const searchNames = (graphDir, query, exact = false) => {
+  const lookup = loadLookup(graphDir);
+  if (exact) return { names: lookup[query] ? [query] : [], lookup };
+  const q = query.toLowerCase();
+  return { names: Object.keys(lookup).filter((n) => n.toLowerCase().includes(q)).sort(), lookup };
+};
+
+// The index's `#modules` table: module, doc, methods, entries, tests.
+const moduleRows = (graphDir) =>
+  tableRows(graphDir, "index.geml", "modules").filter((r) => r[0] && r[1]);
+
+// `src=` lives on the block header line; read each doc once and index by id.
+// The id charset excludes `.`, and src may be quoted or a bare token.
+const srcCache = new Map(); // `${graphDir}\0${doc}` -> Map(id -> src)
+export const srcOf = (graphDir, doc, id) => {
+  const key = `${graphDir}\0${doc}`;
+  if (!srcCache.has(key)) {
+    const map = new Map();
+    try {
+      const text = readFileSync(join(graphDir, doc), "utf8");
+      const re = /\{#([A-Za-z0-9._-]+)\b[^}]*?\bsrc=(?:"([^"]+)"|([^\s}]+))/g;
+      let m;
+      while ((m = re.exec(text))) map.set(m[1], m[2] || m[3]);
+    } catch { /* doc unreadable — a src is a nicety, not the answer */ }
+    srcCache.set(key, map);
+  }
+  return srcCache.get(key).get(id) || "";
+};
+
+// ---- reading the real source a `src=` pointer names -------------------------
+// Same two rules `codemap serve` uses for its source panel, imported rather
+// than restated: WHERE the sources are (the recipe's `root`, else the graph
+// dir's parent) and that a file is only served when it really sits under that
+// root, symlinks resolved. What differs is the slice — serve hands the browser
+// the whole file and lets the viewer highlight the range; a model wants the
+// symbol's own lines and nothing else.
+const MAX_SOURCE_LINES = 400;
+
+// `geml mcp` also confines every path to its own --root. The source root is
+// derived from `_index/refresh.json`, a file inside the graph — data, not
+// configuration this process chose — so a hand-edited `root: "../../.."` must
+// not reach outside the server's root. Unset (a bare library use) = no extra
+// bound beyond the source root itself.
+let SOURCE_BOUND = null;
+export const confineSourceTo = (dir) => { SOURCE_BOUND = dir ? realpathSync(dir) : null; };
+
+const underRoot = (real, root) => real === root || real.startsWith(root + sep);
+
+/** The `src=` attribute of a block header: `path` or `path#Lstart-end`. */
+const srcPointer = (block) => {
+  const m = /\bsrc=(?:"([^"]+)"|([^\s}]+))/.exec(block.split("\n", 1)[0] ?? "");
+  if (!m) return null;
+  const raw = m[1] || m[2];
+  const range = /^(.*?)#L(\d+)(?:-(\d+))?$/.exec(raw);
+  return range
+    ? { path: range[1], start: Number(range[2]), end: Number(range[3] ?? range[2]) }
+    : { path: raw, start: null, end: null };
+};
+
+export const readSource = (graphDir, block) => {
+  const ptr = srcPointer(block);
+  if (!ptr) return "(no `src=` on this block — nothing to read; edge tables and index blocks have no source)";
+  const srcRoot = resolveSrcRoot(graphDir);
+  let realRoot;
+  try { realRoot = realpathSync(srcRoot); } catch { return `(source root ${srcRoot} does not exist — the sources are not next to the graph on this machine)`; }
+  if (SOURCE_BOUND && !underRoot(realRoot, SOURCE_BOUND)) {
+    return `(refused: the graph's recorded source root ${srcRoot} is outside this server's --root)`;
+  }
+  let real;
+  try { real = realpathSync(resolve(realRoot, ptr.path)); } catch { return `(no such source file: ${ptr.path})`; }
+  if (!underRoot(real, realRoot) || (SOURCE_BOUND && !underRoot(real, SOURCE_BOUND))) {
+    return `(refused: ${ptr.path} resolves outside the source root)`;
+  }
+  let text;
+  try { text = readFileSync(real, "utf8"); } catch (e) { return `(cannot read ${ptr.path}: ${e.message})`; }
+  const all = text.split("\n");
+  const start = ptr.start ?? 1;
+  const end = Math.min(ptr.end ?? all.length, start + MAX_SOURCE_LINES - 1);
+  const slice = all.slice(start - 1, end);
+  if (!slice.length) return `(${ptr.path} has no lines ${start}-${end} — the graph is stale; rebuild with \`geml codemap build\`)`;
+  const cut = (ptr.end ?? all.length) > end ? `\n… truncated at ${MAX_SOURCE_LINES} lines` : "";
+  // Line numbers so a model can cite `file:line` without recounting.
+  const body = slice.map((l, i) => `${String(start + i).padStart(5)}  ${l}`).join("\n");
+  return `--- ${ptr.path}:${start}-${end} ---\n${body}${cut}`;
+};
+
 export const TOOLS = [
   {
-    name: "resolve_name",
-    description: "Find a function/class by name in the code graph. Returns candidate anchors with the document and block id to open. Multiple candidates = real ambiguity (overloads/same name) — inspect each, never assume.",
+    name: "geml_codemap_search",
+    description:
+      "Find symbols in the code graph BY NAME — case-insensitive substring by default, or the whole name with `exact: true` when you already know it. Returns `name  doc#id  src` per candidate, the same index the CLI's `geml codemap find` and the viewer's search box use, and `doc`+`id` are what geml_codemap_node and geml_codemap_callchain take. Start here on an unfamiliar codebase (or geml_codemap_list to browse by module). Several candidates for one name is real ambiguity — overloads, or the same name in two modules — so inspect each rather than assuming the first.",
     inputSchema: {
       type: "object",
       properties: {
-        name: { type: "string", description: "Exact symbol name (function/class short name)" },
+        query: { type: "string", description: "The symbol name, or a substring of it (e.g. `token` matches issueToken and TokenStore)" },
+        exact: { type: "boolean", description: "Match the WHOLE name instead of a substring (default false)" },
+        limit: { type: "number", description: "Maximum candidates to return (default 50). Narrow the query rather than raising this." },
         graph_dir: { type: "string", description: "Graph directory (default: $GEML_GRAPH_DIR or ./.geml-code-graph)" },
       },
-      required: ["name"],
+      required: ["query"],
     },
     run: (args) => {
-      const lookupPath = join(graphDirOf(args), "_index/name-lookup.json");
-      if (!existsSync(lookupPath)) throw new Error(`no name-lookup at ${lookupPath} — build the graph first`);
-      const lookup = JSON.parse(readFileSync(lookupPath, "utf8"));
-      const hits = lookup[args.name];
-      if (!hits?.length) return `no symbol named \`${args.name}\` in the graph`;
-      return JSON.stringify(hits, null, 1);
+      const graphDir = graphDirOf(args);
+      const query = String(args.query ?? "");
+      if (!query) throw new Error("`query` is required");
+      const exact = args.exact === true;
+      const { names, lookup } = searchNames(graphDir, query, exact);
+      if (!names.length) {
+        return exact
+          ? `no symbol named \`${query}\` in the graph — drop \`exact\` to match substrings`
+          : `no symbol matching "${query}" in the graph`;
+      }
+      const limit = Math.max(1, Math.min(Number(args.limit) || 50, 500));
+      const lines = [];
+      let total = 0;
+      for (const name of names) {
+        for (const c of lookup[name]) {
+          total++;
+          if (lines.length < limit) {
+            const src = srcOf(graphDir, c.doc, c.id);
+            lines.push(`${name}\t${c.doc}#${c.id}${src ? `\t${src}` : ""}`);
+          }
+        }
+      }
+      const tail = total > lines.length
+        ? `\n\n${lines.length} of ${total} match(es) shown — narrow the query.`
+        : `\n\n${total} match(es) across ${names.length} name(s).`;
+      return lines.join("\n") + tail;
     },
   },
   {
-    name: "open_symbol",
-    description: "Open ONE symbol's block from the code graph (its callees as checked references, confidence annotations, called-by pointer). Equivalent to following a link. Get doc+id from resolve_name.",
+    name: "geml_codemap_callchain",
+    description:
+      "Walk the call graph SEVERAL hops from one symbol and get the whole chain back as an indented tree — `direction: callees` for what it calls (downstream, for tracing a behaviour), `callers` for what reaches it (upstream, the impact path). Use this instead of opening one symbol per level: one call replaces N round trips and returns only the edges, not each symbol's full block. `depth: 1` with `callers` answers \"who calls this\" alone. A repeated symbol is marked and not expanded twice, so recursion terminates. Call SITES (file:line) are not in the tree — read the `#called-by` table with geml_codemap_node(doc, \"#called-by\") for those.",
     inputSchema: {
       type: "object",
       properties: {
-        doc: { type: "string", description: "Document path relative to the codemap dir, e.g. hashtable.c.geml" },
-        id: { type: "string", description: "Block id, e.g. hashtableFind (or #calls / #called-by for the edge tables)" },
+        doc: { type: "string", description: "The symbol's document path, e.g. hashtable.c.geml" },
+        id: { type: "string", description: "The symbol's block id, e.g. hashtableFind" },
+        direction: { type: "string", enum: ["callees", "callers"], description: "`callees` = what this calls (default); `callers` = what calls this" },
+        depth: { type: "number", description: "How many hops to follow (default 3, max 6)" },
         graph_dir: { type: "string", description: "Graph directory (default: $GEML_GRAPH_DIR or ./.geml-code-graph)" },
       },
       required: ["doc", "id"],
     },
-    run: (args) => readBlock(graphDirOf(args), args.doc, args.id),
+    run: (args) => {
+      const graphDir = graphDirOf(args);
+      const direction = args.direction === "callers" ? "callers" : "callees";
+      const depth = Math.max(1, Math.min(Number(args.depth) || 3, 6));
+      const rootId = String(args.id ?? "").replace(/^#/, "");
+      if (!args.doc || !rootId) throw new Error("`doc` and `id` are required");
+      // Prove the symbol exists before reporting an empty chain: "no edges" and
+      // "no such symbol" are different answers and a model must not conflate them.
+      readBlock(graphDir, args.doc, rootId);
+
+      const MAX_NODES = 200;
+      const lines = [];
+      const expanded = new Set();
+      let truncated = false;
+
+      // EVERY line carries the full `doc.geml#id`, including same-document
+      // targets that profile §4 would abbreviate to `#id`. The reader here is
+      // an agent, and each line has to be usable as-is for the next
+      // `open_symbol`/`trace_calls` call. A bare id would make it infer the
+      // document from the line's ancestors — cheaper output, one more thing to
+      // get wrong.
+      const walk = (doc, id, level, prefix, last) => {
+        const key = `${doc}#${id}`;
+        const label = level === 0 ? `${key}` : `${prefix}${last ? "└─ " : "├─ "}${key}`;
+        if (lines.length >= MAX_NODES) { truncated = true; return; }
+        if (expanded.has(key)) { lines.push(`${label}  (already shown)`); return; }
+        lines.push(label);
+        expanded.add(key);
+        if (level >= depth) {
+          // Say whether the cut hides anything, so a model knows to go deeper.
+          if (neighbours(graphDir, doc, id, direction).length) lines.push(`${prefix}${last ? "   " : "│  "}   … (depth limit)`);
+          return;
+        }
+        const next = neighbours(graphDir, doc, id, direction);
+        const childPrefix = level === 0 ? "" : prefix + (last ? "   " : "│  ");
+        next.forEach((n, i) => walk(n.doc, n.id, level + 1, childPrefix, i === next.length - 1));
+      };
+      walk(args.doc, rootId, 0, "", true);
+
+      const noun = direction === "callers" ? "callers" : "callees";
+      if (lines.length === 1) {
+        return `${lines[0]}\n\nno resolved ${noun} — under heuristic extraction that is a blind spot, not proof of none (see the #unresolved table).`;
+      }
+      return lines.join("\n") +
+        `\n\n${direction}, depth ${depth}${truncated ? `, truncated at ${MAX_NODES} nodes` : ""}. ` +
+        "Resolved edges only: `#unresolved` holds the blind spots.";
+    },
   },
   {
-    name: "get_backlinks",
-    description: "Who calls this symbol: opens its backlink block (callers with file:line sites, each a followable reference). Absence means no RESOLVED callers — never proof of none.",
+    name: "geml_codemap_list",
+    description:
+      "Browse the graph by MODULE. Called with no argument it lists every module with its document and symbol count — the map to open first on an unfamiliar repo, before you know any name to search for. Called with a `module` it lists that module's symbols as `name  doc#id  src`, ready to hand to geml_codemap_node or geml_codemap_callchain. Accepts a module name or its document path.",
     inputSchema: {
       type: "object",
       properties: {
-        doc: { type: "string", description: "The symbol's document path, e.g. hashtable.c.geml" },
-        id: { type: "string", description: "The symbol's block id (e.g. hashtableFind); omit to get the whole #called-by table" },
-        graph_dir: { type: "string", description: "Codemap directory (default: $GEML_GRAPH_DIR or ./.geml-code-graph)" },
+        module: { type: "string", description: "Module name (e.g. geml-parser) or its document (geml-parser.geml). Omit to list every module." },
+        graph_dir: { type: "string", description: "Graph directory (default: $GEML_GRAPH_DIR or ./.geml-code-graph)" },
       },
-      required: ["doc"],
     },
     run: (args) => {
-      // codemap profile: in-edges live in the SAME document's #called-by table.
-      let table;
-      try {
-        table = readBlock(graphDirOf(args), args.doc, "called-by");
-      } catch {
-        return `no #called-by table in ${args.doc} — no resolved callers recorded (under heuristic extraction this is a blind spot, not proof of none)`;
+      const graphDir = graphDirOf(args);
+      const rows = moduleRows(graphDir);
+      if (!rows.length) throw new Error(`no #modules table in index.geml (graph dir: ${graphDir}) — build the graph first`);
+      const want = String(args.module ?? "").trim();
+      if (!want) {
+        return rows.map((r) => `${r[0]}\t${r[1]}\t${r[2] || 0} symbol(s)`).join("\n") +
+          `\n\n${rows.length} module(s). Pass one as \`module\` to list its symbols.`;
       }
-      if (!args.id) return table;
-      const id = args.id.replace(/^#/, "");
-      // `id` is client-supplied and goes straight into a RegExp: escape every
-      // regex metacharacter so it matches LITERALLY (an id like `.*` or a
-      // catastrophic-backtracking pattern can neither widen the match nor cause
-      // ReDoS — the pattern is a fixed string wrapped in `,\s*#…\s*,`).
-      const escId = id.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-      const re = new RegExp(`,\\s*#${escId}\\s*,`);
-      const lines = table.split("\n");
-      const hits = lines.filter((l, i) => i < 2 || re.test(l));
-      return hits.length > 2 ? hits.join("\n")
-        : `no resolved callers of #${id} in ${args.doc} (blind spots live in the #unresolved table)`;
+      const row = rows.find((r) => r[0] === want || r[1] === want);
+      if (!row) return `no module \`${want}\` in the graph — call this tool with no argument to list them`;
+      const doc = row[1];
+      // The name index is the symbol list: filtering it by document skips the
+      // per-document edge tables (#calls / #called-by) a raw id listing returns.
+      const lookup = loadLookup(graphDir);
+      const lines = [];
+      for (const [name, cands] of Object.entries(lookup)) {
+        for (const c of cands) {
+          if (c.doc !== doc) continue;
+          const src = srcOf(graphDir, doc, c.id);
+          lines.push(`${name}\t${doc}#${c.id}${src ? `\t${src}` : ""}`);
+        }
+      }
+      // Name the module CANONICALLY (its #modules name), not however the caller
+      // addressed it, so `auth` and `auth.geml` return byte-identical answers.
+      if (!lines.length) return `module \`${row[0]}\` (${doc}) has no symbols in the name index`;
+      lines.sort();
+      return lines.join("\n") + `\n\n${lines.length} symbol(s) in ${row[0]}.`;
+    },
+  },
+  {
+    name: "geml_codemap_node",
+    description:
+      "Open ONE node of the graph verbatim: a symbol's block (its `src=` pointer into the real file, confidence annotations), or a document's edge table — pass `#calls` / `#called-by` / `#unresolved` as the id for those. `#called-by` is where call SITES (file:line) live. Pass `source: true` to also read the REAL SOURCE the `src=` pointer names — the symbol's own lines, the same text the local viewer shows in its source panel — so you do not have to open the file yourself. Get `doc` and `id` from geml_codemap_search or geml_codemap_list.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        doc: { type: "string", description: "Document path relative to the graph dir, e.g. hashtable.c.geml" },
+        id: { type: "string", description: "Block id, e.g. hashtableFind (or #calls / #called-by / #unresolved for the edge tables)" },
+        source: { type: "boolean", description: "Also return the real source lines that `src=` points at (default false). Off by default because a node is often opened in a loop, where the pointer is enough." },
+        graph_dir: { type: "string", description: "Graph directory (default: $GEML_GRAPH_DIR or ./.geml-code-graph)" },
+      },
+      required: ["doc", "id"],
+    },
+    run: (args) => {
+      const graphDir = graphDirOf(args);
+      const block = readBlock(graphDir, args.doc, args.id);
+      if (args.source !== true) return block;
+      return `${block}\n${readSource(graphDir, block)}`;
     },
   },
 ];
@@ -165,8 +424,8 @@ export function handleLine(line, write = (s) => process.stdout.write(s)) {
   }
 }
 
-// Auto-run only as a MAIN module (the CLI dispatcher spawns this file as a
-// child's entry script) — an in-process `import` stays inert.
-if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
-  createInterface({ input: process.stdin }).on("line", (line) => handleLine(line));
-}
+// No main-module block: this file no longer starts a server. Running it
+// directly used to serve the three tools on stdio, and leaving that in would
+// keep the removed entry point alive as a back door — `node codemap/
+// mcp-server.mjs` reachable from any client config. `geml mcp` owns the
+// transport now.

package/dist/geml.js

@@ -598,7 +598,10 @@ function sectionEnd(lines, i, level) {
 // First definition wins, mirroring ctx.ids (a duplicate id is a build error, so
 // `get`/`set` operate on the one the parser actually registered). `base` is the
 // absolute line offset of this slice within the whole document.
-function collectSpans(lines, base, out, ctx, depth = 0) {
+function collectSpans(lines, base, out, ctx, depth = 0, 
+// Optional second index: every typed block by TYPE, id-bearing or not, so a
+// block the author never named is still addressable (`=== meta`).
+types) {
     const add = (id, start, end) => {
         if (!out.has(id))
             out.set(id, { start, end });
@@ -627,11 +630,16 @@ function collectSpans(lines, base, out, ctx, depth = 0) {
             const { end, closed } = fenceClose(lines, i, open);
             if (id !== undefined)
                 add(id, base + i, base + end);
+            if (types) {
+                const list = types.get(type) ?? [];
+                list.push({ span: { start: base + i, end: base + end }, id });
+                types.set(type, list);
+            }
             // Only a flow body is scanned for nested blocks (raw/data bodies are
             // opaque), so an id inside a `code` body is *not* addressable — exactly
             // the parser's contract.
             if ((REGISTRY[type] ?? "raw") === "flow" && depth < MAX_NESTING) {
-                collectSpans(lines.slice(i + 1, closed ? end - 1 : end), base + i + 1, out, ctx, depth + 1);
+                collectSpans(lines.slice(i + 1, closed ? end - 1 : end), base + i + 1, out, ctx, depth + 1, types);
             }
             i = end;
             continue;
@@ -660,6 +668,13 @@ export function blockSpans(source) {
     collectSpans(lines, 0, out, ctx);
     return out;
 }
+function blockTypeSpans(source) {
+    const lines = normalizeSource(source).split("\n");
+    const ctx = { diags: [], ids: new Map(), refs: [], meta: collectMeta(lines) };
+    const types = new Map();
+    collectSpans(lines, 0, new Map(), ctx, 0, types);
+    return types;
+}
 // Split into physical lines while *keeping* each line's terminator, so
 // join("") is byte-exact and slicing by span never rewrites line endings.
 // A line ends at `\n` or at a LONE `\r` (old-Mac style) — the same boundaries
@@ -809,10 +824,11 @@ Usage:
   geml check  <file.geml|-> [--root d] [--json]   validate only: diagnostics + exit code
                                              (--root widens cross-doc refs to dir d, e.g. the repo root)
   geml history <commit|verify|show|restore|log> <file.geml> [...]   .gemlhistory version sidecar
-  geml codemap <build|verify|render|serve|refresh|find|mcp> [...]   code-graph toolkit (alias: codegraph)
-  geml mcp    --root <dir> [--no-history]        serve document CRUD over MCP (stdio)
+  geml codemap <build|verify|render|serve|refresh|find> [...]       code-graph toolkit (alias: codegraph)
+  geml mcp    --root <dir> [--graph <dir>] [--no-history]   serve documents (and the code graph) over MCP (stdio)
                                              (9 tools: list/read/check/history + write/add/delete/rename/revert;
-                                              every write is validated before it reaches disk)
+                                              every write is validated before it reaches disk. A code graph under
+                                              --root adds resolve_name/open_symbol/get_backlinks to the same server)
   geml --help | --version [--json]
 
 Use '-' as the file to read from stdin.
@@ -826,7 +842,7 @@ Exit codes:
 // One-line usage for each subcommand — the single source for both the error
 // shown on misuse and the `<cmd> --help` text.
 const SUBHELP = {
-    get: "usage: geml get <file.geml|-> [#id] [--json] [--head]  (with #id: that block, a heading id = its whole section, --head = its head line; without #id: list every addressable id, --json = array)",
+    get: "usage: geml get <file.geml|-> [#id | '## Heading' | '=== type'] [--json] [--head]  (selector: an #id, or a LINE copied from the document — a heading `## Title` addresses its whole section, a fence `=== meta` addresses that block by type and lists the candidates when several match; --head = the head line; without a selector: list every addressable id, --json = array)",
     set: "usage: geml set <file.geml|-> #id [--head|--body] [--in F | --in F#src | --in -] [-o out.geml]  (content: --in F takes F's block #id, --in F#src takes #src, else stdin raw; default = whole block, --head = head line — both normalize the id to #id — --body = body; guarded splice, refused if it breaks the doc)",
     add: "usage: geml add <file.geml|-> (--append | --before #id | --after #id) [--in F | --in F#src | --in -] [-o out.geml]  (insert a GEML fragment — 1+ blocks and/or prose — at a position; --in F takes all of F, --in F#src takes #src, else stdin raw; content keeps its own ids, a collision is refused)",
     delete: "usage: geml delete <file.geml|-> #id [#id2 …] [-o out.geml]  (remove one or more blocks; a missing id is skipped with a note, not an error; a reference left dangling is a warning, not a refusal — delete never fails on a live reference)",
@@ -841,23 +857,27 @@ const SUBHELP = {
        geml codemap serve  [dir] [--port 8140] [--watch] [--background|--stop]   live viewer: pages render from .geml on request; --watch re-runs the recipe when sources change
        geml codemap refresh [dir] [--force] [--commit] [--background|--hook]   re-run the recorded build recipe (_index/refresh.json); --commit lands it as its own commit
        geml codemap find <name> [dir]            locate a symbol by substring name -> doc#id + src (stdout, no browser)
-       geml codemap mcp                          stdio MCP server (GEML_GRAPH_DIR or graph_dir arg)
        (<dir> for verify/render/serve/refresh/find defaults to ./.geml-code-graph; codegraph and code-graph are accepted as aliases of codemap)`,
-    mcp: `usage: geml mcp --root <dir> [--no-history]
+    mcp: `usage: geml mcp --root <dir> [--graph <dir>] [--no-history]
 
   Serve GEML document CRUD over the MCP stdio transport (JSON-RPC 2.0).
   Nine tools: geml_list_ids · geml_read_block · geml_check · geml_history_log
               geml_write_block · geml_add_block · geml_delete_block
               geml_rename_id · geml_revert_block
+  With a code graph under --root, three more (read-only), so one client entry
+  covers both: resolve_name · open_symbol · get_backlinks
 
   --root <dir>        REQUIRED. Root holding the .geml documents. Every path a
                       client names is confined here; a client cannot widen it.
+  --graph <dir>       Code-graph directory, inside --root. Defaults to
+                      <root>/.geml-code-graph when it holds an index.geml; with
+                      no graph the three graph tools are not served at all.
   --no-history        Skip the .gemlhistory commit taken before each write
                       (default: commit, so geml_revert_block always has a
                       revision to undo to).
 
   Register with a client:
-    claude mcp add geml -- geml mcp --root /abs/path/to/docs`,
+    claude mcp add geml -- geml mcp --root /abs/path/to/repo`,
 };
 // Set from argv at dispatch time; when true, errors are emitted as a JSON
 // envelope so an agent that standardizes on --json never has to parse text.
@@ -1236,6 +1256,72 @@ function positionals(args, valued) {
     }
     return out;
 }
+// Resolve a block SELECTOR to an id. Three spellings address the same block:
+//
+//   `#intro` / `intro`        the id — the CANONICAL address
+//   `## Getting Started`      the heading LINE, copied out of the document
+//   `##Getting Started`       …the space after the `#` run is optional
+//
+// Why more than one form: the id is what `[[#id]]` references, codemap tables
+// and URL fragments (§0.6) all carry, so it must stay accepted verbatim — an id
+// copied out of a reference or out of `geml get <file>` has to work. But a
+// heading's id is AUTO-DERIVED from its text (`## API 设计 (v1)` → `#api-设计-v1`),
+// and nobody can be expected to hand-derive that slug for a heading they can
+// read on screen. So the heading line itself is accepted too.
+//
+// Resolution order, first match wins:
+//   1. the id, exactly — a pasted id is NEVER reinterpreted as prose. (When a
+//      heading's TEXT happens to equal another block's ID, the id wins.)
+//   2. the exact heading LINE: `#` count AND text both match.
+//   3. the text alone, at any level — a heading remembered at the wrong depth
+//      still resolves while its text is unique.
+//   4. text shared by several headings: the `#` count picks one, or the
+//      candidates are listed. Never guessed at.
+function resolveSelector(source, file, raw) {
+    const bare = raw.replace(/^#/, "");
+    const m = /^(#{1,6})[ \t]*(.+?)[ \t]*$/.exec(raw);
+    if (!m)
+        return bare; // not a `#`-run form: an id, verbatim
+    // 1. The id is canonical and always wins. Checked without a parse, so the
+    //    common `get #id` stays a byte-slice on a document with diagnostics.
+    if (blockSpans(source).has(bare))
+        return bare;
+    const level = m[1].length;
+    const want = m[2];
+    const doc = parse(source, { resolveDoc: resolverFor(file) });
+    const heads = doc.ids.flatMap((id) => {
+        const site = findBlockSite(doc.children, id);
+        const b = site?.siblings[site.index];
+        return b?.kind === "heading" ? [{ id, level: b.level, text: b.text.trim() }] : [];
+    });
+    // 2. exact line — what the caller actually typed.
+    const line = heads.find((h) => h.level === level && h.text === want);
+    if (line)
+        return line.id;
+    // 3. the text alone (exact, then case-insensitive).
+    let byText = heads.filter((h) => h.text === want);
+    if (!byText.length) {
+        const lc = want.toLocaleLowerCase();
+        byText = heads.filter((h) => h.text.toLocaleLowerCase() === lc);
+    }
+    if (byText.length === 1)
+        return byText[0].id;
+    // 4. shared text: the level disambiguates, else show the candidates.
+    if (byText.length > 1) {
+        const atLevel = byText.filter((h) => h.level === level);
+        if (atLevel.length === 1)
+            return atLevel[0].id;
+        const list = byText.map((h) => `  #${h.id}  (h${h.level})`).join("\n");
+        fail(`\`${want}\` matches ${byText.length} headings — address one by its id:\n${list}`, 1);
+    }
+    // Nothing matched. A lone `#` with no whitespace was almost certainly meant as
+    // an id, so hand it back and let the caller's own `no block with id` error
+    // stand — the precise diagnosis for a typo'd id. Only a heading-SHAPED
+    // selector gets the heading-flavoured message.
+    if (level === 1 && !/\s/.test(bare))
+        return bare;
+    fail(`no id or heading matches \`${raw}\` — run \`geml get ${file === "-" ? "-" : file}\` to list every addressable id`, 1);
+}
 // `geml get <file>` with no id: list every addressable id — the document's
 // table of contents. Default output is one id per line with its kind (and, for
 // a heading, its level and text); `--json` is a machine-readable array so an
@@ -1285,6 +1371,61 @@ function listIds(source, file, json) {
 // content: a block/footnote id prints its document-model node; a heading id
 // prints a section envelope `{kind:"section", id, level, blocks:[heading,
 // …siblings up to the boundary]}`.
+// `geml get <file> '=== <type>'` — address a block by its TYPE. One match is
+// the block itself; several are LISTED with their line ranges rather than
+// guessed between, so a document with three notes answers "which one" instead
+// of failing. The uniqueness that makes `=== meta` work is checked here, at
+// resolve time — nothing in the format has to promise a document holds only one.
+function getByType(source, file, type, json, headOnly) {
+    const where = file === "-" ? "stdin" : file;
+    const matches = blockTypeSpans(source).get(type) ?? [];
+    if (!matches.length) {
+        fail(`no \`${type}\` block in ${where} — run \`geml get ${where}\` to list every addressable id`, 1);
+    }
+    if (matches.length === 1) {
+        const m = matches[0];
+        if (json) {
+            // The ONLY block of its type: locating it in the model needs no index, so
+            // --json can still answer with the parsed node (meta's key/values, a
+            // table's model) rather than a mere location.
+            const node = onlyBlockOfType(parse(source, { resolveDoc: resolverFor(file) }).children, type);
+            if (node) {
+                console.log(JSON.stringify(node, null, 2));
+                return;
+            }
+        }
+        const span = headOnly ? narrowToHead(m.span) : m.span;
+        process.stdout.write(splitLines(source).slice(span.start, span.end).join(""));
+        return;
+    }
+    // Several: report WHERE they are (data on stdout, the explanation on stderr),
+    // so the caller can name one — by adding an #id, or via its section.
+    if (json) {
+        console.log(JSON.stringify({ kind: "blocks", type, matches: matches.map((m) => ({ ...(m.id ? { id: m.id } : {}), lines: [m.span.start + 1, m.span.end] })) }, null, 2));
+        return;
+    }
+    console.error(`${matches.length} \`${type}\` blocks in ${where} — give one an #id, or address its section:`);
+    for (const m of matches) {
+        console.log(`=== ${type}${m.id ? ` {#${m.id}}` : ""}  L${m.span.start + 1}-${m.span.end}`);
+    }
+}
+// The single block of `type` in a document, or undefined when there is not
+// exactly one (nested flow children included, matching the span scan's reach).
+function onlyBlockOfType(blocks, type) {
+    const hits = [];
+    const walk = (list) => {
+        for (const b of list) {
+            if (b.kind === "block") {
+                if (b.type === type)
+                    hits.push(b);
+                if (b.children)
+                    walk(b.children);
+            }
+        }
+    };
+    walk(blocks);
+    return hits.length === 1 ? hits[0] : undefined;
+}
 function runGet(args) {
     const json = args.includes("--json");
     const headOnly = args.includes("--head");
@@ -1293,12 +1434,23 @@ function runGet(args) {
         fail(SUBHELP.get);
     // No id: list every addressable id — the document's "table of contents", so
     // an agent can discover what `get #id` can target without pulling the model.
+    // One read: stdin can only be consumed once, and the selector resolver needs
+    // the same bytes the slice below works on.
+    const source = readInput(file);
     if (!rawId) {
-        listIds(readInput(file), file, json);
+        listIds(source, file, json);
         return;
     }
-    const id = rawId.replace(/^#/, "");
-    const source = readInput(file);
+    // A FENCE line as the selector (`=== meta`): the same "copy the line out of
+    // the document" move as a heading line, for the blocks that carry no id.
+    // A pasted fence that DOES declare an id defers to the id path below.
+    const fence = /^={3,}[ \t]*([A-Za-z][A-Za-z0-9_-]*)[ \t]*(\{.*\})?[ \t]*$/.exec(rawId.trim());
+    const fenceId = fence?.[2] ? parseAttrs(fence[2]).id : undefined;
+    if (fence && fenceId === undefined) {
+        getByType(source, file, fence[1], json, headOnly);
+        return;
+    }
+    const id = fenceId ?? resolveSelector(source, file, rawId);
     if (json) {
         // The model node(s) — same shapes `geml <file>` emits. Parsing is needed
         // to resolve the tree (and nested-block ids), but only the target prints.
@@ -2017,9 +2169,15 @@ function runCodemap(args) {
         serve: "serve.mjs",
         refresh: "refresh.mjs",
         find: "find.mjs",
-        mcp: "mcp-server.mjs",
     };
     const sub = args[0] ?? "";
+    // `codemap mcp` was a second stdio server over the same repository. It is
+    // gone, not renamed, so name the replacement instead of letting it fall into
+    // `unknown codemap subcommand`: this string is what an operator sees in a
+    // client's server log when the entry they registered stops starting.
+    if (sub === "mcp") {
+        fail("geml codemap mcp was removed: use `geml mcp --root <dir>`, which serves the three code-graph tools alongside the document tools (graph: <root>/.geml-code-graph, or --graph <dir>).");
+    }
     const script = scripts[sub];
     if (!script)
         fail(`unknown codemap subcommand '${sub}'.\n${SUBHELP.codemap}`);
@@ -2027,10 +2185,11 @@ function runCodemap(args) {
     const r = spawnSync(process.execPath, [mod, ...args.slice(1)], { stdio: "inherit" });
     process.exit(r.status ?? 1);
 }
-// geml mcp: the document-CRUD MCP server. Runs as a child's MAIN module for the
-// same reason `codemap mcp` does — it owns stdin/stdout for the whole session
-// (the stdio transport), and dispatching by spawn keeps this module free of a
-// runtime import cycle (mcp.js imports the parser from here).
+// geml mcp: the MCP server — document CRUD, plus the code-graph tools when the
+// root holds a graph. It runs as a child's MAIN module because it owns
+// stdin/stdout for the whole session (the stdio transport), and dispatching by
+// spawn keeps this module free of a runtime import cycle (mcp.js imports the
+// parser from here).
 function runMcp(args) {
     const mod = join(dirname(fileURLToPath(import.meta.url)), "mcp.js");
     const r = spawnSync(process.execPath, [mod, ...args], { stdio: "inherit" });

package/dist/mcp.d.ts

@@ -2,6 +2,7 @@
 export interface McpOptions {
     root: string;
     history: boolean;
+    graph?: string;
 }
 /** Configure the server. Exported so the suite can point it at a temp dir. */
 export declare function configure(o: Partial<McpOptions>): McpOptions;
@@ -13,6 +14,13 @@ export interface Tool {
     run: (args: Record<string, any>) => unknown;
 }
 export declare const TOOLS: Tool[];
+/** Tools served right now: the ten document tools, plus the graph tools when a graph is configured. */
+export declare function allTools(): Tool[];
+/**
+ * Load and confine the code-graph tools. Idempotent; awaited at startup and by
+ * the suite, which drives `handleLine` in-process.
+ */
+export declare function loadGraphTools(): Promise<Tool[]>;
 export declare function handleLine(line: string, write?: (s: string) => void): void;
-export declare const MCP_USAGE = "usage: geml mcp --root <dir> [--no-history]\n\n  Serve GEML document CRUD over the MCP stdio transport (JSON-RPC 2.0).\n\n  --root <dir>        REQUIRED. Root directory holding the .geml documents.\n                      Relative paths resolve against the server process's CWD,\n                      which the CLIENT chooses \u2014 pass an absolute path.\n                      Every path a client names is confined to this directory;\n                      a client cannot widen or override it.\n  --no-history        Do not auto-commit a .gemlhistory revision before each\n                      write. Default is to commit, so geml_revert_block always\n                      has a revision to undo to.\n\n  Register with a client:\n    claude mcp add geml -- geml mcp --root /abs/path/to/docs";
+export declare const MCP_USAGE = "usage: geml mcp --root <dir> [--graph <dir>] [--no-history]\n\n  Serve GEML document CRUD over the MCP stdio transport (JSON-RPC 2.0), plus the\n  read-only code-graph tools when the root holds a code graph.\n\n  --root <dir>        REQUIRED. Root directory holding the .geml documents.\n                      Relative paths resolve against the server process's CWD,\n                      which the CLIENT chooses \u2014 pass an absolute path.\n                      Every path a client names is confined to this directory;\n                      a client cannot widen or override it.\n  --graph <dir>       Code-graph directory, inside --root. Defaults to\n                      <root>/.geml-code-graph when that holds an index.geml.\n                      With no graph, the code-graph tools are not served\n                      at all (a client sees only the document tools).\n  --no-history        Do not auto-commit a .gemlhistory revision before each\n                      write. Default is to commit, so geml_revert always\n                      has a revision to undo to.\n\n  Register with a client:\n    claude mcp add geml -- geml mcp --root /abs/path/to/repo";
 export declare function parseArgs(args: string[]): McpOptions;

package/dist/mcp.js

@@ -1,13 +1,17 @@
 #!/usr/bin/env node
-// `geml mcp` — MCP server for GEML document CRUD.
+// `geml mcp` — MCP server for GEML documents and the code graph.
 //
-// Nine tools over a confined root directory of `.geml` documents: four read-only,
-// five that write. It is the document-editing counterpart to the read-only
-// code-graph server in `codemap/mcp-server.mjs`, and deliberately mirrors its
-// shape (newline-delimited JSON-RPC 2.0 over stdio, zero dependencies, an
-// exported `handleLine` so the suite can drive it in-process).
+// Ten tools over a confined root directory of `.geml` documents: five read-only,
+// five that write, each named after the CLI verb it wraps (`geml set` ->
+// `geml_set`, the bare transform entry -> `geml_to`). When that root holds a code graph, the four read-only
+// code-graph tools from `codemap/mcp-server.mjs` are served from this SAME
+// process, so a client registers one server instead of two. That file stays a
+// standalone `geml codemap mcp` entry point; this one imports its tool table
+// rather than copying it, which is cheap because the two were deliberately
+// built to the same shape (newline-delimited JSON-RPC 2.0 over stdio, zero
+// dependencies, an exported `handleLine` so the suite can drive it in-process).
 //
-//   claude mcp add geml -- geml mcp --root /abs/path/to/docs
+//   claude mcp add geml -- geml mcp --root /abs/path/to/repo
 //
 // Three invariants make this worth more than letting a model `str_replace` the
 // file itself:
@@ -17,11 +21,16 @@
 //      is only overwritten when the result is clean. A bad generation is
 //      refused with the diagnostics that refused it — it does not land and
 //      then wait for a human to notice.
-//   2. EVERY WRITE IS PRECEDED BY A HISTORY COMMIT, so `geml_revert_block` can
+//   2. EVERY WRITE IS PRECEDED BY A HISTORY COMMIT, so `geml_revert` can
 //      always undo the block that was just touched. Without this the strongest
 //      tool in the set would have nothing to revert to.
 //   3. EVERY PATH IS CONFINED to a server-side `--root` directory the client
-//      cannot override or widen.
+//      cannot override or widen. This is where the two servers disagreed, and
+//      merging had to pick one: standalone `codemap mcp` lets the client name
+//      `graph_dir` per call (it is pointed AT a graph and only reads). Here the
+//      same process can write, so a client-named directory is narrowed to the
+//      server root like every other path — a read-anywhere argument does not
+//      belong on a server that also writes.
 //
 // The mutations run through the CLI rather than re-implementing block editing:
 // the tool table is *defined* as CLI equivalences, and `-o -` already yields
@@ -74,24 +83,40 @@ export function resolveInRoot(file) {
         throw new Error(`not a file: ${file}`);
     return real;
 }
-// Cross-document references resolve against the SERVER root, never against
-// a client-named directory: `root` may only NARROW to a directory inside it.
-function resolveRoot(root) {
+// A client-named directory may only NARROW to one inside the server root — it
+// can never widen or escape it. `label` names the argument in the error so the
+// model can tell which of its arguments was refused.
+function narrowToRoot(dir, label) {
     const serverRoot = realpathSync(OPTS.root);
-    if (root === undefined || root === "")
-        return serverRoot;
-    const target = resolve(serverRoot, root);
+    const target = resolve(serverRoot, dir);
     let real;
     try {
         real = realpathSync(target);
     }
     catch {
-        throw new Error(`no such directory under the server root: ${root}`);
+        throw new Error(`no such directory under the server root: ${dir}`);
     }
     if (real !== serverRoot && !real.startsWith(serverRoot + sep))
-        throw new Error(`root escapes the server root: ${root}`);
+        throw new Error(`${label} escapes the server root: ${dir}`);
     return real;
 }
+// Cross-document references resolve against the SERVER root, never against
+// a client-named directory.
+function resolveRoot(root) {
+    if (root === undefined || root === "")
+        return realpathSync(OPTS.root);
+    return narrowToRoot(root, "root");
+}
+// The code-graph directory for one call: the server's `--graph` unless the
+// client named one, and a client-named one is narrowed like any other path.
+function resolveGraphDir(graphDir) {
+    if (graphDir === undefined || graphDir === "") {
+        if (!OPTS.graph)
+            throw new Error("this server has no code graph; start it with --graph <dir> under --root");
+        return OPTS.graph;
+    }
+    return narrowToRoot(String(graphDir), "graph_dir");
+}
 // ---------------------------------------------------------------------------
 // Driving the CLI
 // ---------------------------------------------------------------------------
@@ -214,7 +239,7 @@ const FILE_ARG = { type: "string", description: "Document path relative to the s
 export const TOOLS = [
     // ----- read -----
     {
-        name: "geml_list_ids",
+        name: "geml_list",
         description: "List every addressable block in a GEML document: its `#id`, kind, and heading text. Call this FIRST — the ids it returns are what every other tool in this server addresses. Cheaper and more reliable than reading the file to find out what is in it.",
         inputSchema: { type: "object", properties: { file: FILE_ARG }, required: ["file"] },
         run: (args) => {
@@ -226,8 +251,8 @@ export const TOOLS = [
         },
     },
     {
-        name: "geml_read_block",
-        description: "Read ONE block from a GEML document by its `#id`. Use this instead of reading the whole file: it returns only that block, typically a few percent of the document. Get available ids from `geml_list_ids` first. Reading the whole file to change one block wastes context and risks modifying unrelated content.",
+        name: "geml_get",
+        description: "Read ONE block from a GEML document by its `#id`. Use this instead of reading the whole file: it returns only that block, typically a few percent of the document. Get available ids from `geml_list` first. Reading the whole file to change one block wastes context and risks modifying unrelated content.",
         inputSchema: {
             type: "object",
             properties: {
@@ -270,8 +295,8 @@ export const TOOLS = [
         },
     },
     {
-        name: "geml_history_log",
-        description: "List the recorded revisions of a document, newest first. Each entry's `offset` is the selector `geml_revert_block` takes as `rev` (-1 is the revision before the current one). Use this to find WHICH revision to revert a block to; an empty list means the document has no sidecar yet and nothing can be reverted.",
+        name: "geml_history",
+        description: "List the recorded revisions of a document, newest first. Each entry's `offset` is the selector `geml_revert` takes as `rev` (-1 is the revision before the current one). Use this to find WHICH revision to revert a block to; an empty list means the document has no sidecar yet and nothing can be reverted.",
         inputSchema: { type: "object", properties: { file: FILE_ARG }, required: ["file"] },
         run: (args) => {
             const real = resolveInRoot(args.file);
@@ -281,9 +306,54 @@ export const TOOLS = [
             return { file: args.file, revisions: listRevisions(historyPath) };
         },
     },
+    {
+        name: "geml_to",
+        description: "Convert a WHOLE document and get the result back as text — the read half of the CLI's `geml <file> --to <fmt>`. `to: \"geml\"` on a Markdown file is the importer, the one thing the block tools cannot do; `to: \"md\"` projects a GEML document out (lossy); `to: \"json\"` returns the full document model, for when geml_list plus geml_get is not enough. Nothing is written — pass the result to geml_add or geml_set to land it. `to: \"html\"` also works but returns a whole self-contained page, usually tens of kilobytes this server cannot save for you: prefer the CLI (`geml <file> --to html -o out.html`) unless you really want the markup in the conversation.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                file: FILE_ARG,
+                to: {
+                    type: "string",
+                    enum: ["json", "md", "geml", "html"],
+                    description: "Target format. Default is the CLI's: a GEML input becomes json, a Markdown input becomes geml. `html` is a whole page — large, and not writable from here.",
+                },
+                from: {
+                    type: "string",
+                    enum: ["geml", "md", "json"],
+                    description: "Override the input format, which is otherwise inferred from the extension (.md -> md, .json -> json, else geml).",
+                },
+            },
+            required: ["file"],
+        },
+        run: (args) => {
+            const real = resolveInRoot(args.file);
+            // Enforce the enums here too: a client is free to ignore the schema, and a
+            // typo'd format should come back as this server's clear error rather than
+            // whatever the CLI makes of it.
+            const to = args.to === undefined ? undefined : String(args.to);
+            const from = args.from === undefined ? undefined : String(args.from);
+            if (to !== undefined && !["json", "md", "geml", "html"].includes(to))
+                throw new Error(`unknown \`to\` format: ${to} (want json | md | geml | html)`);
+            if (from !== undefined && !["geml", "md", "json"].includes(from))
+                throw new Error(`unknown \`from\` format: ${from} (want geml | md | json)`);
+            const argv = [real];
+            if (to !== undefined)
+                argv.push("--to", to);
+            if (from !== undefined)
+                argv.push("--from", from);
+            const run = runCli(argv);
+            // The transform exits 1 on a document with errors but still prints the
+            // result; surface the diagnostics rather than the text in that case, so a
+            // model is never handed the output of a document it was told nothing about.
+            if (!run.ok)
+                throw new Error(run.stderr || `could not convert ${args.file}`);
+            return run.stdout;
+        },
+    },
     // ----- write -----
     {
-        name: "geml_write_block",
+        name: "geml_set",
         description: "Replace ONE block, addressed by `#id`, leaving every other byte of the document untouched. Prefer this over rewriting a file. The replacement is VALIDATED BEFORE it is written: if it would break the document, nothing is written and you get the diagnostics back — re-read them and fix the body rather than retrying the same content. `part` selects whole block (default), just the head/fence line, or just the body.",
         inputSchema: {
             type: "object",
@@ -310,7 +380,7 @@ export const TOOLS = [
         },
     },
     {
-        name: "geml_add_block",
+        name: "geml_add",
         description: "Insert new content — one or more blocks, or prose — at a chosen point. `position` is append (end of document), or before/after a block named by `anchor`. Ids inside the content are kept, and a clash with an existing id is refused. Validated before writing, like every write here.",
         inputSchema: {
             type: "object",
@@ -343,7 +413,7 @@ export const TOOLS = [
         },
     },
     {
-        name: "geml_delete_block",
+        name: "geml_delete",
         description: "Remove one or more blocks by id. References left pointing at a removed block are reported as diagnostics but do NOT block the deletion — read them and decide whether to repair or restore. A missing id is skipped, not an error.",
         inputSchema: {
             type: "object",
@@ -367,7 +437,7 @@ export const TOOLS = [
         },
     },
     {
-        name: "geml_rename_id",
+        name: "geml_rename",
         description: "Rename a block id AND every reference to it in the same document, in one id-boundary-safe operation. Use this instead of a text search-and-replace, which would also hit ids that merely share a prefix.",
         inputSchema: {
             type: "object",
@@ -388,8 +458,8 @@ export const TOOLS = [
         },
     },
     {
-        name: "geml_revert_block",
-        description: "Undo ONE block, leaving every other block byte-for-byte unchanged — recover a single block after a bad edit without losing the good edits around it. `rev` defaults to undoing this block's LAST change (its previous distinct version), which holds even when other blocks were edited afterwards; or pass `0` for the tip, a `-N` offset, or a revision id from `geml_history_log`. Reverting across a revision where the block was deleted restores it; across one where it did not exist removes it.",
+        name: "geml_revert",
+        description: "Undo ONE block, leaving every other block byte-for-byte unchanged — recover a single block after a bad edit without losing the good edits around it. `rev` defaults to undoing this block's LAST change (its previous distinct version), which holds even when other blocks were edited afterwards; or pass `0` for the tip, a `-N` offset, or a revision id from `geml_history`. Reverting across a revision where the block was deleted restores it; across one where it did not exist removes it.",
         inputSchema: {
             type: "object",
             properties: {
@@ -417,6 +487,68 @@ export const TOOLS = [
     },
 ];
 // ---------------------------------------------------------------------------
+// Code-graph tools, imported from the standalone server
+// ---------------------------------------------------------------------------
+// The four read-only code-graph tools, re-served here with this
+// server's confinement. Empty until `loadGraphTools()` runs — the import is
+// dynamic because `codemap/mcp-server.mjs` is a plain .mjs script that itself
+// top-level-awaits the parser, and because a server started without a graph
+// should not pay for loading it at all.
+let GRAPH_TOOLS = [];
+/** Tools served right now: the ten document tools, plus the graph tools when a graph is configured. */
+export function allTools() {
+    return OPTS.graph ? [...TOOLS, ...GRAPH_TOOLS] : TOOLS;
+}
+// The upstream `graph_dir` description advertises `$GEML_GRAPH_DIR or
+// ./.geml-code-graph`, neither of which applies here — the env var is bypassed
+// (we always pass a resolved directory) and the default is this server's
+// --graph. A tool description that names something the server will refuse is
+// the exact failure `eb7390a` fixed for `latest`, so rewrite it rather than
+// re-serve it.
+function confineSchema(schema) {
+    const props = schema?.properties;
+    if (!props?.graph_dir)
+        return schema;
+    return {
+        ...schema,
+        properties: {
+            ...props,
+            graph_dir: {
+                type: "string",
+                description: "Code-graph directory, relative to the server's --root (defaults to the server's --graph). Paths outside --root are refused.",
+            },
+        },
+    };
+}
+/**
+ * Load and confine the code-graph tools. Idempotent; awaited at startup and by
+ * the suite, which drives `handleLine` in-process.
+ */
+export async function loadGraphTools() {
+    if (GRAPH_TOOLS.length)
+        return GRAPH_TOOLS;
+    // Non-literal specifier on purpose: this resolves at RUNTIME from dist/ to
+    // the sibling codemap/ directory (both are shipped), and it keeps tsc from
+    // demanding types for an untyped .mjs script.
+    const spec = new URL("../codemap/mcp-server.mjs", import.meta.url).href;
+    const mod = await import(spec);
+    // `geml_codemap_node(source: true)` reads the real sources, and WHERE those
+    // are comes from `_index/refresh.json` inside the graph — data this server
+    // did not choose. Bound it to --root like every other path, so a hand-edited
+    // recipe cannot point the reader out of the tree the operator opened.
+    mod.confineSourceTo(OPTS.root);
+    GRAPH_TOOLS = mod.TOOLS.map((t) => ({
+        name: t.name,
+        description: t.description,
+        inputSchema: confineSchema(t.inputSchema),
+        // Resolve the directory HERE, then hand the tool an absolute path: its own
+        // `graphDirOf` prefers an explicit `graph_dir`, so this shuts out both the
+        // env var and the relative default without touching that file.
+        run: (args) => t.run({ ...args, graph_dir: resolveGraphDir(args.graph_dir) }),
+    }));
+    return GRAPH_TOOLS;
+}
+// ---------------------------------------------------------------------------
 // newline-delimited JSON-RPC 2.0 over stdio
 // ---------------------------------------------------------------------------
 export function handleLine(line, write = (s) => process.stdout.write(s)) {
@@ -448,10 +580,10 @@ export function handleLine(line, write = (s) => process.stdout.write(s)) {
             reply(id, {});
         }
         else if (method === "tools/list") {
-            reply(id, { tools: TOOLS.map(({ name, description, inputSchema }) => ({ name, description, inputSchema })) });
+            reply(id, { tools: allTools().map(({ name, description, inputSchema }) => ({ name, description, inputSchema })) });
         }
         else if (method === "tools/call") {
-            const tool = TOOLS.find((t) => t.name === params?.name);
+            const tool = allTools().find((t) => t.name === params?.name);
             if (!tool) {
                 replyError(id, -32602, `unknown tool: ${params?.name}`);
                 return;
@@ -479,23 +611,29 @@ export function handleLine(line, write = (s) => process.stdout.write(s)) {
 // ---------------------------------------------------------------------------
 // Entry
 // ---------------------------------------------------------------------------
-export const MCP_USAGE = `usage: geml mcp --root <dir> [--no-history]
+export const MCP_USAGE = `usage: geml mcp --root <dir> [--graph <dir>] [--no-history]
 
-  Serve GEML document CRUD over the MCP stdio transport (JSON-RPC 2.0).
+  Serve GEML document CRUD over the MCP stdio transport (JSON-RPC 2.0), plus the
+  read-only code-graph tools when the root holds a code graph.
 
   --root <dir>        REQUIRED. Root directory holding the .geml documents.
                       Relative paths resolve against the server process's CWD,
                       which the CLIENT chooses — pass an absolute path.
                       Every path a client names is confined to this directory;
                       a client cannot widen or override it.
+  --graph <dir>       Code-graph directory, inside --root. Defaults to
+                      <root>/.geml-code-graph when that holds an index.geml.
+                      With no graph, the code-graph tools are not served
+                      at all (a client sees only the document tools).
   --no-history        Do not auto-commit a .gemlhistory revision before each
-                      write. Default is to commit, so geml_revert_block always
+                      write. Default is to commit, so geml_revert always
                       has a revision to undo to.
 
   Register with a client:
-    claude mcp add geml -- geml mcp --root /abs/path/to/docs`;
+    claude mcp add geml -- geml mcp --root /abs/path/to/repo`;
 export function parseArgs(args) {
     let root;
+    let graph;
     let history = true;
     for (let i = 0; i < args.length; i++) {
         const a = args[i];
@@ -503,6 +641,10 @@ export function parseArgs(args) {
             root = args[++i];
         else if (a.startsWith("--root="))
             root = a.slice("--root=".length);
+        else if (a === "--graph")
+            graph = args[++i];
+        else if (a.startsWith("--graph="))
+            graph = a.slice("--graph=".length);
         else if (a === "--no-history")
             history = false;
         // The flag used to be --workspace/-w. Name the replacement instead of
@@ -522,7 +664,26 @@ export function parseArgs(args) {
     const abs = resolve(root);
     if (!existsSync(abs) || !statSync(abs).isDirectory())
         throw new Error(`--root is not a directory: ${root}`);
-    return { root: realpathSync(abs), history };
+    const realRoot = realpathSync(abs);
+    return { root: realRoot, history, graph: resolveGraphOpt(realRoot, graph) };
+}
+// An EXPLICIT --graph is trusted to be a graph (the operator said so) and only
+// has to exist inside the root — failing fast beats starting a server whose
+// graph tools all error. The IMPLICIT default has to be sure it found one, so
+// it requires an index.geml: an unrelated `.geml-code-graph` directory must not
+// make three broken tools appear.
+function resolveGraphOpt(realRoot, graph) {
+    if (graph === undefined || graph === "") {
+        const guess = resolve(realRoot, ".geml-code-graph");
+        return existsSync(resolve(guess, "index.geml")) ? realpathSync(guess) : undefined;
+    }
+    const abs = resolve(realRoot, graph);
+    if (!existsSync(abs) || !statSync(abs).isDirectory())
+        throw new Error(`--graph is not a directory: ${graph}`);
+    const real = realpathSync(abs);
+    if (real !== realRoot && !real.startsWith(realRoot + sep))
+        throw new Error(`--graph must live inside --root: ${graph}`);
+    return real;
 }
 // Auto-run only as a MAIN module: the CLI dispatcher spawns this file as a
 // child's entry script, while an in-process `import` (the test suite) stays inert.
@@ -539,5 +700,10 @@ if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href)
         console.error(`geml mcp: ${e.message}\n\n${MCP_USAGE}`);
         process.exit(2);
     }
+    // Load the graph tools BEFORE the first frame can arrive: `tools/list` is
+    // synchronous, so a client that lists during the load would be told the
+    // server has no code graph and would never ask again.
+    if (OPTS.graph)
+        await loadGraphTools();
     createInterface({ input: process.stdin }).on("line", (line) => handleLine(line));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geml/geml",
-  "version": "1.4.4",
+  "version": "1.4.5",
   "mcpName": "io.github.geml-spec/geml",
   "publishConfig": {
     "access": "public"