{"id":31221012,"url":"https://github.com/toolprint/mcp-graphql-forge","last_synced_at":"2025-09-21T19:10:28.894Z","repository":{"id":302719675,"uuid":"1012665918","full_name":"toolprint/mcp-graphql-forge","owner":"toolprint","description":"MCP that can proxy any GraphQL API and expose graphql operations as mcp tools.","archived":false,"fork":false,"pushed_at":"2025-08-14T22:38:20.000Z","size":720,"stargazers_count":12,"open_issues_count":2,"forks_count":5,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-17T08:35:52.250Z","etag":null,"topics":["graphql","graphql-server","mcp","mcp-server","mcp-to-graphql","model-context-protocol","proxy","toolprint"],"latest_commit_sha":null,"homepage":"https://toolprint.ai","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/toolprint.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-02T17:25:16.000Z","updated_at":"2025-09-10T05:46:32.000Z","dependencies_parsed_at":"2025-07-03T22:18:48.958Z","dependency_job_id":"f0be25ad-ecc7-4a51-98c5-cebd63c792ea","html_url":"https://github.com/toolprint/mcp-graphql-forge","commit_stats":null,"previous_names":["toolprint/mcp-graphql-forge"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/toolprint/mcp-graphql-forge","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toolprint%2Fmcp-graphql-forge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toolprint%2Fmcp-graphql-forge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toolprint%2Fmcp-graphql-forge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toolprint%2Fmcp-graphql-forge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/toolprint","download_url":"https://codeload.github.com/toolprint/mcp-graphql-forge/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toolprint%2Fmcp-graphql-forge/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":275610519,"owners_count":25496008,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-17T02:00:09.119Z","response_time":84,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["graphql","graphql-server","mcp","mcp-server","mcp-to-graphql","model-context-protocol","proxy","toolprint"],"created_at":"2025-09-21T19:10:23.276Z","updated_at":"2025-09-21T19:10:24.002Z","avatar_url":"https://github.com/toolprint.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MCP GraphQL Forge\n\n[![NPM Version](https://img.shields.io/npm/v/@toolprint/mcp-graphql-forge)](https://www.npmjs.com/package/@toolprint/mcp-graphql-forge)\n[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue)](https://www.typescriptlang.org/)\n[![MCP](https://img.shields.io/badge/MCP-2024--11--05-green)](https://modelcontextprotocol.io/)\n\n## Quick Install\n\n[![Install MCP Server](https://cursor.com/deeplink/mcp-install-light.svg)](https://cursor.com/install-mcp?name=toolprint-mcp-graphql\u0026config=JTdCJTIyY29tbWFuZCUyMiUzQSUyMm5weCUyMC15JTIwJTQwdG9vbHByaW50JTJGbWNwLWdyYXBocWwtZm9yZ2UlMjIlMkMlMjJlbnYlMjIlM0ElN0IlMjJHUkFQSFFMX0VORFBPSU5UJTIyJTNBJTIyaHR0cHMlM0ElMkYlMkZ5b3VyLWFwaS5jb20lMkZncmFwaHFsJTIyJTJDJTIyR1JBUEhRTF9BVVRIX0hFQURFUiUyMiUzQSUyMkJlYXJlciUyMFlPVVJfVE9LRU4lMjIlN0QlN0Q%3D)\n\n### Alternative Installation Methods\n\n```bash\n# Via Smithery (recommended)\nnpx @smithery/cli install @toolprint/mcp-graphql-forge --client claude\n\n# Via npm\nnpm install -g @toolprint/mcp-graphql-forge\n```\n\nAn MCP server that makes GraphQL APIs accessible to AI tools by:\n- Automatically generating MCP tools from GraphQL schema introspection\n- Validating parameters and handling errors for reliable AI interactions\n- Supporting both stdio and HTTP transports for development and production\n- Caching schema and field selections for consistent performance\n\n## ✨ Features\n\n- **Tool Generation**: Creates MCP tools from GraphQL schema introspection\n- **Parameter Validation**: Multi-layer validation prevents GraphQL errors\n- **Dual Transport**: Supports stdio (AI tools) and HTTP (development/testing)\n- **Schema Management**: Optional pre-introspection and caching\n- **Authentication**: Flexible header configuration for authenticated endpoints _[Experimental]_\n\n## 🚀 Getting Started\n\n\u003e **Note**: Docker runtime support is currently a work in progress. For production deployments, we recommend using the TypeScript runtime on platforms like Smithery.\n\n### Quick Start with HTTP Mode (Recommended for Development)\n\n1. **Start the server**:\n   ```bash\n   # Start serving it with the Streamable HTTP transport\n   GRAPHQL_ENDPOINT=\"https://your-api.com/graphql\" npx -y @toolprint/mcp-graphql-forge --transport http --port 3001\n   ```\n\n2. **Connect with MCP Inspector**:\n   ```bash\n   # In another terminal, launch the inspector\n   npx @modelcontextprotocol/inspector\n   ```\n\n3. **With authentication**:\n   ```bash\n   # Using environment variables for configuration\n   export GRAPHQL_ENDPOINT=\"https://api.github.com/graphql\"\n   export GRAPHQL_AUTH_HEADER=\"Bearer YOUR_TOKEN\"\n   npx @toolprint/mcp-graphql-forge --transport http --port 3001\n\n   # Or all in one line\n   GRAPHQL_ENDPOINT=\"https://api.github.com/graphql\" GRAPHQL_AUTH_HEADER=\"Bearer YOUR_TOKEN\" npx @toolprint/mcp-graphql-forge --transport http --port 3001\n   ```\n\n### Direct AI Integration (Claude/Cursor)\n\nCreate an `mcp.json` in your project root. This will run it in **stdio** mode.\n\n```json\n{\n    \"mcpServers\": {\n        \"mcp-graphql-forge\": {\n            \"command\": \"npx\",\n            \"args\": [\n              \"-y\",\n              \"@toolprint/mcp-graphql-forge\"\n            ],\n            \"env\": {\n                \"GRAPHQL_ENDPOINT\": \"https://your-api.com/graphql\",\n                \"GRAPHQL_AUTH_HEADER\": \"Bearer YOUR_TOKEN\"\n            }\n        }\n    }\n}\n```\n\n### Schema Management\n\n1. **Pre-generate schema**:\n   ```bash\n   # Generate schema without starting server\n   GRAPHQL_ENDPOINT=\"https://your-api.com/graphql\" mcp-graphql-forge introspect\n\n   # Start server using pre-generated schema\n   mcp-graphql-forge --no-introspection --transport http --port 3001\n   ```\n\n2. **Custom schema location**:\n   ```bash\n   # Generate schema in custom location\n   SCHEMA_PATH=\"./schemas/my-api.json\" mcp-graphql-forge introspect\n\n   # Use custom schema location\n   SCHEMA_PATH=\"./schemas/my-api.json\" mcp-graphql-forge --no-introspection --transport http --port 3001\n   ```\n\n3. **Force schema regeneration**:\n   ```bash\n   # Force regenerate schema even if it exists\n   mcp-graphql-forge introspect --force\n\n   # Regenerate and start server\n   mcp-graphql-forge --force-introspection --transport http --port 3001\n   ```\n\n### Advanced Configuration\n\n```bash\n# Multiple custom headers\nexport GRAPHQL_HEADER_X_API_KEY=\"your-api-key\"\nexport GRAPHQL_HEADER_X_CLIENT_ID=\"your-client-id\"\nmcp-graphql-forge --transport http --port 3001\n\n# Development mode with auto-reload on schema changes\nmcp-graphql-forge --transport http --port 3001 --watch\n```\n\n## 🛠️ How It Works\n\n### 1. **Schema Introspection**\n```bash\n🗂️  Building field selection cache for all types...\n📊 Generated field selections for 44 types  \n💾 Field selection cache contains 44 full selections and 5 minimal selections\nGenerated 63 tools from GraphQL schema:\n  - 30 query tools\n  - 33 mutation tools\n```\n\n### 2. **Intelligent Tool Generation**\n\nFor a GraphQL schema like:\n```graphql\ntype Query {\n  user(id: ID!): User\n  articles(filters: ArticleFiltersInput, pagination: PaginationArg): [Article]\n}\n\ntype Mutation {\n  createUser(input: CreateUserInput!): User\n}\n```\n\nFast MCP GraphQL automatically generates:\n- ✅ `query_user` - with required `id` parameter validation\n- ✅ `query_articles` - with optional filtering and pagination\n- ✅ `mutation_createUser` - with input validation and complete field selections\n\n### 3. **Smart Field Selection**\n\nInstead of manual GraphQL query construction:\n```graphql\n# ❌ Error-prone manual approach\nquery {\n  articles {\n    # Missing required field selections!\n    author {\n      # Circular reference issues!\n    }\n  }\n}\n```\n\nFast MCP GraphQL generates optimal queries automatically:\n```graphql\n# ✅ Auto-generated with full field selections\nquery articlesOperation($filters: ArticleFiltersInput, $pagination: PaginationArg) {\n  articles(filters: $filters, pagination: $pagination) {\n    documentId\n    title\n    description\n    author {\n      documentId\n      name\n      email\n      articles_connection {\n        nodes { documentId }  # Circular reference handled!\n      }\n    }\n    category {\n      documentId\n      name\n      articles { documentId }  # Cached selection reused!\n    }\n  }\n}\n```\n\n## 🏗️ Architecture\n\n### Caching System\n- **Type-Level Caching**: Each GraphQL type's field selection is computed once and reused\n- **Circular Reference Resolution**: Intelligent detection with minimal field fallbacks\n- **Consistent Output**: Same type always generates identical field selections\n\n### Validation Pipeline\n1. **JSON Schema Validation**: MCP clients validate parameters before execution\n2. **Server-Side Validation**: Prevents execution with missing required parameters\n3. **GraphQL Validation**: Final validation at the GraphQL layer\n\n### Transport Support\n- **Stdio Transport**: For MCP client integration (default)\n- **HTTP Transport**: RESTful interface with MCP 2025 Streamable HTTP specification\n- **Session Management**: Automatic session handling for HTTP transport\n\n## 📚 API Reference\n\n### CLI Options\n\n```bash\nmcp-graphql-forge [options]\n\nOptions:\n  --transport \u003ctype\u003e     Transport type: stdio or http (default: stdio)\n  --port \u003cnumber\u003e        Port for HTTP transport (default: 3000)\n  --no-introspection     Skip schema introspection (use cached schema)\n  --version              Show version number\n  --help                 Show help\n```\n\n### Environment Variables\n\n| Variable | Description | Example |\n|----------|-------------|---------|\n| `GRAPHQL_ENDPOINT` | GraphQL API endpoint | `https://api.example.com/graphql` |\n| `GRAPHQL_AUTH_HEADER` | Authorization header | `Bearer token123` |\n| `GRAPHQL_HEADER_*` | Custom headers | `GRAPHQL_HEADER_X_API_KEY=key123` |\n| `SCHEMA_PATH` | Schema cache file path | `./schema.json` |\n| `PORT` | HTTP server port | `3001` |\n\n### Generated Tool Schema\n\nEach generated tool follows this pattern:\n\n```typescript\n{\n  name: \"query_user\",\n  description: \"Execute GraphQL query: user\",\n  inputSchema: {\n    type: \"object\",\n    properties: {\n      id: { type: \"string\" }\n    },\n    required: [\"id\"]  // Only truly required parameters\n  }\n}\n```\n\n## 🧪 Testing\n\n### Comprehensive Test Suite\n\n- **40+ Test Cases**: Covering all functionality and edge cases\n- **Real-World Scenarios**: Tests against actual GraphQL schemas (Strapi, GitHub, etc.)\n- **Security Testing**: Prototype pollution protection and input validation\n- **Performance Testing**: Cache efficiency and field selection optimization\n\n```bash\n# Run all tests\nnpm test\n\n# Run specific test suites\nnpm test -- src/__tests__/field-selection-cache.test.ts\nnpm test -- src/__tests__/server-validation.test.ts\nnpm test -- src/__tests__/graphql-execution.test.ts\n\n# Coverage report\nnpm run test:coverage\n```\n\n### Integration Testing\n\n```bash\n# Test with real GraphQL endpoints\nGRAPHQL_ENDPOINT=\"https://countries.trevorblades.com/\" npm test\n\n# Test caching performance\nnpm run test:performance\n```\n\n## 🛡️ Security\n\n### Parameter Validation\n- **Required Parameter Enforcement**: Prevents GraphQL variable errors\n- **Null/Undefined Checking**: Validates parameter presence and values\n- **Prototype Pollution Protection**: Uses secure property checking methods\n\n### Schema Security\n- **Input Sanitization**: All GraphQL inputs are properly typed and validated\n- **Circular Reference Protection**: Prevents infinite recursion in field selections\n- **Header Validation**: Secure header handling for authentication\n\n## 🚀 Performance\n\n### Benchmarks\n- **Schema Introspection**: ~10ms for typical schemas\n- **Tool Generation**: ~5ms with caching enabled\n- **Field Selection**: Pre-computed and cached for instant access\n- **Memory Usage**: Efficient caching with minimal memory footprint\n\n### Optimization Features\n- **Field Selection Caching**: Eliminates redundant field selection computation\n- **Schema Caching**: Optional schema persistence for faster restarts\n- **Minimal GraphQL Queries**: Only requests necessary fields\n- **Connection Pooling**: Efficient HTTP client management\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\n\n### Development Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/toolprint/mcp-graphql-forge.git\ncd mcp-graphql-forge\n\n# Install dependencies\nnpm install\n\n# Run tests\nnpm test\n\n# Start development\nnpm run dev\n```\n\n### Code Quality\n\n- **TypeScript**: Fully typed codebase\n- **ESLint**: Consistent code formatting\n- **Vitest**: Modern testing framework\n- **100% Test Coverage**: Comprehensive test suite\n\n## 📖 Examples\n\n### Real-World Usage\n\n\u003cdetails\u003e\n\u003csummary\u003e🔸 \u003cstrong\u003eStrapi CMS Integration\u003c/strong\u003e\u003c/summary\u003e\n\n```bash\n# Connect to Strapi GraphQL API\nexport GRAPHQL_ENDPOINT=\"https://your-strapi.com/graphql\"\nexport GRAPHQL_AUTH_HEADER=\"Bearer YOUR_STRAPI_TOKEN\"\nmcp-graphql-forge\n\n# Generates tools like:\n# - query_articles, query_users, query_categories\n# - mutation_createArticle, mutation_updateUser\n# - Full field selections with media, relations, and metadata\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e🔸 \u003cstrong\u003eGitHub API Integration\u003c/strong\u003e\u003c/summary\u003e\n\n```bash\n# Connect to GitHub GraphQL API\nexport GRAPHQL_ENDPOINT=\"https://api.github.com/graphql\"\nexport GRAPHQL_AUTH_HEADER=\"Bearer YOUR_GITHUB_TOKEN\"\nmcp-graphql-forge\n\n# Generates tools like:\n# - query_repository, query_user, query_organization\n# - query_search (with intelligent result type handling)\n# - mutation_createIssue, mutation_addComment\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e🔸 \u003cstrong\u003eE-commerce Platform\u003c/strong\u003e\u003c/summary\u003e\n\n```bash\n# Connect to Shopify/WooCommerce GraphQL\nexport GRAPHQL_ENDPOINT=\"https://your-shop.myshopify.com/api/graphql\"\nexport GRAPHQL_HEADER_X_SHOPIFY_ACCESS_TOKEN=\"YOUR_TOKEN\"\nmcp-graphql-forge\n\n# Generates tools for:\n# - Product management (query_products, mutation_productCreate)\n# - Order processing (query_orders, mutation_orderUpdate)\n# - Customer management with full relationship mapping\n```\n\u003c/details\u003e\n\n### Custom Schema Example\n\n```typescript\n// Example: Blog Platform Schema\ntype Query {\n  posts(published: Boolean, authorId: ID): [Post]\n  post(slug: String!): Post\n  authors: [Author]\n}\n\ntype Mutation {\n  createPost(input: CreatePostInput!): Post\n  publishPost(id: ID!): Post\n}\n\n// Generated Tools:\n// ✅ query_posts (published?: boolean, authorId?: string)\n// ✅ query_post (slug: string) ← Required parameter enforced\n// ✅ query_authors () ← No parameters\n// ✅ mutation_createPost (input: CreatePostInput) ← Validated input\n// ✅ mutation_publishPost (id: string) ← Required parameter enforced\n```\n\n## 📄 License\n\nThis project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.\n\n## 🏢 About OneGrep, Inc.\n\nMCP GraphQL Forge is developed and maintained by [OneGrep, Inc.](https://onegrep.dev), a company focused on building developer tools and AI infrastructure.\n\n---\n\n**[Issues](https://github.com/toolprint/mcp-graphql-forge/issues)** • \n**[Discussions](https://github.com/toolprint/mcp-graphql-forge/discussions)**\n\nMade with ❤️ by the OneGrep team\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftoolprint%2Fmcp-graphql-forge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftoolprint%2Fmcp-graphql-forge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftoolprint%2Fmcp-graphql-forge/lists"}