Como e por que construí um servidor MCP para Svelte

Se estiver usando o Svelte com assistentes de codificação, você sabe que esses assistentes nem sempre estão cientes dos recursos mais recentes do Svelte 5 e do SvelteKit. Eles sugerirão padrões desatualizados, misturarão a antiga sintaxe reativa com o novo sistema de runas ou simplesmente alucinarão uma sintaxe que não existe. Esses problemas tornaram os assistentes LLM menos úteis em projetos Svelte e SvelteKit – então decidi definir e construir um servidor MCP (Model Context Protocol) que dê aos assistentes de IA acesso direto à documentação mais recente do Svelte.

Demonstração: O que isso pode realmente fazer?

Aqui está um pequeno vídeo que gravei demonstrando alguns dos recursos, como pesquisa de documentação, recursos e o prompt dedicado “Svelte Developer”:

Em primeiro lugar, por que precisamos de um Svelte MCP?

Svelte 5 introduziu grandes mudanças de sintaxe para melhorar a linguagem. A antiga sintaxe de reatividade como let count = 0; $: doubled = count * 2 desapareceu, substituído por runas: let count = $state(0); let doubled = $derived(count * 2). Manipuladores de eventos alterados de on:click para onclick. O SvelteKit também recebeu novos recursos como Funções Remotas. A lista de mudanças continua.

A maioria dos modelos de IA foram treinados antes que essas mudanças ocorressem. Quando você pede ajuda, eles fornecem códigos antigos com segurança. Pior ainda, às vezes eles misturam a sintaxe Svelte 4 e Svelte 5 no mesmo exemplo, criando código que não funciona.

Como os MCPs preenchem a lacuna de conhecimento

MCP (Model Context Protocol) é um padrão da Anthropic que permite que assistentes de IA se conectem a ferramentas externas e fontes de dados. Em vez de depender apenas de dados de treinamento, o assistente pode buscar informações sob demanda. Dá aos assistentes de IA a capacidade de pesquisar as coisas quando necessário, assim como você faria verificando a documentação oficial.

O servidor MCP que construí oferece a documentação mais recente do Svelte e SvelteKit diretamente do repositório oficial do GitHub. O assistente pode consultar tópicos específicos, listar seções disponíveis ou obter conjuntos inteiros de documentação com base na tarefa em questão.

O que o MCP como protocolo oferece?

O MCP fornece vários primitivos para estender assistentes de IA.

• Ferramentas são funções que o assistente pode chamar. Nós fornecemos lista_seções que lista todas as seções de documentação disponíveis, e obter_documentação que retorna uma ou mais seções de documentação solicitadas pelo LLM.
• Recursos são fontes de dados somente leitura pelas quais o assistente pode navegar – cada seção de documentação se torna um recurso acessível via URIs como svelte-llm://docs/svelte/runes. Fornecemos todos os arquivos markdown da documentação do Svelte e do SvelteKit como um recurso separado.
• Solicitações são modelos reutilizáveis ​​que injetam contexto específico – Nós os usamos para fornecer conjuntos de documentação com curadoria como “svelte-core” ou “sveltekit-production”, bem como uma predefinição “Svelte Developer” que fornece um prompt personalizado para tarefas Svelte e SvelteKit.

(Existem mais primitivos, como Completions, e recursos específicos do cliente, como Sampling e Elicitation, mas estes não foram usados.)

Como concluímos acima, o grande benefício do MCP é que, em vez de despejar conjuntos inteiros de documentação no contexto (também conhecidos como arquivos llms.txt), o assistente pode buscar de forma inteligente o que é necessário.

Qual é a aparência real do código?

Uma das coisas que me incomodou ao ler sobre o MCP é que há tanta prosa – por que isso é bom, por que você deve usá-lo, por que é melhor que uma API REST, mas os exemplos de código eram poucos e raros. Então, estou aqui para dizer que trabalhar em um MCP funciona de maneira muito parecida com uma API REST comum do ponto de vista de programação. Vamos construir uma ferramenta MCP simples chamada roll_die que retorna o resultado de um lançamento de dados no lado N:

server.tool(
  'roll_die',
  'Rolls a die with a specified number of sides',
  {
    sides: z
      .number()
      .int()
      .min(2)
      .default(6)
      .describe('Number of sides on the die (defaults to 6)')
  },
  async ({ sides }: { sides: number }) => {
    const result = Math.floor(Math.random() * sides) + 1
    
    return {
      content: (
        {
          type: 'text' as const,
          text: `🎲 Rolled a d${sides}: **${result}**`
        }
      )
    }
  }
)

