Construindo ferramentas MCP flexíveis com grafql e ferrugem

No cenário em rápida evolução da IA, a capacidade de grandes modelos de idiomas (LLMs) de interagir com dados e serviços externos é um requisito central para a construção de agentes verdadeiramente capazes. O Model Context Protocol (MCP) fornece uma estrutura padronizada para essa interação, permitindo que os agentes descubram e utilizem ferramentas de maneira consistente. Embora existam muitas abordagens para criar essas ferramentas, a exposição de APIs através do GraphQL oferece uma vantagem única. Ao fornecer um esquema declarativo e seguro de tipo, o GraphQL pode atuar como um intermediário mais eficiente e poderoso do que as APIs de REST tradicionais ou acesso direto ao banco de dados. Este artigo examina uma implementação específica desse padrão: o APOLLO MCP Server1, de código aberto, que é incorporado a Rust para expor as operações do GraphQL como ferramentas MCP. Expondo as APIs existentes a um agente Um desafio comum no desenvolvimento do agente de IA está conectando um modelo a um vasto e complexo ecossistema de dados e serviços existentes. Uma abordagem ingênua pode ser fornecer ao agente especificações de API bruta, como um esquema completo do OpenAPI, e deixar o modelo descobrir os detalhes. No entanto, à medida que a API cresce em complexidade, isso pode se tornar ineficiente e levar ao uso excessivo de token na janela de contexto do LLM. O servidor Apollo MCP oferece uma solução mais refinada, permitindo que os desenvolvedores se curtem e exponham ferramentas específicas e criadas para fins específicos a um agente. Essa abordagem é demonstrada através de um exemplo usando a enorme API do GitHub GraphQL. Em vez de dar acesso a um agente a toda a API, o desenvolvedor usa o servidor Apollo MCP para criar uma ferramenta focada, como um para “buscar os cinco últimos problemas de um repositório do GitHub”. Essa ferramenta aproveita o esquema GraphQL subjacente, mas abstraia a complexidade, fornecendo ao agente uma função limpa e granulada. O servidor binário, escrito em ferrugem, pode ser configurado com um arquivo YAML simples para definir quais operações do GraphQL a expor. Construindo uma ferramenta orientada pela comunidade, além de expor uma única API, a força do servidor Apollo MCP está em sua capacidade de combinar fontes de dados díspares em uma única ferramenta coesa. Um exemplo prático é uma ferramenta de construção da comunidade para envios de conversas. Esta ferramenta orquestra dados de um banco de dados do Superbase com lógica personalizada de uma instância do Apollo Server. O banco de dados Superbase, que gera automaticamente as APIs de REST a partir de seu esquema PostgreSQL, serve como o principal armazenamento de dados. O servidor Apollo MCP usa seus conectores REST para mapear esses recursos de REST para os tipos de graphQL. Para lidar com a lógica personalizada, como a validação de envios de conversas, uma API grafql separada é criada usando o Apollo Server. Este servidor, que pode ser escrito em idiomas como JavaScript, TypeScript ou Python, pode conter a lógica de negócios que seria muito complexa ou insegura para expor diretamente ao agente. O servidor Apollo MCP pode se conectar e orquestrar o esquema grafql baseado em Superbase e o servidor Apollo-Logic Custom, expondo-os como um conjunto único e unificado de ferramentas MCP ao agente. Essa arquitetura composta permite que os desenvolvedores escolham a melhor tecnologia para cada parte de seu aplicativo, apresentando uma interface simples e unificada ao agente da IA. Nos bastidores: o fluxo de trabalho MCP-GRAPHQL A funcionalidade principal do servidor Apollo MCP e sua interação com um agente de IA como o Goose3 é um processo de várias etapas. Descoberta de ferramentas: o agente, que é um aplicativo configurado para interagir com um servidor MCP, consulta o servidor para recuperar uma lista de ferramentas disponíveis e seus esquemas. O servidor Apollo MCP, por meio de sua configuração, fornece uma lista de operações grafql expostas, cada uma com um nome, descrição e parâmetros necessários. Solicitação do usuário: Um usuário fornece um prompt de linguagem natural ao agente, como “buscar os cinco mais recentes problemas do repositório do Apollo GraphQL Rover”. Raciocínio do agente: o agente usa um LLM (neste caso, o AWS Bedrock’s4 Claude 3,7 sonetos) para analisar o prompt. Com base na intenção do usuário e nas ferramentas disponíveis, o LLM decide chamar a ferramenta de pesquisa para encontrar os campos de esquema relevantes. A ferramenta de pesquisa é descrita como uma alternativa mais eficiente à introspecção completa do GraphQL. Execução da ferramenta: Uma vez que o agente tenha informações suficientes, ele constrói uma consulta GraphQL completa e a envia para o Apollo MCP Server5 para execução. A capacidade do agente de raciocinar sobre os parâmetros corretos e a estrutura da consulta é uma função de seu treinamento e a qualidade das definições de ferramentas. Geração de consultas e reloadia a quente: O recurso mais atraente do Apollo MCP Server para desenvolvedores é sua capacidade de reloalização a quente. Depois que uma consulta inicial é gerada pelo agente, os desenvolvedores podem inspecionar e refinar a consulta GraphQL em sua máquina local. Quaisquer alterações na definição de consulta, como a remoção de campos estranhos, como um URL ou rótulos desnecessários, estão imediatamente disponíveis para o agente sem exigir um reinício do servidor. Isso permite um ciclo de desenvolvimento iterativo rápido para as ferramentas de construção e ajuste fino. Resposta e otimização: o servidor executa a consulta GraphQL otimizada e retorna uma carga útil concisa e relevante ao agente. Esse processo minimiza o uso de token na janela de contexto do LLM, garantindo que apenas dados essenciais sejam recuperados e transmitidos, o que é uma vantagem fundamental da natureza declarativa do GraphQL. Esse fluxo de trabalho destaca a importância de criar ferramentas granulares e de granulação grossa, adaptadas a casos de uso específicos, um contraste gritante de simplesmente expor uma API crua e de granulação fina ao agente. Esse design intencional reduz a pressão da janela de contexto LLM e aumenta a previsibilidade e a eficiência das ações do agente. Meus pensamentos O servidor Apollo MCP fornece uma abordagem pragmática e focada no desenvolvedor para a construção de agentes de IA que evita as armadilhas dos sistemas monolíticos. A ênfase em uma camada de ferramenta acionada por casos de granulação grossa é um padrão arquitetônico crítico que aborda diretamente as limitações dos LLMs atuais. Ao contrário de uma abordagem simples de “despejar tudo e esperar para a melhor”, esse método garante que as ações do agente sejam mais intencionais e eficientes. A capacidade de compor ferramentas de várias fontes de dados, sejam as APIs de REST por meio de conectores ou APIs lógicas personalizadas, demonstra um alto grau de flexibilidade. A experiência de desenvolvedor rápida e relevante é uma vitória significativa, pois permite a iteração e o refinamento rápidos das ferramentas-uma etapa necessária, dada a natureza um tanto imprevisível da engenharia imediata. O desafio, como em qualquer sistema agêntico, permanece na “magia LLM” da engenharia imediata. Embora a camada da ferramenta seja robusta, a capacidade do agente de raciocinar e selecionar a ferramenta correta ainda depende da especificidade do prompt inicial. Melhorias futuras podem envolver métodos ainda mais avançados para o raciocínio do lado do agente ou uma linguagem de definição de ferramentas de nível superior que abstraça ainda mais as complexidades das APIs subjacentes. A adição de recursos como o OAuth, como mencionado na palestra, é um próximo passo crucial para a adoção corporativa, permitindo que os desenvolvedores protejam ferramentas com autenticação e autorização adequadas. Agradecimentos Muito obrigado a MA’am Amanda Martin, do Apollo GraphQL pela conversa informativa, “Vibe Code MCP Tools com GraphQL”, 6 e a toda a comunidade Apollo e MCP/AI mais ampla por seu trabalho colaborativo no avanço dessa tecnologia. REFERÊNCIAS APOLLO MCP Server Github Repository ↩ Supabase: APIs de repouso geradas automaticamente com pós-grest ↩ Agente de AI de ganso do bloco ↩ AWS Bedrock: Claude 3.7 Sonnet Antropic ↩ Documentação do servidor Apollo ↩ Código Vibe Código McP Ferramentas com grafql, yt link ↩

Fonte