Tailwind Svelte Assistant

Fornece documentação e trechos de código para SvelteKit e Tailwind CSS.

GitHub
10
Experimente este MCPPatrocinado

Documentação

Servidor MCP Tailwind Svelte Assistant

smithery badge

Um servidor de Model Context Protocol (MCP) seguro e de alta performance que fornece documentação completa de SvelteKit e Tailwind CSS (100% de cobertura) e trechos de código com segurança aprimorada, implementação adequada em TypeScript e tratamento abrangente de erros.

✨ Novidades (v0.1.1)

📚 Cobertura Completa de Documentação

  • 100% de Cobertura Svelte/SvelteKit: Documentação oficial otimizada para LLM (1,04 MB)
  • 100% de Cobertura Tailwind CSS: Documentação completa via extração Repomix (2,1 MB, 249 arquivos)
  • Busca Inteligente: Pesquise na documentação completa com contexto
  • Melhoria de 12,5x a 25x: De 4-8% de cobertura para 100% de cobertura

🚀 Principais Melhorias (v0.1.1)

🔒 Aprimoramentos de Segurança

  • Proteção contra Path Traversal: Sanitização abrangente de entrada previne ataques de travessia de diretórios
  • Validação de Entrada: Validação rigorosa de parâmetros com correspondência de padrões e limites de comprimento
  • Operações Seguras de Arquivo: Acesso a arquivos limitado com validação de caminho e limites de tamanho
  • Registro de Auditoria: Registro estruturado de eventos de segurança para monitoramento

🏗️ Melhorias de Arquitetura

  • Design Modular: Preocupações separadas em serviços e utilitários dedicados
  • Excelência em TypeScript: Segurança total de tipos com interfaces adequadas e sem tipos any
  • Módulos ES: Sistema moderno de módulos JavaScript com importações adequadas
  • Tratamento de Erros: Classificação abrangente de erros e mensagens de erro seguras

⚡ Otimizações de Performance

  • Cache de Conteúdo: Cache LRU com timeout configurável para melhorar os tempos de resposta
  • Limites de Tamanho de Arquivo: Previne esgotamento de recursos com limites configuráveis
  • Operações Assíncronas: Operações de arquivo não bloqueantes para melhor concorrência
  • Gerenciamento de Memória: Limpeza automática de cache e coleta de lixo

📁 Estrutura do Projeto

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

🚀 Início Rápido

Instalação via Smithery (Recomendado)

A maneira mais fácil de instalar este servidor MCP é através do Smithery:

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

Isso irá automaticamente:

  • Instalar o servidor
  • Configurá-lo para o Claude Desktop
  • Configurar todas as dependências necessárias

Instalação via URL Direta

Para outros clientes MCP, use a URL direta do servidor:

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

Adicione isso à configuração do seu cliente MCP:

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

🛠️ Instalação e Configuração Manual

Pré-requisitos

  • Node.js 20+ (necessário para suporte a módulos ES e dependências)
  • npm ou yarn
  • Git (para clonar o repositório)

Instalar Dependências

npm install

Compilar o Servidor

npm run build

Modo de Desenvolvimento

npm run watch

🔧 Configuração

O servidor usa padrões seguros, mas pode ser configurado através da interface 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
};

Atualizações de Documentação

A documentação é baixada e atualizada automaticamente:

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

Este script:

  • Baixa a documentação oficial otimizada para LLM do Svelte (svelte.dev/llms-full.txt)
  • Extrai a documentação completa do Tailwind do GitHub via Repomix
  • Atualiza os timestamps dos trechos de componentes
  • Gera um resumo do conteúdo

Fontes:

  • Svelte/SvelteKit: Arquivo de texto oficial otimizado para LLM (100% de cobertura)
  • Tailwind CSS: Repositório GitHub via extração Repomix (249 arquivos MDX)
  • Trechos: Exemplos locais selecionados de componentes (43 arquivos)

🛡️ Recursos de Segurança

