webnav-ts-mcp 0.2.0 → 0.3.0

package/README.md

@@ -140,6 +140,31 @@ own edit alone. `move`'s HTML/CSS rewrite understands relative and root-absolute
 listed as mentions, not rewritten. HTML/CSS edits are checked by their language
 servers (syntax and CSS lint), not against the cross-file index.
 
+## Several calls in one request: `batch`
+
+Reading three files or changing five symbols no longer costs one round-trip each.
+`batch` takes a list of calls for any tool above (reads and writes mixed):
+
+```json
+{"calls": [
+  {"tool": "outline", "args": {"file_path": "src/app.ts"}},
+  {"tool": "symbol_info", "args": {"name": "Cart.total"}},
+  {"tool": "edit", "args": {"file_path": "src/app.ts", "old_string": "x = 1", "new_string": "x = 2"}},
+  {"tool": "edit_symbol", "args": {"action": "delete", "name": "legacyParse"}}
+]}
+```
+
+- Calls run **in order**, each through the real tool, so every write is type-checked,
+  previewed or applied, and undoable on its own (one edit id per write), and later calls
+  see what earlier ones wrote.
+- One numbered section per call, then a summary line (`batch: 3/4 ok, 1 failed`).
+- A bad tool name or argument is reported in its own section with a hint; the rest still run.
+- `stop_on_error` (default: stop when the batch contains a write, continue when it only
+  reads) skips the remaining calls after the first failure or write that was not applied.
+- Not atomic: calls that ran stay applied. After an edit, prefer name-based calls over
+  line/column positions computed earlier. Max 25 calls, no nesting, each result capped at
+  20,000 characters.
+
 ## Environment
 
 | Variable | Default | Purpose |
@@ -156,6 +181,7 @@ servers (syntax and CSS lint), not against the cross-file index.
 src/
   cli.ts          stdio entry point (exits when the host closes stdin)
   server.ts       registers the tools on the MCP SDK
+  batch.ts        the `batch` engine: runs several registered tools in one request
   webnav.ts       the tools as plain async functions returning text; owns all state
   webIndex.ts     CSS var / selector index
   langCommand.ts  how to launch tsc / html / css language servers

package/dist/batch.js

