Spartan Ng Mcp

spartan-ng-mcp

警告

このプロジェクトは非推奨となっており、メンテナンスも終了しています。 代わりに、公式の Spartan MCP サーバーを使用してください：@spartan-ng/mcp (ドキュメント、ソース）。

このサーバーがレジストリデータの取得に利用していた Spartan Analog API は利用できなくなったため、同梱のレジストリは更新されず、実行時の更新も機能しなくなりました。このパッケージは既存ユーザー向けに npm に残りますが、更新は行われません。

移行するには、MCP クライアントの設定で "args": ["-y", "spartan-ng-mcp"] を "args": ["-y", "@spartan-ng/mcp"] に置き換えてください。

AI 対応 IDE やアシスタント向けに、Spartan Angular UI エコシステムをインテリジェントなツールとして提供する MCP（Model Context Protocol）サーバーです。MCP プロトコルを通じて、コンポーネントの検索、Brain／Helm API の参照、ソースコードの取得、インストールコマンドの生成、プロジェクトコンテキストの検出、ページレベルの構成要素の利用ができます。

理由

Spartan の二層アーキテクチャ（ヘッドレスロジックの Brain と、スタイル付きコンポーネントの Helm）は強力ですが、習得には時間がかかります。AI アシスタントが正確な Angular コードを生成するには、コンポーネント API、ソースコード、インストール方法に構造化された形でアクセスする必要があります。この MCP サーバーはそのギャップを埋め、Spartan エコシステム全体を、クエリ可能でコンテキストを認識するツール群として提供します。

機能

• 56 個のコンポーネント：Brain／Helm API の詳細（ディレクティブ、入力、出力、シグナルモデル）を網羅
• 17 個のページレベルの構成要素（サイドバー、ログイン、サインアップ、カレンダーのバリエーション）
• コンポーネント、構成要素、ドキュメントを対象にしたあいまい検索
• GitHub からの TypeScript ソースコード取得（インテリジェントなキャッシュ機能付き）
• プロジェクトコンテキストの検出：Angular のバージョン、Nx ワークスペース、Tailwind 設定、ゾーンレスモード
• インストールコマンドの生成：nx generate または npm install（ピア依存関係の解決付き）
• インストール後の監査：Tailwind プリセット、Brain／Helm の組み合わせ、OnPush の確認チェックリスト
• 実行時のレジストリ更新：MCP の更新なしで新しい Spartan コンポーネントを取得
• スキルのインストーラー：spartan-ng-skills を任意の Angular プロジェクトに導入

クイックスタート

npm からインストール

npm install -g spartan-ng-mcp

IDE を設定する

Claude Code

プロジェクトの .mcp.json に追加します：

{
  "mcpServers": {
    "spartan-ng": {
      "command": "npx",
      "args": ["-y", "spartan-ng-mcp"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

Cursor

.cursor/mcp.json に追加します：

{
  "mcpServers": {
    "spartan-ng": {
      "command": "npx",
      "args": ["-y", "spartan-ng-mcp"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

VS Code（Copilot）

.vscode/mcp.json に追加します：

{
  "servers": {
    "spartan-ng": {
      "command": "npx",
      "args": ["-y", "spartan-ng-mcp"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

注： GITHUB_TOKEN は省略できますが、設定をおすすめします。設定しない場合、GitHub API リクエストは 1 時間あたり 60 回に制限されます。トークンを設定すると（スコープは不要です。公開リポジトリへのアクセスのみを使用します）、上限は 1 時間あたり 5000 回になります。

.env ファイルを使用する

トークンを IDE の設定ファイルに記載する代わりに（これらのファイルが git にコミットされる可能性があります）、プロジェクトのルートに .env ファイルを作成できます：

GITHUB_TOKEN=ghp_your_token_here
SPARTAN_CACHE_TTL_HOURS=48

MCP サーバーは起動時に .env を自動的に読み込みます。.env が .gitignore に含まれていることを確認してください。

代替方法：ソースからインストール

git clone https://github.com/carlospalacin/spartan-ng-mcp.git
cd spartan-ng-mcp
npm install
npm run build

ソースからインストールする場合は、上記の IDE 設定で "command": "npx" と "args": ["-y", "spartan-ng-mcp"] を、それぞれ "command": "node" と "args": ["/absolute/path/to/spartan-ng-mcp/dist/index.js"] に置き換えてください。

ツール

検索

ツール	説明
spartan_list	すべてのコンポーネントとブロックを一覧表示します。種類またはブロックのカテゴリで絞り込めます。
spartan_search	コンポーネント、ブロック、ドキュメントをあいまい検索します。スコア付きで、順位付けされた結果を表示します。
spartan_view	コンポーネントの詳細を表示します。Brain の指示、Helm コンポーネント、入力／出力、例、インストール用スニペットを確認できます。
spartan_dependencies	コンポーネントの依存関係グラフを表示します。直接依存、推移的依存、逆方向の依存関係を確認できます。

ソースコード

ツール	説明
spartan_source	GitHub から Brain／Helm の TypeScript ソースコードを取得します。
spartan_block_source	共有ユーティリティと抽出されたインポートを含むブロックのソースコードを取得します。

ドキュメント

ツール	説明
spartan_docs	インストール、CLI、テーマ設定、ダークモード、タイポグラフィ、figma、変更履歴に関するドキュメントを取得します。

インストール

ツール	説明
spartan_install_command	nx generate @spartan-ng/cli:ui または npm install コマンドを生成します。パッケージマネージャーを自動検出します。
spartan_audit	インストール後のチェックリストです。Angular プロジェクト、Tailwind、Spartan プリセット、Brain／Helm の組み合わせ、OnPush を確認します。
spartan_install_skills	spartan-ng-skills を、プロジェクトの .claude/skills/spartan/ ディレクトリにインストールします。

プロジェクトコンテキスト

ツール	説明
spartan_project_info	Angular／Nx の設定、Tailwind のバージョン、インストール済みパッケージ、パッケージマネージャー、ゾーンレスモードを検出します。
spartan_project_components	インストール済みの Brain／Helm パッケージを一覧表示し、不足している組み合わせを検出します。

キャッシュとレジストリ

ツール	説明
spartan_cache	キャッシュの状態確認、クリア、再構築を行います。メモリとファイルの統計情報、GitHub のレート制限を表示します。
spartan_registry_refresh	ライブの Spartan Analog API からレジストリを更新します。追加、更新、削除されたコンポーネントを報告します。

リソース

MCP リソースは、spartan:// URI スキームを介してデータに直接アクセスできます。

URI	説明
spartan://components/list	Brain／Helm の利用可否を含むすべてのコンポーネント
spartan://blocks/list	カテゴリー別にグループ化されたすべてのブロック
spartan://project/info	レジストリのメタデータ
spartan://component/{name}/api	コンポーネントの Brain と Helm の API 仕様
spartan://component/{name}/examples	コンポーネントのコード例

プロンプト

一般的なタスク向けに事前作成されたワークフローテンプレートです。

プロンプト	説明
spartan-get-started	任意のコンポーネントのインストール、API の概要、基本的な使い方
spartan-compare-layers	Brain と Helm の API を横並びで比較
spartan-implement	機能を実装するためのステップごとのガイド
spartan-use-block	ソース取得を含むブロックの統合ガイド
spartan-migrate	Nx ジェネレーターを使ったバージョン移行ガイド

アーキテクチャ

src/
├── index.ts                  # Entry point — stdio transport
├── server.ts                 # McpServer factory + tool registration
├── tools/                    # 14 MCP tools (one file per group)
│   ├── discovery.ts          # list, search, view, dependencies
│   ├── source.ts             # component + block source
│   ├── docs.ts               # documentation topics
│   ├── install.ts            # CLI commands + audit
│   ├── context.ts            # project detection
│   ├── cache.ts              # cache + registry refresh
│   ├── dependencies.ts       # dependency graph
│   └── skills.ts             # skills installer
├── data/                     # API clients
│   ├── analog-api.ts         # Spartan Analog API (primary data source)
│   ├── github.ts             # GitHub API (source code)
│   └── types.ts              # Shared TypeScript types
├── registry/                 # Hybrid component registry
│   ├── registry.ts           # Loader + search + runtime refresh
│   ├── schema.ts             # Zod validation schemas
│   └── registry.json         # Static registry (56 components, 17 blocks)
├── cache/                    # Multi-layer caching
│   ├── memory-cache.ts       # LRU with TTL (5 min)
│   ├── file-cache.ts         # Versioned file cache (24h)
│   └── cache-manager.ts      # Orchestrator: memory → file → network
├── project/                  # Project scanner
│   ├── detector.ts           # Angular/Nx/Tailwind/zoneless detection
│   └── types.ts              # SpartanProjectContext type
├── search/fuzzy.ts           # fuzzysort wrapper
├── errors/errors.ts          # SpartanError + 17 error codes
├── resources/spartan.ts      # spartan:// URI handlers
├── prompts/workflows.ts      # 5 workflow templates
└── utils/                    # Pure utilities
    ├── constants.ts           # URLs, timeouts, allowed hosts
    ├── fetch.ts               # HTTP client with SSRF protection
    ├── html.ts                # HTML parsing + extraction
    └── imports.ts             # TypeScript import/export extraction

データ解決（3 層）

Discovery (list, search)    →  Static Registry (instant, offline)
Details (view, examples)    →  Memory Cache → File Cache → Analog API
Source code (source, block) →  Memory Cache → File Cache → GitHub API

1. 静的レジストリ（registry.json） — リリースごとにコミットされ、遅延はゼロです
2. Analog API — spartan.ng の構造化 JSON。30 分間（メモリ）＋24 時間（ファイル）キャッシュされます
3. GitHub API — TypeScript ソースコード。24 時間キャッシュされ、レート制限があります

Spartan UI の概念

コンポーネントには 2 つの API レイヤーがあります。

• Brain — ヘッドレスで、ロジックのみを扱うプリミティブです。[brnDialogTrigger] のような属性セレクターを使用します。ARIA、キーボード操作、フォーカス管理を提供します。
• Helm — hostDirectives を使って Brain を組み合わせる、スタイル付きのラッパーです。[hlmBtn]、hlm-dialog-content、[hlmCard],hlm-card のような混合セレクターを使用します。バリアントには CVA（Class Variance Authority）、スタイリングには Tailwind を使用します。

一部の Helm コンポーネントは Brain ではなく、@angular/cdk を直接ラップします（DropdownMenu、ContextMenu、Menubar）。

ブロックはページレベルの構成要素です。複数の Spartan コンポーネントを組み合わせた、完全な Angular コンポーネントです（サイドバーのレイアウト、ログインフォーム、カレンダー表示など）。

スキル

この MCP サーバーは、spartan-ng-skills と連携するよう設計されています。これは、Spartan コンポーネントを正しく組み合わせる方法を AI アシスタントに教える Claude Code スキルです。

MCP が知識を提供します。つまり、どのコンポーネントが存在するか、それらの API、ソースコードです。 スキル が知恵を提供します。つまり、正しい使い方、組み合わせのルール、スタイリングの慣例です。

スキルを任意のプロジェクトにインストールできます。

# Via MCP tool
spartan_install_skills(cwd="/path/to/your-angular-project")

# Or manually
cp -r /path/to/spartan-ng-skills/.claude /path/to/your-angular-project/

スキルには、正しい Angular コードと誤った Angular コードのペアを含む 6 つのルールファイルがあり、以下を扱います。

• Brain と Helm の選択および hostDirectives
• コンポーネントの組み合わせ（Dialog、Card、Tabs、フォーム）
• hlm()、classes()、CVA バリアント、セマンティックトークンを使ったスタイリング
• HlmField システムを使った Angular Reactive Forms
• ng-icon を使ったアイコンのパターン
• Angular ディレクティブ：シグナル、@if／@for、inject()、OnPush

設定

すべての設定は、MCP 設定ファイル（.mcp.json、.cursor/mcp.json など）の env ブロックで渡します。

{
  "mcpServers": {
    "spartan-ng": {
      "command": "npx",
      "args": ["-y", "spartan-ng-mcp"],
      "env": {
        "GITHUB_TOKEN": "ghp_...",
        "SPARTAN_CACHE_TTL_HOURS": "48"
      }
    }
  }
}

利用可能な環境変数

環境変数	デフォルト	説明
GITHUB_TOKEN	—	5000 req/hr（未設定の場合は60/hr）のGitHub PATです。スコープは不要です。
SPARTAN_CACHE_TTL_HOURS	24	ファイルキャッシュのTTL（時間）
SPARTAN_CACHE_TTL_MS	300000	メモリー内キャッシュのTTL（ミリ秒、5分）
SPARTAN_FETCH_TIMEOUT_MS	15000	HTTPフェッチのタイムアウト（ミリ秒）

レジストリの更新

Spartanが新しいコンポーネントをリリースした場合：

# Regenerate from live Analog API
npm run generate-registry

# Rebuild
npm run build

再ビルドせずに、実行時に更新する場合：

spartan_registry_refresh(force=true)

開発

npm run dev          # TypeScript watch mode
npm run typecheck    # Type-check without emitting
npm run build        # Compile to dist/
npm test             # Run tests
npm run lint         # ESLint

ライセンス

MIT