@geml/geml 1.4.3 → 1.4.5

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 workspace 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-docs -- geml mcp --workspace /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 `--workspace` root the client
-//      cannot override or widen.
+//   3. EVERY PATH IS CONFINED to a server-side `--root` directory the client
+//      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
@@ -32,10 +41,14 @@ import { resolve, dirname, sep } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { spawnSync } from "node:child_process";
 import { createInterface } from "node:readline";
-import { parse } from "./geml.js";
+import { parse, PARSER_VERSION } from "./geml.js";
 import { commit, listRevisions, isCurrent } from "./history.js";
-const SERVER_VERSION = "0.1.0";
-let OPTS = { workspace: process.cwd(), history: true };
+// One version for the whole package: `geml --version` and the MCP handshake
+// must not disagree. This used to be its own literal and had drifted to 0.1.0
+// against a 1.4.x package — invisible to everyone except the user reading their
+// client's server list.
+const SERVER_VERSION = PARSER_VERSION;
+let OPTS = { root: process.cwd(), history: true };
 /** Configure the server. Exported so the suite can point it at a temp dir. */
 export function configure(o) {
     OPTS = { ...OPTS, ...o };
@@ -45,49 +58,65 @@ export function configure(o) {
 // Workspace confinement
 // ---------------------------------------------------------------------------
 // `file` is client-supplied, so `../../../etc/passwd` — or a symlink planted
-// inside the workspace that points out of it — must not resolve. Canonicalize
+// inside the root that points out of it — must not resolve. Canonicalize
 // BOTH sides with realpathSync (which follows every link component) and require
 // the real target to sit at or under the real root. Unlike the code-graph
 // server, whose `graph_dir` is intentionally client-chosen, the root here is
 // fixed by the operator at startup: this server WRITES, so a client that could
 // name its own root could write anywhere.
-export function resolveInWorkspace(file) {
+export function resolveInRoot(file) {
     if (typeof file !== "string" || file === "")
         throw new Error("`file` is required");
-    const root = realpathSync(OPTS.workspace);
+    const root = realpathSync(OPTS.root);
     const target = resolve(root, file);
     let real;
     try {
         real = realpathSync(target);
     }
     catch {
-        throw new Error(`no such file in the workspace: ${file}`);
+        throw new Error(`no such file under the server root: ${file}`);
     }
     if (real !== root && !real.startsWith(root + sep)) {
-        throw new Error(`path escapes the workspace: ${file}`);
+        throw new Error(`path escapes the server root: ${file}`);
     }
     if (!statSync(real).isFile())
         throw new Error(`not a file: ${file}`);
     return real;
 }
-// Cross-document references resolve against the workspace root, never against
-// a client-named directory: `root` may only NARROW to a directory inside it.
-function resolveRoot(root) {
-    const ws = realpathSync(OPTS.workspace);
-    if (root === undefined || root === "")
-        return ws;
-    const target = resolve(ws, 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);
+    const target = resolve(serverRoot, dir);
     let real;
     try {
         real = realpathSync(target);
     }
     catch {
-        throw new Error(`no such directory in the workspace: ${root}`);
+        throw new Error(`no such directory under the server root: ${dir}`);
     }
-    if (real !== ws && !real.startsWith(ws + sep))
-        throw new Error(`root escapes the workspace: ${root}`);
+    if (real !== serverRoot && !real.startsWith(serverRoot + sep))
+        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
 // ---------------------------------------------------------------------------
@@ -130,9 +159,9 @@ function parseRefusal(stderr) {
 }
 const asText = (v) => (typeof v === "string" ? v : JSON.stringify(v, null, 1));
 function applyWrite(spec) {
-    const real = resolveInWorkspace(spec.file);
+    const real = resolveInRoot(spec.file);
     const before = readFileSync(real, "utf8");
-    const root = realpathSync(OPTS.workspace);
+    const root = realpathSync(OPTS.root);
     const errorKey = (d) => `${d.code}:${d.message}`;
     const preexisting = new Set(parse(before, { resolveDoc: docResolver(root) }).diagnostics
         .filter((d) => d.severity === "error")
@@ -206,15 +235,15 @@ function docResolver(root) {
     };
 }
 const hashId = (id) => (id.startsWith("#") ? id : `#${id}`);
-const FILE_ARG = { type: "string", description: "Document path relative to the server's --workspace root, e.g. notes/spec.geml" };
+const FILE_ARG = { type: "string", description: "Document path relative to the server's --root directory, e.g. notes/spec.geml" };
 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) => {
-            const real = resolveInWorkspace(args.file);
+            const real = resolveInRoot(args.file);
             const run = runCli(["get", real, "--json"]);
             if (!run.ok)
                 throw new Error(run.stderr || "could not list ids");
@@ -222,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: {
@@ -233,7 +262,7 @@ export const TOOLS = [
             required: ["file", "id"],
         },
         run: (args) => {
-            const real = resolveInWorkspace(args.file);
+            const real = resolveInRoot(args.file);
             const run = runCli(["get", real, hashId(args.id)]);
             if (!run.ok)
                 throw new Error(run.stderr || `no block with id ${hashId(args.id)}`);
@@ -247,12 +276,12 @@ export const TOOLS = [
             type: "object",
             properties: {
                 file: FILE_ARG,
-                root: { type: "string", description: "Directory (inside the workspace) against which cross-document references resolve. Defaults to the workspace root." },
+                root: { type: "string", description: "Directory (inside the server root) against which cross-document references resolve. Defaults to the server root itself. This is a REFERENCE root and is distinct from the server's own --root sandbox, which it can only narrow." },
             },
             required: ["file"],
         },
         run: (args) => {
-            const real = resolveInWorkspace(args.file);
+            const real = resolveInRoot(args.file);
             const root = resolveRoot(args.root);
             const doc = parse(readFileSync(real, "utf8"), { resolveDoc: docResolver(root) });
             const errors = doc.diagnostics.filter((d) => d.severity === "error").length;
@@ -266,20 +295,65 @@ 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 = resolveInWorkspace(args.file);
+            const real = resolveInRoot(args.file);
             const historyPath = real.replace(/\.geml$/, "") + ".gemlhistory";
             if (!existsSync(historyPath))
                 return { file: args.file, revisions: [], note: "no .gemlhistory sidecar yet — the first write through this server creates one" };
             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",
@@ -292,7 +366,7 @@ export const TOOLS = [
             required: ["file", "id", "body"],
         },
         run: (args) => {
-            const real = resolveInWorkspace(args.file);
+            const real = resolveInRoot(args.file);
             const part = args.part ?? "whole";
             if (!["whole", "head", "body"].includes(part))
                 throw new Error(`part must be whole|head|body, got \`${part}\``);
@@ -306,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",
@@ -319,7 +393,7 @@ export const TOOLS = [
             required: ["file", "content", "position"],
         },
         run: (args) => {
-            const real = resolveInWorkspace(args.file);
+            const real = resolveInRoot(args.file);
             let where;
             if (args.position === "append")
                 where = ["--append"];
@@ -339,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",
@@ -350,7 +424,7 @@ export const TOOLS = [
             required: ["file", "ids"],
         },
         run: (args) => {
-            const real = resolveInWorkspace(args.file);
+            const real = resolveInRoot(args.file);
             const ids = Array.isArray(args.ids) ? args.ids : [args.ids];
             if (!ids.length)
                 throw new Error("`ids` must name at least one block");
@@ -363,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",
@@ -375,7 +449,7 @@ export const TOOLS = [
             required: ["file", "old", "new"],
         },
         run: (args) => {
-            const real = resolveInWorkspace(args.file);
+            const real = resolveInRoot(args.file);
             return applyWrite({
                 file: args.file,
                 cliArgs: ["rename", real, hashId(args.old), hashId(args.new), "-o", "-"],
@@ -384,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: {
@@ -396,7 +470,7 @@ export const TOOLS = [
             required: ["file", "id"],
         },
         run: (args) => {
-            const real = resolveInWorkspace(args.file);
+            const real = resolveInRoot(args.file);
             // Default to `--rev changed`, NOT the tip (`0`) or the CLI's own `-1`. Each
             // write commits the PRE-write state, so the tip undoes the block only when
             // it was the MOST RECENT write — a later write to ANOTHER block moves the
@@ -413,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)) {
@@ -434,7 +570,7 @@ export function handleLine(line, write = (s) => process.stdout.write(s)) {
             reply(id, {
                 protocolVersion: params?.protocolVersion ?? "2024-11-05",
                 capabilities: { tools: {} },
-                serverInfo: { name: "geml-docs", version: SERVER_VERSION },
+                serverInfo: { name: "geml", version: SERVER_VERSION },
             });
         }
         else if (method?.startsWith("notifications/")) {
@@ -444,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;
@@ -475,39 +611,79 @@ export function handleLine(line, write = (s) => process.stdout.write(s)) {
 // ---------------------------------------------------------------------------
 // Entry
 // ---------------------------------------------------------------------------
-export const MCP_USAGE = `usage: geml mcp --workspace <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.
 
-  --workspace <dir>   REQUIRED. Root directory holding the .geml documents.
+  --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-docs -- geml mcp --workspace /abs/path/to/docs`;
+    claude mcp add geml -- geml mcp --root /abs/path/to/repo`;
 export function parseArgs(args) {
-    let workspace;
+    let root;
+    let graph;
     let history = true;
     for (let i = 0; i < args.length; i++) {
         const a = args[i];
-        if (a === "--workspace" || a === "-w")
-            workspace = args[++i];
-        else if (a.startsWith("--workspace="))
-            workspace = a.slice("--workspace=".length);
+        if (a === "--root" || a === "-r")
+            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
+        // failing with a bare `unknown option`: this runs inside a client's server
+        // config, where the only thing the user sees is that the server did not
+        // start, and guessing from `unknown option '--workspace'` is a bad evening.
+        else if (a === "--workspace" || a === "-w" || a.startsWith("--workspace=")) {
+            throw new Error("--workspace is now --root (same meaning: the one directory the server may read and write)");
+        }
         else
             throw new Error(`unknown option '${a}'`);
     }
-    if (!workspace)
-        throw new Error("--workspace <dir> is required (the root the server may read and write)");
-    const abs = resolve(workspace);
+    if (!root)
+        throw new Error("--root <dir> is required (the one directory the server may read and write)");
+    // Relative paths resolve against THIS process's cwd, which an MCP client
+    // picks — so they work from a shell and are a coin flip from a client config.
+    const abs = resolve(root);
     if (!existsSync(abs) || !statSync(abs).isDirectory())
-        throw new Error(`--workspace is not a directory: ${workspace}`);
-    return { workspace: realpathSync(abs), history };
+        throw new Error(`--root is not a directory: ${root}`);
+    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.
@@ -524,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/dist/render-html.js

@@ -36,43 +36,43 @@ function page(title, body, ctx, source) {
         ? `<script type="importmap">{"imports":{"node:fs":"${lg}_node-stub.js","node:path":"${lg}_node-stub.js","node:crypto":"${lg}_node-stub.js","node:url":"${lg}_node-stub.js","node:child_process":"${lg}_node-stub.js"}}</script>\n`
         : "";
     const liveJs = wantLive
-        ? `<script type="module">
-globalThis.process ??= { argv: [], env: {} };
-const { parse } = await import("${lg}geml.js");
-const { codeGraphWaves } = await import("${lg}render.js");
-const w = codeGraphWaves(async (rel) => {
-  try { const r = await fetch(rel, { cache: "no-cache" }); return r.ok ? await r.text() : null; } catch { return null; }
-}, parse);
-for (const m of document.querySelectorAll(".cg-mount[data-start]")) {
-  const start = m.getAttribute("data-start");
-  m._cgView = async (view) => {
-    // A directed view builds from the node's OWN document (its meta names the
-    // module and graph-depth); {doc} opens that document; else the mount's.
-    const src = view && view.doc ? view.doc
-      : view && view.node ? view.node.slice(0, view.node.lastIndexOf("#"))
-      : start;
-    const r = await w.build(src, view && view.doc ? undefined : view);
-    return r.error !== undefined ? null : r.data;
-  };
-}
+        ? `<script type="module">
+globalThis.process ??= { argv: [], env: {} };
+const { parse } = await import("${lg}geml.js");
+const { codeGraphWaves } = await import("${lg}render.js");
+const w = codeGraphWaves(async (rel) => {
+  try { const r = await fetch(rel, { cache: "no-cache" }); return r.ok ? await r.text() : null; } catch { return null; }
+}, parse);
+for (const m of document.querySelectorAll(".cg-mount[data-start]")) {
+  const start = m.getAttribute("data-start");
+  m._cgView = async (view) => {
+    // A directed view builds from the node's OWN document (its meta names the
+    // module and graph-depth); {doc} opens that document; else the mount's.
+    const src = view && view.doc ? view.doc
+      : view && view.node ? view.node.slice(0, view.node.lastIndexOf("#"))
+      : start;
+    const r = await w.build(src, view && view.doc ? undefined : view);
+    return r.error !== undefined ? null : r.data;
+  };
+}
 </script>\n`
         : "";
-    return `<!doctype html>
-<html lang="en">
-<head>
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width, initial-scale=1">
-<title>${esc(title)}</title>
-<style>${CSS}</style>
-${importMap}${mathHead}${mermaidHead}</head>
-<body>
-<main>
-${body}
-</main>
-${footer}
-<script>${JS}</script>
-${ctx.usedCodeGraph ? `<script>${CODE_GRAPH_JS}</script>\n` : ""}${liveJs}</body>
-</html>
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${esc(title)}</title>
+<style>${CSS}</style>
+${importMap}${mathHead}${mermaidHead}</head>
+<body>
+<main>
+${body}
+</main>
+${footer}
+<script>${JS}</script>
+${ctx.usedCodeGraph ? `<script>${CODE_GRAPH_JS}</script>\n` : ""}${liveJs}</body>
+</html>
 `;
 }
 export function renderHtml(doc, opts = {}) {

package/package.json

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