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"]。

一个 MCP（Model Context Protocol）服务，将 Spartan Angular UI 生态系统作为智能工具提供给 AI 驱动的 IDE 和助手。发现组件、浏览 Brain/Helm API、获取源代码、生成安装命令、检测项目上下文，并使用页面级构建块——所有操作均通过 MCP 协议完成。

为什么需要

Spartan 的双层架构（Brain 提供无头逻辑，Helm 提供带样式的组件）功能强大，但存在一定的学习曲线。AI 助手需要结构化地访问组件 API、源代码和安装模式，才能生成正确的 Angular 代码。此 MCP 服务填补了这一空白，将整个 Spartan 生态系统转变为可查询且具备上下文感知能力的工具集合。

功能

• 56 个组件，包含完整的 Brain/Helm API 详情（指令、输入、输出、信号模型）
• 17 个页面级构建块（侧边栏、登录、注册、日历变体）
• 支持对组件、构建块和文档进行模糊搜索
• 从 GitHub 获取 TypeScript 源代码，并进行智能缓存
• 项目上下文检测——Angular 版本、Nx 工作区、Tailwind 配置、无 Zone 模式
• 安装命令生成——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 请求限制为每小时 60 次。设置令牌后（无需任何权限范围，仅需访问公开仓库），限制为每小时 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 版本、已安装的包、包管理器和 zoneless 模式。
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

数据解析（三层）

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 概念

组件有两个 API 层：

• Brain ——无头、仅包含逻辑的原语。属性选择器，如 [brnDialogTrigger]。提供 ARIA、键盘处理和焦点管理。
• Helm ——使用 hostDirectives 组合 Brain 的样式化封装。混合选择器：[hlmBtn]、hlm-dialog-content、[hlmCard],hlm-card。使用 CVA（Class Variance Authority）实现变体，并使用 Tailwind 进行样式设计。

部分 Helm 组件直接封装 @angular/cdk，而不是 Brain（DropdownMenu、ContextMenu、Menubar）。

区块是页面级构建模块——由多个 Spartan 组件组成的完整 Angular 组件（侧边栏布局、登录表单、日历视图）。

技能

此 MCP 服务旨在与 spartan-ng-skills 配合使用——这些 Claude Code 技能用于教会 AI 助手如何正确组合 Spartan 组件。

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/

这些技能包含 6 个规则文件，其中有正确和错误的 Angular 代码示例，涵盖：

• Brain 与 Helm 的选择以及 hostDirectives
• 组件组合（Dialog、Card、Tabs、表单）
• 使用 hlm()、classes()、CVA 变体和语义令牌进行样式设计
• 使用 HlmField 系统的 Angular Reactive Forms
• 使用 ng-icon 的图标模式
• Angular 指令：signals、@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	—	GitHub PAT，每小时可发起 5000 次请求（未设置时为 60 次）。无需任何作用域。
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