# GraphQL Introspection MCP Server

A Model Context Protocol (MCP) server that provides comprehensive GraphQL introspection capabilities with filtering and detailed analysis features.

## Features

- **Complete Schema Introspection**: Get full GraphQL schema with SDL and structured data
- **Smart Filtering**: Filter queries, mutations, and types with search patterns
- **Detailed Analysis**: Get comprehensive information about specific types and fields
- **Query Execution**: Execute read-only GraphQL queries against any endpoint
- **Mutation Support**: Execute GraphQL mutations with explicit opt-in via `ALLOW_MUTATIONS` flag
- **Safety Controls**: 3-layer protection with tool listing, execution guards, and GraphQL AST validation

## Safety & Permissions

### Default Mode (Read-Only)
By default, only read-only operations are available:
- All 6 introspection tools (schema, queries, mutations, types, type details, field details)
- `execute_query` — executes GraphQL queries only

### Dangerous Mode (Mutations Enabled)
To enable mutation execution, set the `ALLOW_MUTATIONS` environment variable:

```bash
ALLOW_MUTATIONS=true npx graphql-inspector-mcp
```

Or in your MCP config:
```json
{
  "mcpServers": {
    "graphql-introspection": {
      "command": "npx",
      "args": ["-y", "graphql-inspector-mcp"],
      "env": {
        "ALLOW_MUTATIONS": "true"
      }
    }
  }
}
```

When enabled, the `execute_mutation` tool becomes available.

### Safety Architecture
Three layers of protection prevent unauthorized mutations:
1. **Tool Listing**: `execute_mutation` is hidden from tool discovery when `ALLOW_MUTATIONS` is not set
2. **Execution Guard**: Even if called directly, `execute_mutation` rejects when not in dangerous mode
3. **AST Validation**: GraphQL documents are parsed and validated — operation type is verified at the AST level, not string matching
- **MCP Annotations**: All tools annotated with `readOnlyHint` for MCP-aware clients
- **Authentication Support**: Basic Auth and Bearer token authentication
- **Caching**: In-memory caching with 5-minute expiration for better performance
- **AI-Friendly Output**: Structured JSON responses optimized for AI agents

## Installation

```bash
npm install
npm run build
```

## Usage

### Using npx

You can run the tool directly via npx:

```bash
npx graphql-inspector-mcp
```

This will start the MCP server and expose GraphQL introspection tools.

---

## CLI Arguments

The following arguments can be provided via JSON config, environment variables, or MCP tool requests. They are not traditional CLI flags, but are passed as options to the server or tools.

| Argument         | Type      | Description                                                                 | Example Value                      |
|------------------|-----------|-----------------------------------------------------------------------------|------------------------------------|
| `endpoint`       | string    |GraphQL endpoint URL (default: `http://localhost:5555/graphql`)             | `http://localhost:5555/graphql`    |
| `username`       | string    | Username for basic authentication (optional)                                | `admin`                            |
| `password`       | string    | Password for basic authentication (optional)                                | `secret`                           |
| `bearer_token`   | string    | Bearer token for authentication (optional)                                  | `eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...` |
| `search`         | string    | Search pattern to filter queries, mutations, or types (case-insensitive)    | `user`                             |
| `detailed`       | boolean   | Return detailed information (default: `false`)                              | `true`                             |
| `kind`           | string    | Filter by type kind (`OBJECT`, `SCALAR`, `ENUM`, `INTERFACE`, `UNION`, `INPUT_OBJECT`) | `OBJECT`                   |
| `type_name`      | string    | Name of the type to get details for                                         | `User`                             |
| `field_name`     | string    | Name of the field to get details for                                        | `getUser`                          |
| `operation_type` | string    | Type of operation (`query` or `mutation`)                                   | `query`                            |
| `query`          | string    | GraphQL query or mutation string                                            | `query { users { id name } }`      |
| `variables`      | object    | Variables for the GraphQL operation (optional)                              | `{"userId": "123"}`                |
| `operation_name` | string    | Name of the operation to execute (optional, for multi-operation documents)  | `GetUserById`                      |

### Usage Example

```bash
npx graphql-inspector-mcp
```

With config file (`mcp.config.json`):

```json
{
  "mcpServers": {
    "graphql-introspection": {
      "command": "npx",
      "args": [
        "-y",
        "kokorolx/graphql-inspector-mcp"
      ],
      "options": {
        "endpoint": "http://localhost:5555/graphql"
      }
    }
  }
}
```

Or via environment variables:

```bash
export GRAPHQL_DEFAULT_ENDPOINT="http://localhost:4000/graphql"
export CACHE_DURATION_MS="600000"
```

Or via MCP tool request JSON:

```json
{
  "endpoint": "http://localhost:5555/graphql",
  "search": "user",
  "detailed": true
}
```

### MCP Config File

The MCP config file allows you to customize server settings and tool behavior. By default, the config file should be named `mcp.config.json` and placed in your project root.

**Example `mcp.config.json`:**

```json
{
  "mcpServers": {
    "graphql-introspection": {
      "command": "npx",
      "args": [
        "-y",
        "kokorolx/graphql-inspector-mcp"
      ],
      "options": {
        "endpoint": "http://localhost:5550/graphql"
      }
    }
  }
}
```

- **Location:** Project root (e.g., `./mcp.config.json`)
- **Format:** Standard JSON
- **Usage:** The MCP client will automatically detect and use this configuration when starting the server.

### Available Tools

#### 1. get_graphql_schema
Get complete GraphQL schema introspection with SDL and structured data.

```json
{
  "endpoint": "http://localhost:5555/graphql",
  "username": "optional_username",
  "password": "optional_password",
  "bearer_token": "optional_bearer_token"
}
```

#### 2. filter_queries
Filter and list available GraphQL queries with optional search.

```json
{
  "endpoint": "http://localhost:5555/graphql",
  "search": "user",
  "detailed": true
}
```

#### 3. filter_mutations
Filter and list available GraphQL mutations with optional search.

```json
{
  "endpoint": "http://localhost:5555/graphql",
  "search": "create",
  "detailed": false
}
```

#### 4. filter_types
Filter and list available GraphQL types by kind and search pattern.

```json
{
  "endpoint": "http://localhost:5555/graphql",
  "search": "User",
  "kind": "OBJECT",
  "detailed": true
}
```

Supported type kinds:
- `OBJECT` - Object types
- `SCALAR` - Scalar types
- `ENUM` - Enumeration types
- `INTERFACE` - Interface types
- `UNION` - Union types
- `INPUT_OBJECT` - Input object types

#### 5. get_type_details
Get comprehensive information about a specific GraphQL type.

```json
{
  "type_name": "User",
  "endpoint": "http://localhost:5555/graphql"
}
```

#### 6. get_field_details
Get detailed information about a specific query or mutation field.

```json
{
  "field_name": "getUser",
  "operation_type": "query",
  "endpoint": "http://localhost:5555/graphql"
}
```

#### 7. execute_query
Execute a read-only GraphQL query against the endpoint.

```json
{
  "query": "query { users { id name email } }",
  "variables": {},
  "endpoint": "http://localhost:5555/graphql"
}
```

#### 8. execute_mutation
Execute a GraphQL mutation (requires `ALLOW_MUTATIONS=true`).

```json
{
  "query": "mutation { createUser(name: \"John\") { id name } }",
  "variables": {},
  "endpoint": "http://localhost:5555/graphql"
}
```

## Authentication

The server supports multiple authentication methods:

### Basic Authentication
```json
{
  "endpoint": "https://api.example.com/graphql",
  "username": "your_username",
  "password": "your_password"
}
```

### Bearer Token
```json
{
  "endpoint": "https://api.example.com/graphql",
  "bearer_token": "your_jwt_token"
}
```

## Response Format

All responses are structured JSON optimized for AI processing:

### Success Response
```json
{
  "success": true,
  "endpoint": "http://localhost:5555/graphql",
  "data": {
    // ... relevant data
  }
}
```

### Error Response
```json
{
  "success": false,
  "error": "Error description",
  "endpoint": "http://localhost:5555/graphql"
}
```

## Example Responses

### Filter Queries (Summary)
```json
{
  "success": true,
  "endpoint": "http://localhost:5555/graphql",
  "search_term": "user",
  "queries": [
    {
      "name": "getUser",
      "description": "Fetch a user by ID",
      "deprecated": false,
      "deprecation_reason": null
    },
    {
      "name": "searchUsers",
      "description": "Search users by criteria",
      "deprecated": false,
      "deprecation_reason": null
    }
  ],
  "total": 2
}
```

### Filter Queries (Detailed)
```json
{
  "success": true,
  "endpoint": "http://localhost:5555/graphql",
  "queries": [
    {
      "name": "getUser",
      "description": "Fetch a user by ID",
      "deprecated": false,
      "deprecation_reason": null,
      "arguments": [
        {
          "name": "id",
          "description": "User ID",
          "type": {
            "kind": "NON_NULL",
            "of_type": {
              "kind": "SCALAR",
              "name": "ID"
            },
            "is_required": true
          },
          "default_value": null
        }
      ],
      "return_type": {
        "kind": "OBJECT",
        "name": "User",
        "description": "A user in the system"
      }
    }
  ],
  "total": 1
}
```

### Type Details
```json
{
  "success": true,
  "endpoint": "http://localhost:5555/graphql",
  "type": {
    "name": "User",
    "kind": "OBJECT",
    "description": "A user in the system",
    "fields": [
      {
        "name": "id",
        "description": "Unique identifier",
        "type": {
          "kind": "NON_NULL",
          "of_type": {
            "kind": "SCALAR",
            "name": "ID"
          },
          "is_required": true
        },
        "deprecated": false,
        "deprecation_reason": null
      },
      {
        "name": "email",
        "description": "User email address",
        "type": {
          "kind": "SCALAR",
          "name": "String"
        },
        "deprecated": false,
        "deprecation_reason": null
      }
    ],
    "interfaces": [],
    "possible_types": null
  }
}
```

## Caching

The server implements in-memory caching with the following characteristics:

- **Cache Duration**: 5 minutes
- **Cache Key**: Combination of endpoint URL and authentication method
- **Automatic Invalidation**: Expired entries are automatically removed
- **Performance**: Subsequent requests to the same endpoint return cached data instantly

## Error Handling

The server provides comprehensive error handling for:

- **Network Issues**: Connection timeouts, DNS resolution failures
- **HTTP Errors**: 4xx and 5xx responses from GraphQL endpoints
- **GraphQL Errors**: Schema validation errors, introspection failures
- **Authentication Errors**: Invalid credentials, expired tokens
- **Validation Errors**: Missing required parameters, invalid type names

## Development

### Build
```bash
npm run build
```

### Development Mode
```bash
npm run dev
```

### Clean Build
```bash
npm run clean
npm run build
```

## Configuration

### Default Settings
- **Default Endpoint**: `http://localhost:5555/graphql`
- **Cache Duration**: 5 minutes (300 seconds)
- **Timeout**: Uses fetch default timeout
- **Max Cache Size**: No limit (memory permitting)

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `GRAPHQL_DEFAULT_ENDPOINT` | `http://localhost:5555/graphql` | Default GraphQL endpoint |
| `CACHE_DURATION_MS` | `300000` | Cache duration in milliseconds (5 minutes) |
| `ALLOW_MUTATIONS` | `false` | Enable mutation execution (`true` to enable) |

## Best Practices

### For AI Agents
1. **Use Detailed Mode**: Set `detailed: true` when you need comprehensive information
2. **Filter Effectively**: Use search patterns to reduce response size
3. **Cache Awareness**: Subsequent calls to the same endpoint will be faster due to caching
4. **Error Handling**: Always check the `success` field in responses

### For Performance
1. **Specific Searches**: Use specific search terms to reduce response size
2. **Type Filtering**: Use the `kind` parameter when filtering types
3. **Summary Mode**: Use `detailed: false` for quick overviews
4. **Endpoint Reuse**: Reuse the same endpoint URL to benefit from caching

## Troubleshooting

### Common Issues

**Schema not found**
- Verify the GraphQL endpoint URL is correct
- Check if the endpoint requires authentication
- Ensure the endpoint supports introspection queries

**Authentication failures**
- Verify credentials are correct
- Check if the endpoint expects Basic Auth or Bearer tokens
- Ensure tokens haven't expired

**Network timeouts**
- Check network connectivity to the GraphQL endpoint
- Verify firewall settings allow outbound connections
- Consider if the GraphQL server is running and responsive

### Debug Mode
Enable debug logging by setting the environment variable:
```bash
export DEBUG=graphql-introspection:*
```

## License

MIT License - see LICENSE file for details.