{"id":47727092,"url":"https://github.com/mstuart/graphql-agent-toolkit","last_synced_at":"2026-04-02T20:48:43.524Z","repository":{"id":346011547,"uuid":"1158314595","full_name":"mstuart/graphql-agent-toolkit","owner":"mstuart","description":"Turn any GraphQL API into AI-agent-ready tools — MCP servers, LangChain tools, and standalone SDKs","archived":false,"fork":false,"pushed_at":"2026-03-21T20:23:26.000Z","size":742,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-22T09:21:29.069Z","etag":null,"topics":["ai-agent","crewai","graphql","graphql-tools","langchain","mcp","model-context-protocol","sdk","typescript","vercel-ai"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mstuart.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":".github/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-15T06:28:14.000Z","updated_at":"2026-03-21T20:22:32.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mstuart/graphql-agent-toolkit","commit_stats":null,"previous_names":["mstuart/graphql-agent-toolkit"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/mstuart/graphql-agent-toolkit","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mstuart%2Fgraphql-agent-toolkit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mstuart%2Fgraphql-agent-toolkit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mstuart%2Fgraphql-agent-toolkit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mstuart%2Fgraphql-agent-toolkit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mstuart","download_url":"https://codeload.github.com/mstuart/graphql-agent-toolkit/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mstuart%2Fgraphql-agent-toolkit/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31316007,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-02T12:59:32.332Z","status":"ssl_error","status_checked_at":"2026-04-02T12:54:48.875Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["ai-agent","crewai","graphql","graphql-tools","langchain","mcp","model-context-protocol","sdk","typescript","vercel-ai"],"created_at":"2026-04-02T20:48:39.382Z","updated_at":"2026-04-02T20:48:43.516Z","avatar_url":"https://github.com/mstuart.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# graphql-agent-toolkit\n\n[![CI](https://github.com/mstuart/graphql-agent-toolkit/actions/workflows/ci.yml/badge.svg)](https://github.com/mstuart/graphql-agent-toolkit/actions/workflows/ci.yml)\n[![npm version](https://img.shields.io/npm/v/graphql-agent-toolkit.svg)](https://www.npmjs.com/package/graphql-agent-toolkit)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nTurn any GraphQL API into AI-agent-ready tools -- MCP servers, LangChain tools, and framework adapters.\n\n**graphql-agent-toolkit** introspects a GraphQL endpoint, generates typed operations, and exposes them as tools that AI agents can discover and call. It supports the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) out of the box, so you can connect any MCP-compatible AI client to any GraphQL API in seconds.\n\n## Quick Start\n\n```bash\nnpx graphql-agent-toolkit init --endpoint https://your-api.com/graphql\n```\n\nThis introspects your schema and prints a configuration summary. To start an MCP server:\n\n```bash\nnpx graphql-agent-toolkit serve --endpoint https://your-api.com/graphql\n```\n\n## Installation\n\n```bash\nnpm install graphql-agent-toolkit graphql\n```\n\n## Requirements\n\n- Node.js \u003e= 18.0.0\n- `graphql` \u003e= 16.0.0 (peer dependency)\n- TypeScript \u003e= 5.0 (optional, for type definitions)\n\nFully written in TypeScript with complete type exports for all public APIs.\n\n## Features\n\n- **Schema Introspection** -- Automatically fetches and parses any GraphQL schema\n- **Operation Builder** -- Generates queries and mutations with proper variable definitions and nested selection sets\n- **MCP Server** -- Creates a fully functional MCP server with tools for every query and mutation\n- **Semantic Search** -- TF-IDF powered schema navigator to find relevant types and fields\n- **Pagination Handling** -- Auto-detects and handles Relay and offset pagination across multiple pages\n- **Result Summarization** -- Truncate large responses for LLM context windows with markdown formatting\n- **Framework Adapters** -- Generate tools for LangChain, CrewAI, and Vercel AI SDK with zero framework dependencies\n- **Mock Data Generation** -- Generate deterministic mock data from your schema with `@mock()` directive support\n- **CLI** -- Command-line interface for quick setup and serving\n- **Dual Format** -- Ships as both ESM and CJS with full TypeScript types\n\n## Programmatic API\n\n### Introspect and Parse a Schema\n\n```typescript\nimport { fetchSchema, parseSchema } from 'graphql-agent-toolkit';\n\nconst introspection = await fetchSchema({\n  endpoint: 'https://your-api.com/graphql',\n  headers: { Authorization: 'Bearer YOUR_TOKEN' },\n});\n\nconst schema = parseSchema(introspection);\n\nconsole.log(`Query type: ${schema.queryType}`);\nconsole.log(`Types: ${schema.types.size}`);\n```\n\n### Build Operations\n\n```typescript\nimport { fetchSchema, parseSchema, buildOperation } from 'graphql-agent-toolkit';\n\nconst introspection = await fetchSchema({ endpoint: 'https://your-api.com/graphql' });\nconst schema = parseSchema(introspection);\n\nconst op = buildOperation(schema, 'user', { maxDepth: 3 });\nconsole.log(op.operation);\n// query UserQuery($id: ID!) {\n//   user(id: $id) {\n//     id\n//     name\n//     email\n//     posts {\n//       id\n//       title\n//     }\n//   }\n// }\nconsole.log(op.variables);\n// [{ name: 'id', type: 'ID!', required: true, description: 'User ID' }]\n```\n\n### Create an MCP Server\n\n```typescript\nimport { createAgentToolkitServer } from 'graphql-agent-toolkit';\nimport { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';\n\nconst server = await createAgentToolkitServer({\n  endpoint: 'https://your-api.com/graphql',\n  headers: { Authorization: 'Bearer YOUR_TOKEN' },\n  operationDepth: 2,\n});\n\nconst transport = new StdioServerTransport();\nawait server.connect(transport);\n```\n\nEach query becomes a `query_\u003cfieldName\u003e` tool, and each mutation becomes a `mutate_\u003cfieldName\u003e` tool. An additional `explore_schema` tool lets the agent browse types and fields.\n\n### Semantic Schema Navigation\n\n```typescript\nimport { fetchSchema, parseSchema, SchemaNavigator } from 'graphql-agent-toolkit';\n\nconst introspection = await fetchSchema({ endpoint: 'https://your-api.com/graphql' });\nconst schema = parseSchema(introspection);\n\nconst navigator = new SchemaNavigator();\nnavigator.index(schema);\n\n// Search for relevant types\nconst results = navigator.search('user authentication');\nfor (const result of results) {\n  console.log(`${result.typeName} (${result.kind}) - score: ${result.score.toFixed(3)}`);\n}\n\n// Get detailed context for a type\nconst context = navigator.getTypeContext('User');\nconsole.log(context);\n```\n\n### Result Summarization\n\nTruncate large GraphQL responses to fit within LLM context windows:\n\n```typescript\nimport { summarizeResponse, formatForLLM } from 'graphql-agent-toolkit';\n\n// Summarize a large response\nconst { summary, metadata } = summarizeResponse(largeResponse, {\n  maxItems: 5,        // max array items to include\n  maxDepth: 3,        // max nesting depth\n  maxStringLength: 200, // truncate long strings\n  includeMetadata: true, // add _meta with counts\n});\n\nconsole.log(metadata);\n// { totalItems: 1500, truncated: true, originalSize: 48230 }\n\n// Format as clean markdown for LLM context\nconst markdown = formatForLLM(largeResponse, { maxItems: 10 });\nconsole.log(markdown);\n```\n\n### Framework Adapters\n\nGenerate tools for popular AI frameworks -- no framework dependencies required.\n\n#### LangChain\n\n```typescript\nimport { createLangChainTools, createStructuredTools } from 'graphql-agent-toolkit';\n\n// Basic tools (input is JSON string)\nconst tools = createLangChainTools(schema, executor, { maxDepth: 2 });\n\n// Structured tools with Zod schemas (for @langchain/core StructuredTool)\nconst structuredTools = createStructuredTools(schema, executor);\n\nfor (const tool of tools) {\n  console.log(`${tool.name}: ${tool.description}`);\n  // tool.func(jsonString) -\u003e Promise\u003cstring\u003e\n}\n```\n\n#### CrewAI\n\n```typescript\nimport { createCrewAITools } from 'graphql-agent-toolkit';\n\nconst tools = createCrewAITools(schema, executor);\n\nfor (const tool of tools) {\n  console.log(`${tool.name}: ${tool.description}`);\n  // tool.args_schema is a JSON Schema object\n  // tool.func(argsObject) -\u003e Promise\u003cstring\u003e\n}\n```\n\n#### Vercel AI SDK\n\n```typescript\nimport { createVercelAITools } from 'graphql-agent-toolkit';\n\nconst tools = createVercelAITools(schema, executor);\n\n// Returns Record\u003cstring, { description, parameters: ZodSchema, execute }\u003e\n// Use directly with Vercel AI SDK's tool() function\nfor (const [name, tool] of Object.entries(tools)) {\n  console.log(`${name}: ${tool.description}`);\n  // tool.parameters is a Zod schema\n  // tool.execute(args) -\u003e Promise\u003cstring\u003e\n}\n```\n\n### Mock Data Generation\n\nGenerate deterministic mock data from your schema for testing:\n\n```typescript\nimport { generateMockData, createMockExecutor } from 'graphql-agent-toolkit';\n\n// Generate mock data for a specific type\nconst mockUser = generateMockData(schema, 'User', {\n  seed: 42,         // deterministic output\n  arrayLength: 3,   // items per list field\n  maxDepth: 3,      // max recursion depth\n});\nconsole.log(mockUser);\n// { id: 'id_id_0', name: 'mock_name', posts: [...] }\n\n// Create a drop-in mock executor (no HTTP calls)\nconst mockExecutor = createMockExecutor(schema, { seed: 42 });\n\n// Use it anywhere a GraphQLExecutor is expected\nconst result = await mockExecutor.execute(\n  'query { user(id: \"1\") { id name } }',\n  { id: '1' }\n);\n```\n\nUse the `@mock()` directive in field descriptions for custom values:\n\n```graphql\ntype Product {\n  \"The product name @mock(\\\"Widget Pro\\\")\"\n  name: String!\n  \"Current price in USD @mock(29.99)\"\n  price: Float!\n  \"Whether the product is in stock @mock(true)\"\n  inStock: Boolean!\n}\n```\n\n## CLI Usage\n\n### `init` -- Introspect and generate config\n\n```bash\ngraphql-agent-toolkit init \\\n  --endpoint https://your-api.com/graphql \\\n  --header \"Authorization: Bearer YOUR_TOKEN\" \\\n  --output config.json\n```\n\n### `serve` -- Start MCP server\n\n```bash\n# From a config file\ngraphql-agent-toolkit serve --config config.json\n\n# Directly from an endpoint\ngraphql-agent-toolkit serve --endpoint https://your-api.com/graphql\n```\n\n## MCP Server Usage\n\nAdd to your MCP client configuration (e.g., Claude Desktop):\n\n```json\n{\n  \"mcpServers\": {\n    \"my-graphql-api\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"graphql-agent-toolkit\",\n        \"serve\",\n        \"--endpoint\",\n        \"https://your-api.com/graphql\"\n      ]\n    }\n  }\n}\n```\n\n## Configuration\n\nThe `AgentToolkitConfig` object accepts:\n\n| Property | Type | Default | Description |\n|----------|------|---------|-------------|\n| `endpoint` | `string` | (required) | GraphQL endpoint URL |\n| `headers` | `Record\u003cstring, string\u003e` | `{}` | HTTP headers for requests |\n| `operationDepth` | `number` | `2` | Max depth for generated selection sets |\n| `includeDeprecated` | `boolean` | `false` | Include deprecated fields |\n\n## API Reference\n\n### Introspection\n\n- `fetchSchema(options)` -- Fetch introspection query result from a GraphQL endpoint\n- `parseSchema(introspection)` -- Parse raw introspection result into a `ParsedSchema`\n\n### Operations\n\n- `buildOperation(schema, fieldName, options?)` -- Generate a GraphQL operation string with variables\n\n### MCP\n\n- `createAgentToolkitServer(config, options?)` -- Create a fully configured MCP server\n- `createToolsFromSchema(schema, executor, options?)` -- Create tool definitions from a parsed schema\n- `GraphQLExecutor` -- Class for executing GraphQL operations\n\n### Semantic\n\n- `SchemaNavigator` -- Class for indexing and searching a GraphQL schema\n  - `.index(schema)` -- Index a parsed schema\n  - `.search(query, limit?)` -- Search for relevant types\n  - `.getTypeContext(typeName)` -- Get formatted context for a type\n\n### Pagination\n\n- `executePaginated(executor, operation, variables, config?)` -- Execute a paginated query, collecting all pages\n- `detectPaginationStyle(schema, typeName)` -- Auto-detect Relay or offset pagination from a type\n\n### Summarization\n\n- `summarizeResponse(data, config?)` -- Truncate arrays, limit depth, and shorten strings in a response\n- `formatForLLM(data, config?)` -- Format data as clean markdown for LLM context\n\n### Framework Adapters\n\n- `createLangChainTools(schema, executor, options?)` -- Create LangChain-compatible tools (JSON string input)\n- `createStructuredTools(schema, executor, options?)` -- Create LangChain StructuredTool-compatible tools (Zod schemas)\n- `createCrewAITools(schema, executor, options?)` -- Create CrewAI-compatible tools (dict input, `args_schema`)\n- `createVercelAITools(schema, executor, options?)` -- Create Vercel AI SDK-compatible tools (Zod parameters, Record)\n\n### Mock Data\n\n- `generateMockData(schema, typeName, config?)` -- Generate mock data for a given type\n- `createMockExecutor(schema, config?)` -- Create a mock executor as drop-in replacement for GraphQLExecutor\n\n### Types\n\n- `AgentToolkitConfig` -- Configuration object\n- `ParsedSchema` -- Parsed schema with type map\n- `SchemaType` -- Individual type definition\n- `SchemaField` -- Field definition with args\n- `GeneratedOperation` -- Generated operation with variables\n- `SearchResult` -- Semantic search result\n- `SummaryConfig` -- Configuration for response summarization\n- `PaginationConfig` -- Configuration for paginated queries\n- `MockConfig` -- Configuration for mock data generation\n- `LangChainToolConfig` -- LangChain tool definition shape\n- `CrewAIToolConfig` -- CrewAI tool definition shape\n- `VercelAIToolConfig` -- Vercel AI SDK tool definition shape\n\n## Contributing\n\n1. Clone the repository\n2. Install dependencies: `npm install`\n3. Run tests: `npm test`\n4. Build: `npm run build`\n5. Lint: `npm run lint`\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmstuart%2Fgraphql-agent-toolkit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmstuart%2Fgraphql-agent-toolkit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmstuart%2Fgraphql-agent-toolkit/lists"}