@geml/geml 1.4.3 → 1.4.5

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
@@ -668,6 +683,22 @@ export function blockSpans(source) {
 function splitLines(source) {
     return source.split(/(?<=\n|\r(?!\n))/);
 }
+// Newline handling lives HERE, in one place, because it is easy to get subtly
+// wrong in each caller. Content reaching a mutation is often LF even when the
+// document is not: a history revision is stored newline-normalized, `--in` may
+// come from either kind of file, stdin from anywhere. So: detect the DOCUMENT's
+// style, compare on the normalized (LF) form, and convert back on the way in —
+// which is what keeps a CRLF document from ending up half CRLF, half LF.
+function newlineOf(text) {
+    return /\r\n/.test(text) ? "\r\n" : "\n";
+}
+function toLf(text) {
+    return text.replace(/\r\n?/g, "\n");
+}
+function toNewline(text, nl) {
+    const lf = toLf(text);
+    return nl === "\n" ? lf : lf.replace(/\n/g, nl);
+}
 // `--head`: narrow any id's span to its HEAD line — the single declaring line
 // (a heading's `# … {#id}` line, a typed block's opening fence, a footnote's
 // `[^id]:` line). The head is by construction the FIRST line of the span, so
@@ -737,7 +768,32 @@ function parseStamp(s) {
     return new Date(Date.UTC(+y, +mo - 1, +d, +h, +mi, +se));
 }
 const VERSION = "1.0"; // GEML spec version this CLI targets
-const PARSER_VERSION = "1.4.3"; // reference implementation; keep in sync with package.json
+// The published version, read from package.json rather than restated here.
+// "Keep in sync with package.json" was a comment, and comments do not run: this
+// literal said 1.4.3 while the MCP server's own copy still said 0.1.0.
+// Resolved from this module's location — `dist/geml.js` -> `../package.json`,
+// and npm always ships package.json whatever `files` says. In a browser bundle
+// `import.meta.url` degenerates to "" (see the `entry` note below), so every
+// lookup fails and we fall back rather than throw at import time.
+export const PARSER_VERSION = (() => {
+    let dir;
+    try {
+        dir = dirname(fileURLToPath(import.meta.url));
+    }
+    catch {
+        return "0.0.0";
+    }
+    for (let i = 0; i < 3 && dir; i++) {
+        try {
+            const v = JSON.parse(readFileSync(join(dir, "package.json"), "utf8")).version;
+            if (typeof v === "string" && v)
+                return v;
+        }
+        catch { /* not here — walk up */ }
+        dir = dirname(dir);
+    }
+    return "0.0.0";
+})();
 const USAGE = `geml — GEML reference CLI
 
 Usage:
@@ -768,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    --workspace <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.
@@ -785,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)",
@@ -800,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 --workspace <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
 
-  --workspace <dir>   REQUIRED. Root holding the .geml documents. Every path a
+  --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-docs -- geml mcp --workspace /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.
@@ -1195,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
@@ -1244,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");
@@ -1252,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.
@@ -1394,7 +1587,7 @@ function runSetBody(source, id, from, rawChannel, file, out) {
     let head = headLine;
     if (head !== "" && !/(\r\n|\r|\n)$/.test(head))
         head += "\n";
-    let b = body.replace(/\r\n?/g, "\n");
+    let b = toLf(body); // spliceBlock converts the result to the document's style
     if (closeLine !== null && b !== "" && !b.endsWith("\n"))
         b += "\n";
     const replacement = closeLine !== null ? head + b + closeLine : head + b;
@@ -1462,18 +1655,19 @@ function insertFragment(source, lines, at, fragment, file) {
     const beforeIds = parse(source, { resolveDoc: resolverFor(file) }).ids;
     const before = lines.slice(0, at);
     const after = lines.slice(at);
+    const nl = newlineOf(source); // the fragment AND every separator we add
     // The preceding line must end in a newline so the fragment starts on its own.
     if (before.length && !/(\r\n|\r|\n)$/.test(before[before.length - 1])) {
-        before[before.length - 1] += "\n";
+        before[before.length - 1] += nl;
     }
-    let frag = fragment.replace(/\r\n?/g, "\n");
+    let frag = toNewline(fragment, nl);
     if (!frag.endsWith("\n"))
-        frag += "\n";
+        frag += nl;
     // A single blank separator on each side that has adjacent content and isn't
     // already blank — keeps a following head / preceding block from fusing.
     const blank = (s) => stripEol(s).trim() === "";
-    const sepBefore = before.length && !blank(before[before.length - 1]) ? "\n" : "";
-    const sepAfter = after.length && !blank(after[0]) ? "\n" : "";
+    const sepBefore = before.length && !blank(before[before.length - 1]) ? nl : "";
+    const sepAfter = after.length && !blank(after[0]) ? nl : "";
     const updated = before.join("") + sepBefore + frag + sepAfter + after.join("");
     const reparsed = parse(updated, { resolveDoc: resolverFor(file) });
     const errs = reparsed.diagnostics.filter((d) => d.severity === "error");
@@ -1717,10 +1911,11 @@ function spliceBlock(source, id, replacement, file, headOnly = false, guardCount
     const span = headOnly ? narrowToHead(found) : found;
     const before = orig.slice(0, span.start);
     const after = orig.slice(span.end);
-    let inject = replacement.replace(/\r\n?/g, "\n");
+    const nl = newlineOf(source); // adopt the document's style, not LF
+    let inject = toNewline(replacement, nl);
     const lastLine = span.end >= orig.length;
     if (!inject.endsWith("\n") && !lastLine)
-        inject += "\n";
+        inject += nl;
     const updated = before.join("") + inject + after.join("");
     // Re-parse and refuse a broken result. A parse error or a duplicate id both
     // surface as error diagnostics (registerId flags dups); one check covers both.
@@ -1786,6 +1981,13 @@ function runRevert(args) {
     const id = rawId.replace(/^#/, "");
     const historyPath = flag(args, "--history") ?? historyPathFor(file);
     const source = readInput(file);
+    // The sidecar stores every revision newline-NORMALIZED (history.ts), so a
+    // revision's text always comes back LF while the working file may be CRLF.
+    // Comparing those raw would make EVERY block look changed on a CRLF document
+    // (`--rev changed` reverting blocks nobody touched, and the no-op check never
+    // firing), so compare normalized and write back in the file's own style.
+    const norm = toLf; // compare on the LF form
+    const toFileNl = (s) => toNewline(s, newlineOf(source));
     const curFull = blockSpans(source).get(id); // undefined => absent now
     const curBlock = curFull === undefined ? undefined : (() => {
         const span = headOnly ? narrowToHead(curFull) : curFull;
@@ -1804,7 +2006,8 @@ function runRevert(args) {
     const target = (() => {
         try {
             if (changed) {
-                const found = firstChangedContent(historyPath, curBlock ?? "", pick);
+                // `pick` reads normalized revision text, so normalize this side too.
+                const found = firstChangedContent(historyPath, curBlock === undefined ? "" : norm(curBlock), pick);
                 if (!found)
                     fail(`no earlier revision changes \`${id}\``, 1);
                 return found;
