Tailwind Svelte Assistant

Proporciona documentación y fragmentos de código para SvelteKit y Tailwind CSS.

GitHub
10
Prueba este MCPPatrocinado

Documentación

Servidor MCP Tailwind Svelte Assistant

smithery badge

Un servidor de Protocolo de Contexto de Modelo (MCP) seguro y de alto rendimiento que proporciona documentación completa de SvelteKit y Tailwind CSS (100% de cobertura) y fragmentos de código con seguridad mejorada, implementación adecuada en TypeScript y manejo integral de errores.

✨ Novedades (v0.1.1)

📚 Cobertura Completa de Documentación

  • 100% de Cobertura Svelte/SvelteKit: Documentación oficial optimizada para LLM (1.04 MB)
  • 100% de Cobertura Tailwind CSS: Documentación completa mediante extracción Repomix (2.1 MB, 249 archivos)
  • Búsqueda Inteligente: Búsqueda dentro de la documentación completa con contexto
  • Mejora de 12.5x-25x: Del 4-8% de cobertura al 100%

🚀 Mejoras Clave (v0.1.1)

🔒 Mejoras de Seguridad

  • Protección contra Recorrido de Rutas: Saneamiento integral de entradas para prevenir ataques de recorrido de directorios
  • Validación de Entradas: Validación estricta de parámetros con coincidencia de patrones y límites de longitud
  • Operaciones Seguras de Archivos: Acceso limitado a archivos con validación de rutas y límites de tamaño
  • Registro de Auditoría: Registro estructurado de eventos de seguridad para monitoreo

🏗️ Mejoras de Arquitectura

  • Diseño Modular: Separación de responsabilidades en servicios y utilidades dedicadas
  • Excelencia en TypeScript: Seguridad total de tipos con interfaces adecuadas y sin tipos any
  • Módulos ES: Sistema moderno de módulos JavaScript con importaciones adecuadas
  • Manejo de Errores: Clasificación integral de errores y mensajes de error seguros

⚡ Optimizaciones de Rendimiento

  • Caché de Contenido: Caché LRU con tiempo de espera configurable para mejorar los tiempos de respuesta
  • Límites de Tamaño de Archivos: Previene el agotamiento de recursos con límites configurables
  • Operaciones Asíncronas: Operaciones de archivos no bloqueantes para mejor concurrencia
  • Gestión de Memoria: Limpieza automática de caché y recolección de basura

📁 Estructura del Proyecto

src/
├── index.ts                 # Main server with security hardening
├── types.ts                 # TypeScript type definitions
├── services/
│   └── fileService.ts       # Secure file operations with caching
└── utils/
    ├── security.ts          # Input validation and path sanitization
    └── errorHandler.ts      # Comprehensive error handling

🚀 Inicio Rápido

Instalación mediante Smithery (Recomendado)

La forma más fácil de instalar este servidor MCP es a través de Smithery:

npx -y @smithery/cli install @CaullenOmdahl/tailwind-svelte-assistant --client claude

Esto automáticamente:

  • Instalará el servidor
  • Lo configurará para Claude Desktop
  • Configurará todas las dependencias requeridas

Instalación mediante URL Directa

Para otros clientes MCP, use la URL directa del servidor:

https://server.smithery.ai/@CaullenOmdahl/tailwind-svelte-assistant/mcp

Agregue esto a la configuración de su cliente MCP:

{
  "mcpServers": {
    "tailwind-svelte-assistant": {
      "url": "https://server.smithery.ai/@CaullenOmdahl/tailwind-svelte-assistant/mcp",
      "transport": "http"
    }
  }
}

🛠️ Instalación y Configuración Manual

Requisitos Previos

  • Node.js 20+ (requerido para soporte de módulos ES y dependencias)
  • npm o yarn
  • Git (para clonar el repositorio)

Instalar Dependencias

npm install

Compilar el Servidor

npm run build

Modo de Desarrollo

npm run watch

🔧 Configuración

