GraphQL API Explorer

Documentação do Servidor MCP

O Servidor MCP (Model Communication Protocol) é um serviço que fornece capacidades inteligentes de introspecção e exploração para qualquer API GraphQL. Esta documentação irá guiá-lo sobre como usar o servidor MCP com o Cursor IDE e o MCP Client.

Visão Geral

O servidor MCP fornece uma interface poderosa para acessar e explorar seu schema GraphQL através de um conjunto avançado de ferramentas. Ele faz introspecção de qualquer schema GraphQL e fornece informações estruturadas e pesquisáveis sobre:

• Tipos
• Queries
• Mutations
• Tipos de entrada

Recursos

1. Pesquisa Inteligente de Schema

O servidor MCP inclui um sistema de pesquisa avançado que ajuda você a encontrar exatamente o que precisa no seu schema GraphQL:

• Correspondência difusa para tolerância a erros de digitação
• Suporte a pesquisa com múltiplas palavras
• Resultados baseados em relevância
• Pesquisa sensível ao contexto
• Capacidades de pesquisa em nível de campo

2. Exploração de Tipos

Informações detalhadas de tipos com:

• Listagens de campos
• Tipos relacionados
• Documentação
• Exemplos de uso

3. Descoberta de Queries/Mutations

Exploração fácil das operações disponíveis:

• Agrupadas por categoria
• Informações detalhadas de parâmetros
• Detalhes do tipo de retorno
• Contexto de uso

Configuração

1. Instale as dependências:

yarn install

2. Configure seu endpoint GraphQL no servidor MCP:

const GRAPHQL_ENDPOINT = "http://your-graphql-endpoint/graphql";

3. Configure o Cursor IDE: Crie ou atualize .cursor/mcp.json no seu projeto:

{
  "mcpServers": {
    "cw-core": {
      "command": "node",
      "args": [
        "/Users/martinshumberto/repositories/cw-mcp-server/build/main.js",
        "--debug"
      ],
      "transport": "stdio"
    }
  }
}

Ferramentas Disponíveis

1. Ferramenta de Schema

// Get complete schema information
{
  "title": "GraphQL Schema",
  "description": "Full introspection of GraphQL schema"
}

2. Ferramenta de Pesquisa

// Advanced search across schema elements
{
  "title": "Search Schema",
  "description": "Advanced search across all GraphQL schema elements",
  "parameters": {
    "searchTerm": "Search term - supports multiple words and partial matches",
    "threshold": "Optional similarity threshold (0-1, default: 0.3)"
  }
}

3. Ferramenta de Tipos

// Get specific type information
{
  "title": "GraphQL Types",
  "description": "Get fields from a specific GraphQL type",
  "parameters": {
    "typeName": "Name of the GraphQL type to inspect"
  }
}

4. Ferramenta de Campo

// Get detailed field information
{
  "title": "Field Details",
  "description": "Get detailed information about a specific field in a type",
  "parameters": {
    "typeName": "Name of the GraphQL type containing the field",
    "fieldName": "Name of the field to inspect"
  }
}

5. Ferramenta de Tipos Relacionados

// Find related types
{
  "title": "Related Types",
  "description": "Find types that are related to a specific type",
  "parameters": {
    "typeName": "Name of the GraphQL type to find relations for"
  }
}

Usando com o Cursor IDE

1. Exemplos de Pesquisa

Pesquisa básica:

{
  "searchTerm": "user"
}

Pesquisa com múltiplas palavras:

{
  "searchTerm": "create user profile"
}

Pesquisa difusa com limite personalizado:

{
  "searchTerm": "user",
  "threshold": 0.5
}

2. Exploração de Tipos

// Get type details
const typeInfo = await getType("User");

// Find related types
const relatedTypes = await findRelatedTypes("User");

// Get field details
const fieldInfo = await getFieldDetails("User", "profile");

Recursos de Integração com Cursor AI

1. Autocomplete de Schema

   • O Cursor AI fornecerá automaticamente conclusão de código inteligente para seus tipos e campos GraphQL
   • Exemplo: Ao digitar uma query GraphQL, pressione Ctrl+Espaço para ver os campos disponíveis

2. Inspeção de Tipos

   • Passe o mouse sobre qualquer tipo GraphQL para ver sua definição completa
   • Use Command+Clique (Mac) ou Ctrl+Clique (Windows) para pular para as definições de tipo

3. Construção de Queries

   • Digite query ou mutation para obter sugestões inteligentes baseadas no seu schema
   • O Cursor AI sugerirá campos e argumentos válidos

Exemplo de Uso com Cursor AI

1. Criando uma Query

// Start typing and Cursor AI will suggest available queries
const userQuery = `
  query Get
`
// After typing "Get", Cursor AI will suggest queries like "GetUser", "GetProfile", etc.

2. Construindo Mutations

// Cursor AI will suggest available mutation fields and their required arguments
const createUserMutation = `
  mutation Create
`
// After typing "Create", you'll get suggestions like "CreateUser", "CreatePost", etc.

Comandos do Cursor AI

Acesse esses recursos através da Paleta de Comandos (Cmd/Ctrl + Shift + P):

1. MCP: Mostrar Schema

   • Exibe o schema GraphQL completo em um painel lateral
   • Útil para explorar tipos e operações disponíveis

2. MCP: Gerar Query

   • Ajuda você a construir uma query GraphQL com tipagem adequada
   • Sugere campos baseados no seu schema

3. MCP: Gerar Tipo

   • Cria interfaces TypeScript a partir de tipos GraphQL
   • Mantém a segurança de tipos entre seu frontend e API

Atalhos de Teclado

Ação	Mac	Windows/Linux
Mostrar Schema	Cmd + Shift + S	Ctrl + Shift + S
Gerar Query	Cmd + Shift + Q	Ctrl + Shift + Q
Gerar Tipo	Cmd + Shift + T	Ctrl + Shift + T
Ir para Definição	Cmd + Clique	Ctrl + Clique
Mostrar Info ao Passar	Option + Hover	Alt + Hover

Melhores Práticas

1. Pesquisa Eficiente

   • Use termos de pesquisa específicos
   • Utilize pesquisa com múltiplas palavras para melhor contexto
   • Ajuste o limite para precisão da pesquisa

2. Exploração de Tipos

   • Comece com tipos de alto nível
   • Use tipos relacionados para entender conexões
   • Explore detalhes de campos para compreensão mais profunda

3. Desempenho

   • Armazene em cache informações de schema usadas com frequência
   • Use ferramentas específicas em vez do schema completo quando possível
   • Implemente tratamento de erros adequado

Tratamento de Erros

O servidor MCP fornece informações detalhadas de erros:

try {
  const result = await searchSchema("user");
} catch (error) {
  if (error.message.includes("not found")) {
    // Handle not found case
  } else {
    // Handle other errors
  }
}

Contribuindo

Sinta-se à vontade para contribuir com o servidor MCP:

1. Reportando problemas
2. Sugerindo novos recursos
3. Enviando pull requests

Licença

Este projeto é licenciado sob a Licença MIT - consulte o arquivo LICENSE para detalhes.