webnav-mcp

⚠️ Deprecated — do not use this package. Use webnav-ts-mcp from the npm registry instead (claude mcp add webnav -- npx webnav-ts-mcp). It is a TypeScript port with the same tools and environment variables, needs only Node.js (no Python or uv), and is the only version that will receive updates.

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's the front-end counterpart to codenav-mcp.

Quick start

You need uv (or pipx) and Node.js ≥ 18:

uvx webnav-mcp

Register it with your MCP host. For Claude Code, from the project root:

claude mcp add webnav -- uvx webnav-mcp

Or add it to a project .mcp.json (Claude Code) or .cursor/mcp.json (Cursor):

{
	"mcpServers": {
		"webnav": {
			"command": "uvx",
			"args": ["webnav-mcp"]
		}
	}
}

In Cursor, also set "env": {"WEBNAV_MCP_WORKSPACE": "${workspaceFolder}"}, because Cursor may start MCP servers with your home directory as the working directory.

Language servers

Requests are routed to three Node language servers by file extension:

Resolution order for tsc / HTML / CSS binaries: navigated project's node_modules/.bin/ → webnav's own package-local install (see Development) → PATH → npx --yes (JS/TS: npx -p typescript@7 tsc --lsp --stdio). webnav does not use typescript-language-server — TypeScript 7 no longer ships classic tsserver.js.

To skip downloads, install in the project (or under this package for standalone):

npm install --save-dev typescript@^7 vscode-langservers-extracted

Tools

For JS/TS, start with the name-based tools:

Then use the position tools once you have a path:line:col:

Cross-file CSS/HTML index (a Python scanner, not the language servers):

search_symbol, symbol_info and outline 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. A missing parameter gets a short hint back instead of a validation error.

Positions are 1-indexed. column is a UTF-16 character offset (a leading tab counts as one character).

Environment

Requirements

• Python ≥ 3.11
• Node.js ≥ 18 (for TypeScript 7's tsc shim and the HTML/CSS servers)
• Installed automatically: mcp, mcp-nav-shared

Related

• Design notes (index heuristics, dynamic selectors, positioning): docs/agent-tooling.md.

Development

Source: github.com/illescasDaniel/webnav-mcp. From a checkout: uv sync --group dev, then npm ci in this directory (owns typescript@^7 + vscode-langservers-extracted for standalone launch), then uv run webnav-mcp.

License

MIT. See LICENSE.