Skip to main content
Glama
@alex-apps/ng-token-saver

@alex-apps/ng-token-saver

by Alex88Ryabov

ng-token-saver

npm version weekly downloads node license

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.

Measured on a production Nx monorepo

Result

A component's contract instead of its whole file

67% fewer tokens over 1298 components

Where one input is bound on a component used 577 times

50 527 → 1 035 tokens against the grep path

Errors of one template

81 tokens, 1 ms warm against a 395-token compiler listing

Whole Claude Code sessions, five read-only questions × 3

no saving: +15% input tokens, −4% cost, 60 of 60 answers right in every arm — why

The last row stays in the table: a per-call saving is not a per-session one, and the difference is explained below.

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

Or, in Claude Code, as a plugin — the same server through npx, plus the one-line hints toward it; no global install needed:

/plugin marketplace add Alex88Ryabov/alex-apps-ng-token-saver
/plugin install ng-token-saver@ng-token-saver

A server already registered with claude mcp add would then run twice; remove it with claude mcp remove ng-token-saver. The plugin's tools carry a plugin prefix (mcp__plugin_ng-token-saver_ng-token-saver__…), so permission rules and agent tool lists written for the bare names need the new ones.

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:

Add to Cursor

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":[{"name":"BasePanel","file":"<repo>\\fixtures\\v17\\src\\app\\base-panel.ts"},{"name":"BaseWidget","file":"<repo>\\fixtures\\v17\\src\\app\\base-widget.ts"}],"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}]}

811 characters with this checkout's absolute paths in place of <repo>, 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, with their files named in ancestors for the next edit. "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.

Related MCP server: agent-workspace-mcp

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 TS2339 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, 1040 characters of descriptions in total. Answers are dense JSON with no markdown.

Tool

What it answers

Needs the language server

ng_template_definition

where a symbol on a template line is declared — the line as Read shows it, the symbol by name

yes

ng_template_diagnostics

Angular compiler errors for a template, or for a files batch; an entry anchored in the companion .ts carries file, a message repeated on several lines comes once with its lines

yes

ng_component_info

the public contract of a component or directive

no

ng_workspace_map

projects, versions, strictTemplates and zone.js per project

no

ng_version_rules

what exists and what does not in this project's Angular version

no

ng_find_usages

where a component, directive, pipe or service is used; with input — where that input is bound

no

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.

Since 0.2.0 every position is 1-based, as Read shows it: ng_template_definition takes the line that way and the symbol by name (character is an alternative for a name that repeats on the line). 0.1.x took a 0-based line and character, the LSP convention — the same numbers now point one line lower.

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:

Nx monorepo

CLI workspace*

Angular / TypeScript

19.2.18 / 5.8.3

17.3.8 / 5.3.3

Components in the tally

1298

407

Parse errors

0

0

Sources

5 404 708 chars

1 735 223 chars

Contracts (base-class members included)

1 759 331 chars

463 563 chars

Saved

67%

73%

Saved in tokens (o200k_base proxy)

67%

71%

Contract shorter than source

1201 of 1298 (93%)

386 of 407 (95%)

Flagged as partial

1 of 1298

3 of 407

First call (loads the project's TypeScript)

306 ms

564 ms

* 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:

Component

grep path

bridge

saved (o200k)

577 usages, mask bound on 5 tags

50 527 tokens

1 035 tokens

98%

466 usages, icon bound on 463 tags

41 698 tokens

22 566 tokens

46%

1211 usages, name bound on 1134 tags

129 227 tokens

30 650 tokens

76%*

* 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.

Measured: whole sessions

The numbers above are per call. Whether they reach the bill was measured on whole sessions: five read-only questions on the production monorepo — an inherited contract, a plain contract, where one input is bound, where a component is used, which APIs the installed version has as stable — each answered three times by claude -p (Claude Code 2.1.322, claude-opus-5-5) in four arms, isolated from the machine's own CLAUDE.md, memory, hooks and MCP servers, with read-only tools and no subagents. Every one of the 60 answers was right.

Arm

Input tokens

Output tokens

Cost*

Turns

A — no server

1 322 306

20 560

$1.27

65

B — no server, told to read only what the question needs

1 347 280

21 062

$1.39

70

C — B plus this server

1 552 429

21 634

$1.34

83

D — C plus the plugin hints

1 537 528

20 828

$1.23

79

* Claude Code's own estimate at API list prices; cached input is cheap, so cost and token totals move apart.

Against the control (C versus B) the server added 15% input tokens and saved 4% of cost — inside the run-to-run spread, which reaches 3× within a single cell. Two reasons, both visible in the logs. Claude Code defers MCP tools, so the first call costs an extra ToolSearch turn, and every turn re-sends some 20 000 tokens of context. And on questions like these the agent spends little on files: for the inherited contract it read the 348-line component whole but grepped its 671-line base class for decorators — a few thousand tokens, which one extra turn outweighs.

The per-call savings hold where the files are large and read whole. In 81 field transcripts on the same monorepo agents read a component or directive file whole 319 times against 99 contract calls, and 254 of those reads came from subagents — see Hints in Claude Code. Whether the hint turns those reads into contract calls is not measured yet. Edits, refactors and builds were not part of this run.

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.

API

v17

v18

v19

v20

v21

v22

provideExperimentalZonelessChangeDetection

–

yes

yes

–

–

–

provideZonelessChangeDetection

–

–

–

yes

yes

yes

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:

API

v17

v18

v19

v20

v21

v22

input, output, model, viewChild, contentChild

preview

preview

stable

stable

stable

stable

effect, toObservable

preview

preview

preview

stable

stable

stable

linkedSignal, afterRenderEffect

–

–

preview

stable

stable

stable

resource, rxResource, httpResource

–

–

experimental

experimental

experimental

stable

So "rewrite @Input() as input()" on a v17 or v18 project means moving to a non-public API, and resource() was experimental all the way through v21. A batch of signal APIs appears exactly at v19: linkedSignal, resource, rxResource, httpResource, afterRenderEffect, provideAppInitializer.

Two documentation claims that measurement contradicted: standalone becomes the default at v19, not v20; and *ngIf is not removed in 22.0.8 — it reports hint TS6385 (TypeScript's deprecation hint) and keeps working, with NgIf still exported from @angular/common.

Compiler gates, read in the 22.0.8 bundle and confirmed by running it — keyed on the project's Angular version, which the server detects from @angular/core next to the tsconfig (--angularCoreVersion is passed too, as a fallback):

Feature

Gate

@if / @for / @switch blocks

≥ 17.0.0

signals in two-way bindings

≥ 17.2.0-0

@let

≥ 18.1.0

implicit standalone

≥ 19.0.0

DOM event type assertion

≥ 20.2.0

Also measured: Signal Forms (@angular/forms/signals) exist only from v21 and are stable on 22.0.8; AbstractControl.events from v18; TestBed.tick from v20.

Outside the measured v17–v22 range ng_version_rules returns nothing and says so — extrapolating "it was in v22, so it is in v23" is exactly the failure it exists to prevent.

Honesty as a feature

An incomplete answer says so, in words, inside the answer:

  • A contract merges base-class members and host-directive exposures, resolved statically through relative imports, tsconfig aliases and barrels. Where the walk cannot continue — a base class from a package, a mixin call — the answer carries incomplete, naming the class and the file to ask about next.

  • ng_version_rules reports notMeasured topics, and a caveat when your minor differs from the measured one.

  • ng_find_usages labels declarations as declaration, admits when class-name matches were found without resolving imports, and names selector twins — a second declaration of the same selector elsewhere in the workspace — instead of silently mixing their usages.

  • ng_template_diagnostics separates three states that all look like an empty list: the template is clean; the server is silently down (caught by a canary probe); or template checking is off for this project — then the answer carries checksDisabled naming the tsconfig responsible. In the measured monorepo strictTemplates is off in two of seven applications, so the distinction is not theoretical.

What this is not

  • Not better than a careful grep at finding usages. grep -rn "<app-widget" finds the same 62 usages. What ng_find_usages adds: the selector and class name are derived from the file for you, usage kinds are labelled, all four attribute-binding spellings are covered, and path scopes the scan — 33 selectors in the measured monorepo are declared in two applications at once, and an unscoped search would mix them.

  • Not a replacement for the Angular CLI MCP — a different layer. ng mcp covers docs, best practices and build orchestration; none of its nine tools touches templates or the language server. The two complement each other.

  • Not a type checker of its own. The LSP-backed tools deliver the project's own compiler output, undistorted.

Known gaps are recorded, not hidden: a base class from a package or behind a mixin call stops the ancestor walk (1 of 1298 components in the measured monorepo), Nx projects with inferred targets come without tsConfig, and pipe twins are not detected.

Requirements and setup

  • Node ≥ 18.20.8 — the measured floor: the published package answered on clean Node 18.20.8, 20.20.2 and 22.x. This is about the MCP server process only — your project keeps building on its own Node. To give just the server a newer runtime, point the client config at that binary: "command": "C:\\node22\\node.exe".

From source (instead of npm):

  • The project's own dependencies: npm install, then npm run build.

  • The shipped language-server branch lives in tools/servers/ls22 and needs npm ci there once.

  • In every client config, replace the ng-token-saver command with node <path>/dist/index.js; for Claude Code: claude mcp add ng-token-saver -- node <path>/dist/index.js.

node_modules folders are not committed, including the twelve inside the stand. To restore the full measurement environment:

npm install && npm run build
cd tools/servers/ls22 && npm ci        # the branch actually shipped
cd fixtures/v22 && npm ci              # repeat per fixture you want to run

Clients

The server is a plain stdio MCP server with no client-specific features, so any MCP client can launch it; installation and Claude Code registration are in Quick start. Usage guidance for the agent travels in the MCP instructions field — see Using with agents.

Cursor — the one-click button in Quick start, or the same mcpServers JSON as in Quick start, in ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project).

Windsurf — the same JSON, in ~/.codeium/windsurf/mcp_config.json.

VS Code (Copilot agent mode) — .vscode/mcp.json; the key is servers and the entry takes a type:

{ "servers": { "ng-token-saver": { "type": "stdio", "command": "ng-token-saver" } } }

Codex CLI — codex mcp add ng-token-saver -- ng-token-saver, or ~/.codex/config.toml:

[mcp_servers.ng-token-saver]
command = "ng-token-saver"

JetBrains AI Assistant / Junie — Settings → Tools → AI Assistant → Model Context Protocol accepts the same JSON as Quick start's; for Junie, additionally enable "Pass custom MCP servers".

Configuration, all variables optional:

  • NG_TOKEN_SAVER_IDLE_MS — a language-server session unused this long shuts its ngserver down; the next call pays the cold start again. Default 900000 (15 minutes); 0 keeps sessions alive until the server exits. A session with a call in flight is never shut down.

  • NG_TOKEN_SAVER_PREWARM=1 — ng_workspace_map with a path inside an app starts loading that app into the language server in the background, so the first diagnostics or definition call finds it ready: 21 s → 1.4 s on the production monorepo. The cost is ~1 GB of memory until the idle shutdown, whether or not an LSP tool follows; a folder holding several projects (a workspace root, an Nx apps/) is not warmed, since which app to load is unknown.

  • NG_TOKEN_SAVER_SERVERS_DIR — where the language-server branch lives, if not in tools/servers next to the build.

Using with agents

The server sends its usage guidance in the MCP instructions field (924 characters), which Claude Code keeps in the agent's context even when tool descriptions are deferred until a tool search (checked on Claude Code 2.1.282: the whole text arrives while the tools show only their names). For a client that ignores instructions, the same text goes into CLAUDE.md or AGENTS.md:

Angular tools that answer from the compiler and the source instead of whole files. Prefer them to reading and grepping: ng_component_info for what a component or directive accepts (inputs, outputs, members, inherited ones included) instead of reading its .ts; ng_find_usages for where a component, directive, pipe or service is used, and with input for where one input is bound, instead of grep; ng_template_diagnostics after editing a template instead of ng build; ng_template_definition for what a template symbol is; ng_version_rules before suggesting an Angular API; ng_workspace_map once for projects, versions and strictTemplates. The first diagnostics or definition call in a workspace loads the project into the Angular language server and takes up to a minute on a large workspace; later calls take milliseconds, so a slow first answer is not a hang. Lines and characters are 1-based everywhere, as Read shows them.

Hints in Claude Code

The instructions alone did not change the habit. Counted with npm run bench:adoption over 81 Claude Code transcripts on the production monorepo, with the server installed and these instructions in context:

Main sessions (53)

Subagents (28)

ng_component_info calls

70

29

Component files read whole (Read, cat, Get-Content), pre-edit Reads left out

53

254

ng_find_usages calls

67

59

Greps for a component element

66

11

ng_template_diagnostics calls / ng/nx builds

112 / 15

13 / 0

Subagents are where the gap is, and a capture of Claude Code's own requests shows why: a subagent receives the MCP instructions only after its first tool call, so its first move is made without them. ng_template_definition was not called once in these transcripts, and ng_version_rules twice.

The plugin's hook (plugin/hooks/hints.mjs) targets exactly these calls, and the counts above use its own definition of them. Before a component or directive file is read in full, an element selector is grepped, or an ng/nx build runs inside an Angular workspace, it adds one line naming the tool that answers it — once per agent and kind; the call itself runs unchanged. A subagent gets a one-sentence pointer before its first prompt. The line arrives next to the tool result, so it steers the next call rather than this one. if filters keep the hook off unrelated commands; where it does run it costs about 95 ms, most of it Node's start.

Reproducing the measurements

npm test                                  build plus 192 unit tests (node:test, no dependencies)
npm run smoke                             end-to-end check with a real MCP client over stdio
npm run bench:settle                      whether a pause after didOpen is needed (it is not)
npm run bench:standalone                  where standalone becomes the default (v17..v22)
npm run bench:api                         which Angular APIs exist in which majors, and their stability
npm run bench:contract <project root>     contract size against reading whole files (--tokens adds token counts)
npm run bench:rename <component> <input>  the grep path against the bridge for an input rename
npm run bench:diagnose                    a compiler listing against one diagnostics call
npm run bench:matrix                      resolution probes across a fixture
npm run bench:negative                    what the server returns when things break
npm run bench:didchange                   diagnostics timing after an edit
npm run bench:adoption <transcripts dir>  tool calls against the habits they replace, in Claude Code transcripts
npm run bench:session <tasks.json>        whole-session A/B through claude -p, four arms (see the file's header)

The whole-session tasks name files of a production project, so the tasks file is not in the repository; tools/bench-session.mjs documents its format, and any workspace will do.

The stand is fixtures/v17..v22 — six real Angular workspaces, each with its own node_modules and its own pinned TypeScript, plus fixtures/negative/* for failure cases.

Status

All six tools verified on the six fixtures and on two production codebases — 1298 and 407 components, zero parse errors — plus one Angular 16 project to check that out-of-range refusals are structured rather than silent. 192 unit tests, all green.

Measured latency: the two LSP-backed tools pay 8–28 s of cold start on the first call and answer in 2–9 ms after it; the four static tools answer in 250–600 ms on the first call and in milliseconds once the project's TypeScript is cached. A session idle for 15 minutes shuts its language server down, and the next call pays the cold start again — see NG_TOKEN_SAVER_IDLE_MS above.

License

GPL-3.0-or-later — see LICENSE. Copyright (C) 2026 Alex Ryabov. Use and modify freely; derivative works must stay open under the same license.

Available Tools

6 tools
ng_component_infoAngular: component contractA

Public contract of a component or directive: inputs, outputs, class members, decorator metadata. Accepts .ts or .html. Reads the source; ngserver is not needed.

Inputs: file (required).

ng_find_usagesAngular: find usagesA

Usages of a component, directive, pipe or service across the workspace: elements, attribute selectors, pipes and class references. Accepts a file path or a selector.

Inputs: selectorOrFile (required), path, input, limit.

ng_template_definitionAngular: declaration of a template symbolA

From a position in an Angular template (.html or inline in .ts) to its TypeScript declaration. line and character are 0-based, as in LSP.

Inputs: file (required), line (required), character (required).

ng_template_diagnosticsAngular: template errorsC

Angular compiler errors for a template after an edit. Accepts .html or .ts; files checks a batch. An entry anchored in the companion file names it in file. An empty list means "no errors" only when the server is healthy.

Inputs: file, files.

ng_version_rulesAngular: rules for the project versionB

What exists and what does not in this project's Angular version: template syntax, signal APIs, zoneless, DI. Every rule was measured on the v17-v22 stand.

Inputs: path, topic.

ng_workspace_mapAngular: workspace mapA

Workspace projects, Angular/CLI/TypeScript versions, strictTemplates and zone.js per project. Understands angular.json, Nx and solution style. Call once per session.

Inputs: path.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 6 tools

    Disambiguation5/5

    Each tool targets a distinct aspect of Angular development: component metadata, template positions, template diagnostics, workspace configuration, version-specific rules, and cross-reference usages. There is no overlap or ambiguity between them.

    Naming Consistency5/5

    All tools follow a consistent 'ng_' prefix with snake_case names that clearly indicate their purpose. The naming pattern is uniform across all six tools, making it easy to predict tool functionality from the name alone.

    Tool Count5/5

    With exactly six tools, the server is appropriately scoped for Angular code analysis. Each tool serves a distinct purpose without redundancy, and the count is within the ideal range.

    Completeness5/5

    The tool set covers the core workflows for Angular analysis: understanding components, navigating from templates to definitions, checking diagnostics, mapping workspace structure, understanding version features, and finding usages. Minor gaps like batch processes are addressed by the batch capability in diagnostics, and the set feels complete for a read-only analysis server.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      A Model Context Protocol server that provides Angular project analysis and refactoring capabilities, enabling LLMs to analyze component usage patterns, dependency structures, and perform safe refactoring with breaking change detection.
      4
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      A TypeScript-aware MCP server that provides coding agents with repository discovery, code intelligence, and web project context for local codebases. It enables deep symbol navigation, diagnostic reporting, and structural analysis of monorepos without requiring full IDE integration.
      7
      11 npm
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that provides structure-aware code analysis (symbol trees, dependencies, docs) to reduce AI agent token consumption by up to 99%, along with Git commit intelligence.
      MIT