martinshumberto/mcp-server-graphql

MCP Server Documentation

The MCP (Model Communication Protocol) Server is a service that provides intelligent introspection and exploration capabilities for any GraphQL API. This documentation will guide you on how to use the MCP server with Cursor IDE and MCP Client.

Overview

The MCP server provides a powerful interface to access and explore your GraphQL schema through an advanced set of tools. It introspects any GraphQL schema and provides structured, searchable information about:

• Types
• Queries
• Mutations
• Input types

Features

1. Smart Schema Search

The MCP server includes an advanced search system that helps you find exactly what you need in your GraphQL schema:

• Fuzzy matching for typo tolerance
• Multi-word search support
• Relevance-based results
• Context-aware searching
• Field-level search capabilities

2. Type Exploration

Detailed type information with:

• Field listings
• Related types
• Documentation
• Usage examples

3. Query/Mutation Discovery

Easy exploration of available operations:

• Grouped by category
• Detailed parameter information
• Return type details
• Usage context

Setup

1. Install dependencies:

yarn install

2. Configure your GraphQL endpoint in the MCP server:

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

3. Configure Cursor IDE: Create or update .cursor/mcp.json in your project:

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

Available Tools

1. Schema Tool

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

2. Search Tool

// 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. Types Tool

// 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. Field Tool

// 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. Related Types Tool

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

Using with Cursor IDE

1. Search Examples

Basic search:

{
  "searchTerm": "user"
}

Multi-word search:

{
  "searchTerm": "create user profile"
}

Fuzzy search with custom threshold:

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

2. Type Exploration

// 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");

Cursor AI Integration Features

1. Schema Autocomplete

   • Cursor AI will automatically provide intelligent code completion for your GraphQL types and fields
   • Example: When typing a GraphQL query, press Ctrl+Space to see available fields

2. Type Inspection

   • Hover over any GraphQL type to see its full definition
   • Use Command+Click (Mac) or Ctrl+Click (Windows) to jump to type definitions

3. Query Building

   • Type query or mutation to get intelligent suggestions based on your schema
   • Cursor AI will suggest valid fields and arguments

Example Usage with Cursor AI

1. Creating a 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. Building 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.

Cursor AI Commands

Access these features through the Command Palette (Cmd/Ctrl + Shift + P):

1. MCP: Show Schema

   • Displays the full GraphQL schema in a side panel
   • Useful for exploring available types and operations

2. MCP: Generate Query

   • Helps you build a GraphQL query with proper typing
   • Suggests fields based on your schema

3. MCP: Generate Type

   • Creates TypeScript interfaces from GraphQL types
   • Maintains type safety between your frontend and API

Keyboard Shortcuts

Best Practices

1. Efficient Searching

   • Use specific search terms
   • Utilize multi-word search for better context
   • Adjust threshold for search precision

2. Type Exploration

   • Start with high-level types
   • Use related types to understand connections
   • Explore field details for deeper understanding

3. Performance

   • Cache frequently used schema information
   • Use specific tools instead of full schema when possible
   • Implement proper error handling

Error Handling

The MCP server provides detailed error information:

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

Contributing

Feel free to contribute to the MCP server by:

1. Reporting issues
2. Suggesting new features
3. Submitting pull requests

License

This project is licensed under the MIT License - see the LICENSE file for details.