El servidor usa valores predeterminados seguros pero puede configurarse mediante la interfaz ServerConfig:

const CONFIG: ServerConfig = {
  maxFileSize: 3 * 1024 * 1024,    // 3MB max file size (for full docs)
  cacheTimeout: 5 * 60 * 1000,     // 5 minutes cache timeout
  contentBasePath: './content',
  svelteFullDocsPath: './content/docs/svelte-sveltekit-full.txt',
  tailwindFullDocsPath: './content/docs/tailwind-docs-full.txt',
  // ... other paths
};

Actualizaciones de Documentación

La documentación se descarga y actualiza automáticamente:

# Update all documentation (Svelte + Tailwind)
npm run update-content

Este script:

  • Descarga la documentación oficial de Svelte optimizada para LLM (svelte.dev/llms-full.txt)
  • Extrae la documentación completa de Tailwind desde GitHub mediante Repomix
  • Actualiza las marcas de tiempo de los fragmentos de componentes
  • Genera un resumen de contenido

Fuentes:

  • Svelte/SvelteKit: Archivo de texto oficial optimizado para LLM (100% de cobertura)
  • Tailwind CSS: Repositorio de GitHub mediante extracción Repomix (249 archivos MDX)
  • Fragmentos: Ejemplos locales de componentes seleccionados (43 archivos)

🛡️ Características de Seguridad

Validación de Entradas

  • Coincidencia de Patrones: Solo se permiten caracteres alfanuméricos, guiones, guiones bajos y puntos
  • Límites de Longitud: Longitudes máximas de entrada configurables
  • Saneamiento de Rutas: Elimina intentos de recorrido de directorios
  • Verificación de Límites: Asegura que el acceso a archivos permanezca dentro de los directorios permitidos

Manejo de Errores

  • Mensajes de Error Seguros: No se expone información sensible a los clientes
  • Registro Estructurado: Registros de auditoría en formato JSON para monitoreo de seguridad
  • Clasificación de Errores: Manejo diferente para distintos tipos de errores
  • Degradación Gradual: Respuestas de respaldo para fallos no críticos

Seguridad del Sistema de Archivos

  • Validación de Rutas: Verifica que las rutas resueltas estén dentro de los directorios base
  • Límites de Tamaño de Archivos: Previene ataques de agotamiento de recursos
  • Operaciones de Solo Lectura: No se exponen operaciones de escritura a los clientes
  • Aislamiento de Caché: El almacenamiento en caché de contenido no expone la estructura del sistema de archivos

📊 Características de Rendimiento

Sistema de Caché

// Automatic content caching with configurable timeout
const fileService = new SecureFileService(
  1024 * 1024,    // Max file size
  5 * 60 * 1000   // Cache timeout (5 minutes)
);

Gestión de Recursos

  • Límites de Memoria: Las restricciones de tamaño de archivos previenen el agotamiento de memoria
  • Limpieza de Caché: Eliminación automática de entradas de caché expiradas
  • E/S Asíncrona: Operaciones de archivos no bloqueantes
  • Recuperación de Errores: Manejo gradual de limitaciones de recursos

🔍 Herramientas Disponibles

🆕 Herramientas de Documentación Completa (Recomendadas)

  • get_svelte_full_docs - Obtener documentación completa de Svelte y SvelteKit (1MB, 100% de cobertura)

    • No requiere parámetros
    • Devuelve toda la documentación en un solo archivo optimizado para LLM
    • Formato oficial del equipo de Svelte

  • get_tailwind_full_docs - Obtener documentación completa de Tailwind CSS (2.1MB, 100% de cobertura)

    • No requiere parámetros
    • Incluye los 249 archivos de documentación
    • Todas las clases de utilidad y conceptos cubiertos

  • search_svelte_docs - Buscar dentro de la documentación de Svelte/SvelteKit

    • Parámetros: query (cadena), limit (opcional, predeterminado: 5)
    • Devuelve secciones coincidentes con contexto circundante
    • Búsqueda rápida en memoria

  • search_tailwind_docs - Buscar dentro de la documentación de Tailwind CSS

    • Parámetros: query (cadena), limit (opcional, predeterminado: 5)
    • Devuelve secciones coincidentes con contexto circundante
    • Cubre todas las clases de utilidad

