Graphql Agent Toolkit

graphql代理工具包

 ](https://www.npmjs.com/package/graphql-agent-toolkit) 

将任何GraphQL API转换为支持AI的工具——MCP服务器、LangChain工具和框架适配器。

graphql代理工具包 内省GraphQL端点，生成类型化操作，并将其作为AI代理可以发现和调用的工具公开。它支持 模型上下文协议（MCP） 开箱即用，因此您可以在几秒钟内将任何兼容MCP的AI客户端连接到任何GraphQL API。

快速开始

npx graphql-agent-toolkit init --endpoint https://your-api.com/graphql

这将反思您的模式并打印配置摘要。要启动MCP服务器，请执行以下操作：

npx graphql-agent-toolkit serve --endpoint https://your-api.com/graphql

安装

npm install graphql-agent-toolkit graphql

需求

• Node.js>=18.0.0
• graphql >=16.0.0（对等依赖）
• TypeScript>=5.0（可选，用于类型定义）

完全用TypeScript编写，所有公共API都有完整的类型导出。

特性

• 图式反思 --自动获取和解析任何GraphQL模式
• 运营建设者 --使用适当的变量定义和嵌套选择集生成查询和突变
• MCP服务器 --创建一个功能齐全的MCP服务器，并为每个查询和变异提供工具
• 语义搜索 --TF-IDF驱动的模式导航器，用于查找相关类型和字段
• 分页处理 --自动检测并处理跨多个页面的中继和偏移分页
• 结果总结 --使用markdown格式截断LLM上下文窗口的大响应
• 框架适配器 --生成零框架依赖的LangChain、CrewAI和Vercel AI SDK工具
• 模拟数据生成 --使用以下命令从模式生成确定性模拟数据 @mock() 指令支持
• 命令行界面 --命令行界面，用于快速设置和服务
• 双格式 --ESM和CJS都带有完整的TypeScript类型

程序化API

反思和分析模式

import { fetchSchema, parseSchema } from 'graphql-agent-toolkit';

const introspection = await fetchSchema({
  endpoint: 'https://your-api.com/graphql',
  headers: { Authorization: 'Bearer YOUR_TOKEN' },
});

const schema = parseSchema(introspection);

console.log(`Query type: ${schema.queryType}`);
console.log(`Types: ${schema.types.size}`);

构建操作

import { fetchSchema, parseSchema, buildOperation } from 'graphql-agent-toolkit';

const introspection = await fetchSchema({ endpoint: 'https://your-api.com/graphql' });
const schema = parseSchema(introspection);

const op = buildOperation(schema, 'user', { maxDepth: 3 });
console.log(op.operation);
// query UserQuery($id: ID!) {
//   user(id: $id) {
//     id
//     name
//     email
//     posts {
//       id
//       title
//     }
//   }
// }
console.log(op.variables);
// [{ name: 'id', type: 'ID!', required: true, description: 'User ID' }]

创建MCP服务器

import { createAgentToolkitServer } from 'graphql-agent-toolkit';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

const server = await createAgentToolkitServer({
  endpoint: 'https://your-api.com/graphql',
  headers: { Authorization: 'Bearer YOUR_TOKEN' },
  operationDepth: 2,
});

const transport = new StdioServerTransport();
await server.connect(transport);

每个查询都变成一个 query_ 工具，每个突变都成为 mutate_ 工具。额外的 explore_schema 该工具允许代理浏览类型和字段。

语义模式导航

import { fetchSchema, parseSchema, SchemaNavigator } from 'graphql-agent-toolkit';

const introspection = await fetchSchema({ endpoint: 'https://your-api.com/graphql' });
const schema = parseSchema(introspection);

const navigator = new SchemaNavigator();
navigator.index(schema);

// Search for relevant types
const results = navigator.search('user authentication');
for (const result of results) {
  console.log(`${result.typeName} (${result.kind}) - score: ${result.score.toFixed(3)}`);
}

// Get detailed context for a type
const context = navigator.getTypeContext('User');
console.log(context);

结果总结

截断大型GraphQL响应以适应LLM上下文窗口：

import { summarizeResponse, formatForLLM } from 'graphql-agent-toolkit';

// Summarize a large response
const { summary, metadata } = summarizeResponse(largeResponse, {
  maxItems: 5,        // max array items to include
  maxDepth: 3,        // max nesting depth
  maxStringLength: 200, // truncate long strings
  includeMetadata: true, // add _meta with counts
});

console.log(metadata);
// { totalItems: 1500, truncated: true, originalSize: 48230 }

// Format as clean markdown for LLM context
const markdown = formatForLLM(largeResponse, { maxItems: 10 });
console.log(markdown);

框架适配器

为流行的AI框架生成工具——不需要框架依赖。

LangChain

import { createLangChainTools, createStructuredTools } from 'graphql-agent-toolkit';

// Basic tools (input is JSON string)
const tools = createLangChainTools(schema, executor, { maxDepth: 2 });

// Structured tools with Zod schemas (for @langchain/core StructuredTool)
const structuredTools = createStructuredTools(schema, executor);

for (const tool of tools) {
  console.log(`${tool.name}: ${tool.description}`);
  // tool.func(jsonString) -> Promise
}

CrewAI

import { createCrewAITools } from 'graphql-agent-toolkit';

const tools = createCrewAITools(schema, executor);

for (const tool of tools) {
  console.log(`${tool.name}: ${tool.description}`);
  // tool.args_schema is a JSON Schema object
  // tool.func(argsObject) -> Promise
}

Vercel AI SDK

import { createVercelAITools } from 'graphql-agent-toolkit';

const tools = createVercelAITools(schema, executor);

// Returns Record
// Use directly with Vercel AI SDK's tool() function
for (const [name, tool] of Object.entries(tools)) {
  console.log(`${name}: ${tool.description}`);
  // tool.parameters is a Zod schema
  // tool.execute(args) -> Promise
}

模拟数据生成

从您的模式生成确定性模拟数据以进行测试：

import { generateMockData, createMockExecutor } from 'graphql-agent-toolkit';

// Generate mock data for a specific type
const mockUser = generateMockData(schema, 'User', {
  seed: 42,         // deterministic output
  arrayLength: 3,   // items per list field
  maxDepth: 3,      // max recursion depth
});
console.log(mockUser);
// { id: 'id_id_0', name: 'mock_name', posts: [...] }

// Create a drop-in mock executor (no HTTP calls)
const mockExecutor = createMockExecutor(schema, { seed: 42 });

// Use it anywhere a GraphQLExecutor is expected
const result = await mockExecutor.execute(
  'query { user(id: "1") { id name } }',
  { id: '1' }
);

使用 @mock() 自定义值字段描述中的指令：

type Product {
  "The product name @mock(\"Widget Pro\")"
  name: String!
  "Current price in USD @mock(29.99)"
  price: Float!
  "Whether the product is in stock @mock(true)"
  inStock: Boolean!
}

CLI使用情况

init --反思并生成配置

graphql-agent-toolkit init \
  --endpoint https://your-api.com/graphql \
  --header "Authorization: Bearer YOUR_TOKEN" \
  --output config.json

serve --启动MCP服务器

# From a config file
graphql-agent-toolkit serve --config config.json

# Directly from an endpoint
graphql-agent-toolkit serve --endpoint https://your-api.com/graphql

MCP服务器使用情况

添加到您的MCP客户端配置中（例如，Claude Desktop）：

{
  "mcpServers": {
    "my-graphql-api": {
      "command": "npx",
      "args": [
        "graphql-agent-toolkit",
        "serve",
        "--endpoint",
        "https://your-api.com/graphql"
      ]
    }
  }
}

配置

这 AgentToolkitConfig 对象接受：

API 参考

内省

• fetchSchema(options) --从GraphQL端点获取自省查询结果
• parseSchema(introspection) --将原始内省结果解析为 ParsedSchema

运营

• buildOperation(schema, fieldName, options?) --生成带有变量的GraphQL操作字符串

主控程序

• createAgentToolkitServer(config, options?) --创建完全配置的MCP服务器
• createToolsFromSchema(schema, executor, options?) --从解析的模式创建工具定义
• GraphQLExecutor --用于执行GraphQL操作的类

语义

• SchemaNavigator --用于索引和搜索GraphQL模式的类

- .index(schema) --为已解析的架构建立索引 - .search(query, limit?) --搜索相关类型 - .getTypeContext(typeName) --获取类型的格式化上下文

分页

• executePaginated(executor, operation, variables, config?) --执行分页查询，收集所有页面
• detectPaginationStyle(schema, typeName) --自动检测类型的中继或偏移分页

摘要

• summarizeResponse(data, config?) --截断数组、限制深度和缩短响应中的字符串
• formatForLLM(data, config?) --将数据格式化为LLM上下文的干净标记

框架适配器

• createLangChainTools(schema, executor, options?) --创建与LangChain兼容的工具（JSON字符串输入）
• createStructuredTools(schema, executor, options?) --创建与LangChain StructuredTool兼容的工具（Zod模式）
• createCrewAITools(schema, executor, options?) --创建CrewAI兼容工具（字典输入， args_schema)
• createVercelAITools(schema, executor, options?) --创建Vercel AI SDK兼容工具（Zod参数，记录）

模拟数据

• generateMockData(schema, typeName, config?) --为给定类型生成模拟数据
• createMockExecutor(schema, config?) --创建一个模拟执行器作为GraphQLExecutor的插入式替换

类型

• AgentToolkitConfig --配置对象
• ParsedSchema --使用类型映射解析模式
• SchemaType --个体类型定义
• SchemaField --带参数的字段定义
• GeneratedOperation --带变量的生成操作
• SearchResult --语义搜索结果
• SummaryConfig --响应汇总配置
• PaginationConfig --分页查询的配置
• MockConfig --模拟数据生成配置
• LangChainToolConfig --LangChain工具定义形状
• CrewAIToolConfig --CrewAI工具定义形状
• VercelAIToolConfig --Vercel AI SDK工具定义形状

贡献

1. 克隆存储库
2. 安装依赖项： npm install
3. 运行测试： npm test
4. 构建： npm run build
5. 棉绒： npm run lint

许可证

麻省理工学院