GraphQL MCP Bridge

A powerful bridge implementation connecting GraphQL APIs with the Model Context Protocol (MCP), enabling seamless integration between GraphQL services and MCP-compatible AI systems. Transform any GraphQL schema into type-safe, validated MCP tools with intelligent field selection and comprehensive runtime validation powered by Zod.

Table of Contents

1. Features
2. Quick Start
3. Documentation
   1. 📚 Complete Documentation
   2. 🚀 Key Topics
4. Installation
5. Why GraphQL MCP Bridge?
6. Contributing
7. License

Features

• 🔗 GraphQL to MCP Bridge: Convert GraphQL schemas to MCP-compatible function definitions
• 📝 Description Preservation: Automatically preserves GraphQL field descriptions as tool descriptions
• ⚙️ Flexible Configuration: Selective operation generation with customizable naming patterns
• 🛡️ Comprehensive Zod Validation: Input validation and output field selection validation
• 🎯 Smart Field Selection: Dynamic field selection with support for nested objects, unions, and interfaces
• 🚀 Query Generation: Automatic GraphQL query string generation with variable handling
• 📝 TypeScript Support: Full TypeScript support with comprehensive type definitions
• ⚙️ Advanced Schema Support: Handles enums, interfaces, unions, complex inputs, and nested types
• ⚡ Runtime Safety: Built-in validation for all operations before execution

Quick Start

import { schemaParser } from 'graphql-mcp-bridge';

// Define your GraphQL schema
const schema = `
  type User {
    id: ID!
    username: String!
    email: String!
    posts: [Post!]!
  }

  type Post {
    id: ID!
    title: String!
    content: String!
    author: User!
  }

  type Query {
    """
    Retrieves a user by their unique identifier
    """
    user(id: ID!): User

    """
    Lists all users with pagination support
    """
    users(limit: Int = 10, offset: Int = 0): [User!]!
  }
`;

// Convert to MCP tools (queries only by default)
const tools = await schemaParser(schema);

// Use the generated tools
const userTool = tools.find(tool => tool.name === 'user');

// The tool automatically validates inputs and field selections
const result = await userTool.execution(
  { id: "123" }, // Variables - validated against input schema
  { id: true, username: true, posts: { title: true } } // Field selection - validated against output schema
);

console.log(result.query);
// Output: query user($id: ID!) { user(id: $id) { id username posts { title } } }

Documentation

📚 Complete Documentation

• Getting Started - Installation, quick start, and basic usage examples
• Configuration - Comprehensive configuration options and customization
• Validation System - Input validation, output validation, and error handling
• Advanced Usage - Complex examples, integration patterns, and advanced features
• Optimization Guide - Memory optimization and performance tips for large schemas

📖 Alternative Access: If the links above don’t work, you can also browse the documentation files directly in the docs/ folder on GitHub.

🚀 Key Topics

• Schema Conversion: Transform GraphQL schemas into MCP-compatible tools
• Type Safety: Comprehensive validation with Zod for both inputs and outputs
• Flexible Configuration: Control which operations are generated and how they’re named
• Large Schema Support: Handle massive schemas like GitHub’s GraphQL API efficiently
• Integration Patterns: Best practices for integrating with MCP servers

Installation

npm install graphql-mcp-bridge
# or
pnpm install graphql-mcp-bridge
# or
yarn add graphql-mcp-bridge

Why GraphQL MCP Bridge?

GraphQL MCP Bridge solves the challenge of connecting GraphQL APIs with AI systems through the Model Context Protocol. It provides:

1. Automatic Tool Generation: Convert any GraphQL schema into MCP tools without manual mapping
2. Type Safety: Full runtime validation ensures your AI systems interact with GraphQL APIs safely
3. Intelligent Field Selection: Prevent over-fetching by validating field selections against your schema
4. Production Ready: Handle large, complex schemas with memory optimization and performance features
5. Developer Experience: Full TypeScript support with comprehensive error handling

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

License

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