# MCP GraphQL Forge [![NPM Version](https://img.shields.io/npm/v/@toolprint/mcp-graphql-forge)](https://www.npmjs.com/package/@toolprint/mcp-graphql-forge) [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE) [![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue)](https://www.typescriptlang.org/) [![MCP](https://img.shields.io/badge/MCP-2024--11--05-green)](https://modelcontextprotocol.io/) ## Quick Install [![Install MCP Server](https://cursor.com/deeplink/mcp-install-light.svg)](https://cursor.com/install-mcp?name=toolprint-mcp-graphql&config=JTdCJTIyY29tbWFuZCUyMiUzQSUyMm5weCUyMC15JTIwJTQwdG9vbHByaW50JTJGbWNwLWdyYXBocWwtZm9yZ2UlMjIlMkMlMjJlbnYlMjIlM0ElN0IlMjJHUkFQSFFMX0VORFBPSU5UJTIyJTNBJTIyaHR0cHMlM0ElMkYlMkZ5b3VyLWFwaS5jb20lMkZncmFwaHFsJTIyJTJDJTIyR1JBUEhRTF9BVVRIX0hFQURFUiUyMiUzQSUyMkJlYXJlciUyMFlPVVJfVE9LRU4lMjIlN0QlN0Q%3D) ### Alternative Installation Methods ```bash # Via Smithery (recommended) npx @smithery/cli install @toolprint/mcp-graphql-forge --client claude # Via npm npm install -g @toolprint/mcp-graphql-forge ``` An MCP server that makes GraphQL APIs accessible to AI tools by: - Automatically generating MCP tools from GraphQL schema introspection - Validating parameters and handling errors for reliable AI interactions - Supporting both stdio and HTTP transports for development and production - Caching schema and field selections for consistent performance ## ✨ Features - **Tool Generation**: Creates MCP tools from GraphQL schema introspection - **Parameter Validation**: Multi-layer validation prevents GraphQL errors - **Dual Transport**: Supports stdio (AI tools) and HTTP (development/testing) - **Schema Management**: Optional pre-introspection and caching - **Authentication**: Flexible header configuration for authenticated endpoints _[Experimental]_ ## 🚀 Getting Started > **Note**: Docker runtime support is currently a work in progress. For production deployments, we recommend using the TypeScript runtime on platforms like Smithery. ### Quick Start with HTTP Mode (Recommended for Development) 1. **Start the server**: ```bash # Start serving it with the Streamable HTTP transport GRAPHQL_ENDPOINT="https://your-api.com/graphql" npx -y @toolprint/mcp-graphql-forge --transport http --port 3001 ``` 2. **Connect with MCP Inspector**: ```bash # In another terminal, launch the inspector npx @modelcontextprotocol/inspector ``` 3. **With authentication**: ```bash # Using environment variables for configuration export GRAPHQL_ENDPOINT="https://api.github.com/graphql" export GRAPHQL_AUTH_HEADER="Bearer YOUR_TOKEN" npx @toolprint/mcp-graphql-forge --transport http --port 3001 # Or all in one line GRAPHQL_ENDPOINT="https://api.github.com/graphql" GRAPHQL_AUTH_HEADER="Bearer YOUR_TOKEN" npx @toolprint/mcp-graphql-forge --transport http --port 3001 ``` ### Direct AI Integration (Claude/Cursor) Create an `mcp.json` in your project root. This will run it in **stdio** mode. ```json { "mcpServers": { "mcp-graphql-forge": { "command": "npx", "args": [ "-y", "@toolprint/mcp-graphql-forge" ], "env": { "GRAPHQL_ENDPOINT": "https://your-api.com/graphql", "GRAPHQL_AUTH_HEADER": "Bearer YOUR_TOKEN" } } } } ``` ### Schema Management 1. **Pre-generate schema**: ```bash # Generate schema without starting server GRAPHQL_ENDPOINT="https://your-api.com/graphql" mcp-graphql-forge introspect # Start server using pre-generated schema mcp-graphql-forge --no-introspection --transport http --port 3001 ``` 2. **Custom schema location**: ```bash # Generate schema in custom location SCHEMA_PATH="./schemas/my-api.json" mcp-graphql-forge introspect # Use custom schema location SCHEMA_PATH="./schemas/my-api.json" mcp-graphql-forge --no-introspection --transport http --port 3001 ``` 3. **Force schema regeneration**: ```bash # Force regenerate schema even if it exists mcp-graphql-forge introspect --force # Regenerate and start server mcp-graphql-forge --force-introspection --transport http --port 3001 ``` ### Advanced Configuration ```bash # Multiple custom headers export GRAPHQL_HEADER_X_API_KEY="your-api-key" export GRAPHQL_HEADER_X_CLIENT_ID="your-client-id" mcp-graphql-forge --transport http --port 3001 # Development mode with auto-reload on schema changes mcp-graphql-forge --transport http --port 3001 --watch ``` ## 🛠️ How It Works ### 1. **Schema Introspection** ```bash 🗂️ Building field selection cache for all types... 📊 Generated field selections for 44 types 💾 Field selection cache contains 44 full selections and 5 minimal selections Generated 63 tools from GraphQL schema: - 30 query tools - 33 mutation tools ``` ### 2. **Intelligent Tool Generation** For a GraphQL schema like: ```graphql type Query { user(id: ID!): User articles(filters: ArticleFiltersInput, pagination: PaginationArg): [Article] } type Mutation { createUser(input: CreateUserInput!): User } ``` Fast MCP GraphQL automatically generates: - ✅ `query_user` - with required `id` parameter validation - ✅ `query_articles` - with optional filtering and pagination - ✅ `mutation_createUser` - with input validation and complete field selections ### 3. **Smart Field Selection** Instead of manual GraphQL query construction: ```graphql # ❌ Error-prone manual approach query { articles { # Missing required field selections! author { # Circular reference issues! } } } ``` Fast MCP GraphQL generates optimal queries automatically: ```graphql # ✅ Auto-generated with full field selections query articlesOperation($filters: ArticleFiltersInput, $pagination: PaginationArg) { articles(filters: $filters, pagination: $pagination) { documentId title description author { documentId name email articles_connection { nodes { documentId } # Circular reference handled! } } category { documentId name articles { documentId } # Cached selection reused! } } } ``` ## 🏗️ Architecture ### Caching System - **Type-Level Caching**: Each GraphQL type's field selection is computed once and reused - **Circular Reference Resolution**: Intelligent detection with minimal field fallbacks - **Consistent Output**: Same type always generates identical field selections ### Validation Pipeline 1. **JSON Schema Validation**: MCP clients validate parameters before execution 2. **Server-Side Validation**: Prevents execution with missing required parameters 3. **GraphQL Validation**: Final validation at the GraphQL layer ### Transport Support - **Stdio Transport**: For MCP client integration (default) - **HTTP Transport**: RESTful interface with MCP 2025 Streamable HTTP specification - **Session Management**: Automatic session handling for HTTP transport ## 📚 API Reference ### CLI Options ```bash mcp-graphql-forge [options] Options: --transport Transport type: stdio or http (default: stdio) --port Port for HTTP transport (default: 3000) --no-introspection Skip schema introspection (use cached schema) --version Show version number --help Show help ``` ### Environment Variables | Variable | Description | Example | |----------|-------------|---------| | `GRAPHQL_ENDPOINT` | GraphQL API endpoint | `https://api.example.com/graphql` | | `GRAPHQL_AUTH_HEADER` | Authorization header | `Bearer token123` | | `GRAPHQL_HEADER_*` | Custom headers | `GRAPHQL_HEADER_X_API_KEY=key123` | | `SCHEMA_PATH` | Schema cache file path | `./schema.json` | | `PORT` | HTTP server port | `3001` | ### Generated Tool Schema Each generated tool follows this pattern: ```typescript { name: "query_user", description: "Execute GraphQL query: user", inputSchema: { type: "object", properties: { id: { type: "string" } }, required: ["id"] // Only truly required parameters } } ``` ## 🧪 Testing ### Comprehensive Test Suite - **40+ Test Cases**: Covering all functionality and edge cases - **Real-World Scenarios**: Tests against actual GraphQL schemas (Strapi, GitHub, etc.) - **Security Testing**: Prototype pollution protection and input validation - **Performance Testing**: Cache efficiency and field selection optimization ```bash # Run all tests npm test # Run specific test suites npm test -- src/__tests__/field-selection-cache.test.ts npm test -- src/__tests__/server-validation.test.ts npm test -- src/__tests__/graphql-execution.test.ts # Coverage report npm run test:coverage ``` ### Integration Testing ```bash # Test with real GraphQL endpoints GRAPHQL_ENDPOINT="https://countries.trevorblades.com/" npm test # Test caching performance npm run test:performance ``` ## 🛡️ Security ### Parameter Validation - **Required Parameter Enforcement**: Prevents GraphQL variable errors - **Null/Undefined Checking**: Validates parameter presence and values - **Prototype Pollution Protection**: Uses secure property checking methods ### Schema Security - **Input Sanitization**: All GraphQL inputs are properly typed and validated - **Circular Reference Protection**: Prevents infinite recursion in field selections - **Header Validation**: Secure header handling for authentication ## 🚀 Performance ### Benchmarks - **Schema Introspection**: ~10ms for typical schemas - **Tool Generation**: ~5ms with caching enabled - **Field Selection**: Pre-computed and cached for instant access - **Memory Usage**: Efficient caching with minimal memory footprint ### Optimization Features - **Field Selection Caching**: Eliminates redundant field selection computation - **Schema Caching**: Optional schema persistence for faster restarts - **Minimal GraphQL Queries**: Only requests necessary fields - **Connection Pooling**: Efficient HTTP client management ## 🤝 Contributing We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details. ### Development Setup ```bash # Clone the repository git clone https://github.com/toolprint/mcp-graphql-forge.git cd mcp-graphql-forge # Install dependencies npm install # Run tests npm test # Start development npm run dev ``` ### Code Quality - **TypeScript**: Fully typed codebase - **ESLint**: Consistent code formatting - **Vitest**: Modern testing framework - **100% Test Coverage**: Comprehensive test suite ## 📖 Examples ### Real-World Usage