@@ -1831,7 +2034,7 @@ function runRevert(args) {
     }
     // both present -> SPLICE (undo set)
     if (curBlock !== undefined && oldBlock !== undefined) {
-        if (oldBlock === curBlock) {
+        if (norm(oldBlock) === norm(curBlock)) {
             console.error(`#${id} is unchanged at ${target.id}; nothing to revert${changed ? "" : " (try --rev -2, or --rev changed)"}`);
             // A no-op still has to PRODUCE the document when an output destination was
             // asked for: `-o` means "write the result somewhere", and the result of a
@@ -1842,12 +2045,13 @@ function runRevert(args) {
                 emit(source, `#${id} unchanged`);
             return;
         }
+        const replacement = toFileNl(oldBlock); // keep the file's newline style
         if (dryRun) {
             console.error(`would revert #${id} to ${target.id}:`);
-            process.stdout.write(oldBlock.endsWith("\n") ? oldBlock : oldBlock + "\n");
+            process.stdout.write(replacement.endsWith("\n") ? replacement : replacement + "\n");
             return;
         }
-        emit(spliceBlock(source, id, oldBlock, file, headOnly), `reverted #${id} to ${target.id}`);
+        emit(spliceBlock(source, id, replacement, file, headOnly), `reverted #${id} to ${target.id}`);
         return;
     }
     // --head is only meaningful for the splice cell (it can't resurrect or remove).
@@ -1859,24 +2063,25 @@ function runRevert(args) {
         // Guard: if the block we'd resurrect is the same (modulo id) as one already
         // present under a different id, #id was likely renamed away — resurrecting
         // would duplicate it. Point at `rename` instead of writing.
-        const cmpKey = normalizeBlockId(oldBlock, "__cmp__");
+        const cmpKey = normalizeBlockId(norm(oldBlock), "__cmp__");
         for (const [cid, cs] of blockSpans(source)) {
             if (cid === id)
                 continue;
             const csrc = splitLines(source).slice(cs.start, cs.end).join("");
-            if (normalizeBlockId(csrc, "__cmp__") === cmpKey) {
+            if (normalizeBlockId(norm(csrc), "__cmp__") === cmpKey) {
                 fail(`#${id} looks renamed to #${cid}; use 'rename #${cid} #${id}' to undo the rename`, 1);
             }
         }
         const { at, where, warn } = resurrectPosition(source, target.text, id, before, after, append, file);
+        const fragment = toFileNl(oldBlock); // keep the file's newline style
         if (dryRun) {
             console.error(`would resurrect #${id} from ${target.id} at ${where}:`);
-            process.stdout.write(oldBlock.endsWith("\n") ? oldBlock : oldBlock + "\n");
+            process.stdout.write(fragment.endsWith("\n") ? fragment : fragment + "\n");
             return;
         }
         if (warn)
             console.error(`warning: anchors for #${id} are gone; appended at end`);
-        emit(insertFragment(source, splitLines(source), at, oldBlock, file), `resurrected #${id} from ${target.id} at ${where}`);
+        emit(insertFragment(source, splitLines(source), at, fragment, file), `resurrected #${id} from ${target.id} at ${where}`);
         return;
     }
     // present now, absent at R -> REMOVE (undo add)
@@ -1884,7 +2089,7 @@ function runRevert(args) {
     // under a different id, #id was likely renamed IN — removing would delete a
     // renamed block. Point at `rename` instead (the dangerous direction).
     {
-        const cmpKey = normalizeBlockId(curBlock, "__cmp__");
+        const cmpKey = normalizeBlockId(norm(curBlock), "__cmp__");
         for (const [rid, rs] of blockSpans(target.text)) {
             if (rid === id)
                 continue;
@@ -1964,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}`);
@@ -1974,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

@@ -1,11 +1,12 @@
 #!/usr/bin/env node
 export interface McpOptions {
-    workspace: string;
+    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;
-export declare function resolveInWorkspace(file: string): string;
+export declare function resolveInRoot(file: string): string;
 export interface Tool {
     name: string;
     description: string;
@@ -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 --workspace <dir> [--no-history]\n\n  Serve GEML document CRUD over the MCP stdio transport (JSON-RPC 2.0).\n\n  --workspace <dir>   REQUIRED. Root directory holding the .geml documents.\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-docs -- geml mcp --workspace /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;