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
- Install dependencies:
yarn install
- Configure your GraphQL endpoint in the MCP server:
const GRAPHQL_ENDPOINT = "http://your-graphql-endpoint/graphql";
- Configure Cursor IDE:
Create or update
.cursor/mcp.jsonin 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
-
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
-
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
-
Query Building
- Type
queryormutationto get intelligent suggestions based on your schema - Cursor AI will suggest valid fields and arguments
- Type
Example Usage with Cursor AI
- 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.
- 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):
-
MCP: Show Schema
- Displays the full GraphQL schema in a side panel
- Useful for exploring available types and operations
-
MCP: Generate Query
- Helps you build a GraphQL query with proper typing
- Suggests fields based on your schema
-
MCP: Generate Type
- Creates TypeScript interfaces from GraphQL types
- Maintains type safety between your frontend and API
Keyboard Shortcuts
| Action | Mac | Windows/Linux |
|---|---|---|
| Show Schema | Cmd + Shift + S | Ctrl + Shift + S |
| Generate Query | Cmd + Shift + Q | Ctrl + Shift + Q |
| Generate Type | Cmd + Shift + T | Ctrl + Shift + T |
| Jump to Definition | Cmd + Click | Ctrl + Click |
| Show Hover Info | Option + Hover | Alt + Hover |
Best Practices
-
Efficient Searching
- Use specific search terms
- Utilize multi-word search for better context
- Adjust threshold for search precision
-
Type Exploration
- Start with high-level types
- Use related types to understand connections
- Explore field details for deeper understanding
-
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:
- Reporting issues
- Suggesting new features
- Submitting pull requests
License
This project is licensed under the MIT License - see the LICENSE file for details.