# 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:
```bash
yarn install
```
2. Configure your GraphQL endpoint in the MCP server:
```typescript
const GRAPHQL_ENDPOINT = "http://your-graphql-endpoint/graphql";
```
3. Configure Cursor IDE:
Create or update `.cursor/mcp.json` in your project:
```json
{
"mcpServers": {
"cw-core": {
"command": "node",
"args": [
"/Users/martinshumberto/repositories/cw-mcp-server/build/main.js",
"--debug"
],
"transport": "stdio"
}
}
}
```
## Available Tools
### 1. Schema Tool
```typescript
// Get complete schema information
{
"title": "GraphQL Schema",
"description": "Full introspection of GraphQL schema"
}
```
### 2. Search Tool
```typescript
// 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
```typescript
// 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
```typescript
// 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
```typescript
// 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:
```json
{
"searchTerm": "user"
}
```
Multi-word search:
```json
{
"searchTerm": "create user profile"
}
```
Fuzzy search with custom threshold:
```json
{
"searchTerm": "user",
"threshold": 0.5
}
```
### 2. Type Exploration
```typescript
// 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**
```typescript
// 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**
```typescript
// 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
| 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
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:
```typescript
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.
