Spartan Ng Mcp

Servidor MCP que concede aos assistentes de IA acesso completo ao ecossistema Spartan Angular UI — descoberta de componentes, APIs Brain/Helm, código-fonte, comandos de instalação e detecção de contexto de projeto.

GitHub

Experimente este MCPPatrocinado

Documentação

spartan-ng-mcp

[!warning] Aviso Este projeto está descontinuado e não é mais mantido. Use o servidor oficial Spartan MCP em vez disso: @spartan-ng/mcp (docs, source).

A API Spartan Analog da qual este servidor dependia para dados de registro não está mais disponível, então o registro incluído está congelado e a atualização em tempo de execução não funciona mais. O pacote permanece no npm para usuários existentes, mas não receberá atualizações.

Para migrar, substitua "args": ["-y", "spartan-ng-mcp"] por "args": ["-y", "@spartan-ng/mcp"] na configuração do seu cliente MCP.

Um servidor MCP (Model Context Protocol) que expõe o ecossistema Spartan Angular UI como ferramentas inteligentes para IDEs e assistentes com IA. Descubra componentes, navegue pelas APIs Brain/Helm, busque código-fonte, gere comandos de instalação, detecte o contexto do projeto e use blocos de construção em nível de página — tudo por meio do protocolo MCP.

Por quê

A arquitetura de camada dupla do Spartan (Brain para lógica headless + Helm para componentes estilizados) é poderosa, mas tem uma curva de aprendizado. Assistentes de IA precisam de acesso estruturado a APIs de componentes, código-fonte e padrões de instalação para gerar código Angular correto. Este servidor MCP preenche essa lacuna — transformando todo o ecossistema Spartan em uma superfície de ferramentas consultável e sensível ao contexto.

Recursos

56 componentes com detalhes completos de API Brain/Helm (diretivas, entradas, saídas, modelos de sinal)
17 blocos em nível de página (sidebar, login, signup, variantes de calendário)
Pesquisa difusa em componentes, blocos e documentação
Busca de código-fonte TypeScript no GitHub com cache inteligente
Detecção de contexto do projeto — versão do Angular, workspace Nx, configuração do Tailwind, modo sem zonas
Geração de comandos de instalação — nx generate ou npm install com resolução de dependências pares
Auditoria pós-instalação — lista de verificação para preset Tailwind, pareamento Brain/Helm, OnPush
Atualização do registro em tempo de execução — capture novos componentes Spartan sem uma atualização do MCP
Instalador de skills — implante spartan-ng-skills em qualquer projeto Angular

Início Rápido

Instalar a partir do npm

npm install -g spartan-ng-mcp

Configurar Sua IDE

Claude Code

Adicione ao .mcp.json do seu projeto:

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

Cursor

Adicione ao .cursor/mcp.json:

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

VS Code (Copilot)

Adicione ao .vscode/mcp.json:

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

Nota: O GITHUB_TOKEN é opcional, mas recomendado. Sem ele, as solicitações à API do GitHub são limitadas a 60/hora. Com um token (sem escopos necessários — apenas acesso a repositórios públicos), o limite é de 5000/hora.

Usando um arquivo .env

Em vez de colocar tokens em arquivos de configuração da IDE (que podem ser commitados no git), você pode criar um arquivo .env na raiz do seu projeto:

GITHUB_TOKEN=ghp_your_token_here
SPARTAN_CACHE_TTL_HOURS=48

O servidor MCP carrega .env automaticamente na inicialização. Certifique-se de que .env esteja no seu .gitignore.

Alternativa: Instalar a partir do Código-Fonte

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

Ao instalar a partir do código-fonte, substitua "command": "npx" e "args": ["-y", "spartan-ng-mcp"] por "command": "node" e "args": ["/absolute/path/to/spartan-ng-mcp/dist/index.js"] nas configurações da IDE acima.

Ferramentas

Descoberta

Ferramenta	Descrição
`spartan_list`	Liste todos os componentes e blocos. Filtre por tipo ou categoria de bloco.
`spartan_search`	Pesquisa difusa em componentes, blocos e docs. Resultados classificados com pontuações.
`spartan_view`	Visualização detalhada do componente: diretivas Brain, componentes Helm, entradas/saídas, exemplos, trechos de instalação.
`spartan_dependencies`	Grafo de dependências do componente com dependências diretas, transitivas e reversas.

Código-Fonte

Ferramenta	Descrição
`spartan_source`	Busque código-fonte TypeScript Brain/Helm do GitHub.
`spartan_block_source`	Busque código-fonte de blocos com utilitários compartilhados e importações extraídas.

Documentação

Ferramenta	Descrição
`spartan_docs`	Busque tópicos de documentação: instalação, CLI, temas, modo escuro, tipografia, figma, changelog.

Instalação

