GraphQL模式探索工具

MCP服务器是一个为GraphQL API提供智能内省和探索能力的服务,适用于开发者在Cursor IDE和MCP客户端中进行GraphQL模式的高效探索与查询构建。

  • by martinshumberto
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 martinshumberto/mcp-server-graphql

使用说明

MCP服务器文档

MCP(模型通信协议)服务器是一种为任何GraphQL API提供智能内省和探索功能的服务。本文档将指导您如何将MCP服务器与Cursor IDE和MCP客户端一起使用。

概述

MCP服务器提供了一个强大的接口,可以通过一组高级工具访问和探索GraphQL模式。它反思任何GraphQL模式,并提供有关以下内容的结构化、可搜索的信息:

  • 类型
  • 查询
  • 突变
  • 输入类型

特性

1.智能模式搜索

MCP服务器包含一个高级搜索系统,可帮助您在GraphQL模式中准确找到所需内容:

  • 拼写公差的模糊匹配
  • 多词搜索支持
  • 基于相关性的结果
  • 上下文感知搜索
  • 现场级搜索功能

2.类型探索

详细的类型信息,包括:

  • 现场列表
  • 相关类型
  • 文档
  • 使用示例

3.查询/突变发现

轻松探索可用操作:

  • 按类别分组
  • 详细参数信息
  • 退货类型详细信息
  • 使用上下文

设置

  1. 安装依赖项:
yarn install
  1. 在MCP服务器中配置GraphQL端点:
const GRAPHQL_ENDPOINT = "http://your-graphql-endpoint/graphql";
  1. 配置游标IDE: 创建或更新 .cursor/mcp.json 在您的项目中:
{
  "mcpServers": {
    "cw-core": {
      "command": "node",
      "args": [
        "/Users/martinshumberto/repositories/cw-mcp-server/build/main.js",
        "--debug"
      ],
      "transport": "stdio"
    }
  }
}

可用工具

1.模式工具

// Get complete schema information
{
  "title": "GraphQL Schema",
  "description": "Full introspection of GraphQL schema"
}

2.搜索工具

// Advanced search across schema elements
{
  "title": "Search Schema",
  "description": "Advanced search across all GraphQL schema elements",
  "parameters": {
    "searchTerm": "Search term - supports multiple words and partial matches",
    "threshold": "Optional similarity threshold (0-1, default: 0.3)"
  }
}

3.类型工具

// Get specific type information
{
  "title": "GraphQL Types",
  "description": "Get fields from a specific GraphQL type",
  "parameters": {
    "typeName": "Name of the GraphQL type to inspect"
  }
}

4.现场工具

// Get detailed field information
{
  "title": "Field Details",
  "description": "Get detailed information about a specific field in a type",
  "parameters": {
    "typeName": "Name of the GraphQL type containing the field",
    "fieldName": "Name of the field to inspect"
  }
}

5.相关类型工具

// Find related types
{
  "title": "Related Types",
  "description": "Find types that are related to a specific type",
  "parameters": {
    "typeName": "Name of the GraphQL type to find relations for"
  }
}

与Cursor IDE一起使用

1.搜索示例

基本搜索:

{
  "searchTerm": "user"
}

多词搜索:

{
  "searchTerm": "create user profile"
}

具有自定义阈值的模糊搜索:

{
  "searchTerm": "user",
  "threshold": 0.5
}

2.类型探索

// Get type details
const typeInfo = await getType("User");

// Find related types
const relatedTypes = await findRelatedTypes("User");

// Get field details
const fieldInfo = await getFieldDetails("User", "profile");

Cursor AI集成功能

  1. 自动完成方案

    • Cursor AI将自动为您的GraphQL类型和字段提供智能代码补全
    • 示例:键入GraphQL查询时,按Ctrl+Space查看可用字段
  2. 型式检验

    • 将鼠标悬停在任何GraphQL类型上以查看其完整定义
    • 使用Command+Click(Mac)或Ctrl+Click(Windows)跳转到类型定义
  3. 查询构建

    • 类型 query 或 mutation 根据您的模式获得智能建议
    • Cursor AI将建议有效的字段和参数

使用Cursor AI的示例用法

  1. 创建查询
// Start typing and Cursor AI will suggest available queries
const userQuery = `
  query Get
`
// After typing "Get", Cursor AI will suggest queries like "GetUser", "GetProfile", etc.
  1. 建筑突变
// Cursor AI will suggest available mutation fields and their required arguments
const createUserMutation = `
  mutation Create
`
// After typing "Create", you'll get suggestions like "CreateUser", "CreatePost", etc.

光标AI命令

通过命令面板(Cmd/Ctrl+Shift+P)访问这些功能:

  1. MCP:显示架构

    • 在侧面板中显示完整的GraphQL架构
    • 可用于探索可用类型和操作
  2. MCP:生成查询

    • 帮助您使用正确的类型构建GraphQL查询
    • 根据您的模式建议字段
  3. MCP:生成类型

    • 从GraphQL类型创建TypeScript接口
    • 维护前端和API之间的类型安全

键盘快捷键

操作 Mac Windows/Linux
显示架构 Cmd+Shift+S Ctrl+Shift+S
生成查询 Cmd+Shift+Q Ctrl+Shift+Q
生成类型 Cmd+Shift+T Ctrl+Shift+T
跳转到定义 Cmd+单击 Ctrl+单击
显示悬停信息 选项+悬停 Alt+悬停

最佳实践

  1. 高效搜索

    • 使用特定的搜索词
    • 利用多词搜索以获得更好的上下文
    • 调整搜索精度阈值
  2. 类型探索

    • 从高级类型开始
    • 使用相关类型来理解连接
    • 深入了解现场细节
  3. 演出

    • 缓存频繁使用的架构信息
    • 尽可能使用特定工具而不是完整模式
    • 实施适当的错误处理

错误处理

MCP服务器提供详细的错误信息:

try {
  const result = await searchSchema("user");
} catch (error) {
  if (error.message.includes("not found")) {
    // Handle not found case
  } else {
    // Handle other errors
  }
}

贡献

您可以通过以下方式为MCP服务器做出贡献:

  1. 报告问题
  2. 建议新功能
  3. 提交拉取请求

许可证

此项目根据MIT许可证获得许可-有关详细信息,请参阅许可证文件。