@@ -0,0 +1,235 @@
+/**
+ * `batch`: several tool calls in one request.
+ *
+ * An agent that wants to read three files or change five symbols would otherwise spend one
+ * round-trip (and the tokens around it) per call. `batch` takes the list, runs the calls in
+ * order through the real tool functions, and returns one numbered section per call. Each
+ * call keeps its own behaviour: every write is type-checked, previewed or applied, and
+ * undoable on its own, and later calls see what earlier calls wrote.
+ *
+ * The registry is plain data (a zod shape plus a run function per tool), so unit tests can
+ * register fake tools and drive `runBatch` without a language server or the MCP SDK.
+ */
+import { z } from "zod";
+import { pyRepr } from "./shared/format.js";
+export const MAX_CALLS = 25;
+export const MAX_CALL_CHARS = 20_000;
+// Text a write tool returns when it did what was asked (applied, undone, previewed, or nothing to do).
+const WRITE_OK_MARKERS = ["Applied as edit", "Applied edit", "Reverted edit", "Preview only", "No changes"];
+function availableTools(registry) {
+    return [...registry.keys()].sort();
+}
+/** Levenshtein edit distance, for the unknown-tool suggestion. */
+function editDistance(a, b) {
+    const width = b.length;
+    let previous = Array.from({ length: width + 1 }, (_, j) => j);
+    for (let i = 1; i <= a.length; i++) {
+        const current = new Array(width + 1).fill(0);
+        current[0] = i;
+        for (let j = 1; j <= width; j++) {
+            const left = previous[j];
+            const up = current[j - 1] + 1;
+            const diagonal = previous[j - 1] + (a.charAt(i - 1) === b.charAt(j - 1) ? 0 : 1);
+            current[j] = Math.min(left + 1, up, diagonal);
+        }
+        previous = current;
+    }
+    return previous[width];
+}
+/**
+ * ` Did you mean 'x' or 'y'?` — the two closest registered names, or "" when none is close.
+ *
+ * Deliberately NOT the Python original's difflib.get_close_matches scoring (SequenceMatcher
+ * ratio >= 0.6; this keeps its n=2): this is Levenshtein distance <= floor(0.4 * max(len)).
+ * The two agree on realistic typos and Levenshtein is simpler — don't "fix" this to match difflib.
+ */
+function suggestion(name, registry) {
+    const close = availableTools(registry)
+        .map((candidate) => ({ candidate, distance: editDistance(name, candidate) }))
+        .filter(({ candidate, distance }) => distance <= Math.floor(Math.max(name.length, candidate.length) * 0.4))
+        .sort((a, b) => a.distance - b.distance || (a.candidate < b.candidate ? -1 : 1))
+        .slice(0, 2)
+        .map(({ candidate }) => pyRepr(candidate));
+    return close.length > 0 ? ` Did you mean ${close.join(" or ")}?` : "";
+}
+function unknownToolHint(name, registry) {
+    return `Unknown tool ${pyRepr(name)}.${suggestion(name, registry)} Available: ${availableTools(registry).join(", ")}.`;
+}
+/** True when the parameter may be left out: `.optional()` or `.default(...)` in the zod shape. */
+function mayBeOmitted(schema) {
+    return schema.safeParse(undefined).success;
+}
+/** `name(a, b=...)`: parameters without a default shown bare, with one shown as `=...`. */
+function signatureHint(name, tool) {
+    const parts = Object.entries(tool.inputSchema).map(([key, schema]) => (mayBeOmitted(schema) ? `${key}=...` : key));
+    return `${name}(${parts.join(", ")})`;
+}
+/** Python-repr-ish text for a call argument in a section header: `'x'`, `7`, `true`, `['a', "b"]`. */
+function reprValue(value) {
+    if (typeof value === "string") {
+        return pyRepr(value);
+    }
+    if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") {
+        return String(value);
+    }
+    if (value === null || value === undefined) {
+        return "null";
+    }
+    // One style throughout (Python repr-ish): strings single-quoted, arrays `[a, b]`, objects `{k: v}`.
+    if (Array.isArray(value)) {
+        return `[${value.map((item) => reprValue(item)).join(", ")}]`;
+    }
+    if (typeof value === "object") {
+        const items = Object.entries(value).map(([key, v]) => `${pyRepr(key)}: ${reprValue(v)}`);
+        return `{${items.join(", ")}}`;
+    }
+    return JSON.stringify(value) ?? "null";
+}
+/** `edit(file_path='src/a.ts', old_string='...')` — only the arguments the call passed. */
+function label(name, args) {
+    const shown = Object.entries(args)
+        .map(([key, value]) => {
+        const repr = reprValue(value);
+        return repr.length <= 60 ? `${key}=${repr}` : `${key}=...`;
+    })
+        .join(", ");
+    return `${name}(${shown})`;
+}
+/**
+ * Validates one call; returns it ready to run, or the error text for its section.
+ * The flat shape `{"tool": "outline", "file_path": "x.ts"}` is accepted too: keys beside
+ * "tool" are treated as arguments.
+ */
+function prepare(registry, index, raw) {
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+        return `Call ${index} must be an object like {"tool": "outline", "args": {"file_path": "src/a.ts"}}.`;
+    }
+    const rest = { ...raw };
+    let name = rest.tool;
+    delete rest.tool;
+    if (!name) {
+        name = rest.name;
+        delete rest.name;
+    }
+    if (typeof name !== "string" || name === "") {
+        return 'Call is missing "tool" (the tool name, e.g. "outline").';
+    }
+    if (name === "batch") {
+        return "batch calls cannot be nested.";
+    }
+    const tool = registry.get(name);
+    if (!tool) {
+        return unknownToolHint(name, registry);
+    }
+    let args = rest.args;
+    delete rest.args;
+    if (args === undefined || args === null) {
+        args = rest;
+    }
+    else if (Object.keys(rest).length > 0) {
+        const extra = Object.keys(rest).sort().map(pyRepr).join(", ");
+        return `Put [${extra}] inside "args" (call shape: {"tool": ..., "args": {...}}).`;
+    }
+    if (typeof args !== "object" || args === null || Array.isArray(args)) {
+        return `"args" must be an object of ${name} parameters: ${signatureHint(name, tool)}.`;
+    }
+    const parameters = args;
+    const unknown = Object.keys(parameters).filter((key) => !Object.hasOwn(tool.inputSchema, key));
+    if (unknown.length > 0) {
+        return `${name} has no parameter ${unknown.map(pyRepr).join(", ")}. Parameters: ${signatureHint(name, tool)}.`;
+    }
+    for (const [key, value] of Object.entries(parameters)) {
+        const result = tool.inputSchema[key]?.safeParse(value);
+        if (result && !result.success) {
+            const message = result.error.issues[0]?.message ?? "invalid value";
+            return `${name}: invalid ${pyRepr(key)}: ${message}. Parameters: ${signatureHint(name, tool)}.`;
+        }
+    }
+    const missing = Object.entries(tool.inputSchema)
+        .filter(([key, schema]) => !mayBeOmitted(schema) && !Object.hasOwn(parameters, key))
+        .map(([key]) => key);
+    if (missing.length > 0) {
+        return `${name}: missing required ${missing.map(pyRepr).join(", ")}. Parameters: ${signatureHint(name, tool)}.`;
+    }
+    // Fill in the defaults exactly as the MCP server would have; the tools rely on them. The checks
+    // above accept every value the per-key schemas accept, so a failure here means those checks
+    // missed something (e.g. an object-level rule, which a per-key ToolShape cannot express) —
+    // report it instead of silently running the call with default-less arguments.
+    const filled = z.object(tool.inputSchema).safeParse(parameters);
+    if (!filled.success) {
+        const issue = filled.error.issues[0];
+        const where = issue !== undefined && issue.path.length > 0 ? `${issue.path.join(".")}: ` : "";
+        return `${name}: internal error validating arguments: ${where}${issue?.message ?? "invalid arguments"}.`;
+    }
+    return { name, tool, args: parameters, call: filled.data };
+}
+/** A write tool's result counts as a failure when it did not do what was asked. */
+function writeFailed(tool, text) {
+    return tool.writes && (text.includes("NOT applied") || !WRITE_OK_MARKERS.some((marker) => text.includes(marker)));
+}
+/**
+ * Runs the calls in order through the registered tools and returns one numbered section per
+ * call, then a summary line. One broken call never loses the others' results.
+ *
+ * `stop_on_error`: stop at the first call that fails or does not apply a write, skipping the
+ * rest. Default (null/omitted): stop when the batch contains a write, keep going when it
+ * only reads.
+ */
+export async function runBatch(calls, stopOnError, registry) {
+    if (!Array.isArray(calls) || calls.length === 0) {
+        return 'batch needs a non-empty "calls" list, e.g. [{"tool": "outline", "args": {"file_path": "src/a.ts"}}].';
+    }
+    if (calls.length > MAX_CALLS) {
+        return `batch takes at most ${MAX_CALLS} calls, got ${calls.length}. Split it into several batches.`;
+    }
+    const prepared = calls.map((raw, i) => prepare(registry, i + 1, raw));
+    const hasWrite = prepared.some((item) => typeof item !== "string" && item.tool.writes);
+    const stop = stopOnError === undefined || stopOnError === null ? hasWrite : stopOnError;
+    const sections = [];
+    let failed = 0;
+    let skipped = 0;
+    let halted = false;
+    const total = prepared.length;
+    for (const [offset, item] of prepared.entries()) {
+        const index = offset + 1;
+        if (halted) {
+            skipped += 1;
+            continue;
+        }
+        if (typeof item === "string") {
+            sections.push(`[${index}/${total}] ERROR\n${item}`);
+            failed += 1;
+            halted = stop;
+            continue;
+        }
+        const header = `[${index}/${total}] ${label(item.name, item.args)}`;
+        let text;
+        try {
+            text = await item.tool.run(item.call);
+        }
+        catch (error) {
+            const message = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
+            sections.push(`${header}\nERROR: ${message}`);
+            failed += 1;
+            halted = stop;
+            continue;
+        }
+        if (writeFailed(item.tool, text)) {
+            failed += 1;
+            halted = stop;
+            text = `NOT DONE\n${text}`;
+        }
+        if (text.length > MAX_CALL_CHARS) {
+            text = `${text.slice(0, MAX_CALL_CHARS)}\n... [truncated ${text.length - MAX_CALL_CHARS} characters; narrow this call]`;
+        }
+        sections.push(`${header}\n${text}`);
+    }
+    let summary = `batch: ${total - failed - skipped}/${total} ok`;
+    if (failed > 0) {
+        summary += `, ${failed} failed`;
+    }
+    if (skipped > 0) {
+        summary += `, ${skipped} skipped after the first failure (stop_on_error)`;
+    }
+    return [...sections, summary].join("\n\n");
+}

package/dist/server.js

@@ -5,9 +5,15 @@
  * parameters are all optional in the schema: a missing one is answered with a
  * short hint by the tool itself, which beats the SDK's schema-validation error
  * for agents that guess `query` vs `name`.
+ *
+ * Every tool is declared once as a spec (`name`, `description`, `inputSchema`,
+ * `annotations`, `writes`, `run`). `createServer` registers each spec on the
+ * MCP server, and the `batch` engine resolves its calls against the same specs,
+ * so a batch call is validated and run exactly like the tool called alone.
  */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
+import { runBatch } from "./batch.js";
 import { INSTRUCTIONS, Webnav } from "./webnav.js";
 const POSITION_DOC = "`line` and `column` are 1-indexed. `column` is a UTF-16 character offset on the line " +
     "(not a visual/display column): a leading tab counts as one character.";