Ferramenta	Descrição
`spartan_install_command`	Gere comandos `nx generate @spartan-ng/cli:ui` ou `npm install`. Detecta automaticamente o gerenciador de pacotes.
`spartan_audit`	Lista de verificação pós-instalação: projeto Angular, Tailwind, preset Spartan, pareamento Brain/Helm, OnPush.
`spartan_install_skills`	Instale spartan-ng-skills no diretório `.claude/skills/spartan/` de um projeto.

Contexto do Projeto

Ferramenta	Descrição
`spartan_project_info`	Detecte configuração Angular/Nx, versão do Tailwind, pacotes instalados, gerenciador de pacotes, modo sem zonas.
`spartan_project_components`	Liste pacotes Brain/Helm instalados com detecção de pares ausentes.

Cache e Registro

Ferramenta	Descrição
`spartan_cache`	Status do cache, limpar ou reconstruir. Mostra estatísticas de memória + arquivo e limite de taxa do GitHub.
`spartan_registry_refresh`	Atualize o registro a partir da API Spartan Analog ao vivo. Relata componentes adicionados/atualizados/removidos.

Recursos

Os recursos MCP fornecem acesso direto a dados por meio do esquema de URI spartan://:

URI	Descrição
`spartan://components/list`	Todos os componentes com disponibilidade Brain/Helm
`spartan://blocks/list`	Todos os blocos agrupados por categoria
`spartan://project/info`	Metadados do registro
`spartan://component/{name}/api`	Especificações de API Brain e Helm para um componente
`spartan://component/{name}/examples`	Exemplos de código para um componente

Prompts

Modelos de fluxo de trabalho pré-construídos para tarefas comuns:

Prompt	Descrição
`spartan-get-started`	Visão geral de instalação + API + uso básico para qualquer componente
`spartan-compare-layers`	Comparação lado a lado de API Brain vs Helm
`spartan-implement`	Guia passo a passo de implementação de recursos
`spartan-use-block`	Guia de integração de blocos com busca de código-fonte
`spartan-migrate`	Guia de migração de versão com geradores Nx

Arquitetura

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

Resolução de Dados (3 camadas)

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

Registro Estático (registry.json) — commitado por versão, latência zero
API Analog — JSON estruturado de spartan.ng, cache de 30min (memória) + 24h (arquivo)
API GitHub — código-fonte TypeScript, cache de 24h, com limite de taxa

Conceitos da UI Spartan

Os componentes têm duas camadas de API:

Brain — primitivos headless, somente lógica. Seletores de atributo como [brnDialogTrigger]. Fornece ARIA, manipulação de teclado e gerenciamento de foco.
Helm — wrappers estilizados usando hostDirectives para compor Brain. Seletores mistos: [hlmBtn], hlm-dialog-content, [hlmCard],hlm-card. Usa CVA (Class Variance Authority) para variantes e Tailwind para estilização.

Alguns componentes Helm envolvem @angular/cdk diretamente em vez de Brain (DropdownMenu, ContextMenu, Menubar).

Blocos são blocos de construção em nível de página — componentes Angular completos que combinam vários componentes Spartan (layouts de sidebar, formulários de login, visualizações de calendário).

Skills

Este servidor MCP foi projetado para funcionar em conjunto com spartan-ng-skills — skills do Claude Code que ensinam assistentes de IA a compor corretamente componentes Spartan.

MCP fornece o conhecimento: quais componentes existem, suas APIs, código-fonte. Skills fornecem a sabedoria: como usá-los corretamente, regras de composição, convenções de estilo.

Instale skills em qualquer projeto:

# 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/

As skills incluem 6 arquivos de regras com pares de código Angular correto/incorreto cobrindo:

Seleção Brain vs Helm e hostDirectives
Composição de componentes (Dialog, Card, Tabs, formulários)
Estilização com hlm(), classes(), variantes CVA, tokens semânticos
Formulários reativos Angular com o sistema HlmField
Padrões de ícones com ng-icon
Diretivas Angular: signals, @if / @for, inject(), OnPush

Configuração

Todas as configurações são passadas por meio do bloco env no seu arquivo de configuração MCP (.mcp.json, .cursor/mcp.json, etc.):

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

Variáveis Disponíveis

Variável	Padrão	Descrição
`GITHUB_TOKEN`	—	PAT do GitHub para 5000 req/h (60/h sem). Nenhum escopo necessário.
`SPARTAN_CACHE_TTL_HOURS`	`24`	TTL do cache de arquivos em horas
`SPARTAN_CACHE_TTL_MS`	`300000`	TTL do cache em memória em ms (5 min)
`SPARTAN_FETCH_TIMEOUT_MS`	`15000`	Tempo limite de busca HTTP em ms

Atualizando o Registro

Quando o Spartan lança novos componentes:

# Regenerate from live Analog API
npm run generate-registry

# Rebuild
npm run build

Ou em tempo de execução sem reconstruir:

spartan_registry_refresh(force=true)

Desenvolvimento

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