Spartan Ng Mcp

Servidor MCP que otorga a los asistentes de IA acceso completo al ecosistema de interfaz de usuario Spartan Angular: descubrimiento de componentes, APIs Brain/Helm, código fuente, comandos de instalación y detección de contexto de proyecto.

GitHub

Prueba este MCPPatrocinado

Documentación

spartan-ng-mcp

[!warning] Advertencia Este proyecto está obsoleto y ya no recibe mantenimiento. Usa el servidor oficial Spartan MCP en su lugar: @spartan-ng/mcp (docs, fuente).

La API Spartan Analog de la que este servidor dependía para los datos del registro ya no está disponible, por lo que el registro incluido está congelado y la actualización en tiempo de ejecución ya no funciona. El paquete permanece en npm para los usuarios existentes, pero no recibirá actualizaciones.

Para migrar, reemplaza "args": ["-y", "spartan-ng-mcp"] por "args": ["-y", "@spartan-ng/mcp"] en la configuración de tu cliente MCP.

Un servidor MCP (Protocolo de Contexto de Modelo) que expone el ecosistema Spartan Angular UI como herramientas inteligentes para IDEs y asistentes impulsados por IA. Descubre componentes, explora las APIs de Brain/Helm, obtén código fuente, genera comandos de instalación, detecta el contexto del proyecto y usa bloques de construcción a nivel de página, todo a través del protocolo MCP.

Por qué

La arquitectura de doble capa de Spartan (Brain para lógica headless + Helm para componentes con estilo) es potente pero tiene una curva de aprendizaje. Los asistentes de IA necesitan acceso estructurado a las APIs de componentes, código fuente y patrones de instalación para generar código Angular correcto. Este servidor MCP cierra esa brecha: convierte todo el ecosistema Spartan en una superficie de herramientas consultable y consciente del contexto.

Características

56 componentes con detalles completos de API Brain/Helm (directivas, entradas, salidas, modelos de señal)
17 bloques a nivel de página (barra lateral, inicio de sesión, registro, variantes de calendario)
Búsqueda difusa en componentes, bloques y documentación
Obtención de código fuente TypeScript desde GitHub con caché inteligente
Detección de contexto del proyecto — versión de Angular, espacio de trabajo Nx, configuración de Tailwind, modo sin zonas
Generación de comandos de instalación — nx generate o npm install con resolución de dependencias entre pares
Auditoría posterior a la instalación — lista de verificación para el preset de Tailwind, emparejamiento Brain/Helm, OnPush
Actualización del registro en tiempo de ejecución — incorpora nuevos componentes Spartan sin una actualización de MCP
Instalador de habilidades — implementa spartan-ng-skills en cualquier proyecto Angular

Inicio rápido

Instalar desde npm

npm install -g spartan-ng-mcp

Configurar tu IDE

Claude Code

Añade a .mcp.json de tu proyecto:

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

Cursor

Añade a .cursor/mcp.json:

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

VS Code (Copilot)

Añade a .vscode/mcp.json:

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

Nota: El GITHUB_TOKEN es opcional pero recomendado. Sin él, las solicitudes a la API de GitHub están limitadas a 60/hora. Con un token (sin permisos necesarios — solo acceso a repositorios públicos), el límite es de 5000/hora.

Usar un archivo .env

En lugar de poner tokens en los archivos de configuración del IDE (que pueden llegar a git), puedes crear un archivo .env en la raíz de tu proyecto:

GITHUB_TOKEN=ghp_your_token_here
SPARTAN_CACHE_TTL_HOURS=48

El servidor MCP carga .env automáticamente al iniciar. Asegúrate de que .env esté en tu .gitignore.

Alternativa: Instalar desde el código fuente

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

Al instalar desde el código fuente, reemplaza "command": "npx" y "args": ["-y", "spartan-ng-mcp"] por "command": "node" y "args": ["/absolute/path/to/spartan-ng-mcp/dist/index.js"] en las configuraciones de IDE anteriores.

Herramientas

Descubrimiento

Herramienta	Descripción
`spartan_list`	Lista todos los componentes y bloques. Filtra por tipo o categoría de bloque.
`spartan_search`	Búsqueda difusa en componentes, bloques y documentación. Resultados clasificados con puntuaciones.
`spartan_view`	Vista detallada del componente: directivas Brain, componentes Helm, entradas/salidas, ejemplos, fragmentos de instalación.
`spartan_dependencies`	Grafo de dependencias del componente con dependencias directas, transitivas e inversas.

Código fuente

Herramienta	Descripción
`spartan_source`	Obtiene el código fuente TypeScript de Brain/Helm desde GitHub.
`spartan_block_source`	Obtiene el código fuente del bloque con utilidades compartidas e importaciones extraídas.

Documentación

Herramienta	Descripción
`spartan_docs`	Obtiene temas de documentación: instalación, CLI, temas, modo oscuro, tipografía, figma, registro de cambios.

Instalación

