webnav-ts-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel Illescas Romero
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,257 @@
+# webnav-ts-mcp
+
+An MCP server that gives AI agents JS/TS/HTML/CSS navigation, plus a
+cross-file index of CSS custom properties and `#id`/`.class` selectors that
+single-file language servers can't provide. It is the TypeScript port of the
+Python [`webnav-mcp`](https://pypi.org/project/webnav-mcp/), so a web project can
+add it with its own package manager and have no Python or `uv` in the chain.
+
+## Quick start
+
+You need Node.js ≥ 20:
+
+```bash
+npx webnav-ts-mcp
+```
+
+Register it with your MCP host. For Claude Code, from the project root:
+
+```bash
+claude mcp add webnav -- npx webnav-ts-mcp
+```
+
+Or add it to a project `.mcp.json` (Claude Code) or `.cursor/mcp.json` (Cursor):
+
+```json
+{
+	"mcpServers": {
+		"webnav": {
+			"command": "npx",
+			"args": ["webnav-ts-mcp"]
+		}
+	}
+}
+```
+
+In Cursor, also set `"env": {"WEBNAV_MCP_WORKSPACE": "${workspaceFolder}"}`,
+because Cursor may start MCP servers with your home directory as the working
+directory.
+
+To pin it per project instead of resolving through `npx` each time:
+
+```bash
+npm install --save-dev webnav-ts-mcp
+```
+
+## Language servers
+
+Requests are routed to three Node language servers by file extension:
+
+| Extension | Backend |
+|-----------|---------|
+| `.js` / `.mjs` / `.cjs` / `.jsx` / `.ts` / `.mts` / `.cts` / `.tsx` | TypeScript 7 native LSP: `tsc --lsp --stdio` (JS via `allowJs` / `jsconfig.json`) |
+| `.html` | `vscode-html-language-server` |
+| `.css` | `vscode-css-language-server` |
+
+They are ordinary npm dependencies, so nothing is downloaded at runtime. A
+TypeScript ≥ 7 in the navigated project wins; otherwise the copy installed with
+webnav-ts-mcp is used. (An app on an older TypeScript still works, at the cost of
+the extra install size: see [Costs](#costs).)
+
+## Tools
+
+**For JS/TS, start with the name-based tools:**
+
+| Tool | Answers |
+|------|---------|
+| `symbol_info` | What is this? Header, hover, definition and references in one call |
+| `outline` | What's in this file? (source order; locals and imports left out unless `detailed=true`) |
+| `callers` | Who calls this function/method? (call hierarchy) |
+| `implementations` | Who implements/extends this interface, class or method? |
+| `search_symbol` | JS/TS workspace symbol search (ranked, capped; optional `kind=` / `path=` filters) |
+| `workspace` | Which directory is being navigated, and why |
+
+Then use the position tools once you have a `path:line:col`:
+
+| Tool | Answers |
+|------|---------|
+| `hover` | Type and docs at a position |
+| `definition` | Go to definition (CSS/HTML tokens answer from the index below) |
+| `references` | All usages (CSS/HTML tokens answer from the index below) |
+| `diagnostics` | Language-server diagnostics; CSS/HTML also get unreferenced-selector and undefined-variable warnings |
+
+**Cross-file CSS/HTML index:**
+
+| Tool | Answers |
+|------|---------|
+| `css_var` | Where is `--name` defined and used? |
+| `selector` | Where is `#id` or `.class` defined and used (CSS, HTML, JS)? |
+
+`search_symbol`, `symbol_info`, `outline`, `callers` and `implementations` are
+**JS/TS only**. Use `css_var` and `selector` for markup and stylesheets.
+`name` and `query` are accepted as aliases of each other on the name-based tools.
+Positions are **1-indexed**; `column` is a UTF-16 character offset (a leading
+tab counts as one character).
+
+## Environment
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `WEBNAV_MCP_WORKSPACE` | unset: follows the client's MCP roots when they name a worktree of the same git repository, else `CLAUDE_PROJECT_DIR`, else the working directory | Pins the project root (never overridden). See the `workspace` tool |
+| `WEBNAV_MCP_ROOTS` | the whole workspace as one root, labelled `web` | Comma-separated `label=relative/path` pairs to index separately, e.g. `app=src,prototypes=design` |
+| `WEBNAV_MCP_EXCLUDE` | nothing | Comma-separated workspace-relative paths of generated script output (e.g. the JS a TS build emits). Not opened, hidden from `search_symbol`, rejected by the position tools; the CSS/selector index still reads them |
+
+Tool names, parameter names and environment variables are identical to the
+Python package, so existing prompts, hosts and configs keep working.
+
+## Differences from the Python package
+
+| | Python `webnav-mcp` | webnav-ts-mcp |
+|---|---|---|
+| Runtime | Python ≥ 3.11 **and** Node ≥ 18 | Node ≥ 20 only (tested on 22) |
+| Language servers | found in the project's `node_modules`, then the package dir, then `PATH`, then `npx --yes` (downloads at first use) | ordinary npm dependencies: a TypeScript ≥ 7 in the *project* wins, else the copy installed with webnav. Nothing is downloaded at runtime |
+| Launch | `.bin` shims (`.cmd` special case on Windows) | `node <server>.js`, no shims, no `PATH` dependence |
+| JSON-RPC framing | hand-written | [`vscode-jsonrpc`](https://www.npmjs.com/package/vscode-jsonrpc) |
+| UTF-16 columns | encode/decode helpers | JS strings already are UTF-16 |
+| Cold start (init handshake) | ~530 ms | ~100 ms (see [Speed](#speed)) |
+
+## Layout
+
+```
+src/
+  cli.ts          stdio entry point (exits when the host closes stdin)
+  server.ts       registers the twelve tools on the MCP SDK
+  webnav.ts       the tools as plain async functions returning text; owns all state
+  webIndex.ts     CSS var / selector index (port of web_index.py)
+  langCommand.ts  how to launch tsc / html / css language servers
+  glob.ts         just enough glob for jsconfig `include`
+  shared/         port of mcp_nav_shared: lspClient, format, resolve, workspace,
+                  notices, errors, params, exclude
+tests/            vitest; fixtures/sample-app is the shared fixture
+scripts/parity.mjs  drives Python and TS servers side by side and diffs the output
+```
+
+`shared/` is deliberately a directory, not a second package: see
+[Shared library](#the-shared-library).
+
+## Development
+
+```bash
+npm install
+npm run check     # biome + tsc + vitest (pretest builds dist/)
+npm run bench     # speed/memory vs the Python package (same sibling checkout requirement)
+npm run parity    # needs the Python webnav-mcp checked out at ../webnav-mcp with `uv sync`; see the script header
+node bin/launch.mjs   # checkout launcher: installs + builds when needed, then starts the server
+```
+
+Source: [github.com/illescasDaniel/webnav-ts-mcp](https://github.com/illescasDaniel/webnav-ts-mcp).
+
+## Speed
+
+Measured with `npm run bench` on Linux (Node 24, Python venv binary started directly so `uv`'s ~20 ms
+is excluded), real MCP over stdio against a real web project (SpaceMaker: 3 roots, ~60 JS/TS/CSS/HTML
+files, a 3k-line wireframe), median of 7 alternating runs, 15 warm calls per tool:
+
+| Metric | Python | TypeScript | |
+|---|---|---|---|
+| Cold start (spawn → `initialize`) | 528 ms | 103 ms | 5.1× |
+| First `symbol_info` (spawns `tsc` LSP) | 717 ms | 106 ms | 6.7× |
+| First HTML `diagnostics` (spawns HTML server) | 1197 ms | 978 ms | 1.2× |
+| Warm `symbol_info` / `references` / `hover` | 8.3 / 7.9 / 7.2 ms | 4.4 / 3.6 / 2.7 ms | ~2× |
+| Warm `outline` / `search_symbol` | 7.1 / 8.7 ms | 2.0 / 4.0 ms | 2–3.5× |
+| Warm `css_var` / `selector` (own index) | 2.6 / 2.6 ms | 0.5 / 0.7 ms | 4–5× |
+| Whole session (connect + every tool once + 15 warm calls each) | 3.5 s | 1.6 s | 2.2× |
+| Memory, server + language servers | 477 MiB | 359 MiB | 1.3× |
+| Shutdown after stdin closes | 61 ms | 13 ms | 4.6× |
+
+Warm calls are dominated by the language servers, which are identical in both, so the gap there is
+the fixed cost of the MCP layer. Launching through `npx webnav-ts-mcp` adds roughly 0.2 s to the
+cold start (npm resolving the `.bin` shim); a locally installed copy started with `node` does not.
+
+## Notes from the port
+
+`webnav` is glue: it spawns three Node language servers and formats their answers,
+plus a regex-grade index. Nothing in it depends on Python. The MCP SDK, the LSP
+plumbing and the file scanning all have first-class Node equivalents.
+
+**Behavioural parity**, measured by `scripts/parity.mjs` (real MCP over stdio,
+identical calls, diffed text):
+
+- A real web project ([SpaceMaker](https://github.com/illescasDaniel/SpaceMaker)'s assets, three roots): **37 / 37 identical**
+- `tests/fixtures/sample-app`, including edits behind the servers' backs (fix a
+  type error, create/delete a file, change a stylesheet, change `jsconfig.json`
+  and get the restart notice): **71 / 71 identical** (counting the one intentional
+  inherited-member difference below)
+
+The one intentional difference is the reason string of "Cannot read file as
+UTF-8 text: …", which is a Python codec detail; the parity script masks it.
+
+**Tests:** 152 vitest tests (unit ports of the index/format tests, real
+language servers against the fixture, MCP protocol over an in-memory transport
+incl. worktree selection via client roots with a real `git worktree`, LSP
+client failure modes, and the built executable). The Python side has ~260 tests
+across the two packages; the port covers the behaviour that matters for the
+tools, not every case one-to-one.
+
+### Things the port surfaced
+
+- **The MCP SDK's stdio server does not treat stdin EOF as a close.** With a
+  language server child alive, the process kept running after the host went
+  away (found by installing the tarball and launching via `npx`). `cli.ts` now
+  handles `stdin` `end`/`close`; `tests/cli.test.ts` fails without it.
+- **UTF-16 handling gets simpler:** JS strings are UTF-16, so the column
+  conversion helpers in the Python `format.py`/`lsp_client.py` disappear.
+- **One known regex divergence:** Python's `\w` is Unicode-aware, JS's is ASCII.
+  The index regexes use `(?<![\w-])` to avoid matching `data-id=`; a non-ASCII
+  letter directly before `id=`/`class=`/`style=` is treated differently (a
+  match in JS, none in Python). Vanishingly rare in real markup, not covered by
+  parity fixtures.
+- **Inherited-member lookup needed a different approach.** The Python package
+  finds `Class.member` for a member declared on a base class through the LSP's
+  type hierarchy, but TypeScript 7's language server advertises no type
+  hierarchy (checked against its `initialize` capabilities), so
+  `symbol_info("Widget.greet")` used to say "not found" in both implementations.
+  This port reads the `extends`/`implements` clauses from the source and resolves
+  each base with `textDocument/definition`, breadth-first across files (generic
+  bases, qualified names and mixin calls handled; `.d.ts`/`node_modules` bases
+  aren't followed). It is the one intentional difference the parity script
+  shows.
+- **Two tools the Python webnav never had:** the same capability check showed the
+  server offers `callHierarchyProvider` and `implementationProvider`, so this
+  port adds `callers` and `implementations` (12 tools now; the Python one has 10).
+
+### Costs
+
+- **Install size:** a fresh app installing this next to its own TypeScript 5:
+  177 MB `node_modules` (`vscode-langservers-extracted` 66 MB, TypeScript 7
+  ~50 MB with its native binary). An app already on TypeScript ≥ 7 shares that
+  copy. The Python package had the same npm payload, plus Python.
+- **Code size:** ~4.2k lines of TypeScript (2.3k of it in `shared/`) vs ~3.7k
+  lines of Python for webnav + the shared library (which also carries
+  codenav-only code that wasn't ported).
+- **Not ported** (codenav-only in the shared library): `typeDefinition`,
+  scratch documents, source-root helpers. (Call hierarchy was ported after all,
+  for `callers`.)
+- **Not verified:** Windows, macOS, Node 20/24. Only Linux + Node 22.
+
+### The shared library
+
+The user-visible downside of the port is that `mcp-nav-shared` (LSP client,
+formatting, symbol resolution, workspace selection) now exists twice. Options,
+roughly in order of effort:
+
+1. **Keep `src/shared/` internal to the TS package** (what this package does).
+   Zero coordination cost; the two copies can drift. Mitigated by
+   `scripts/parity.mjs`, which fails when their output diverges.
+2. **Publish it as its own npm package** (`mcp-nav-shared`) only if a second TS
+   server appears. `codenav` is tied to `ty` (Python) and has no reason to move.
+3. **Retire the Python `webnav-mcp`** and keep only the TS one, leaving
+   `mcp-nav-shared` for `codenav-mcp` alone. Removes the duplication, breaks
+   `uvx webnav-mcp` users.
+
+The Python shared library's webnav-relevant part is small (LSP client, format,
+resolve, workspace, notices), which is why the duplication is tolerable.
+
+## License
+
+MIT. See [LICENSE](https://github.com/illescasDaniel/webnav-ts-mcp/blob/main/LICENSE).

package/dist/cli.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+/** Console entry point: serve over stdio. */
+import fs from "node:fs";
+import { fileURLToPath } from "node:url";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createServer } from "./server.js";
+function packageVersion() {
+    try {
+        const url = new URL("../package.json", import.meta.url);
+        return JSON.parse(fs.readFileSync(fileURLToPath(url), "utf8")).version ?? "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+}
+const { server, webnav } = createServer(packageVersion());
+let closing = false;
+async function shutdown(code) {
+    if (closing) {
+        return;
+    }
+    closing = true;
+    await webnav.dispose();
+    process.exit(code);
+}
+process.on("SIGINT", () => void shutdown(0));
+process.on("SIGTERM", () => void shutdown(0));
+server.server.onclose = () => void shutdown(0);
+// The SDK's stdio transport never reports EOF as a close. A host that disconnects
+// (or a wrapper like `npx` that doesn't forward signals) would otherwise leave
+// this process and its language servers running.
+process.stdin.on("end", () => void shutdown(0));
+process.stdin.on("close", () => void shutdown(0));
+await server.connect(new StdioServerTransport());

package/dist/glob.js

@@ -0,0 +1,65 @@
+/** Just enough glob for `jsconfig.json` `include` entries. */
+import fs from "node:fs";
+import path from "node:path";
+import { EXCLUDED_DIR_NAMES } from "./shared/exclude.js";
+import { escapeRegExp } from "./shared/text.js";
+function globToRegExp(pattern) {
+    let out = "";
+    for (let i = 0; i < pattern.length; i++) {
+        const ch = pattern.charAt(i);
+        if (ch === "*" && pattern.charAt(i + 1) === "*") {
+            if (pattern.charAt(i + 2) === "/") {
+                out += "(?:.*/)?";
+                i += 2;
+            }
+            else {
+                out += ".*";
+                i += 1;
+            }
+        }
+        else if (ch === "*") {
+            out += "[^/]*";
+        }
+        else if (ch === "?") {
+            out += "[^/]";
+        }
+        else {
+            out += escapeRegExp(ch);
+        }
+    }
+    return new RegExp(`^${out}$`);
+}
+/** Files under `root` matching a workspace-relative glob (a plain directory name matches everything below it). */
+export function globFiles(root, pattern) {
+    let normalized = pattern.replaceAll("\\", "/").replace(/^\.\//, "").replace(/\/+$/, "");
+    if (!/[*?]/.test(normalized)) {
+        normalized += "/**/*";
+        if (fs.existsSync(path.join(root, pattern)) && fs.statSync(path.join(root, pattern)).isFile()) {
+            return [path.join(root, pattern)];
+        }
+    }
+    const re = globToRegExp(normalized);
+    const matches = [];
+    const walk = (dir, rel) => {
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            const childRel = rel ? `${rel}/${entry.name}` : entry.name;
+            if (entry.isDirectory()) {
+                if (!EXCLUDED_DIR_NAMES.has(entry.name)) {
+                    walk(path.join(dir, entry.name), childRel);
+                }
+            }
+            else if (re.test(childRel)) {
+                matches.push(path.join(dir, entry.name));
+            }
+        }
+    };
+    walk(root, "");
+    return matches;
+}

package/dist/langCommand.js

@@ -0,0 +1,71 @@
+/**
+ * Resolves how to launch the Node-based language servers webnav multiplexes to.
+ *
+ * Unlike the Python distribution, the servers are ordinary npm dependencies of
+ * this package, so there is nothing to download at runtime: a TypeScript 7+
+ * install in the navigated project wins (it matches the project's own
+ * compiler), else the copy that came with webnav. Both are launched through
+ * the current `node` executable rather than `.bin` shims, which sidesteps
+ * `.cmd` handling on Windows and PATH differences under GUI-launched hosts.
+ *
+ * JS/TS uses TypeScript 7's native LSP (`tsc --lsp --stdio`).
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { ToolInputError } from "./shared/errors.js";
+function readPackageJson(dir) {
+    try {
+        return JSON.parse(fs.readFileSync(path.join(dir, "package.json"), "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Directories to look for `node_modules/<pkg>` in: the navigated workspace, then every ancestor of this module (webnav's own install, hoisted or nested). */
+function searchDirs(workspaceRoot) {
+    const dirs = [workspaceRoot];
+    for (let dir = path.dirname(fileURLToPath(import.meta.url));; dir = path.dirname(dir)) {
+        dirs.push(dir);
+        if (path.dirname(dir) === dir) {
+            break;
+        }
+    }
+    return dirs;
+}
+function findPackage(workspaceRoot, name, accept = () => true) {
+    for (const base of searchDirs(workspaceRoot)) {
+        const dir = path.join(base, "node_modules", ...name.split("/"));
+        const pkg = readPackageJson(dir);
+        if (pkg?.name === name && accept(pkg)) {
+            return { dir, pkg };
+        }
+    }
+    return undefined;
+}
+function binPath(dir, pkg, binName) {
+    const bin = typeof pkg.bin === "string" ? pkg.bin : pkg.bin?.[binName];
+    return bin ? path.join(dir, bin) : undefined;
+}
+const isTypescript7 = (pkg) => Number.parseInt((pkg.version ?? "").split(".")[0] ?? "", 10) >= 7;
+/** Launch TypeScript 7's native language server: `tsc --lsp --stdio`. */
+export function resolveTsCommand(workspaceRoot) {
+    const found = findPackage(workspaceRoot, "typescript", isTypescript7);
+    const tsc = found && binPath(found.dir, found.pkg, "tsc");
+    if (!tsc) {
+        throw new ToolInputError("TypeScript 7 (`typescript@^7`) was not found in the workspace or in webnav's own dependencies; " +
+            "reinstall webnav-ts-mcp or run `npm install --save-dev typescript@^7` in the project.");
+    }
+    return [process.execPath, tsc, "--lsp", "--stdio"];
+}
+function resolveLangserver(workspaceRoot, binName) {
+    const found = findPackage(workspaceRoot, "vscode-langservers-extracted");
+    const bin = found && binPath(found.dir, found.pkg, binName);
+    if (!bin) {
+        throw new ToolInputError("`vscode-langservers-extracted` was not found in the workspace or in webnav's own dependencies; " +
+            "reinstall webnav-ts-mcp or run `npm install --save-dev vscode-langservers-extracted` in the project.");
+    }
+    return [process.execPath, bin, "--stdio"];
+}
+export const resolveHtmlCommand = (workspaceRoot) => resolveLangserver(workspaceRoot, "vscode-html-language-server");
+export const resolveCssCommand = (workspaceRoot) => resolveLangserver(workspaceRoot, "vscode-css-language-server");

package/dist/outlineImports.js

@@ -0,0 +1,46 @@
+/**
+ * Keeps import bindings out of `outline`. TypeScript's language server reports every
+ * imported name as a top-level `Variable`, which drowns the file's own structure; the
+ * statements are found in the source text, so a name imported over several lines is
+ * hidden too. `outline(detailed=true)` still lists them.
+ */
+import { splitLines } from "./shared/text.js";
+// A statement's last line ends in the module specifier (optionally followed by an import attribute).
+const ENDS_WITH_SPECIFIER = /["'][^"']*["']\s*(?:(?:with|assert)\s*\{[^}]*\}\s*)?;?\s*(?:\/\/.*)?$/;
+const IMPORT_EQUALS = /^import\s+(?:type\s+)?[\w$]+\s*=/;
+const MAX_IMPORT_LINES = 500;
+/** 0-based lines covered by top-level `import` statements. */
+export function importLines(source) {
+    const lines = splitLines(source);
+    const covered = new Set();
+    for (let i = 0; i < lines.length; i++) {
+        if (!/^import\b/.test(lines[i] ?? "")) {
+            continue;
+        }
+        let end = i;
+        if (!(IMPORT_EQUALS.test(lines[i] ?? "") && !/["']/.test(lines[i] ?? ""))) {
+            while (end < lines.length && end - i < MAX_IMPORT_LINES && !ENDS_WITH_SPECIFIER.test(lines[end] ?? "")) {
+                end++;
+            }
+            if (end >= lines.length || end - i >= MAX_IMPORT_LINES) {
+                end = i; // no specifier found: treat it as a one-line statement
+            }
+        }
+        for (let line = i; line <= end; line++) {
+            covered.add(line);
+        }
+        i = end;
+    }
+    return covered;
+}
+/** `symbols` without the ones declared on an import line (works for both `documentSymbol` shapes). */
+export function dropImportSymbols(symbols, source) {
+    const covered = importLines(source);
+    if (covered.size === 0) {
+        return symbols;
+    }
+    return symbols.filter((sym) => {
+        const line = (sym.range ?? sym.location?.range)?.start?.line;
+        return line === undefined || !covered.has(line);
+    });
+}

package/dist/server.js

@@ -0,0 +1,165 @@
+/**
+ * MCP surface of webnav: registers `Webnav` methods as tools.
+ *
+ * Tool names and parameter names (snake_case) match the Python `webnav-mcp`
+ * so hosts and prompts written against either keep working. Name-ish
+ * 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`.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+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.";
+const text = (value) => ({
+    content: [{ type: "text", text: value }],
+});
+export function createServer(version) {
+    const server = new McpServer({ name: "webnav", version }, { instructions: INSTRUCTIONS });
+    const webnav = new Webnav({
+        rootsProvider: async () => {
+            if (!server.server.getClientCapabilities()?.roots) {
+                return undefined;
+            }
+            return (await server.server.listRoots()).roots.map((root) => root.uri);
+        },
+    });
+    const position = {
+        file_path: z.string(),
+        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)));
+    return { server, webnav };
+}