Validação de Entrada

  • Correspondência de Padrões: Apenas caracteres alfanuméricos, hífens, sublinhados e pontos são permitidos
  • Limites de Comprimento: Comprimentos máximos de entrada configuráveis
  • Sanitização de Caminho: Remove tentativas de travessia de diretórios
  • Verificação de Limites: Garante que o acesso a arquivos permaneça dentro dos diretórios permitidos

Tratamento de Erros

  • Mensagens de Erro Seguras: Nenhuma informação sensível é exposta aos clientes
  • Registro Estruturado: Registros de auditoria formatados em JSON para monitoramento de segurança
  • Classificação de Erros: Tratamento diferente para diferentes tipos de erro
  • Degradação Graciosa: Respostas de fallback para falhas não críticas

Segurança do Sistema de Arquivos

  • Validação de Caminho: Verifica se os caminhos resolvidos estão dentro dos diretórios base
  • Limites de Tamanho de Arquivo: Previne ataques de esgotamento de recursos
  • Operações Somente Leitura: Nenhuma operação de escrita é exposta aos clientes
  • Isolamento de Cache: O cache de conteúdo não expõe a estrutura do sistema de arquivos

📊 Recursos de Performance

Sistema de Cache

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

Gerenciamento de Recursos

  • Limites de Memória: Restrições de tamanho de arquivo previnem esgotamento de memória
  • Limpeza de Cache: Remoção automática de entradas de cache expiradas
  • I/O Assíncrono: Operações de arquivo não bloqueantes
  • Recuperação de Erros: Tratamento gracioso de limitações de recursos

🔍 Ferramentas Disponíveis

🆕 Ferramentas de Documentação Completa (Recomendado)

  • get_svelte_full_docs - Obtenha a documentação completa de Svelte & SvelteKit (1MB, 100% de cobertura)

    • Nenhum parâmetro necessário
    • Retorna toda a documentação em um único arquivo otimizado para LLM
    • Formato oficial da equipe Svelte

  • get_tailwind_full_docs - Obtenha a documentação completa do Tailwind CSS (2,1MB, 100% de cobertura)

    • Nenhum parâmetro necessário
    • Inclui todos os 249 arquivos de documentação
    • Todas as classes utilitárias e conceitos cobertos

  • search_svelte_docs - Pesquise na documentação de Svelte/SvelteKit

    • Parâmetros: query (string), limit (opcional, padrão: 5)
    • Retorna seções correspondentes com contexto ao redor
    • Busca rápida em memória

  • search_tailwind_docs - Pesquise na documentação do Tailwind CSS

    • Parâmetros: query (string), limit (opcional, padrão: 5)
    • Retorna seções correspondentes com contexto ao redor
    • Cobre todas as classes utilitárias

Ferramentas de Documentação Legadas

Nota: Essas ferramentas cobrem apenas ~4-8% da documentação disponível. Use as ferramentas de documentação completa acima para cobertura total.

  • get_sveltekit_doc - Recupera tópico específico da documentação do SvelteKit
  • get_tailwind_info - Obtém informações específicas do Tailwind CSS
  • list_sveltekit_topics - Lista a documentação disponível do SvelteKit (limitada)
  • list_tailwind_info_topics - Lista a documentação do Tailwind (limitada)

Ferramentas de Componentes

  • get_component_snippet - Busca código de componente Svelte
  • list_snippet_categories - Lista categorias de componentes
  • list_snippets_in_category - Lista trechos na categoria

Esquemas Aprimorados de Ferramentas

Todas as ferramentas incluem:

  • Validação de padrões com restrições de regex
  • Limites de comprimento para parâmetros de entrada
  • Descrições abrangentes com exemplos de uso
  • Sanitização de entrada endurecida por segurança

📝 Exemplos de Uso

Configuração do Cliente MCP

Opção 1: Hospedado no Smithery (Recomendado)

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

Opção 2: Instalação Local

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

Uso de Ferramentas

Recomendado: Documentação 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
});

Legado: Tópicos 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", {});

Trechos 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", {});

🧪 Testes e Garantia de Qualidade

Auditoria de Segurança

npm run security-audit

Verificação de Dependências

npm run outdated-check

Inspetor MCP

npm run inspector

🐳 Implantação com Docker

