GraphQL API Explorer

Documentación del Servidor MCP

El servidor MCP (Protocolo de Comunicación de Modelos) es un servicio que proporciona capacidades inteligentes de introspección y exploración para cualquier API GraphQL. Esta documentación te guiará sobre cómo usar el servidor MCP con Cursor IDE y el Cliente MCP.

Descripción General

El servidor MCP proporciona una interfaz potente para acceder y explorar tu esquema GraphQL mediante un conjunto avanzado de herramientas. Realiza introspección de cualquier esquema GraphQL y proporciona información estructurada y buscable sobre:

• Tipos
• Consultas
• Mutaciones
• Tipos de entrada

Características

1. Búsqueda Inteligente de Esquemas

El servidor MCP incluye un sistema de búsqueda avanzada que te ayuda a encontrar exactamente lo que necesitas en tu esquema GraphQL:

• Coincidencia difusa para tolerancia a errores tipográficos
• Soporte de búsqueda de múltiples palabras
• Resultados basados en relevancia
• Búsqueda consciente del contexto
• Capacidades de búsqueda a nivel de campo

2. Exploración de Tipos

Información detallada de tipos con:

• Listados de campos
• Tipos relacionados
• Documentación
• Ejemplos de uso

3. Descubrimiento de Consultas/Mutaciones

Exploración fácil de operaciones disponibles:

• Agrupadas por categoría
• Información detallada de parámetros
• Detalles del tipo de retorno
• Contexto de uso

Configuración

1. Instala las dependencias:

yarn install

2. Configura tu endpoint GraphQL en el servidor MCP:

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

3. Configura Cursor IDE: Crea o actualiza .cursor/mcp.json en tu proyecto:

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

Herramientas Disponibles

1. Herramienta de Esquema

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

2. Herramienta de Búsqueda

// 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. Herramienta 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. Herramienta 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. Herramienta 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"
  }
}

Uso con Cursor IDE

1. Ejemplos de Búsqueda

Búsqueda básica:

{
  "searchTerm": "user"
}

Búsqueda de múltiples palabras:

{
  "searchTerm": "create user profile"
}

Búsqueda difusa con umbral personalizado:

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

2. Exploración 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");

Funciones de Integración con Cursor AI

1. Autocompletado de Esquemas

   • Cursor AI proporcionará automáticamente autocompletado inteligente de código para tus tipos y campos GraphQL
   • Ejemplo: Al escribir una consulta GraphQL, presiona Ctrl+Espacio para ver los campos disponibles

2. Inspección de Tipos

   • Pasa el cursor sobre cualquier tipo GraphQL para ver su definición completa
   • Usa Comando+Clic (Mac) o Ctrl+Clic (Windows) para saltar a las definiciones de tipos

3. Construcción de Consultas

   • Escribe query o mutation para obtener sugerencias inteligentes basadas en tu esquema
   • Cursor AI sugerirá campos y argumentos válidos

Ejemplo de Uso con Cursor AI

1. Creando una Consulta

// 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. Construyendo Mutaciones

// 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 de Cursor AI

Accede a estas funciones a través de la Paleta de Comandos (Cmd/Ctrl + Shift + P):

1. MCP: Mostrar Esquema

   • Muestra el esquema GraphQL completo en un panel lateral
   • Útil para explorar tipos y operaciones disponibles

2. MCP: Generar Consulta

   • Te ayuda a construir una consulta GraphQL con tipado adecuado
   • Sugiere campos basados en tu esquema

3. MCP: Generar Tipo

   • Crea interfaces TypeScript a partir de tipos GraphQL
   • Mantiene la seguridad de tipos entre tu frontend y la API

Atajos de Teclado

Acción	Mac	Windows/Linux
Mostrar Esquema	Cmd + Shift + S	Ctrl + Shift + S
Generar Consulta	Cmd + Shift + Q	Ctrl + Shift + Q
Generar Tipo	Cmd + Shift + T	Ctrl + Shift + T
Ir a Definición	Cmd + Click	Ctrl + Click
Mostrar Info al Pasar	Option + Hover	Alt + Hover

Mejores Prácticas

1. Búsqueda Eficiente

   • Usa términos de búsqueda específicos
   • Utiliza búsqueda de múltiples palabras para mejor contexto
   • Ajusta el umbral para precisión de búsqueda

2. Exploración de Tipos

   • Comienza con tipos de alto nivel
   • Usa tipos relacionados para entender conexiones
   • Explora detalles de campos para una comprensión más profunda

3. Rendimiento

   • Almacena en caché la información de esquema utilizada con frecuencia
   • Usa herramientas específicas en lugar del esquema completo cuando sea posible
   • Implementa un manejo adecuado de errores

Manejo de Errores

El servidor MCP proporciona información detallada de errores:

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

Contribuciones

Siéntete libre de contribuir al servidor MCP:

1. Reportando problemas
2. Sugiriendo nuevas funciones
3. Enviando solicitudes de extracción (pull requests)

Licencia

Este proyecto está licenciado bajo la Licencia MIT - consulta el archivo LICENSE para más detalles.