Herramientas de Documentación Heredadas

Nota: Estas herramientas solo cubren aproximadamente el 4-8% de la documentación disponible. Use las herramientas de documentación completa anteriores para una cobertura total.

  • get_sveltekit_doc - Recuperar un tema específico de documentación de SvelteKit
  • get_tailwind_info - Obtener información específica de Tailwind CSS
  • list_sveltekit_topics - Listar documentos de SvelteKit disponibles (limitado)
  • list_tailwind_info_topics - Listar documentación de Tailwind (limitado)

Herramientas de Componentes

  • get_component_snippet - Obtener código de componentes Svelte
  • list_snippet_categories - Listar categorías de componentes
  • list_snippets_in_category - Listar fragmentos en una categoría

Esquemas de Herramientas Mejorados

Todas las herramientas incluyen:

  • Validación de patrones con restricciones de expresiones regulares
  • Límites de longitud para parámetros de entrada
  • Descripciones completas con ejemplos de uso
  • Saneamiento de entradas reforzado para seguridad

📝 Ejemplos de Uso

Configuración del Cliente MCP

Opción 1: Alojado en Smithery (Recomendado)

{
  "mcpServers": {
    "tailwind-svelte-assistant": {
      "url": "https://server.smithery.ai/@CaullenOmdahl/tailwind-svelte-assistant/mcp",
      "transport": "http"
    }
  }
}

Opción 2: Instalación Local

{
  "mcpServers": {
    "tailwind-svelte-assistant": {
      "command": "node",
      "args": ["./dist/index.js"],
      "env": {}
    }
  }
}

Uso de Herramientas

Recomendado: Documentación Completa

// Get complete Svelte/SvelteKit documentation (1MB, 100% coverage)
await client.callTool("get_svelte_full_docs", {});

// Get complete Tailwind CSS documentation (2.1MB, 100% coverage)
await client.callTool("get_tailwind_full_docs", {});

// Search within Svelte documentation
await client.callTool("search_svelte_docs", {
  query: "load function",
  limit: 5  // optional
});

// Search within Tailwind documentation
await client.callTool("search_tailwind_docs", {
  query: "padding utilities",
  limit: 3  // optional
});

Heredado: Temas Específicos (Cobertura Limitada)

// Get specific SvelteKit topic (only covers ~8% of docs)
await client.callTool("get_sveltekit_doc", { topic: "routing" });

// Get specific Tailwind info (only covers ~4% of docs)
await client.callTool("get_tailwind_info", { query: "padding" });

// List available topics (limited)
await client.callTool("list_tailwind_info_topics", {});

Fragmentos de Componentes

// Get a component snippet
await client.callTool("get_component_snippet", {
  component_category: "headers",
  snippet_name: "navbar-default"
});

// List snippet categories
await client.callTool("list_snippet_categories", {});

🧪 Pruebas y Aseguramiento de Calidad

Auditoría de Seguridad

npm run security-audit

Verificación de Dependencias

npm run outdated-check

Inspector MCP

npm run inspector

🐳 Despliegue con Docker

El Dockerfile incluido proporciona una compilación segura de múltiples etapas:

# Multi-stage build with security hardening
FROM node:18-alpine AS builder
# ... build process

FROM node:18-alpine AS release
# ... production setup with non-root user

Características de Seguridad

  • Compilación de múltiples etapas reduce la superficie de ataque
  • Alpine Linux para una huella mínima
  • Usuario no root para seguridad del contenedor
  • Solo dependencias de producción

📈 Monitoreo y Registro

Registro Estructurado

Todas las operaciones se registran con JSON estructurado para facilitar el análisis:

{
  "timestamp": "2024-01-15T10:30:00.000Z",
  "level": "info",
  "operation": "tool_request",
  "tool": "get_sveltekit_doc",
  "topic": "routing"
}