O Dockerfile incluído fornece uma compilação segura em múltiplos estágios:

# 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

Recursos de Segurança

  • Compilação em múltiplos estágios reduz a superfície de ataque
  • Alpine Linux para pegada mínima
  • Usuário não root para segurança do contêiner
  • Apenas dependências de produção

📈 Monitoramento e Registro

Registro Estruturado

Todas as operações são registradas com JSON estruturado para fácil análise:

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

Eventos de Auditoria

  • Solicitações de ferramentas com parâmetros
  • Violações de segurança e solicitações bloqueadas
  • Condições de erro com classificação
  • Métricas de performance e acertos de cache

🔄 Migração da v0.1.0

Mudanças Importantes

  • Módulos ES: Atualizado para usar import/export em vez de require
  • TypeScript: Tipagem estrita pode exigir asserções de tipo em alguns casos
  • Mensagens de Erro: Mensagens de erro mais seguras e menos detalhadas

Compatibilidade

  • Interface de Ferramentas: Todas as ferramentas existentes funcionam com validação aprimorada
  • Estrutura de Conteúdo: Nenhuma mudança na organização do conteúdo
  • Docker: Imagem base atualizada e endurecimento de segurança

🤝 Contribuindo

Diretrizes de Desenvolvimento

  1. Segurança em Primeiro Lugar: Todas as mudanças devem passar pela revisão de segurança
  2. Segurança de Tipos: Manter conformidade estrita com TypeScript
  3. Cobertura de Testes: Incluir testes para novas funcionalidades
  4. Documentação: Atualizar o README para qualquer mudança na API

Checklist de Revisão de Código

  • Validação de entrada para todas as entradas do usuário
  • Tratamento de erros com mensagens de erro seguras
  • Tipos TypeScript sem any
  • Auditoria de segurança para operações de caminho
  • Avaliação de impacto na performance

📚 Documentação

🐛 Solução de Problemas

Problemas Comuns

Erros de Compilação

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

Erros de Permissão

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

Erros de Importação

  • Garanta Node.js 18+ para suporte a módulos ES
  • Verifique "type": "module" no package.json

Preocupações de Segurança

Se você descobrir uma vulnerabilidade de segurança, por favor reporte-a através das issues do GitHub com o rótulo security.

📄 Licença

Este projeto mantém a mesma licença do projeto original Tailwind-Svelte-Assistant.

⚡ Benchmarks de Performance

Antes vs Depois (v0.1.1)

  • Cobertura de Documentação: 🔴 4-8% → 🟢 100% (melhoria de 12,5x a 25x)
  • Segurança: 🔴 Vulnerabilidades críticas → 🟢 Endurecida
  • Segurança de Tipos: 🟡 Tipos mistos → 🟢 TypeScript estrito
  • Performance: 🟡 Sem cache → 🟢 Cache LRU de 5 minutos
  • Arquitetura: 🔴 Monolítica → 🟢 Serviços modulares
  • Tratamento de Erros: 🟡 Básico → 🟢 Classificação abrangente

Métricas de Documentação

  • Svelte/SvelteKit: 1.065.921 bytes (1,04 MB)
  • Tailwind CSS: 2.197.160 bytes (2,1 MB, 249 arquivos)
  • Total de Tokens: 606.587 tokens (Tailwind)
  • Método de Atualização: Automatizado via script npm

Performance do Cache

  • Início a Frio: ~50-100ms por leitura de arquivo
  • Acerto de Cache: ~1-5ms de tempo de resposta
  • Uso de Memória: ~1-3MB por documento completo em cache
  • Eficiência do Cache: 80-95% de taxa de acerto no uso típico
  • Performance de Busca: <10ms para busca em memória

Fontes de Documentação

  • Svelte: Formato oficial otimizado para LLM da equipe Svelte
  • Tailwind: Extraído via Repomix do repositório oficial do GitHub
  • Atualizações: Script automatizado com mecanismos de fallback

Este servidor MCP atualizado transforma o protótipo original em um serviço pronto para produção com cobertura completa de documentação, segurança de nível empresarial, performance e manutenibilidade.