marias1lva/mcp-graphql-generator

🚀 MCP GraphQL Query Generator

What is MCP?

The Model Context Protocol (MCP) is a new protocol that lets tools, APIs, and models talk to each other in a structured way. Instead of manually copying data into your IDE or chat window, MCP servers can: - Provide real-time API access directly inside VS Code or AI tools. - Enable natural language queries ("show me all products with pagination"). - Act as connectors between AI assistants (like Copilot) and external systems. This project is an MCP server for GraphQL APIs: - It introspects any GraphQL schema. - Generates queries automatically. - Exposes them through CLI, REST, and VS Code integration. In short: you don’t need to handcraft GraphQL queries anymore — just ask, and they’re generated for you.

What is this?

This tool automatically introspects any GraphQL API and generates intelligent, production-ready queries with:

• Auto-discovery of all available queries and types in your GraphQL API
• Smart field selecion, including nested types
• Table-formatted queries with pagination, filtering, and sorting
• Natural language integration with GitHub Copilot
• Zero configuration - just point it to your GraphQL endpoint
• Multi-auth support (Bearer, API Key, Keycloak, etc.)
• Multiple interfaces (CLI, REST API, MCP Server, Web UI)

Features

For Developers

• Instant GraphQL exploration - No need to read documentation
• Smart query generation - Automatically includes relevant fields
• Production-ready queries - With proper pagination and error handling
• Type-safe - Full TypeScript support

For AI Integration

• GitHub Copilot integration - Ask questions in natural language
• VS Code extension ready - Works globally across all projects
• Context-aware - Understands your API structure
• Intelligent suggestions - Based on your schema

For Teams

• Consistent query patterns - Standardized across projects
• Documentation generator - Auto-generates API insights
• Multi-environment - Dev, staging, prod configurations
• Docker ready - Easy deployment and scaling

Quick Start

Option 1: Global VS Code Installation (Recommended)

Transform VS Code into a GraphQL powerhouse in 2 minutes:

# 1. Install Bun runtime (faster than Node.js)
powershell -c "irm bun.sh/install.ps1 | iex"

# 2. Clone and install globally
git clone https://github.com/marias1lva/mcp-graphql-generator.git
cd mcp-graphql-generator
.\install-global.ps1

# 3. Add to VS Code settings.json:
{
  "mcp.servers": {
    "graphql-query-generator": {
      "name": "GraphQL Query Generator",
      "url": "http://localhost:3001",
      "enabled": true
    }
  }
}

# 4. Configure your API
notepad %APPDATA%\MCPGraphQLServer\.env
# Add: GRAPHQL_API_URL=https://your-api.example.com/graphql

That's it! Now ask GitHub Copilot: "List available GraphQL queries"

Option 2: Local Development

# Clone and setup
git clone https://github.com/marias1lva/mcp-graphql-generator.git
cd mcp-graphql-generator
bun install

# Configure API
cp .env.example .env
# Edit .env with your GraphQL API URL

# Start MCP server
bun mcp-server.ts

# Or use CLI directly
bun src/cli.ts list
bun src/cli.ts generate listUsers

VS Code Integration

Once installed, use natural language with GitHub Copilot:

👤 "List all available GraphQL queries"
🤖 Found these queries:
   • listUsers - Get all users with pagination
   • listProducts - Browse products catalog  
   • listOrders - View order history

👤 "Generate a query to get users with their profiles"
🤖 query ListUsers($first: Int, $after: String) {
     listUsers(first: $first, after: $after) {
       edges {
         node {
           id
           name
           email
           profile {
             firstName
             lastName
             avatar
           }
         }
       }
       pageInfo {
         hasNextPage
         endCursor
       }
     }
   }

👤 "What fields are available in the Product type?"
🤖 Product type fields:
   • id (ID!) - Unique identifier
   • name (String!) - Product name
   • price (Float!) - Product price
   • description (String) - Product description
   • category (Category) - Product category

Usage Options

1. CLI Interface

# Discover available queries
bun src/cli.ts list

# Generate a specific query
bun src/cli.ts generate listUsers

# Generate with options
bun src/cli.ts generate listProducts --depth 3 --pagination

# Interactive mode
bun src/cli.ts interactive

2. REST API

### Get all available queries
GET http://localhost:3001/mcp/queries

### Generate a specific query
POST http://localhost:3001/mcp/generate-query
Content-Type: application/json

{
  "queryName": "listUsers",
  "options": {
    "includePagination": true,
    "maxDepth": 2,
    "selectedFields": ["id", "name", "email"]
  }
}

### Analyze a type
GET http://localhost:3001/mcp/analyze/User

3. Programmatic Usage

import { GenericQueryGenerator } from './src/generators/genericQueryGenerator';

const generator = new GenericQueryGenerator();

// Get available queries
const queries = await generator.getAvailableQueries();

// Generate a table query
const query = await generator.generateTableQuery('listUsers', {
  includePagination: true,
  maxDepth: 2
});

// Generate custom query
const customQuery = await generator.generateCustomQuery('listUsers', 
  ['id', 'name', 'email'], 
  { includePagination: true }
);