@@ -25,6 +31,37 @@ const writeParams = {
 const text = (value) => ({
     content: [{ type: "text", text: value }],
 });
+/**
+ * Declares a tool: the zod shape is registered with the MCP server (whose own schema parsing
+ * fills the same defaults) and is reused by `batch` to validate each call.
+ */
+function tool(name, config) {
+    return {
+        name,
+        description: config.description,
+        inputSchema: config.inputSchema,
+        writes: config.writes,
+        annotations: config.annotations,
+        run: config.run,
+    };
+}
+const BATCH_DESCRIPTION = "Run several webnav tool calls in ONE request (saves round-trips and tokens).\n\n" +
+    'Example: `batch(calls=[{"tool": "outline", "args": {"file_path": "src/app.ts"}}, ' +
+    '{"tool": "symbol_info", "args": {"name": "Cart.total"}}])`. Works for reads and writes alike, e.g. ' +
+    'two edits in different files: `[{"tool": "edit", "args": {"file_path": "src/app.ts", "old_string": ' +
+    '"x = 1", "new_string": "x = 2"}}, {"tool": "edit_symbol", "args": {...}}]`.\n\n' +
+    "Each call takes the same arguments as the tool called alone (`args` is that tool's parameter object) " +
+    "and behaves as if you had called it separately: calls run in order, so a later call sees what an " +
+    "earlier write changed, and every write is type-checked, previewed/applied and undoable on its own " +
+    "(see its own section for the edit id). The result has one numbered section per call, then a summary " +
+    "line.\n\n" +
+    "`stop_on_error`: stop at the first call that fails or does not apply a write (the rest are skipped " +
+    "and listed). Default (null): stop when the batch contains a write, keep going when it only reads. " +
+    "Up to 25 calls; `batch` cannot be nested.\n\n" +
+    "Not atomic: calls that already ran stay applied (each has its own undo id). Line/column positions " +
+    "you computed before the batch may be stale after an earlier edit in it, so prefer name-based calls " +
+    "(symbol_info, edit_symbol, rename_symbol) after writes. A preview id is invalid once a later call " +
+    "changes the same file.";
 export function createServer(version) {
     const server = new McpServer({ name: "webnav", version }, { instructions: INSTRUCTIONS });
     const webnav = new Webnav({
@@ -40,320 +77,383 @@ export function createServer(version) {
         line: z.number().int(),
         column: z.number().int(),
     };
-    server.registerTool("hover", {
-        description: `Get type/documentation info for the symbol at a position.\n\n${POSITION_DOC}`,
-        inputSchema: position,
-    }, async ({ file_path, line, column }) => text(await webnav.hover(file_path, line, column)));
-    server.registerTool("workspace", {
-        description: "Which directory is webnav navigating, and why? Use when results look like they come from the wrong checkout/worktree.",
-        inputSchema: {},
-    }, async () => text(await webnav.workspace()));
-    server.registerTool("definition", {
-        description: "Go to the definition of the symbol at a position.\n\n" +
-            `${POSITION_DOC} On a \`--custom-property\`/\`#id\`/\`.class\` token in a \`.css\`/` +
-            '`.html` file (or a name inside an HTML `id="..."`/`class="..."` value), ' +
-            "answers from the cross-file index (see css_var/selector) " +
-            "instead of the single-file language server: for `definition`, just the " +
-            "definition(s) in the file's own root (each `WEBNAV_MCP_ROOTS` root " +
-            "is separate); for `references`, that root's definitions and usages.",
-        inputSchema: position,
-    }, async ({ file_path, line, column }) => text(await webnav.definition(file_path, line, column)));
-    server.registerTool("references", {
-        description: "Find all usages of the symbol at a position across the workspace.\n\n" +
-            `${POSITION_DOC} On a \`--custom-property\`/\`#id\`/\`.class\` token in a \`.css\`/` +
-            '`.html` file (or a name inside an HTML `id="..."`/`class="..."` value), ' +
-            "answers from the cross-file index (see css_var/selector) " +
-            "instead of the single-file language server, limited to the file's own root " +
-            "(each `WEBNAV_MCP_ROOTS` root is separate) unless it has no hits there.",
-        inputSchema: { ...position, include_declaration: z.boolean().default(true) },
-    }, async ({ file_path, line, column, include_declaration }) => text(await webnav.references(file_path, line, column, include_declaration)));
-    server.registerTool("search_symbol", {
-        description: "Search JS/TS files for a symbol by name (function, class, const, etc.).\n\n" +
-            "JS/TS-only: the HTML/CSS language servers don't implement useful " +
-            "workspace-wide symbol search (webnav does not reimplement it). Prefer " +
-            "`symbol_info` for a one-call summary. Returned positions point at the " +
-            "identifier name and use the same character-offset column convention as " +
-            "the other tools. Results include a SymbolKind label and are capped. " +
-            "`name` is accepted as an alias for `query`. Narrow broad queries with " +
-            "`kind` (SymbolKind labels, comma-separated: `class`, `function,method`, " +
-            "`interface`, ...) and `path` (workspace-relative prefix such as `src/`, " +
-            "or a glob such as `src/**/*.ts`). Production code ranks before tests. " +
-            "Loose fuzzy hits whose names don't contain the query are summarised as a " +
-            "count when real matches exist; pass `fuzzy=true` to list them too.",
-        inputSchema: {
-            query: z.string().optional(),
-            name: z.string().optional(),
-            kind: z.string().optional(),
-            path: z.string().optional(),
-            fuzzy: z.boolean().default(false),
-        },
-    }, async (args) => text(await webnav.searchSymbol(args)));
-    server.registerTool("symbol_info", {
-        description: 'What is X and where is it used? Example: `symbol_info(name="renderSidebar")`.\n\n' +
-            "One-call summary for a JS/TS name: header, hover text, definition, and " +
-            "references grouped by file, the usual first lookup instead of chaining " +
-            "search_symbol → hover → definition → references by hand. Pass `file_path` " +
-            "to disambiguate; `query` is accepted as an alias for `name`. For CSS/HTML " +
-            "cross-file lookups use `css_var` / `selector` instead.",
-        inputSchema: {
-            name: z.string().optional(),
-            query: z.string().optional(),
-            file_path: z.string().optional(),
-            include_references: z.boolean().default(true),
-        },
-    }, async ({ name, query, file_path, include_references }) => text(await webnav.symbolInfo({ name, query, filePath: file_path, includeReferences: include_references })));
-    server.registerTool("callers", {
-        description: 'Who calls this function? Example: `callers(name="renderSidebar")`.\n\n' +
-            "Narrower than references, since it leaves out imports and type-only usages " +
-            "and only lists actual call sites, each with the calling function and its " +
-            "call-site lines. `name` resolves the same way as symbol_info (dotted " +
-            "`Class.method` accepted, inherited members included; pass `file_path` to " +
-            "disambiguate a common name). `query` is accepted as an alias for `name`. JS/TS only.",
-        inputSchema: { name: z.string().optional(), query: z.string().optional(), file_path: z.string().optional() },
-    }, async ({ name, query, file_path }) => text(await webnav.callers({ name, query, filePath: file_path })));
-    server.registerTool("implementations", {
-        description: 'Who implements or extends this? Example: `implementations(name="Shape")`.\n\n' +
-            "For an interface or class, lists the classes that implement or extend it " +
-            "(transitively); for an interface or abstract method (`Shape.area`), lists the " +
-            "methods that implement it. Backed by the language server's " +
-            "`textDocument/implementation`, so it follows the type checker, not naming. " +
-            "`name` resolves like symbol_info (pass `file_path` to disambiguate); `query` is " +
-            "accepted as an alias. JS/TS only.",
-        inputSchema: { name: z.string().optional(), query: z.string().optional(), file_path: z.string().optional() },
-    }, async ({ name, query, file_path }) => text(await webnav.implementations({ name, query, filePath: file_path })));
-    server.registerTool("outline", {
-        description: 'What\'s in this file? Example: `outline(file_path="src/app.ts")`.\n\n' +
-            "Indented outline (functions, classes, interfaces, with `:start-end` line " +
-            "spans) of a JS/TS file in source order, so you can navigate without reading " +
-            "it in full. Locals, callbacks and object-literal keys inside functions and " +
-            "variables are left out; pass `detailed=true` to include them. Follow up " +
-            "with hover/definition/references at a listed line, or symbol_info by name.",
-        inputSchema: { file_path: z.string(), detailed: z.boolean().default(false) },
-    }, async ({ file_path, detailed }) => text(await webnav.outline(file_path, detailed)));
-    server.registerTool("diagnostics", {
-        description: "Get the relevant language server's diagnostics (errors/warnings) for a single file.\n\n" +
-            "For `.css`/`.html` files, this also includes index-derived warnings the " +
-            "single-file language server can't see: `var(--x)` used with no matching " +
-            "declaration anywhere in the same indexed root, and CSS selectors " +
-            "(`#id`/`.class`) with no HTML/JS reference in that root.",
-        inputSchema: { file_path: z.string() },
-    }, async ({ file_path }) => text(await webnav.diagnostics(file_path)));
-    server.registerTool("css_var", {
-        description: 'Where is this `--custom-property` defined and used? Example: `css_var(name="--bg")`.\n\n' +
-            "The CSS/HTML language servers only see one file at a time, so `var(--x)` " +
-            "usages can't be cross-referenced across files that way. This scans " +
-            '`.css` files and HTML `<style>`/`style="…"` blocks/attributes instead. ' +
-            "`name` may be given with or without the leading `--`. Definitions (value " +
-            "+ enclosing context, e.g. `@media (prefers-color-scheme: dark) › :root`) " +
-            "and usages (grouped by file with line numbers) are reported separately per " +
-            "configured root (see `WEBNAV_MCP_ROOTS`; a single unnamed root by default), " +
-            "since each may define its own values. `query` is accepted as an alias for `name`.",
-        inputSchema: { name: z.string().optional(), query: z.string().optional() },
-    }, async (args) => text(await webnav.cssVar(args)));
-    server.registerTool("selector", {
-        description: 'Who uses this `#id` or `.class`? Example: `selector(name=".card-title")`.\n\n' +
-            "Looks up the selector across the whole workspace.\n\n" +
-            "Cross-references CSS rule definitions, HTML `id=`/`class=` attributes, " +
-            "and JS usages (`getElementById`, `classList.add/remove/toggle/contains`, " +
-            "`querySelector`/`querySelectorAll`, `className` assignment, and any JS " +
-            "string literal exactly equal to the bare name, e.g. an id passed to a " +
-            'project\'s own helper like `onClick("btn-save", …)`, labeled "string ' +
-            'literal"). Hits in generated output (`WEBNAV_MCP_EXCLUDE`) are labeled ' +
-            "`[generated]`; edit their source instead. This is something " +
-            "the single-file CSS/HTML language servers can't do. `name` must include " +
-            "the leading `#` or `.`. Grouped by file with line numbers, separately per " +
-            "configured root (see `WEBNAV_MCP_ROOTS`). A JS hit built from string " +
-            'concatenation (e.g. `getElementById("view-" + x)`) is reported against ' +
-            'only its static prefix and labeled "dynamic partial match"; a query whose ' +
-            "name starts with such a prefix (e.g. `#view-components` against a stored " +
-            '`#view-`) also surfaces that hit, labeled "dynamic partial match via ' +
-            "'<prefix>'\", instead of being silently dropped or guessed. `query` is " +
-            "accepted as an alias for `name`.",
-        inputSchema: { name: z.string().optional(), query: z.string().optional() },
-    }, async (args) => text(await webnav.selectorLookup(args)));
-    registerWriteTools(server, webnav);
+    // Registered in order; `batch` is LAST so its registry can reach every other tool
+    // (a call for "batch" inside a batch is refused, so it never enters the registry itself).
+    const registry = new Map();
+    const specs = [
+        tool("hover", {
+            description: `Get type/documentation info for the symbol at a position.\n\n${POSITION_DOC}`,
+            inputSchema: position,
+            run: async ({ file_path, line, column }) => webnav.hover(file_path, line, column),
+            writes: false,
+        }),
+        tool("workspace", {
+            description: "Which directory is webnav navigating, and why? Use when results look like they come from the wrong checkout/worktree.",
+            inputSchema: {},
+            run: async () => webnav.workspace(),
+            writes: false,
+        }),
+        tool("definition", {
+            description: "Go to the definition of the symbol at a position.\n\n" +
+                `${POSITION_DOC} On a \`--custom-property\`/\`#id\`/\`.class\` token in a \`.css\`/` +
+                '`.html` file (or a name inside an HTML `id="..."`/`class="..."` value), ' +
+                "answers from the cross-file index (see css_var/selector) " +
+                "instead of the single-file language server: for `definition`, just the " +
+                "definition(s) in the file's own root (each `WEBNAV_MCP_ROOTS` root " +
+                "is separate); for `references`, that root's definitions and usages.",
+            inputSchema: position,
+            run: async ({ file_path, line, column }) => webnav.definition(file_path, line, column),
+            writes: false,
+        }),
+        tool("references", {
+            description: "Find all usages of the symbol at a position across the workspace.\n\n" +
+                `${POSITION_DOC} On a \`--custom-property\`/\`#id\`/\`.class\` token in a \`.css\`/` +
+                '`.html` file (or a name inside an HTML `id="..."`/`class="..."` value), ' +
+                "answers from the cross-file index (see css_var/selector) " +
+                "instead of the single-file language server, limited to the file's own root " +
+                "(each `WEBNAV_MCP_ROOTS` root is separate) unless it has no hits there.",
+            inputSchema: { ...position, include_declaration: z.boolean().default(true) },
+            run: async ({ file_path, line, column, include_declaration }) => webnav.references(file_path, line, column, include_declaration),
+            writes: false,
+        }),
+        tool("search_symbol", {
+            description: "Search JS/TS files for a symbol by name (function, class, const, etc.).\n\n" +
+                "JS/TS-only: the HTML/CSS language servers don't implement useful " +
+                "workspace-wide symbol search (webnav does not reimplement it). Prefer " +
+                "`symbol_info` for a one-call summary. Returned positions point at the " +
+                "identifier name and use the same character-offset column convention as " +
+                "the other tools. Results include a SymbolKind label and are capped. " +
+                "`name` is accepted as an alias for `query`. Narrow broad queries with " +
+                "`kind` (SymbolKind labels, comma-separated: `class`, `function,method`, " +
+                "`interface`, ...) and `path` (workspace-relative prefix such as `src/`, " +
+                "or a glob such as `src/**/*.ts`). Production code ranks before tests. " +
+                "Loose fuzzy hits whose names don't contain the query are summarised as a " +
+                "count when real matches exist; pass `fuzzy=true` to list them too.",
+            inputSchema: {
+                query: z.string().optional(),
+                name: z.string().optional(),
+                kind: z.string().optional(),
+                path: z.string().optional(),
+                fuzzy: z.boolean().default(false),
+            },
+            run: async (args) => webnav.searchSymbol(args),
+            writes: false,
+        }),
+        tool("symbol_info", {
+            description: 'What is X and where is it used? Example: `symbol_info(name="renderSidebar")`.\n\n' +
+                "One-call summary for a JS/TS name: header, hover text, definition, and " +
+                "references grouped by file, the usual first lookup instead of chaining " +
+                "search_symbol → hover → definition → references by hand. Pass `file_path` " +
+                "to disambiguate; `query` is accepted as an alias for `name`. For CSS/HTML " +
+                "cross-file lookups use `css_var` / `selector` instead.",
+            inputSchema: {
+                name: z.string().optional(),
+                query: z.string().optional(),
+                file_path: z.string().optional(),
+                include_references: z.boolean().default(true),
+            },
+            run: async ({ name, query, file_path, include_references }) => webnav.symbolInfo({ name, query, filePath: file_path, includeReferences: include_references }),
+            writes: false,
+        }),
+        tool("callers", {
+            description: 'Who calls this function? Example: `callers(name="renderSidebar")`.\n\n' +
+                "Narrower than references, since it leaves out imports and type-only usages " +
+                "and only lists actual call sites, each with the calling function and its " +
+                "call-site lines. `name` resolves the same way as symbol_info (dotted " +
+                "`Class.method` accepted, inherited members included; pass `file_path` to " +
+                "disambiguate a common name). `query` is accepted as an alias for `name`. JS/TS only.",
+            inputSchema: { name: z.string().optional(), query: z.string().optional(), file_path: z.string().optional() },
+            run: async ({ name, query, file_path }) => webnav.callers({ name, query, filePath: file_path }),
+            writes: false,
+        }),
+        tool("implementations", {
+            description: 'Who implements or extends this? Example: `implementations(name="Shape")`.\n\n' +
+                "For an interface or class, lists the classes that implement or extend it " +
+                "(transitively); for an interface or abstract method (`Shape.area`), lists the " +
+                "methods that implement it. Backed by the language server's " +
+                "`textDocument/implementation`, so it follows the type checker, not naming. " +
+                "`name` resolves like symbol_info (pass `file_path` to disambiguate); `query` is " +
+                "accepted as an alias. JS/TS only.",
+            inputSchema: { name: z.string().optional(), query: z.string().optional(), file_path: z.string().optional() },
+            run: async ({ name, query, file_path }) => webnav.implementations({ name, query, filePath: file_path }),
+            writes: false,
+        }),
+        tool("outline", {
+            description: 'What\'s in this file? Example: `outline(file_path="src/app.ts")`.\n\n' +
+                "Indented outline (functions, classes, interfaces, with `:start-end` line " +
+                "spans) of a JS/TS file in source order, so you can navigate without reading " +
+                "it in full. Locals, callbacks and object-literal keys inside functions and " +
+                "variables are left out; pass `detailed=true` to include them. Follow up " +
+                "with hover/definition/references at a listed line, or symbol_info by name.",
+            inputSchema: { file_path: z.string(), detailed: z.boolean().default(false) },
+            run: async ({ file_path, detailed }) => webnav.outline(file_path, detailed),
+            writes: false,
+        }),
+        tool("diagnostics", {
+            description: "Get the relevant language server's diagnostics (errors/warnings) for a single file.\n\n" +
+                "For `.css`/`.html` files, this also includes index-derived warnings the " +
+                "single-file language server can't see: `var(--x)` used with no matching " +
+                "declaration anywhere in the same indexed root, and CSS selectors " +
+                "(`#id`/`.class`) with no HTML/JS reference in that root.",
+            inputSchema: { file_path: z.string() },
+            run: async ({ file_path }) => webnav.diagnostics(file_path),
+            writes: false,
+        }),
+        tool("css_var", {
+            description: 'Where is this `--custom-property` defined and used? Example: `css_var(name="--bg")`.\n\n' +
+                "The CSS/HTML language servers only see one file at a time, so `var(--x)` " +
+                "usages can't be cross-referenced across files that way. This scans " +
+                '`.css` files and HTML `<style>`/`style="…"` blocks/attributes instead. ' +
+                "`name` may be given with or without the leading `--`. Definitions (value " +
+                "+ enclosing context, e.g. `@media (prefers-color-scheme: dark) › :root`) " +
+                "and usages (grouped by file with line numbers) are reported separately per " +
+                "configured root (see `WEBNAV_MCP_ROOTS`; a single unnamed root by default), " +
+                "since each may define its own values. `query` is accepted as an alias for `name`.",
+            inputSchema: { name: z.string().optional(), query: z.string().optional() },
+            run: async (args) => webnav.cssVar(args),
+            writes: false,
+        }),
+        tool("selector", {
+            description: 'Who uses this `#id` or `.class`? Example: `selector(name=".card-title")`.\n\n' +
+                "Looks up the selector across the whole workspace.\n\n" +
+                "Cross-references CSS rule definitions, HTML `id=`/`class=` attributes, " +
+                "and JS usages (`getElementById`, `classList.add/remove/toggle/contains`, " +
+                "`querySelector`/`querySelectorAll`, `className` assignment, and any JS " +
+                "string literal exactly equal to the bare name, e.g. an id passed to a " +
+                'project\'s own helper like `onClick("btn-save", …)`, labeled "string ' +
+                'literal"). Hits in generated output (`WEBNAV_MCP_EXCLUDE`) are labeled ' +
+                "`[generated]`; edit their source instead. This is something " +
+                "the single-file CSS/HTML language servers can't do. `name` must include " +
+                "the leading `#` or `.`. Grouped by file with line numbers, separately per " +
+                "configured root (see `WEBNAV_MCP_ROOTS`). A JS hit built from string " +
+                'concatenation (e.g. `getElementById("view-" + x)`) is reported against ' +
+                'only its static prefix and labeled "dynamic partial match"; a query whose ' +
+                "name starts with such a prefix (e.g. `#view-components` against a stored " +
+                '`#view-`) also surfaces that hit, labeled "dynamic partial match via ' +
+                "'<prefix>'\", instead of being silently dropped or guessed. `query` is " +
+                "accepted as an alias for `name`.",
+            inputSchema: { name: z.string().optional(), query: z.string().optional() },
+            run: async (args) => webnav.selectorLookup(args),
+            writes: false,
+        }),
+        tool("edit", {
+            description: 'Edit text in a JS/TS/HTML/CSS file, type-checked: `edit(file_path="src/app.ts", old_string="x = 1", new_string="x = 2")`.\n\n' +
+                "For changes that are not a whole definition (a few lines, an import, a rule, markup) or for rewriting a " +
+                "whole file (`new_text`, which also creates a new file). To replace, add or delete a function/class/method " +
+                "by name use `edit_symbol`. `old_string` must match exactly once unless `replace_all=true` " +
+                "(line endings follow the file). `include_dependents=false` skips checking the importers. " +
+                WRITE_RULE,
+            inputSchema: {
+                file_path: z.string().optional(),
+                old_string: z.string().optional(),
+                new_string: z.string().optional(),
+                replace_all: z.boolean().default(false),
+                new_text: z.string().optional(),
+                include_dependents: z.boolean().default(true),
+                ...writeParams,
+            },
+            run: async ({ max_new_errors, ...a }) => webnav.edit({
+                filePath: a.file_path,
+                oldString: a.old_string,
+                newString: a.new_string,
+                replaceAll: a.replace_all,
+                newText: a.new_text,
+                includeDependents: a.include_dependents,
+                apply: a.apply,
+                maxNewErrors: max_new_errors,
+            }),
+            annotations: WRITES,
+            writes: true,
+        }),
+        tool("edit_symbol", {
+            description: "Replace, add or delete a JS/TS function, class, interface, enum, const or member by name. Examples: " +
+                '`edit_symbol(action="replace", name="Cart.total", source="total(): number { ... }")`, ' +
+                '`edit_symbol(action="insert", file_path="src/utils.ts", name="parse", source="function helper() {}")`, ' +
+                '`edit_symbol(action="delete", name="legacyParse")`.\n\n' +
+                '- `action="replace"`: `name` (dotted `Class.method` ok) and `source` (the complete new definition, ' +
+                "decorators included; re-indented to the old one's place in the file's own indent style). The doc comment " +
+                "above is kept unless `source` brings its own. A changed signature shows up as errors at call sites.\n" +
+                '- `action="insert"`: `source` and `file_path`. `position` is relative to `name`: "after" (default when ' +
+                '`name` is given) / "before" a symbol, "into" a class/interface/enum/namespace (appended to its body), or ' +
+                '"end" of the file (default without `name`; creates the file if missing). Refuses a name that already exists there.\n' +
+                '- `action="delete"`: `name` only. Refuses while anything still uses it and lists the users (`force=true` ' +
+                "deletes anyway and shows what breaks). Imports only the deleted code used are removed (`prune_imports`). " +
+                "Strings, comments and docs naming it are listed and the deletion is previewed instead of applied.\n\n" +
+                "`file_path` narrows `name` when several symbols share it. `imports` (replace/insert) is a list of " +
+                'import statements the new code needs (`["import { Money } from \\"./money\\""]`), merged into the file if missing. ' +
+                WRITE_RULE,
+            inputSchema: {
+                action: z.enum(["replace", "insert", "delete"]).optional(),
+                name: z.string().optional(),
+                source: z.string().optional(),
+                file_path: z.string().optional(),
+                position: z.enum(["after", "before", "into", "end"]).optional(),
+                imports: z.array(z.string()).optional(),
+                force: z.boolean().default(false),
+                prune_imports: z.boolean().default(true),
+                ...writeParams,
+            },
+            run: async ({ max_new_errors, ...a }) => webnav.editSymbol({
+                action: a.action,
+                name: a.name,
+                source: a.source,
+                filePath: a.file_path,
+                position: a.position,
+                imports: a.imports,
+                force: a.force,
+                pruneImports: a.prune_imports,
+                apply: a.apply,
+                maxNewErrors: max_new_errors,
+            }),
+            annotations: WRITES,
+            writes: true,
+        }),
+        tool("rename_symbol", {
+            description: 'Rename a symbol everywhere it is used. Examples: `rename_symbol(name="Cart.total", new_name="sum")`, ' +
+                '`rename_symbol(name="--accent", new_name="--brand")`, `rename_symbol(name=".card-title", new_name="heading")`.\n\n' +
+                "JS/TS: give `name` (dotted `Class.method` ok; `file_path` narrows it) or `file_path` + `line` + `column` " +
+                "(1-indexed). Built on the TypeScript language server's rename (imports, aliases, overriding members); " +
+                '`parameter="x"` with a function\'s name renames one parameter. Places that still say the old name that ' +
+                "the type checker cannot link (strings, comments, docs, other languages) are listed.\n\n" +
+                "CSS/HTML: a `name` starting with `--`, `#` or `.` renames that custom property / id / class across " +
+                "stylesheets (declarations, `var()`, selectors), HTML (`class`, `id`, and the attributes that refer to ids: " +
+                '`for`, `aria-*`, `href="#id"`) and scripts (`getElementById`, `classList`, `querySelector`, `className`, ' +
+                '`setProperty`/`getPropertyValue`, markup inside strings). Names built dynamically (`"row-" + id`) are listed, ' +
+                "not renamed; script string literals that merely equal the name are listed and renamed only with " +
+                "`include_string_literals=true`. Refuses a new name that already exists (`force=true` merges). With several " +
+                "`WEBNAV_MCP_ROOTS` pass `file_path` to say which root. " +
+                WRITE_RULE,
+            inputSchema: {
+                new_name: z.string().optional(),
+                name: z.string().optional(),
+                file_path: z.string().optional(),
+                line: z.number().int().optional(),
+                column: z.number().int().optional(),
+                parameter: z.string().optional(),
+                force: z.boolean().default(false),
+                include_string_literals: z.boolean().default(false),
+                allow_large: z.boolean().default(false),
+                ...writeParams,
+            },
+            run: async ({ max_new_errors, ...a }) => webnav.renameSymbol({
+                newName: a.new_name,
+                name: a.name,
+                filePath: a.file_path,
+                line: a.line,
+                column: a.column,
+                parameter: a.parameter,
+                force: a.force,
+                includeStringLiterals: a.include_string_literals,
+                allowLarge: a.allow_large,
+                apply: a.apply,
+                maxNewErrors: max_new_errors,
+            }),
+            annotations: WRITES,
+            writes: true,
+        }),
+        tool("move", {
+            description: "Move a declaration to another file, or a whole file, and fix every reference. Examples: " +
+                '`move(name="parseDate", to_file="src/app/dates.ts")`, `move(file_path="src/old/util.ts", to_file="src/lib/util.ts")`.\n\n' +
+                "With `name`: moves that top-level function/class/interface/enum/type/const (`file_path` narrows which). " +
+                "The destination is created if missing; the code gets the imports it needs (found by the language server), " +
+                '`export` is added if it was private, every `import { name } from "old"` elsewhere is repointed, the old ' +
+                "file imports it from the new place if it still uses it (`keep_reexport=true` also leaves `export { name } " +
+                'from "new"`), and imports only the moved code used are dropped. Import cycles are warned about.\n\n' +
+                "Without `name`: `file_path` is the file to move or rename (any file; `to_file` may be a directory). Every " +
+                "import/re-export in JS/TS (the language server's own rewrite), `<script src>`/`<link href>`/`<img src>` in " +
+                "HTML (relative and root-absolute), and `url()`/`@import` in CSS follow, and the moved file's own relative " +
+                "references are re-based. Configs, path aliases and string paths are listed, not rewritten. " +
+                WRITE_RULE,
+            inputSchema: {
+                to_file: z.string().optional(),
+                name: z.string().optional(),
+                file_path: z.string().optional(),
+                keep_reexport: z.boolean().default(false),
+                allow_large: z.boolean().default(false),
+                ...writeParams,
+            },
+            run: async ({ max_new_errors, ...a }) => webnav.move({
+                toFile: a.to_file,
+                name: a.name,
+                filePath: a.file_path,
+                keepReexport: a.keep_reexport,
+                allowLarge: a.allow_large,
+                apply: a.apply,
+                maxNewErrors: max_new_errors,
+            }),
+            annotations: WRITES,
+            writes: true,
+        }),
+        tool("quick_fix", {
+            description: 'Apply the TypeScript language server\'s own fixes to a JS/TS file: `quick_fix(file_path="src/app.ts")`.\n\n' +
+                "`action=\"fix\"` (default) fixes the file's errors one by one with the server's code actions (missing " +
+                "imports, misspelled names, ...), re-checking after each; `line` limits it to errors starting on that line. " +
+                "A fix with several candidates is listed, not guessed. The other actions are source actions on the whole " +
+                "file: `organize_imports`, `remove_unused_imports`, `sort_imports`, `fix_all`. " +
+                WRITE_RULE,
+            inputSchema: {
+                file_path: z.string().optional(),
+                line: z.number().int().optional(),
+                action: z.enum(["fix", "organize_imports", "remove_unused_imports", "sort_imports", "fix_all"]).optional(),
+                ...writeParams,
+            },
+            run: async ({ max_new_errors, ...a }) => webnav.quickFix({
+                filePath: a.file_path,
+                line: a.line,
+                action: a.action,
+                apply: a.apply,
+                maxNewErrors: max_new_errors,
+            }),
+            annotations: WRITES,
+            writes: true,
+        }),
+        tool("verify_changes", {
+            description: "What did the edits since a git revision break? Compares the language servers' diagnostics now against " +
+                "`since` (default `HEAD`).\n\nRun it after editing with any tool (your own Edit/Write included): the " +
+                "changed JS/TS/HTML/CSS files and the script files importing them are checked, with the committed versions " +
+                'substituted in for the "before" side. Read-only.',
+            inputSchema: { since: z.string().default("HEAD"), include_dependents: z.boolean().default(true) },
+            run: async ({ since, include_dependents }) => webnav.verifyChanges({ since, includeDependents: include_dependents }),
+            annotations: READS,
+            writes: false,
+        }),
+        tool("apply_edit", {
+            description: "Write a previewed edit (the id comes from a write tool's preview). Fails, writing nothing, if any file " +
+                "changed since the preview.",
+            inputSchema: { id: z.string().optional(), allow_large: z.boolean().default(false) },
+            run: async ({ id, allow_large }) => webnav.applyEdit(id ?? "", allow_large),
+            annotations: WRITES,
+            writes: true,
+        }),
+        tool("undo_edit", {
+            description: "Revert an edit applied by the write tools (the latest one by default). Refuses when any of its files " +
+                "changed after the edit, so later work is never overwritten.",
+            inputSchema: { id: z.string().optional() },
+            run: async ({ id }) => webnav.undoEdit(id),
+            annotations: WRITES,
+            writes: true,
+        }),
+        // Last: the batch can reach every tool registered above and carries the strictest hints of them.
+        tool("batch", {
+            description: BATCH_DESCRIPTION,
+            inputSchema: {
+                calls: z.array(z.record(z.string(), z.unknown())),
+                stop_on_error: z.boolean().nullable().optional(),
+            },
+            run: ({ calls, stop_on_error }) => runBatch(calls, stop_on_error, registry),
+            annotations: WRITES,
+            writes: true,
+        }),
+    ];
+    for (const spec of specs) {
+        server.registerTool(spec.name, {
+            description: spec.description,
+            inputSchema: spec.inputSchema,
+            annotations: spec.annotations,
+        }, async (args) => text(await spec.run(args)));
+        if (spec.name !== "batch") {
+            registry.set(spec.name, spec);
+        }
+    }
     return { server, webnav };
 }
-function registerWriteTools(server, webnav) {
-    server.registerTool("edit", {
-        description: 'Edit text in a JS/TS/HTML/CSS file, type-checked: `edit(file_path="src/app.ts", old_string="x = 1", new_string="x = 2")`.\n\n' +
-            "For changes that are not a whole definition (a few lines, an import, a rule, markup) or for rewriting a " +
-            "whole file (`new_text`, which also creates a new file). To replace, add or delete a function/class/method " +
-            "by name use `edit_symbol`. `old_string` must match exactly once unless `replace_all=true` " +
-            "(line endings follow the file). `include_dependents=false` skips checking the importers. " +
-            WRITE_RULE,
-        inputSchema: {
-            file_path: z.string().optional(),
-            old_string: z.string().optional(),
-            new_string: z.string().optional(),
-            replace_all: z.boolean().default(false),
-            new_text: z.string().optional(),
-            include_dependents: z.boolean().default(true),
-            ...writeParams,
-        },
-        annotations: WRITES,
-    }, async ({ max_new_errors, ...a }) => text(await webnav.edit({
-        filePath: a.file_path,
-        oldString: a.old_string,
-        newString: a.new_string,
-        replaceAll: a.replace_all,
-        newText: a.new_text,
-        includeDependents: a.include_dependents,
-        apply: a.apply,
-        maxNewErrors: max_new_errors,
-    })));
-    server.registerTool("edit_symbol", {
-        description: "Replace, add or delete a JS/TS function, class, interface, enum, const or member by name. Examples: " +
-            '`edit_symbol(action="replace", name="Cart.total", source="total(): number { ... }")`, ' +
-            '`edit_symbol(action="insert", file_path="src/utils.ts", name="parse", source="function helper() {}")`, ' +
-            '`edit_symbol(action="delete", name="legacyParse")`.\n\n' +
-            '- `action="replace"`: `name` (dotted `Class.method` ok) and `source` (the complete new definition, ' +
-            "decorators included; re-indented to the old one's place in the file's own indent style). The doc comment " +
-            "above is kept unless `source` brings its own. A changed signature shows up as errors at call sites.\n" +
-            '- `action="insert"`: `source` and `file_path`. `position` is relative to `name`: "after" (default when ' +
-            '`name` is given) / "before" a symbol, "into" a class/interface/enum/namespace (appended to its body), or ' +
-            '"end" of the file (default without `name`; creates the file if missing). Refuses a name that already exists there.\n' +
-            '- `action="delete"`: `name` only. Refuses while anything still uses it and lists the users (`force=true` ' +
-            "deletes anyway and shows what breaks). Imports only the deleted code used are removed (`prune_imports`). " +
-            "Strings, comments and docs naming it are listed and the deletion is previewed instead of applied.\n\n" +
-            "`file_path` narrows `name` when several symbols share it. `imports` (replace/insert) is a list of " +
-            'import statements the new code needs (`["import { Money } from \\"./money\\""]`), merged into the file if missing. ' +
-            WRITE_RULE,
-        inputSchema: {
-            action: z.enum(["replace", "insert", "delete"]).optional(),
-            name: z.string().optional(),
-            source: z.string().optional(),
-            file_path: z.string().optional(),
-            position: z.enum(["after", "before", "into", "end"]).optional(),
-            imports: z.array(z.string()).optional(),
-            force: z.boolean().default(false),
-            prune_imports: z.boolean().default(true),
-            ...writeParams,
-        },
-        annotations: WRITES,
-    }, async ({ max_new_errors, ...a }) => text(await webnav.editSymbol({
-        action: a.action,
-        name: a.name,
-        source: a.source,
-        filePath: a.file_path,
-        position: a.position,
-        imports: a.imports,
-        force: a.force,
-        pruneImports: a.prune_imports,
-        apply: a.apply,
-        maxNewErrors: max_new_errors,
-    })));
-    server.registerTool("rename_symbol", {
-        description: 'Rename a symbol everywhere it is used. Examples: `rename_symbol(name="Cart.total", new_name="sum")`, ' +
-            '`rename_symbol(name="--accent", new_name="--brand")`, `rename_symbol(name=".card-title", new_name="heading")`.\n\n' +
-            "JS/TS: give `name` (dotted `Class.method` ok; `file_path` narrows it) or `file_path` + `line` + `column` " +
-            "(1-indexed). Built on the TypeScript language server's rename (imports, aliases, overriding members); " +
-            '`parameter="x"` with a function\'s name renames one parameter. Places that still say the old name that ' +
-            "the type checker cannot link (strings, comments, docs, other languages) are listed.\n\n" +
-            "CSS/HTML: a `name` starting with `--`, `#` or `.` renames that custom property / id / class across " +
-            "stylesheets (declarations, `var()`, selectors), HTML (`class`, `id`, and the attributes that refer to ids: " +
-            '`for`, `aria-*`, `href="#id"`) and scripts (`getElementById`, `classList`, `querySelector`, `className`, ' +
-            '`setProperty`/`getPropertyValue`, markup inside strings). Names built dynamically (`"row-" + id`) are listed, ' +
-            "not renamed; script string literals that merely equal the name are listed and renamed only with " +
-            "`include_string_literals=true`. Refuses a new name that already exists (`force=true` merges). With several " +
-            "`WEBNAV_MCP_ROOTS` pass `file_path` to say which root. " +
-            WRITE_RULE,
-        inputSchema: {
-            new_name: z.string().optional(),
-            name: z.string().optional(),
-            file_path: z.string().optional(),
-            line: z.number().int().optional(),
-            column: z.number().int().optional(),
-            parameter: z.string().optional(),
-            force: z.boolean().default(false),
-            include_string_literals: z.boolean().default(false),
-            allow_large: z.boolean().default(false),
-            ...writeParams,
-        },
-        annotations: WRITES,
-    }, async ({ max_new_errors, ...a }) => text(await webnav.renameSymbol({
-        newName: a.new_name,
-        name: a.name,
-        filePath: a.file_path,
-        line: a.line,
-        column: a.column,
-        parameter: a.parameter,
-        force: a.force,
-        includeStringLiterals: a.include_string_literals,
-        allowLarge: a.allow_large,
-        apply: a.apply,
-        maxNewErrors: max_new_errors,
-    })));
-    server.registerTool("move", {
-        description: "Move a declaration to another file, or a whole file, and fix every reference. Examples: " +
-            '`move(name="parseDate", to_file="src/app/dates.ts")`, `move(file_path="src/old/util.ts", to_file="src/lib/util.ts")`.\n\n' +
-            "With `name`: moves that top-level function/class/interface/enum/type/const (`file_path` narrows which). " +
-            "The destination is created if missing; the code gets the imports it needs (found by the language server), " +
-            '`export` is added if it was private, every `import { name } from "old"` elsewhere is repointed, the old ' +
-            "file imports it from the new place if it still uses it (`keep_reexport=true` also leaves `export { name } " +
-            'from "new"`), and imports only the moved code used are dropped. Import cycles are warned about.\n\n' +
-            "Without `name`: `file_path` is the file to move or rename (any file; `to_file` may be a directory). Every " +
-            "import/re-export in JS/TS (the language server's own rewrite), `<script src>`/`<link href>`/`<img src>` in " +
-            "HTML (relative and root-absolute), and `url()`/`@import` in CSS follow, and the moved file's own relative " +
-            "references are re-based. Configs, path aliases and string paths are listed, not rewritten. " +
-            WRITE_RULE,
-        inputSchema: {
-            to_file: z.string().optional(),
-            name: z.string().optional(),
-            file_path: z.string().optional(),
-            keep_reexport: z.boolean().default(false),
-            allow_large: z.boolean().default(false),
-            ...writeParams,
-        },
-        annotations: WRITES,
-    }, async ({ max_new_errors, ...a }) => text(await webnav.move({
-        toFile: a.to_file,
-        name: a.name,
-        filePath: a.file_path,
-        keepReexport: a.keep_reexport,
-        allowLarge: a.allow_large,
-        apply: a.apply,
-        maxNewErrors: max_new_errors,
-    })));
-    server.registerTool("quick_fix", {
-        description: 'Apply the TypeScript language server\'s own fixes to a JS/TS file: `quick_fix(file_path="src/app.ts")`.\n\n' +
-            "`action=\"fix\"` (default) fixes the file's errors one by one with the server's code actions (missing " +
-            "imports, misspelled names, ...), re-checking after each; `line` limits it to errors starting on that line. " +
-            "A fix with several candidates is listed, not guessed. The other actions are source actions on the whole " +
-            "file: `organize_imports`, `remove_unused_imports`, `sort_imports`, `fix_all`. " +
-            WRITE_RULE,
-        inputSchema: {
-            file_path: z.string().optional(),
-            line: z.number().int().optional(),
-            action: z.enum(["fix", "organize_imports", "remove_unused_imports", "sort_imports", "fix_all"]).optional(),
-            ...writeParams,
-        },
-        annotations: WRITES,
-    }, async ({ max_new_errors, ...a }) => text(await webnav.quickFix({
-        filePath: a.file_path,
-        line: a.line,
-        action: a.action,
-        apply: a.apply,
-        maxNewErrors: max_new_errors,
-    })));
-    server.registerTool("verify_changes", {
-        description: "What did the edits since a git revision break? Compares the language servers' diagnostics now against " +
-            "`since` (default `HEAD`).\n\nRun it after editing with any tool (your own Edit/Write included): the " +
-            "changed JS/TS/HTML/CSS files and the script files importing them are checked, with the committed versions " +
-            'substituted in for the "before" side. Read-only.',
-        inputSchema: { since: z.string().default("HEAD"), include_dependents: z.boolean().default(true) },
-        annotations: READS,
-    }, async ({ since, include_dependents }) => text(await webnav.verifyChanges({ since, includeDependents: include_dependents })));
-    server.registerTool("apply_edit", {
-        description: "Write a previewed edit (the id comes from a write tool's preview). Fails, writing nothing, if any file " +
-            "changed since the preview.",
-        inputSchema: { id: z.string().optional(), allow_large: z.boolean().default(false) },
-        annotations: WRITES,
-    }, async ({ id, allow_large }) => text(await webnav.applyEdit(id ?? "", allow_large)));
-    server.registerTool("undo_edit", {
-        description: "Revert an edit applied by the write tools (the latest one by default). Refuses when any of its files " +
-            "changed after the edit, so later work is never overwritten.",
-        inputSchema: { id: z.string().optional() },
-        annotations: WRITES,
-    }, async ({ id }) => text(await webnav.undoEdit(id)));
-}

package/dist/webnav.js

@@ -71,7 +71,9 @@ export const INSTRUCTIONS = "Code navigation for this project's JS/TS/HTML/CSS,
     ".classes), move (a declaration or a file), quick_fix. They type-check the " +
     "edit before writing and write it when it adds no errors (max_new_errors=0; " +
     "apply=false only previews); verify_changes shows what the working tree " +
-    `broke, undo_edit reverts. ${POSITION_NOTE}`;
+    "broke, undo_edit reverts. To read or change several files or symbols, send them as " +
+    "one batch(calls=[{tool, args}, ...]) instead of many separate calls. " +
+    POSITION_NOTE;
 export class Webnav {
     selector = new WorkspaceSelector("WEBNAV_MCP_WORKSPACE");
     notices;

package/dist/write/fixTools.js

@@ -126,9 +126,12 @@ export async function quickFix(host, args) {
             notes.push(`not fixed: ${(d.range?.start?.line ?? 0) + 1}:${(d.range?.start?.character ?? 0) + 1} ${d.message?.split("\n")[0]} (${u.why})`);
         }
         if (result.applied.length === 0) {
+            // Start with "No changes" so `batch` classifies the no-op as ok (see its WRITE_OK_MARKERS).
             return result.unfixed.length === 0
-                ? `${rel}${args.line ? `:${args.line}` : ""} has no errors to fix.`
-                : `${title}\n${notes.map((n) => `  - ${n}`).join("\n")}`;
+                ? `No changes: ${rel}${args.line ? `:${args.line}` : ""} has no errors to fix.`
+                : `No changes: quick fix in ${rel}${args.line ? ` (line ${args.line})` : ""} applied 0 fix(es).\n${notes
+                    .map((n) => `  - ${n}`)
+                    .join("\n")}`;
         }
     }
     else {
@@ -140,7 +143,7 @@ export async function quickFix(host, args) {
         const edits = chosen && editsForFile(chosen, file, text);
         title = `${chosen?.title ?? action} in ${rel}`;
         if (!chosen || !edits) {
-            return `The language server offers nothing for ${action} in ${rel}.`;
+            return `No changes: the language server offers nothing for ${action} in ${rel}.`;
         }
         next = applyEdits(text, edits);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "webnav-ts-mcp",
-	"version": "0.2.0",
+	"version": "0.3.0",
 	"description": "MCP server exposing JS/TS/HTML/CSS language-server features plus a workspace-wide CSS custom-property/selector index as MCP tools. TypeScript port of the Python webnav-mcp.",
 	"keywords": [
 		"mcp",