# 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.