Eventos de Auditoría

  • Solicitudes de herramientas con parámetros
  • Violaciones de seguridad y solicitudes bloqueadas
  • Condiciones de error con clasificación
  • Métricas de rendimiento y aciertos de caché

🔄 Migración desde v0.1.0

Cambios Importantes

  • Módulos ES: Actualizado para usar import/export en lugar de require
  • TypeScript: El tipado estricto puede requerir aserciones de tipo en algunos casos
  • Mensajes de Error: Mensajes de error más seguros y menos detallados

Compatibilidad

  • Interfaz de Herramientas: Todas las herramientas existentes funcionan con validación mejorada
  • Estructura de Contenido: Sin cambios en la organización del contenido
  • Docker: Imagen base actualizada y endurecimiento de seguridad

🤝 Contribuciones

Guías de Desarrollo

  1. Seguridad Primero: Todos los cambios deben pasar la revisión de seguridad
  2. Seguridad de Tipos: Mantener cumplimiento estricto de TypeScript
  3. Cobertura de Pruebas: Incluir pruebas para nueva funcionalidad
  4. Documentación: Actualizar el README para cualquier cambio en la API

Lista de Verificación de Revisión de Código

  • Validación de entradas para todas las entradas de usuario
  • Manejo de errores con mensajes de error seguros
  • Tipos de TypeScript sin any
  • Auditoría de seguridad para operaciones de rutas
  • Evaluación del impacto en el rendimiento

📚 Documentación

🐛 Solución de Problemas

Problemas Comunes

Errores de Compilación

# Clear dist and rebuild
rm -rf dist && npm run build

Errores de Permisos

# Ensure executable permissions
chmod +x dist/index.js

Errores de Importación

  • Asegúrese de tener Node.js 18+ para soporte de módulos ES
  • Verifique "type": "module" en package.json

Preocupaciones de Seguridad

Si descubre una vulnerabilidad de seguridad, repórtela mediante los problemas de GitHub con la etiqueta security.

📄 Licencia

Este proyecto mantiene la misma licencia que el proyecto original Tailwind-Svelte-Assistant.

⚡ Puntos de Referencia de Rendimiento

Antes vs Después (v0.1.1)

  • Cobertura de Documentación: 🔴 4-8% → 🟢 100% (mejora de 12.5x-25x)
  • Seguridad: 🔴 Vulnerabilidades críticas → 🟢 Endurecido
  • Seguridad de Tipos: 🟡 Tipos mixtos → 🟢 TypeScript estricto
  • Rendimiento: 🟡 Sin caché → 🟢 Caché LRU de 5 minutos
  • Arquitectura: 🔴 Monolítica → 🟢 Servicios modulares
  • Manejo de Errores: 🟡 Básico → 🟢 Clasificación integral

Métricas de Documentación

  • Svelte/SvelteKit: 1,065,921 bytes (1.04 MB)
  • Tailwind CSS: 2,197,160 bytes (2.1 MB, 249 archivos)
  • Tokens Totales: 606,587 tokens (Tailwind)
  • Método de Actualización: Automatizado mediante script npm

Rendimiento de Caché

  • Inicio en Frío: ~50-100ms por lectura de archivo
  • Acierto de Caché: ~1-5ms de tiempo de respuesta
  • Uso de Memoria: ~1-3MB por documento completo en caché
  • Eficiencia de Caché: 80-95% de tasa de aciertos en uso típico
  • Rendimiento de Búsqueda: <10ms para búsqueda en memoria

Fuentes de Documentación

  • Svelte: Formato oficial optimizado para LLM del equipo de Svelte
  • Tailwind: Extraído mediante Repomix del repositorio oficial de GitHub
  • Actualizaciones: Script automatizado con mecanismos de respaldo

Este servidor MCP mejorado transforma el prototipo original en un servicio listo para producción con cobertura completa de documentación, seguridad de nivel empresarial, rendimiento y mantenibilidad.