Supercarregando o desenvolvimento do Adobe Commerce: introduzindo o servidor adobe-commerce-docs-mcp

Se você escreve código para Adobe Commerce ou Magento 2, passa muito tempo esperando. Os tempos de construção são lentos, a implantação de conteúdo estático leva uma eternidade, mas o verdadeiro desperdício de tempo é a documentação. A arquitetura EAV, layouts XML aninhados e mutações GraphQL em constante mudança significam que você está constantemente alternando para um navegador para verificar um padrão de sintaxe.

Toda vez que você sai do seu IDE para pesquisar no portal Experience League, você perde seu fio de pensamento. Você copia códigos de erro, vasculha resultados de pesquisa não relacionados e tenta encontrar um trecho de código funcional. É exaustivo.

Eu queria que meu assistente de codificação soubesse essas coisas sem que eu precisasse procurá-las. É por isso que configurei este servidor MCP.

O pacote adobe-commerce-docs-mcp conecta seu IDE diretamente à documentação oficial da Adobe. Ele funciona com Cursor, Claude Desktop, VS Code e Windsurf, puxando documentos markdown brutos diretamente para o contexto do seu chat.

A arquitetura: conectando IA e documentação

Em vez de depender de pesquisa na web ou dados de treinamento desatualizados, o servidor consulta o site ao vivo do Adobe Experience League. Ele indexa o conteúdo localmente, armazena páginas em cache e lida com consultas via protocolo MCP.

1. Classificação de pesquisa BM25

O servidor analisa o sitemap oficial da Adobe e classifica as páginas usando a pontuação de relevância BM25. Este é o mesmo algoritmo de pesquisa que os bancos de dados usam para pesar a frequência de termos de pesquisa em relação ao comprimento do documento. Isso significa que seu assistente obtém o guia de configuração mais relevante primeiro, não apenas a página que menciona uma palavra-chave com mais frequência.

2. Sinônimos e correspondência aproximada

Você não precisa consultar a terminologia exata. O mecanismo de busca mapeia sinônimos específicos do Magento:

pesquisas graphql também encontram páginas com gql
pesquisas de módulo também correspondem a extensão
pesquisas em nuvem correspondem a ece

Ele também corrige erros de digitação simples como chekout ou catlog para checkout e catalog.

3. Cache local

As solicitações de rede são lentas, então o servidor usa duas camadas de cache:

Um cache em memória para consultas recentes.
Um cache de arquivo persistente no seu disco. Os dados do sitemap duram 24 horas, enquanto as páginas markdown baixadas duram 7 dias. Isso torna as consultas subsequentes instantâneas e economiza chamadas de API.

Nove ferramentas integradas

O servidor registra nove ferramentas que seu assistente pode executar.

Ferramenta	O que faz
search_adobe_commerce_docs	Pesquisa o sitemap indexado com expansão de sinônimos.
get_doc_content	Puxa o conteúdo markdown limpo de uma página.
get_code_examples	Extrai apenas os blocos de código, pulando textos longos para economizar tokens.
get_page_toc	Busca títulos de cabeçalho para que o modelo possa inspecionar a estrutura da página primeiro.
get_related_docs	Encontra páginas irmãs ou relacionadas na árvore de documentação.
lookup_error_code	Consulta códigos de erro específicos como MDVA-43395.
multi_page_search	Executa até cinco consultas ao mesmo tempo e combina resultados únicos.
list_doc_sections	Lista todas as categorias raiz da documentação.
refresh_sitemap	Força a atualização do índice do sitemap em cache.

Recursos configurados

Recursos são URIs estáticos que o modelo pode navegar. Você pode consultar:

commerce://sections: Lista seções.
commerce://stats: Mostra tamanhos de cache e contagens de índice.
commerce://docs/{section}: Mostra listas de páginas para uma categoria específica.

Prompts prontos

O servidor expõe prompts integrados para lidar com fluxos de trabalho comuns:

troubleshoot-commerce-error: Ajuda a resolver problemas a partir de saídas de log.
explain-commerce-concept: Passo a passo de coisas como plugins ou injeção de dependência.
commerce-code-review: Audita arquivos de acordo com os padrões do Adobe Commerce.
commerce-upgrade-guide: Conselhos de planejamento para atualizações de versão.

Instalação e configuração

Você não precisa clonar o repositório ou construir os arquivos você mesmo. O servidor é executado via npx.

Configuração com um clique para Cursor

Se você usa o Cursor, abra seu terminal e execute este instalador:

bash <(curl -sS https://raw.githubusercontent.com/jigarkkarangiya/adobe-commerce-docs-mcp/main/setup-cursor.sh)

Este script adiciona a configuração ao seu arquivo de configurações automaticamente.

Configuração manual

Você também pode adicionar manualmente. Edite seu arquivo de configurações dependendo da aplicação:

Cursor (mcp.json)

{
  "mcpServers": {
    "adobe-commerce-docs": {
      "command": "npx",
      "args": [
        "-y",
        "adobe-commerce-docs-mcp"
      ]
    }
  }
}

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "adobe-commerce-docs": {
      "command": "npx",
      "args": [
        "-y",
        "adobe-commerce-docs-mcp"
      ]
    }
  }
}

Variáveis de ambiente

Você pode alterar comportamentos padrão definindo variáveis de ambiente em sua configuração:

SITEMAP_URL substitui a URL padrão do Experi