ng-token-saver

An MCP server that lets an AI agent understand Angular templates by asking the same compiler that builds the project, instead of guessing from file text. The token saving is measured, not promised.

Angular ships a first-class language server, but no official AI integration exposes it — the Angular CLI MCP (ng mcp) works at the docs-and-build level and does not touch templates. This server is that missing layer, and it answers for the Angular version the project actually runs.

Everything below marked as measured was produced by running code against six real Angular workspaces (17.3.12, 18.2.14, 19.2.25, 20.3.26, 21.2.18, 22.0.8) and two production projects. Every number can be reproduced with the commands in Reproducing the measurements.

Quick start

The language server ships as a regular dependency — nothing to install besides the package:

npm install -g @alex-apps/ng-token-saver

Claude Code:

claude mcp add ng-token-saver -- ng-token-saver

Codex CLI:

codex mcp add ng-token-saver -- ng-token-saver

Any other MCP client:

{ "mcpServers": { "ng-token-saver": { "command": "ng-token-saver" } } }

Or skip the install and let the client fetch it through npx:

{ "mcpServers": { "ng-token-saver": { "command": "npx", "args": ["-y", "@alex-apps/ng-token-saver"] } } }

In Cursor that npx form is one click:

The npm and npx paths are verified by running: the packed tarball (79 kB, dist only) was installed into a clean prefix and all four tool kinds answered through a real MCP client, and the npx form connects in 1.2–2.0 s from a warm npm cache (the very first run on a machine also downloads the dependency tree — the language server alone unpacks to 13.6 MB).

A first question to ask it — the contract of a component whose members are scattered across an extends chain. Asked for fixtures/v17/src/app/derived-card.component.ts (a fixture in this repository), ng_component_info answers, verbatim:

{"found":true,"angularVersion":"17.3.12","className":"DerivedCardComponent","kind":"component","selector":"app-derived-card","standalone":true,"inlineTemplate":true,"styleUrls":[],"imports":[],"hostDirectives":[],"extends":"BasePanel","ancestors":["BasePanel","BaseWidget"],"inputs":[{"name":"accent","type":"boolean"},{"name":"heading","type":"string"},{"name":"disabled","type":"boolean"}],"outputs":[{"name":"blurred","type":"void"}],"publicMembers":[{"name":"focus","kind":"method","signature":"focus(): void","noop":true},{"name":"collapse","kind":"method","signature":"collapse(animated: boolean): void","noop":true}]}

624 characters, 305 ms on the session's first call (it loads the project's own TypeScript), single-digit milliseconds after. The asked file declares one input and an extends clause; heading, disabled, the output and both methods live in BasePanel and BaseWidget and are resolved statically, and "noop": true on focus() is the subclass shadowing it with an empty body — the kind of fact that otherwise costs a whole file read per ancestor.

Configs for Cursor, VS Code, Windsurf, Codex CLI and JetBrains, the Node floor, and running from source are in Requirements and setup.

The two problems it solves

1. No template awareness. grep over an .html file cannot tell you where {{ user().fullName }} is declared, and no amount of reading gives you NG2339 Property 'emailAddress' does not exist on type 'UserVm'. That is compiler output, not text.

2. Version drift. The AI context files on angular.dev (llms.txt) describe only the newest major and carry no version markers; the versioned archive sites serve none at all. On v17–v21 they hand the agent instructions that produce APIs which do not exist. Measured examples are in Version facts.

Tools

Six tools, 1001 characters of descriptions in total. Answers are dense JSON with no markdown.

Four of the six never start the language server, so they answer in milliseconds and keep working on workspaces where the server refuses to load.

Measured: contract instead of the whole file

ng_component_info returns the public contract of a component rather than its source. Measured across two production codebases through a real MCP client:

* measured with the pre-0.1.2 wire format; the current format is leaner, so this saving is a floor.

The largest component in the monorepo shrinks from 177 863 to 10 770 characters while listing 117 contract members. Contracts include members inherited from base classes — the extends chain is resolved through relative imports, tsconfig path aliases and barrels. Before that resolver, 91 of 1298 monorepo contracts were flagged as partial; now 1 is.

Three caveats that travel with these numbers:

• Tokens are counted through a proxy — OpenAI's o200k_base, since Claude's tokenizer is not public; cl100k_base agrees within one point on this data. Characters are exact.
• The baseline is reading the whole file, which is what an agent does by default.
• JSON tokenizes slightly worse than TypeScript, so token savings sit a point or two below character savings. The table carries both.

On small components there is no saving at all: a 17-line component produces a 578-character contract against a 315-character source. The contract grows with the number of members, the source with method bodies — and on production code the second wins almost always.

Measured: rename and diagnose

Renaming an input across usages. The grep path an agent actually takes — read the component file to learn the selector, then grep the selector and the binding spellings repo-wide — against ng_component_info plus ng_find_usages with its input filter, which returns only the tags that bind the name, each entry pointing at the binding itself. On the production monorepo, 6243 files scanned:

* the tool returns at most 500 entries per answer, and the answer says so.

The saving is decided by how many of the usages actually bind the input: mask is bound on 5 of 568 tags, and grep still prints every selector line plus 67 binding-shaped lines from across the repo — 62 of them somebody else's mask — while the bridge answers with exactly those five sites.

Diagnosing a template that will not compile. A whole-project compiler listing costs 395 tokens and 1321 ms; one ng_template_diagnostics call answers with the asked file's diagnostics in 81 tokens, 1 ms warm. The gap only widens with project size: the listing grows with the project, the answer does not. After an edit, fresh diagnostics arrive as a 340–400 ms push — against a rebuild.

Version facts

ng_version_rules contains no rule taken from documentation: the data comes from importing the packages actually installed in each fixture and from running the compiler.

The zoneless provider is renamed between v19 and v20.

Advice to "enable zoneless" without a version breaks on three majors out of six.

Existing is not the same as ready. The @experimental and @developerPreview tags live only in declaration JSDoc and are invisible at runtime: