Angular token saver

ng-token-saver

AI エージェントが、ファイルのテキストから推測するのではなく、プロジェクトをビルドするのと同じコンパイラーに尋ねて、Angular のテンプレートを理解できるようにする MCP サーバーです。トークンの節約量は、謳い文句ではなく実測値です。

Angular には標準のランゲージサーバーが用意されていますが、それを公開する公式の AI 統合はありません。Angular CLI MCP（ng mcp）はドキュメントとビルドのレベルで動作し、テンプレートには触れません。このサーバーは、その欠けている層を補い、プロジェクトで実際に使われている Angular のバージョンに基づいて回答します。

以下で実測値として示されているものはすべて、実際の 6 つの Angular ワークスペース（17.3.12、18.2.14、19.2.25、20.3.26、21.2.18、22.0.8）と 2 つの本番プロジェクトでコードを実行して得られたものです。すべての数値は、測定値の再現に記載されたコマンドで再現できます。

クイックスタート

ランゲージサーバーは通常の依存関係として提供されるため、このパッケージ以外にインストールするものはありません。

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

その他の MCP クライアント：

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

または、インストールを省略し、クライアントに npx 経由で取得させます。

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

Cursor では、この npx 形式をワンクリックで設定できます。

npm と npx の方法は、実行して検証済みです。パッケージ化した tarball（79 kB、dist のみ）をクリーンなプレフィックスにインストールし、実際の MCP クライアント経由で 4 種類すべてのツールから応答を得ました。また、npx 形式は、npm キャッシュが温まった状態なら 1.2～2.0 秒で接続します（そのマシンでの初回実行時には依存関係ツリーもダウンロードされます。ランゲージサーバー単体の展開サイズは 13.6 MB です）。

最初に尋ねる質問の例として、メンバーが複数の extends チェーンに分散したコンポーネントの契約を見てみましょう。このリポジトリ内のフィクスチャである fixtures/v17/src/app/derived-card.component.ts について尋ねると、ng_component_info は次のようにそのまま回答します。

{"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}]}

<repo> をこのチェックアウトの絶対パスに置き換えた場合、811 文字です。セッションの最初の呼び出しでは 305 ms（プロジェクト独自の TypeScript を読み込みます）、その後は数ミリ秒です。質問したファイルで宣言されているのは 1 つの入力と extends 節だけです。heading、disabled、出力、両方のメソッドは BasePanel と BaseWidget に定義されており、静的に解決されます。次の編集に向けて、そのファイルも ancestors に記載されます。focus() の "noop": true は、サブクラスが空の本体で上書きしていることを示します。これは、そうでなければ祖先ごとにファイル全体を読む必要が生じる情報です。

Cursor、VS Code、Windsurf、Codex CLI、JetBrains の設定、Node の最低要件、ソースからの実行方法については、要件とセットアップを参照してください。

このツールが解決する 2 つの問題

1. テンプレートを認識できません。 .html ファイルを grep しても、{{ user().fullName }} がどこで宣言されているかは分かりません。また、どれだけ読んでも、TS2339 Property 'emailAddress' does not exist on type 'UserVm' というエラーにはたどり着けません。これはテキストではなく、コンパイラーの出力です。

2. バージョンのずれ。 angular.dev の AI コンテキストファイル（llms.txt）は最新のメジャーバージョンだけを説明し、バージョンを示す印がありません。また、バージョン別のアーカイブサイトには、該当するコンテンツがありません。v17～v21 では、エージェントに存在しない API を使わせる手順が提示されます。実測例はバージョンの事実に記載されています。

ツール

6 つのツールがあり、説明は合計 1040 文字です。回答はマークダウンを含まない、情報量の多い JSON です。

ツール	回答する内容	言語サーバーが必要
ng_template_definition	テンプレートの行にあるシンボルの宣言位置 — Read に表示される行と、名前で指定したシンボル	はい
ng_template_diagnostics	テンプレート、または files バッチの Angular コンパイラーエラー。対応する .ts に紐づくエントリーには file が含まれ、複数行で繰り返されるメッセージは lines とともに 1 回だけ表示されます	はい
ng_component_info	コンポーネントまたはディレクティブの公開コントラクト	いいえ
ng_workspace_map	プロジェクト、バージョン、プロジェクトごとの strictTemplates と zone.js	いいえ
ng_version_rules	このプロジェクトの Angular バージョンで利用できる機能と、利用できない機能	いいえ
ng_find_usages	コンポーネント、ディレクティブ、パイプ、サービスが使われている場所。input を指定すると、その入力がバインドされている場所	いいえ

6 つのうち 4 つは言語サーバーを起動しないため、ミリ秒単位で回答し、サーバーの読み込みに失敗するワークスペースでも動作し続けます。

0.2.0 以降、すべての位置は Read の表示と同じ 1 始まりです。ng_template_definition では、行をその形式で指定し、シンボルは名前で指定します（行に同じ名前が繰り返し現れる場合は、character で代わりに指定できます）。0.1.x では LSP の規約に従い、line と character を 0 始まりで指定していました。現在は同じ数値を指定すると、1 行下が指されます。

実測：ファイル全体ではなくコントラクト

ng_component_info はコンポーネントのソースではなく、公開コントラクトを返します。実際の MCP クライアントを介して、2 つの本番コードベースで測定しました。

	Nx モノレポ	CLI ワークスペース*
Angular / TypeScript	19.2.18 / 5.8.3	17.3.8 / 5.3.3
集計対象のコンポーネント数	1298	407
解析エラー	0	0
ソース	5 404 708 文字	1 735 223 文字
コントラクト（基底クラスのメンバーを含む）	1 759 331 文字	463 563 文字
削減率	67%	73%
トークンの削減率（o200k_base による推定）	67%	71%
コントラクトがソースより短い割合	1298 件中 1201 件（93%）	407 件中 386 件（95%）
部分的としてフラグ付けされた件数	1298 件中 1 件	407 件中 3 件
初回呼び出し（プロジェクトの TypeScript を読み込み）	306 ms	564 ms

* 0.1.2 より前のワイヤーフォーマットで測定しています。現在のフォーマットはより軽量なため、この削減率は下限です。

モノレポで最大のコンポーネントは、117 個のコントラクトメンバーを列挙しながら、177 863 文字から 10 770 文字に縮小されます。コントラクトには基底クラスから継承したメンバーも含まれます。extends チェーンは、相対インポート、tsconfig のパスエイリアス、バレルを通じて解決されます。このリゾルバーを導入する前は、モノレポのコントラクト 1298 件中 91 件が部分的としてフラグ付けされていましたが、現在は 1 件です。

これらの数値には、次の 3 つの注意点があります。

• トークン数は推定値で数えています — Claude のトークナイザーは公開されていないため、OpenAI の o200k_base を使用しています。このデータでは cl100k_base との差は 1 ポイント以内です。文字数は正確です。
• 比較対象はファイル全体を読み込む場合です。エージェントはデフォルトでこの方法をとります。
• JSON は TypeScript よりトークン化の効率がわずかに低いため、トークンの削減率は文字数の削減率より 1〜2 ポイント低くなります。表には両方を記載しています。

小さなコンポーネントでは、まったく削減されない場合もあります。17 行のコンポーネントでは、ソースが 315 文字なのに対し、コントラクトは 578 文字になります。コントラクトの長さはメンバー数に応じて増え、ソースの長さはメソッド本体に応じて増えます。本番コードでは、ほぼ常に後者のほうが大きくなります。

計測：名前の変更と診断

使用箇所をまたいだ入力の名前変更。 エージェントが実際にたどる grep の手順、つまりコンポーネントファイルを読んでセレクターを確認し、その後リポジトリ全体でセレクターとバインディングの表記を grep する方法と、ng_component_info に加えて input フィルターを指定した ng_find_usages を比較します。後者は、その名前をバインドするタグだけを返し、各エントリはバインディング自体を指します。本番用モノレポで6243ファイルをスキャンした結果です。

コンポーネント	grep の手順	ブリッジ	削減量（o200k）
577件の使用箇所、mask は5個のタグでバインド	50 527トークン	1 035トークン	98%
466件の使用箇所、icon は463個のタグでバインド	41 698トークン	22 566トークン	46%
1211件の使用箇所、name は1134個のタグでバインド	129 227トークン	30 650トークン	76%*

* ツールは回答ごとに最大500件を返し、その旨を回答に記載します。

削減量は、使用箇所のうち実際に入力をバインドしているものの数で決まります。mask は568個のタグのうち5個でバインドされており、grep ではセレクターを含む行すべてに加え、リポジトリ全体からバインディングに見える行が67件出力されます。そのうち62件は別の場所にある mask です。一方、ブリッジは該当する5か所だけを返します。

コンパイルできないテンプレートの診断。 プロジェクト全体のコンパイラー出力には395トークン、1321 msかかります。一方、ng_template_diagnostics を1回呼び出せば、指定ファイルの診断結果を81トークン、ウォーム状態で1 msで返します。プロジェクトの規模が大きくなるほど差は広がります。出力一覧はプロジェクトとともに大きくなりますが、回答は変わりません。編集後は、再ビルドを待つ代わりに、最新の診断結果が340～400 msでプッシュされます。

バージョンに関する事実

ng_version_rules には、ドキュメントから取得したルールは含まれていません。データは、各フィクスチャに実際にインストールされたパッケージをインポートし、コンパイラーを実行して得られたものです。

ゾーンレスプロバイダーは v19 と v20 の間で名前が変更されています。

API	v17	v18	v19	v20	v21	v22
provideExperimentalZonelessChangeDetection	–	yes	yes	–	–	–
provideZonelessChangeDetection	–	–	–	yes	yes	yes

バージョンを示さずに「ゾーンレスを有効にする」と助言すると、6つのメジャーバージョンのうち3つで問題が起きます。

存在することと、利用準備が整っていることは同じではありません。 @experimental と @developerPreview タグは宣言の JSDoc にしかなく、実行時には確認できません。

API	v17	v18	v19	v20	v21	v22
input, output, model, viewChild, contentChild	プレビュー	プレビュー	安定版	安定版	安定版	安定版
effect, toObservable	プレビュー	プレビュー	プレビュー	安定版	安定版	安定版
linkedSignal, afterRenderEffect	–	–	プレビュー	安定版	安定版	安定版
resource, rxResource, httpResource	–	–	実験的	実験的	実験的	安定版

したがって、v17 または v18 のプロジェクトで「@Input() を input() に書き換える」というのは、非公開 API への移行を意味します。また、resource() は v21 までずっと実験的でした。一連のシグナル API は v19 で一斉に登場します。具体的には linkedSignal、resource、rxResource、httpResource、afterRenderEffect、provideAppInitializer です。

測定結果と矛盾したドキュメント上の主張が2つあります。 standalone がデフォルトになるのは v20 ではなく v19 です。また、*ngIf は 22.0.8 で削除されていません。ヒント TS6385（TypeScript の非推奨ヒント）が報告されますが、引き続き動作し、NgIf も @angular/common からエクスポートされたままです。

コンパイラーの適用条件。22.0.8 のバンドルを読み取り、実行して確認しました。適用条件はプロジェクトの Angular バージョンに基づきます。サーバーは tsconfig と同じ場所にある @angular/core からバージョンを検出します（フォールバックとして --angularCoreVersion も渡されます）。

機能	適用条件
@if / @for / @switch ブロック	≥ 17.0.0
双方向バインディング内のシグナル	≥ 17.2.0-0
@let	≥ 18.1.0
standalone の暗黙的な設定	≥ 19.0.0
DOM イベント型アサーション	≥ 20.2.0

ほかに、Signal Forms（@angular/forms/signals）は v21 以降でのみ利用でき、22.0.8 では安定版であること、AbstractControl.events は v18 から、TestBed.tick は v20 から利用できることも測定しました。

測定対象の v17～v22 の範囲外では、ng_version_rules は何も返さず、その旨を伝えます。「v22 にあったから v23 にもある」と推測することこそ、このツールが防ごうとしている失敗です。

正直さを機能として

不完全な回答は、その旨を回答内で明示します。

• コントラクトは、基底クラスのメンバーとホストディレクティブの公開メンバーを統合し、相対インポート、tsconfig のエイリアス、バレルを静的にたどって解決します。基底クラスがパッケージ由来の場合や、ミックスイン呼び出しの場合など、探索を続けられないときは、次に確認すべきクラス名とファイル名を示す incomplete が回答に含まれます。
• ng_version_rules は、未測定のトピックを notMeasured として報告し、マイナーバージョンが測定対象と異なる場合は caveat を示します。
• ng_find_usages は宣言に declaration のラベルを付け、インポートを解決せずにクラス名の一致が見つかった場合はその旨を明示します。また、ワークスペース内の別の場所にある同じセレクターの2つ目の宣言である「セレクターの重複」を示し、それらの使用箇所を黙って混在させません。
• ng_template_diagnostics は、空のリストに見える3つの状態を区別します。テンプレートに問題がない場合、カナリアプローブで検出されたサーバーの停止が通知されない場合、そしてこのプロジェクトでテンプレートチェックが無効の場合です。最後の場合、原因となっている tsconfig を示す checksDisabled が回答に含まれます。測定対象のモノレポでは、7つのアプリケーションのうち2つで strictTemplates が無効になっているため、この区別は机上の話ではありません。

これは何ではないか

• 使用箇所を探すうえで、丁寧な grep より優れているわけではありません。 grep -rn "<app-widget" でも同じ62件の使用箇所が見つかります。ng_find_usages が追加するのは、セレクターとクラス名をファイルから自動的に導き出すこと、使用種別にラベルを付けること、4種類すべての属性バインディング表記を対象にすること、そして path で検索範囲を絞れることです。測定対象のモノレポでは33個のセレクターが2つのアプリケーションで同時に宣言されており、範囲を絞らない検索ではそれらが混在します。
• Angular CLI MCP の代替ではありません — 異なるレイヤーです。ng mcp が対象とするのはドキュメント、ベストプラクティス、ビルドのオーケストレーションです。その9つのツールにテンプレートや言語サーバーを扱うものはありません。両者は互いを補完します。
• それ自体が型チェッカーではありません。 LSP を利用するツールは、プロジェクト独自のコンパイラー出力を加工せずに返します。

既知の制約は隠さず記録されています。パッケージ由来、またはミックスイン呼び出しの背後にある基底クラスがある場合、祖先の走査はそこで停止します（測定対象のモノレポでは1298個のコンポーネントのうち1個）。推論されたターゲットを持つ Nx プロジェクトには tsConfig がなく、パイプの同名要素は検出されません。

要件とセットアップ

• Node ≥ 18.20.8 — 測定で確認された最低バージョンです。公開パッケージは、クリーンな Node 18.20.8、20.20.2、22.x で応答しました。これは MCP サーバープロセスだけに関する要件です。プロジェクトは引き続き、独自の Node でビルドできます。サーバーだけに新しいランタイムを使うには、クライアントの設定でそのバイナリを指定します。例："command": "C:\\node22\\node.exe"。

ソースから（npm の代わりに）：

• プロジェクト独自の依存関係をインストールします。npm install を実行してから、npm run build を実行します。
• 同梱されている言語サーバーのブランチは tools/servers/ls22 にあり、そこで一度 npm ci を実行する必要があります。
• すべてのクライアント設定で、ng-token-saver コマンドを node <path>/dist/index.js に置き換えます。Claude Code の場合：claude mcp add ng-token-saver -- node <path>/dist/index.js。

node_modules フォルダーは、スタンド内にある12個を含め、コミットされていません。測定環境全体を復元するには：

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

クライアント

このサーバーはクライアント固有の機能を持たない、標準的な stdio MCP サーバーなので、どの MCP クライアントからでも起動できます。インストールと Claude Code の登録方法については、クイックスタートを参照してください。エージェント向けの使用ガイドは MCP の instructions フィールドに記述されています。エージェントとの使用を参照してください。

Cursor — クイックスタートのワンクリックボタンを使うか、クイックスタートと同じ mcpServers JSON を ~/.cursor/mcp.json（すべてのプロジェクト）または .cursor/mcp.json（1つのプロジェクト）に記述します。

Windsurf — 同じ JSON を ~/.codeium/windsurf/mcp_config.json に記述します。

VS Code（Copilot エージェントモード） — .vscode/mcp.json を使用します。キーは servers で、エントリーには type が必要です。

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

Codex CLI — codex mcp add ng-token-saver -- ng-token-saver を実行するか、~/.codex/config.toml に記述します。

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

JetBrains AI Assistant / Junie — Settings → Tools → AI Assistant → Model Context Protocol で、クイックスタートと同じ JSON を使用できます。Junie の場合は、さらに「Pass custom MCP servers」を有効にしてください。

設定項目（すべて任意）：

• NG_TOKEN_SAVER_IDLE_MS — 言語サーバーのセッションがこの時間未使用の場合、その ngserver は終了します。次の呼び出しでは、再びコールドスタートが発生します。デフォルトは900000（15分）です。0 にすると、サーバーが終了するまでセッションが維持されます。呼び出しの処理中のセッションが終了されることはありません。
• NG_TOKEN_SAVER_PREWARM=1 — アプリ内の path を指定して ng_workspace_map を呼び出すと、バックグラウンドでそのアプリを言語サーバーに読み込みます。これにより、最初の診断や定義の呼び出し時には準備が整います。実運用のモノレポでは21秒から1.4秒に短縮されました。代償として、アイドル時の終了まで約1 GBのメモリを消費します。LSP ツールが続けて呼び出されるかどうかは関係ありません。複数のプロジェクトを含むフォルダー（ワークスペースのルートや Nx の apps/ など）は、どのアプリを読み込むか不明なため、ウォームアップされません。
• NG_TOKEN_SAVER_SERVERS_DIR — 言語サーバーのブランチの場所です。ビルドの隣にある tools/servers 以外の場所にある場合に指定します。

エージェントでの使用

サーバーは MCP の instructions フィールド（924 文字）で使用方法を案内します。この内容は、ツールの説明がツール検索まで保留される場合でも、Claude Code のエージェントのコンテキストに保持されます（Claude Code 2.1.282 で確認済み：ツールには名前だけが表示される一方、テキスト全体が届きます）。instructions を無視するクライアントでは、同じ内容が CLAUDE.md または AGENTS.md に入ります。

コンパイラーとソースコードに基づいて回答する Angular ツールです。ファイル全体を読んだり grep したりする代わりに、こちらを優先してください。コンポーネントやディレクティブが受け付けるもの（入力、出力、メンバー、継承されたものを含む）には ng_component_info を使い、.ts ファイルを読む代わりにしてください。コンポーネント、ディレクティブ、パイプ、サービスが使われている場所には ng_find_usages を使い、grep の代わりにしてください。また、入力を指定すると、その入力がバインドされている場所を調べられます。テンプレートの編集後には ng build の代わりに ng_template_diagnostics を使ってください。テンプレートのシンボルの定義には ng_template_definition を使ってください。Angular API を提案する前には ng_version_rules を使ってください。プロジェクト、バージョン、strictTemplates を確認するには ng_workspace_map を一度使ってください。ワークスペースで最初に診断または定義を呼び出すと、プロジェクトが Angular language server に読み込まれるため、大規模なワークスペースでは最大 1 分かかります。その後の呼び出しは数ミリ秒で完了するため、最初の応答が遅くてもハングではありません。行と文字の位置はすべて 1 始まりで、Read と同じです。

測定値の再現

npm test                                  build plus 182 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

テスト対象は fixtures/v17..v22 です。実際の Angular ワークスペースが 6 つあり、それぞれに独自の node_modules と固定された TypeScript バージョンがあります。また、失敗ケース用に fixtures/negative/* があります。

ステータス

6 つすべてのツールを 6 つのフィクスチャと 2 つの本番コードベースで検証済みです。コンポーネント数はそれぞれ 1298 個と 407 個で、パースエラーはありません。また、範囲外の拒否が無言で行われず、構造化されることを確認するため、Angular 16 のプロジェクトでも検証しました。ユニットテストは 182 件で、すべて成功しています。

測定されたレイテンシー：LSP を使用する 2 つのツールは、初回呼び出し時にコールドスタートで 8～28 秒かかり、以降は 2～9 ms で応答します。静的な 4 つのツールは初回呼び出し時に 250～600 ms かかり、プロジェクトの TypeScript がキャッシュされた後は数ミリ秒で応答します。セッションが 15 分間アイドル状態になると、language server がシャットダウンされ、次の呼び出しでは再びコールドスタートにかかります。上記の NG_TOKEN_SAVER_IDLE_MS を参照してください。

ライセンス

GPL-3.0-or-later — LICENSE を参照してください。Copyright (C) 2026 Alex Ryabov. 自由に使用および変更できます。派生物も同じライセンスでオープンにする必要があります。