🔸 Strapi CMS Integration

```bash # Connect to Strapi GraphQL API export GRAPHQL_ENDPOINT="https://your-strapi.com/graphql" export GRAPHQL_AUTH_HEADER="Bearer YOUR_STRAPI_TOKEN" mcp-graphql-forge # Generates tools like: # - query_articles, query_users, query_categories # - mutation_createArticle, mutation_updateUser # - Full field selections with media, relations, and metadata ```

🔸 GitHub API Integration

```bash # Connect to GitHub GraphQL API export GRAPHQL_ENDPOINT="https://api.github.com/graphql" export GRAPHQL_AUTH_HEADER="Bearer YOUR_GITHUB_TOKEN" mcp-graphql-forge # Generates tools like: # - query_repository, query_user, query_organization # - query_search (with intelligent result type handling) # - mutation_createIssue, mutation_addComment ```

🔸 E-commerce Platform

```bash # Connect to Shopify/WooCommerce GraphQL export GRAPHQL_ENDPOINT="https://your-shop.myshopify.com/api/graphql" export GRAPHQL_HEADER_X_SHOPIFY_ACCESS_TOKEN="YOUR_TOKEN" mcp-graphql-forge # Generates tools for: # - Product management (query_products, mutation_productCreate) # - Order processing (query_orders, mutation_orderUpdate) # - Customer management with full relationship mapping ```

### Custom Schema Example ```typescript // Example: Blog Platform Schema type Query { posts(published: Boolean, authorId: ID): [Post] post(slug: String!): Post authors: [Author] } type Mutation { createPost(input: CreatePostInput!): Post publishPost(id: ID!): Post } // Generated Tools: // ✅ query_posts (published?: boolean, authorId?: string) // ✅ query_post (slug: string) ← Required parameter enforced // ✅ query_authors () ← No parameters // ✅ mutation_createPost (input: CreatePostInput) ← Validated input // ✅ mutation_publishPost (id: string) ← Required parameter enforced ``` ## 📄 License This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details. ## 🏢 About OneGrep, Inc. MCP GraphQL Forge is developed and maintained by [OneGrep, Inc.](https://onegrep.dev), a company focused on building developer tools and AI infrastructure. --- **[Issues](https://github.com/toolprint/mcp-graphql-forge/issues)** • **[Discussions](https://github.com/toolprint/mcp-graphql-forge/discussions)** Made with ❤️ by the OneGrep team