Herramienta	Descripción
`spartan_install_command`	Genera comandos `nx generate @spartan-ng/cli:ui` o `npm install`. Detecta automáticamente el gestor de paquetes.
`spartan_audit`	Lista de verificación posterior a la instalación: proyecto Angular, Tailwind, preset Spartan, emparejamiento Brain/Helm, OnPush.
`spartan_install_skills`	Instala spartan-ng-skills en el directorio `.claude/skills/spartan/` de un proyecto.

Contexto del proyecto

Herramienta	Descripción
`spartan_project_info`	Detecta configuración de Angular/Nx, versión de Tailwind, paquetes instalados, gestor de paquetes, modo sin zonas.
`spartan_project_components`	Lista paquetes Brain/Helm instalados con detección de pares faltantes.

Caché y registro

Herramienta	Descripción
`spartan_cache`	Estado de la caché, limpiar o reconstruir. Muestra estadísticas de memoria y archivos, y el límite de tasa de GitHub.
`spartan_registry_refresh`	Actualiza el registro desde la API Spartan Analog en vivo. Informa componentes añadidos/actualizados/eliminados.

Recursos

Los recursos MCP proporcionan acceso directo a datos mediante el esquema de URI spartan://:

URI	Descripción
`spartan://components/list`	Todos los componentes con disponibilidad de Brain/Helm
`spartan://blocks/list`	Todos los bloques agrupados por categoría
`spartan://project/info`	Metadatos del registro
`spartan://component/{name}/api`	Especificaciones de API Brain y Helm para un componente
`spartan://component/{name}/examples`	Ejemplos de código para un componente

Prompts

Plantillas de flujo de trabajo preconstruidas para tareas comunes:

Prompt	Descripción
`spartan-get-started`	Instalación + descripción general de API + uso básico para cualquier componente
`spartan-compare-layers`	Comparación lado a lado de API Brain vs Helm
`spartan-implement`	Guía de implementación de funciones paso a paso
`spartan-use-block`	Guía de integración de bloques con obtención de código fuente
`spartan-migrate`	Guía de migración de versiones con generadores Nx

Arquitectura

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

Resolución de datos (3 niveles)

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) — confirmado por versión, latencia cero
API Analog — JSON estructurado de spartan.ng, en caché 30 min (memoria) + 24 h (archivo)
API de GitHub — código fuente TypeScript, en caché 24 h, con límite de tasa

Conceptos de Spartan UI

Los componentes tienen dos capas de API:

Brain — primitivas headless, solo lógica. Selectores de atributo como [brnDialogTrigger]. Proporciona ARIA, manejo de teclado y gestión de enfoque.
Helm — envoltorios con estilo que usan hostDirectives para componer Brain. Selectores mixtos: [hlmBtn], hlm-dialog-content, [hlmCard],hlm-card. Usa CVA (Class Variance Authority) para variantes y Tailwind para estilos.

Algunos componentes Helm envuelven @angular/cdk directamente en lugar de Brain (DropdownMenu, ContextMenu, Menubar).

Los bloques son bloques de construcción a nivel de página: componentes Angular completos que combinan múltiples componentes Spartan (diseños de barra lateral, formularios de inicio de sesión, vistas de calendario).

Habilidades

Este servidor MCP está diseñado para funcionar junto con spartan-ng-skills — habilidades de Claude Code que enseñan a los asistentes de IA cómo componer correctamente componentes Spartan.

MCP proporciona el conocimiento: qué componentes existen, sus APIs, código fuente. Las habilidades proporcionan la sabiduría: cómo usarlos correctamente, reglas de composición, convenciones de estilo.

Instala habilidades en cualquier proyecto:

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

Las habilidades incluyen 6 archivos de reglas con pares de código Angular correcto/incorrecto que cubren:

Selección de Brain vs Helm y hostDirectives
Composición de componentes (Dialog, Card, Tabs, formularios)
Estilos con hlm(), classes(), variantes CVA, tokens semánticos
Formularios reactivos de Angular con el sistema HlmField
Patrones de iconos con ng-icon
Directivas de Angular: señales, @if / @for, inject(), OnPush

Configuración

Todos los ajustes se pasan mediante el bloque env en tu archivo de configuración 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"
      }
    }
  }
}

Variables disponibles

Variable	Predeterminado	Descripción
`GITHUB_TOKEN`	—	PAT de GitHub para 5000 solicitudes/hora (60/hora sin él). No se requieren permisos.
`SPARTAN_CACHE_TTL_HOURS`	`24`	TTL de caché de archivos en horas
`SPARTAN_CACHE_TTL_MS`	`300000`	TTL de caché en memoria en ms (5 min)
`SPARTAN_FETCH_TIMEOUT_MS`	`15000`	Tiempo de espera de obtención HTTP en ms

Actualizar el registro

Cuando Spartan publique nuevos componentes:

# Regenerate from live Analog API
npm run generate-registry

# Rebuild
npm run build

O en tiempo de ejecución sin reconstruir:

spartan_registry_refresh(force=true)

Desarrollo

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