Omiti o código de inicialização do MCP por questões de brevidade, mas você pode ver que é o padrão familiar “registrar uma rota/ferramenta e um manipulador de retorno de chamada”. Se você quiser ver a implementação real das ferramentas Svelte MCP, você pode encontrá-las no GitHub!

Como funciona o Svelte MCP

A cada hora, um trabalho agendado busca a documentação mais recente do repositório oficial do Svelte GitHub. Os arquivos markdown da documentação são processados, os metadados são extraídos e tudo é armazenado no PostgreSQL. Quando um assistente de IA precisa de documentação, ele se conecta ao servidor MCP que consulta o banco de dados. Claro, usamos o próprio SvelteKit para fornecer o site e a funcionalidade MCP, e o adaptador mcp para lidar com o protocolo MCP.

Destilando documentação para economizar contexto

A documentação completa do Svelte e SvelteKit tem cerca de 800 KB de texto. São centenas de milhares de tokens, que consomem ou esgotam completamente o comprimento do contexto dos LLMs! Também foi demonstrado que os LLMs ficam “desfocados” à medida que o contexto cresce. Para combater isso, criei um recurso que usa um LLM para criar versões condensadas dos documentos.

O processo de destilação elimina conteúdo redundante enquanto mantém exemplos de código e conceitos-chave. O resultado é cerca de 50% menor, mas ainda contém as informações essenciais.

Você mesmo pode comparar o antes/depois do processo de destilação visitando esta ferramenta de comparação interativa! O processo é executado no lado do servidor onde o serviço está hospedado, portanto, só precisa ser feito uma vez ou após atualizações significativas da documentação.

As versões destiladas são geradas automaticamente e armazenadas junto com os originais. Para as predefinições de recursos dedicadas no MCP (svelte-core, svelte-advanced, svelte-complete e assim por diante), decidi usar essas predefinições destiladas em vez da documentação completa para economizar espaço de contexto.

O ecossistema fragmentado do cliente MCP

Existem três protocolos diferentes para interface com servidores MCP – stdio, SSE e Streamable HTTP – e nem todos os clientes suportam todos eles.

Stdio é executado localmente (normalmente é apenas um comando npx ou Python) e pode acessar recursos locais, como leitura/gravação de seus arquivos, mas você também precisa instalá-lo em todas as máquinas.

SSE e Streamable HTTP são protocolos remotos – basta apontar para uma URL e eles funcionam. Streamable também é mais fácil de implementar do que SSE, pois o SSE, por motivos técnicos, requer uma fila (Redis no nosso caso) para passar mensagens entre o servidor e o cliente.

Por exemplo, para adicionar o Svelte MCP ao Claude Code, você só precisa digitar este comando em seu terminal:

claude mcp add --transport http --scope project svelte-llm https://svelte-llm.stanislav.garden/mcp/mcp

Como observação lateral, embora a Anthropic tenha criado o protocolo MCP, Claude Desktop demorou a oferecer suporte ao Streamable HTTP. Até recentemente, você tinha que usar o protocolo SSE ao usar o Claude Desktop. Agora, felizmente, a maioria dos clientes finalmente oferece suporte ao Streamable! Mas, no final, acabei oferecendo suporte a SSE e Streamable HTTP para maximizar a compatibilidade com clientes mais antigos.

Reflexões finais

Construir este MCP foi realmente interessante. Eu uso o Svelte diariamente e ter assistentes de IA que entendem a versão atual economiza muito tempo! Mas, de forma mais ampla, este projeto mostra que não precisamos esperar que os modelos de IA sejam retreinados para obter informações precisas sobre ferramentas em rápida evolução. À medida que as estruturas e bibliotecas continuam a evoluir rapidamente, este tipo de acesso à documentação em tempo real torna-se cada vez mais valioso.

Se você trabalha com assistentes de codificação Svelte e AI, pode experimentá-los em svelte-llm.stanislav.garden. O projeto é de código aberto e contribuições são bem-vindas. Também tenho alguns novos recursos interessantes planejados para este MCP e estou conversando com os mantenedores do Svelte sobre a criação de um Svelte MCP oficial também!

Foto social do estúdio Cottonbro.