webnav-ts-mcp 0.1.0 → 0.1.1

package/README.md

@@ -2,9 +2,8 @@
 
 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.
+single-file language servers can't provide. It needs only Node.js and installs
+with a web project's own package manager.
 
 ## Quick start
 
@@ -100,20 +99,7 @@ tab counts as one character).
 | `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)) |
+| `WEBNAV_MCP_PUBLIC` | nothing | Comma-separated workspace-relative stylesheets (files or directories) that are a public API, e.g. a design-token file consumed by other projects. `diagnostics` stops reporting their custom properties as "declared but never used" and their selectors as "never referenced"; undefined `var()` usages are still reported |
 
 ## Layout
 
@@ -122,136 +108,66 @@ 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)
+  webIndex.ts     CSS var / selector index
   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
+  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
+npm run upload    # check + publish to npm (--build-only / --dry-run / --otp CODE after `--`); needs `npm login`
+npm run test-package  # install the published version in a throwaway project and drive it over MCP stdio
 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
+## Design notes
 
 `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.
+plus a regex-grade index.
 
-**Behavioural parity**, measured by `scripts/parity.mjs` (real MCP over stdio,
-identical calls, diffed text):
+**Tests:** vitest (unit tests for the index/format code, 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).
 
-- 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
+### Things worth knowing
 
 - **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
+- **Columns are UTF-16 offsets,** which is what LSP uses and what JS strings
+  already are, so no conversion is needed.
+- **Regex index limit:** `\w` is ASCII in JS. The index regexes use
+  `(?<![\w-])` to avoid matching `data-id=`, so a non-ASCII letter directly
+  before `id=`/`class=`/`style=` still counts as a match. Vanishingly rare in
+  real markup.
+- **Inherited-member lookup needs a different approach.** TypeScript 7's
+  language server advertises no type hierarchy (checked against its `initialize`
+  capabilities), so a member declared on a base class can't be found that way.
+  webnav 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).
+  aren't followed).
+- **`callers` and `implementations`** are offered because the server advertises
+  `callHierarchyProvider` and `implementationProvider`.
 
 ### 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`.)
+  copy.
 - **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/langCommand.js

@@ -1,7 +1,7 @@
 /**
  * Resolves how to launch the Node-based language servers webnav multiplexes to.
  *
- * Unlike the Python distribution, the servers are ordinary npm dependencies of
+ * 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

package/dist/server.js

@@ -1,8 +1,7 @@
 /**
  * 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
+ * Tool and parameter names are snake_case. 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`.

package/dist/shared/paths.js

@@ -1,7 +1,7 @@
 /** Path helpers: symlink-resolving normalisation and containment checks. */
 import fs from "node:fs";
 import path from "node:path";
