星战科技xingzhan.cloud
返回市场
图形查询语言MCP服务器

图形查询语言MCP服务器

作者：ctkadvisors8 星标更新：2025-03-18
安装使用来源：spider==github.com

项目介绍

GraphQL MCP 服务器

一个强类型化的 TypeScript 模型上下文协议（MCP）服务器，通过 Claude AI 提供对任何 GraphQL API 的无缝访问。

特性

  • 强类型化：使用 TypeScript 构建，提高代码质量和类型安全性
  • 动态 GraphQL 集成：自动工具生成连接到任何 GraphQL API
  • 模式内省：自动发现并暴露所有 GraphQL 操作作为工具
  • 全面的变更支持：提供对 GraphQL 变更的一级支持，并正确处理
  • 查询与变更白名单：可选的白名单控制哪些 GraphQL 操作被暴露
  • 丰富的类型支持：正确处理复杂的 GraphQL 类型、输入对象和变量
  • 符合 MCP 标准：遵循模型上下文协议格式，实现与 Claude 的无缝集成
  • 智能查询生成：构建高效的 GraphQL 查询，正确选择字段
  • 认证支持：简单的 API 密钥认证

仓库结构

graphql-mcp/
├── src/
│   └── graphql-mcp-server.ts     # 主服务实现（TypeScript）
├── dist/                         # 编译后的 JavaScript（自动生成）
├── docs/
│   ├── GETTING_STARTED.md         # 设置和使用指南
│   ├── PROJECT_STATUS.md          # 当前项目状态
│   └── TECHNICAL.md               # 技术文档
├── .env.development               # 环境变量
├── .env.sample                    # 环境变量模板样本
├── claude_desktop_sample_config.json  # Claude Desktop 配置样本
├── package.json                   # 项目依赖
├── tsconfig.json                  # TypeScript 配置
├── run-graphql-mcp.sh             # 运行服务的脚本
└── README.md                      # 该文件

先决条件

  • Node.js 18 或更高版本
  • TypeScript 5.x 或更高版本
  • 支持 MCP 的 Claude Desktop
  • 一个 GraphQL API 端点（未指定时默认为国家 API）

安装

方案 1：从 npm 安装

# 全局安装
npm install -g graphql-mcp

# 运行服务
graphql-mcp-server

方案 2：克隆仓库

# 克隆仓库
git clone https://github.com/ctkadvisors/graphql-mcp.git
cd graphql-mcp

# 安装依赖
npm install

# 运行服务
npm start

快速开始

1. 设置环境变量

复制样本环境文件并更新您的 GraphQL API 细节：

cp .env.sample .env.development

编辑 .env.development 文件，添加您的 GraphQL API 端点和可选的 API 密钥。

2. 编译和运行

首先编译 TypeScript 代码：

npm install
npm run build

然后运行服务：

node dist/graphql-mcp-server.js

或者使用提供的脚本一次性编译和运行：

./run-graphql-mcp.sh

3. Claude Desktop 集成

将此服务添加到您的 Claude Desktop 配置中：

  1. 使用样本配置作为模板：

    cp claude_desktop_sample_config.json ~/Library/Application\ Support/Claude/claude_desktop_config.json

  2. 编辑配置并更新路径指向您的安装：

    {
  "mcpServers": {
    "graphql": {
      "command": "node",
      "args": ["/绝对路径到/dist/graphql-mcp-server.js"],
      "env": {
        "GRAPHQL_API_ENDPOINT": "https://您的-graphql-api.com/graphql",
        "GRAPHQL_API_KEY": "需要的-api-key",
        "WHITELISTED_QUERIES": "[\"countries\",\"continent\",\"languages\"]"
      }
    }
  }
}

  3. 重启 Claude Desktop 以连接到服务器

您现在应该在 Claude Desktop 中看到可用的 GraphQL 操作！

操作白名单

出于安全或性能原因，您可能希望限制哪些 GraphQL 操作（查询和变更）暴露给 Claude。有两种方法来控制访问：

  1. 启用/禁用变更：默认情况下，为了安全，所有变更都被禁用。要启用变更：
