webnav-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'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

Developed in the SpaceMaker repository as a uv workspace member (mcp-servers/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.