-/** Like Python's `Path.resolve()`: absolute, symlinks resolved when the path exists. */
+/** Absolute path with symlinks resolved when the path exists. */
 export function resolveReal(p) {
     const abs = path.resolve(p);
     try {
@@ -22,7 +22,7 @@ export function relativeWithin(child, parent) {
 export function toPosix(p) {
     return p.split(path.sep).join("/");
 }
-/** Component-wise path ordering, matching how Python orders `Path` objects. */
+/** Component-wise path ordering. */
 export function comparePaths(a, b) {
     const pa = a.split(path.sep);
     const pb = b.split(path.sep);

package/dist/webIndex.js

@@ -738,6 +738,19 @@ export function undefinedVarUsages(idx) {
     }
     return result;
 }
+/**
+ * Declared custom properties never read by any `var()` in the root. A JS/TS
+ * string literal equal to the name (e.g. `getPropertyValue("--x")`) counts as a use.
+ */
+export function unusedVarDeclarations(idx) {
+    const result = [];
+    for (const [name, decls] of idx.varDeclarations) {
+        if (!idx.varUsages.has(name) && !idx.stringLiterals.has(name)) {
+            result.push(...decls);
+        }
+    }
+    return result;
+}
 /**
  * CSS-defined tokens with no HTML/JS reference. A dynamically-built JS hit
  * elsewhere in the root counts as a reference for any token it's a prefix of;
@@ -754,14 +767,23 @@ export function unreferencedSelectors(idx) {
     }
     return unreferenced.sort(cmp);
 }
-/** Index-derived warning lines for one file: undefined `var(--x)` usages (no fallback) and CSS selectors with no HTML/JS reference in this root. */
-export function diagnosticsForFile(idx, fileRel) {
+/** Index-derived warning lines for one file: undefined `var(--x)` usages (no fallback), unused `--x` declarations and CSS selectors with no HTML/JS reference in this root. */
+export function diagnosticsForFile(idx, fileRel, publicPaths = []) {
     const warnings = [];
     for (const usage of undefinedVarUsages(idx)) {
         if (usage.file === fileRel) {
             warnings.push(`${usage.line}:1 [warning] var(${usage.name}) is never defined in ${idx.name}`);
         }
     }
+    // `WEBNAV_MCP_PUBLIC` files are an API for other projects: nothing in them is "unused".
+    if (isGenerated(fileRel, publicPaths)) {
+        return sortWarnings(warnings);
+    }
+    for (const decl of unusedVarDeclarations(idx)) {
+        if (decl.file === fileRel) {
+            warnings.push(`${decl.line}:1 [warning] ${decl.name} is declared but never used in ${idx.name}`);
+        }
+    }
     for (const token of new Set(unreferencedSelectors(idx))) {
         for (const hit of idx.selectorHits.get(token) ?? []) {
             if (hit.kind === "css" && hit.file === fileRel) {
@@ -769,5 +791,8 @@ export function diagnosticsForFile(idx, fileRel) {
             }
         }
     }
+    return sortWarnings(warnings);
+}
+function sortWarnings(warnings) {
     return warnings.sort((a, b) => Number.parseInt(a, 10) - Number.parseInt(b, 10));
 }

package/dist/webnav.js

@@ -72,6 +72,11 @@ export class Webnav {
     // with a pointer to the source. Navigation-only: the CSS/selector index
     // still reads them, since emitted JS is where a root's runtime usages live.
     rawExclude = process.env.WEBNAV_MCP_EXCLUDE ?? "";
+    // Comma-separated workspace-relative files/directories of stylesheets that
+    // are a public API (design tokens for other projects). `diagnostics` never
+    // reports their custom properties or selectors as unused.
+    rawPublic = process.env.WEBNAV_MCP_PUBLIC ?? "";
+    publicRelative = [];
     // A malformed WEBNAV_MCP_ROOTS must not crash the server at startup (the host
     // would only show "server failed to start"): remember the problem and report
     // it as tool text from every index-backed tool instead.
@@ -113,6 +118,13 @@ export class Webnav {
         this.generatedRelative = this.generatedPaths
             .filter((p) => relativeWithin(p, resolvedRoot) !== undefined)
             .map((p) => relativeWithin(p, resolvedRoot).split(path.sep).join("/"));
+        this.publicRelative = this.rawPublic
+            .split(",")
+            .map((part) => part.trim())
+            .filter(Boolean)
+            .map((part) => relativeWithin(resolveReal(path.resolve(root, part)), resolvedRoot))
+            .filter((rel) => rel !== undefined)
+            .map((rel) => rel.split(path.sep).join("/"));
     }
     /** Stop every running language server. */
     async dispose() {
@@ -503,7 +515,7 @@ export class Webnav {
                 try {
                     const located = webIndex.rootIndexForFile(this.indexes(), this.resolvePath(filePath));
                     if (located) {
-                        const extra = webIndex.diagnosticsForFile(located[0], located[1]);
+                        const extra = webIndex.diagnosticsForFile(located[0], located[1], this.publicRelative);
                         if (extra.length > 0) {
                             lines.push(extra.join("\n"));
                         }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "webnav-ts-mcp",
-	"version": "0.1.0",
+	"version": "0.1.1",
 	"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",
@@ -42,9 +42,9 @@
 		"check": "npm run lint && npm run typecheck && npm test",
 		"pretest": "npm run build",
 		"test": "vitest run",
-		"parity": "node scripts/parity.mjs",
 		"prepack": "npm run build",
-		"bench": "node scripts/bench.mjs"
+		"upload": "bash scripts/publish.sh",
+		"test-package": "node scripts/test_package.mjs"
 	},
 	"dependencies": {
 		"@modelcontextprotocol/sdk": "^1.31.0",