"env": {
  "GRAPHQL_API_ENDPOINT": "https://示例-graphql-api.com/graphql",
  "ENABLE_MUTATIONS": "true"
}
  1. 操作白名单：您可以指定哪些特定的操作应该是可用的：
"env": {
  "GRAPHQL_API_ENDPOINT": "https://示例-graphql-api.com/graphql",
  "ENABLE_MUTATIONS": "true",
  "WHITELISTED_QUERIES": "[\"countries\",\"continent\",\"languages\"]",
  "WHITELISTED_MUTATIONS": "[\"createUser\",\"updateProfile\"]"
}

白名单可以采用两种格式：

  • 作为 JSON 数组字符串（如上所示）："[\"query1\",\"query2\"]"
  • 逗号分隔的列表："query1,query2,query3"

重要：白名单值必须是字符串，而不是实际的 JSON 数组对象。环境变量总是以字符串形式传递，因此您需要像上面那样正确转义 JSON 字符串中的引号。

Claude Desktop 配置中的正确格式示例：

"graphql-api": {
  "command": "node",
  "args": [
    "/Users/用户名/Projects/graphql-mcp/dist/graphql-mcp-server.js"
  ],
  "env": {
    "GRAPHQL_API_ENDPOINT": "https://示例-graphql-api.com/graphql",
    "NODE_ENV": "development",
    "DEBUG": "true",
    "ENABLE_MUTATIONS": "true",
    "WHITELISTED_QUERIES": "[\"getUser\",\"getProducts\",\"getOrders\"]",
    "WHITELISTED_MUTATIONS": "[\"createOrder\",\"updateProfile\"]"
  }
}

避免的常见错误：

// 错误 - 不会工作！
"WHITELISTED_QUERIES": ["getUser", "getProducts"],
"WHITELISTED_MUTATIONS": ["createOrder", "updateProfile"]

// 正确
"WHITELISTED_QUERIES": "[\"getUser\",\"getProducts\"]",
"WHITELISTED_MUTATIONS": "[\"createOrder\",\"updateProfile\"]"

如果未提供特定操作类型的白名单，则该类型的 GraphQL 模式中的所有操作都将可用。

示例用法

查询数据

一旦连接到 Claude Desktop，您可以使用如下命令：

查看来自 countries 的结果 from graphql (本地){}

或者带有参数：

查看来自 country 的结果 from graphql (本地){
  "code": "US"
}

使用变更

对于变更，工具前面有 mutation_ 前缀以区分它们与查询：

查看来自 mutation_createUser 的结果 from graphql (本地){
  "name": "John Doe",
  "email": "john.doe@example.com"
}

或者一个更复杂的变更：

查看来自 mutation_updateProduct 的结果 from graphql (本地){
  "id": "prod-123",
  "input": {
    "name": "更新的产品名称",
    "price": 29.99,
    "description": "这是一个更新的产品描述"
  }
}

变更遵循与查询相同的模式，但允许您修改 GraphQL API 中的数据。

文档

更多详细信息，请参阅：

开发

要更改服务器：

  1. 修改 TypeScript 源码 src/graphql-mcp-server.ts
  2. 编译 TypeScript 代码：npm run build
  3. 运行编译后的服务器：node dist/graphql-mcp-server.js

发布到 npm

要将此包发布到 npm：

# 确保已登录到 npm
npm login

# 构建项目
npm run build

# 发布到 npm
npm publish

该包将包括 dist 目录中的预构建 JavaScript 文件，使其无需额外构建步骤即可使用。

许可证

该项目根据商业源许可证 1.1（BSL 1.1）许可，允许：

  • 非商业用途：您可以将此软件用于任何非商业目的
  • 内部业务用途：您可以将此软件用于不向第三方提供托管或管理服务的内部业务操作
  • 开源转换：2029 年 3 月 14 日，代码将自动转换为 MIT 许可证

商业用途，包括向他人提供此软件作为服务，需要从 CTK Advisors 获取商业许可证。更多信息，请联系我们或查看完整的 LICENSE 文件。

BSL 许可证旨在平衡开源可用性和可持续商业发展，为所有人提供免费的非商业用途访问，同时保护我们长期支持和增强软件的能力。