Configuration

Environment Variables

# Required: Your GraphQL API endpoint
GRAPHQL_API_URL=https://your-api.example.com/graphql

# Optional: Authentication
API_TOKEN=your_bearer_token
API_KEY=your_api_key

# Optional: Keycloak authentication
KEYCLOAK_CLIENT_ID=your_client_id
KEYCLOAK_CLIENT_SECRET=your_client_secret
KEYCLOAK_URL=https://your-keycloak.example.com/auth
KEYCLOAK_REALM=your-realm

# Optional: Server configuration
MCP_PORT=3001
MAX_DEPTH=3

Per-Project Configuration

Create .vscode/settings.json in your project:

{
  "mcpGraphQL.projectSettings": {
    "apiUrl": "https://project-specific-api.com/graphql",
    "authToken": "${env:PROJECT_API_TOKEN}",
    "defaultDepth": 2,
    "enablePagination": true
  }
}

Examples

Example Output - List Users Query

query ListUsers($first: Int, $after: String, $orderBy: UserOrderByInput) {
  listUsers(first: $first, after: $after, orderBy: $orderBy) {
    edges {
      node {
        id
        name
        email
        createdAt
        profile {
          firstName
          lastName
          avatar
        }
      }
    }
    pageInfo {
      hasNextPage
      hasPreviousPage
      startCursor
      endCursor
    }
    totalCount
  }
}

Example Output - Products with Categories

query ListProducts($first: Int, $after: String, $filters: ProductFiltersInput) {
  listProducts(first: $first, after: $after, filters: $filters) {
    edges {
      node {
        id
        name
        price
        description
        category {
          id
          name
          slug
        }
        images {
          url
          alt
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Architecture

mcp-graphql-generator/
├── src/
│   ├── cli.ts                     # Command line interface
│   ├── app.ts                     # HTTP server entry point
│   ├── generators/
│   │   └── genericQueryGenerator.ts  # Core query generation logic
│   ├── services/
│   │   ├── graphqlIntrospection.ts   # API discovery service
│   │   └── keycloakAuth.ts           # Authentication service
│   ├── mcp/
│   │   └── server.ts                 # MCP protocol server
│   ├── config/
│   │   └── credentials.ts            # Credential management
│   └── types/
│       ├── auth.ts                   # Authentication types
│       └── env.d.ts                  # Environment types
├── mcp-server.ts              # MCP server entry point
├── install-global.ps1         # Global VS Code installation
├── configure-autostart.ps1    # Auto-start configuration
├── docker-compose.global.yml  # Docker deployment
└── docs/                      # Additional documentation

Docker Deployment

# docker-compose.yml
version: '3.8'
services:
  mcp-server:
    build: .
    ports:
      - "3001:3001"
    environment:
      - GRAPHQL_API_URL=https://your-api.example.com/graphql
      - API_TOKEN=your_token
    restart: unless-stopped

# Deploy with Docker
docker-compose up -d

# Or with Docker directly
docker build -t mcp-graphql-generator .
docker run -p 3001:3001 -e GRAPHQL_API_URL=https://your-api.com/graphql mcp-graphql-generator

API Compatibility

Works with any GraphQL API that supports introspection, including:

• ✅ Apollo Server - Full compatibility
• ✅ GraphQL Yoga - Full compatibility
• ✅ Hasura - Including metadata queries
• ✅ Postgraphile - Auto-generated CRUD
• ✅ AWS AppSync - With custom resolvers
• ✅ Shopify Admin API - E-commerce queries
• ✅ GitHub GraphQL API - Repository data
• ✅ Strapi GraphQL - Headless CMS
• ✅ Contentful - Content management
• ✅ Custom GraphQL APIs - Any introspection-enabled API

Development

Setup Development Environment

# Clone repository
git clone https://github.com/marias1lva/mcp-graphql-generator.git
cd mcp-graphql-generator

# Install dependencies
bun install

# Copy environment template
cp .env.example .env
# Edit .env with your test GraphQL API

# Start in development mode
bun --watch mcp-server.ts

# Run CLI in development
bun --watch src/cli.ts list

# Build for production
bun build

# Run tests (when implemented)
bun test

Project Scripts

{
  "scripts": {
    "start": "bun src/app.ts",
    "dev": "bun --watch mcp-server.ts", 
    "build": "bun build",
    "cli": "bun src/cli.ts",
    "cli:list": "bun src/cli.ts list",
    "cli:interactive": "bun src/cli.ts interactive"
  }
}

Contributing

We welcome contributions! Here's how to get started:

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Make your changes with proper TypeScript types
4. Test your changes with a real GraphQL API
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

Contribution Guidelines

• TypeScript - All code must be properly typed
• Bun - Use Bun for package management and runtime
• Testing - Include tests for new features
• Documentation - Update README and inline docs
• Code Style - Follow existing patterns

License

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

Acknowledgments

• Bun - For blazing fast JavaScript runtime
• Model Context Protocol - For VS Code integration standard
• GraphQL - For the amazing query language
• GitHub Copilot - For AI-powered development
• TypeScript - For type safety and developer experience