文本到GraphQL MCP

Name: 文本到GraphQL MCP
Author: Arize-ai

作者：Arize-ai20 星标更新：2025-07-02

安装使用来源：spider==github.com

项目介绍

文本到GraphQL MCP服务器

使用MCP（模型上下文协议）服务器将自然语言查询转换为GraphQL查询，该服务器可以无缝集成到AI助手如Claude Desktop和Cursor中。

Claude演示

🚀 概述

Text-to-GraphQL MCP服务器使用LangGraph构建的AI代理将自然语言描述转换为有效的GraphQL查询。它在人类语言和GraphQL API之间提供了一个桥梁，使数据库和API交互对开发人员和非技术人员都更加直观。

✨ 特性

自然语言到GraphQL: 将纯英文查询转换为有效的GraphQL
模式管理: 自动加载和检查GraphQL模式
查询验证: 根据加载的模式验证生成的查询
查询执行: 对GraphQL端点进行认证后执行查询
查询历史: 跨会话跟踪和管理查询历史
MCP协议: 完全兼容Claude Desktop、Cursor和其他MCP客户端
错误处理: 具有详细调试信息的优雅错误处理
缓存: 内置模式和常用查询的缓存

🛠 安装

预备条件：安装UV（推荐）

UV是一个快速的Python包安装器和解析器。首先安装它：

macOS/Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows:

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

找到你的UV安装路径:

# 找到UV安装的位置
which uv

# 常见位置:
# macOS/Linux: ~/.local/bin/uv
# Windows: %APPDATA%\uv\bin\uv.exe

重要: 你需要UV路径来配置MCP。典型的路径是macOS/Linux上的~/.local/bin，这对应于/Users/yourusername/.local/bin（用你的实际用户名替换yourusername）。

设置以供MCP使用

# 克隆仓库
git clone https://github.com/Arize-ai/text-to-graphql-mcp.git
cd text-to-graphql-mcp

# 安装依赖项（UV自动创建虚拟环境）
uv sync

# 测试安装
uv run text-to-graphql-mcp --help

注意: uv run模式自动处理虚拟环境，使得MCP配置比传统的pip安装更干净、可靠。

替代安装方法

从PyPI安装（当发布时）:

pip install text-to-graphql-mcp

开发设置:

# 为项目贡献
uv sync --dev

🏃‍♂️ 快速开始

1. 使用Cursor配置（推荐）

添加到你的.cursor/mcp.json:

{
  "text-to-graphql": {
    "command": "uv",
    "args": [
      "--directory",
      "/path/to/text-to-graphql-mcp",
      "run",
      "text-to-graphql-mcp"
    ],
    "env": {
      "PATH": "/path/to/uv/bin:/usr/bin:/bin",
      "OPENAI_API_KEY": "your_openai_api_key_here",
      "GRAPHQL_ENDPOINT": "https://your-graphql-api.com/graphql",
      "GRAPHQL_API_KEY": "your_api_key_here",
      "GRAPHQL_AUTH_TYPE": "bearer"
    }
  }
}

重要设置说明:

将/path/to/text-to-graphql-mcp替换为你克隆的仓库的实际路径

将/path/to/uv/bin替换为你的实际UV安装路径（通常在macOS上为/Users/yourusername/.local/bin）

PATH环境变量是必需的，以便MCP客户端能够找到uv命令

2. 使用Claude Desktop配置

添加到你的Claude Desktop MCP配置文件:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "text-to-graphql": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/text-to-graphql-mcp",
        "run",
        "text-to-graphql-mcp"
      ],
      "env": {
        "PATH": "/path/to/uv/bin:/usr/bin:/bin",
        "OPENAI_API_KEY": "your_openai_api_key_here",
        "GRAPHQL_ENDPOINT": "https://your-graphql-api.com/graphql",
        "GRAPHQL_API_KEY": "your_api_key_here",
        "GRAPHQL_AUTH_TYPE": "bearer"
      }
    }
  }
}

设置说明:

找到你的UV路径: 在终端运行which uv（通常为/Users/yourusername/.local/bin/uv）

设置PATH: 使用包含uv的目录（例如/Users/yourusername/.local/bin）

替换路径: 更新--directory参数和PATH环境变量的实际路径

添加你的API密钥: 将占位符值替换为你的实际API密钥

3. 常见UV路径示例

# 查找你的UV安装
which uv

# 不同操作系统的常见路径:
# macOS: /Users/yourusername/.local/bin/uv
# Linux: /home/yourusername/.local/bin/uv  
# Windows: C:\Users\yourusername\AppData\Roaming\uv\bin\uv.exe

# 对于MCP配置，使用目录路径:
# macOS: /Users/yourusername/.local/bin
# Linux: /home/yourusername/.local/bin
# Windows: C:\Users\yourusername\AppData\Roaming\uv\bin

4. 替代方案：使用环境变量

如果你更喜欢使用.env文件（适用于本地开发）：

# 必需
OPENAI_API_KEY=your_openai_api_key_here
GRAPHQL_ENDPOINT=https://your-graphql-api.com/graphql
GRAPHQL_API_KEY=your_api_key_here

# 可选 - 认证方式（bearer|apikey|direct）
GRAPHQL_AUTH_TYPE=bearer

# 可选 - 模型设置
MODEL_NAME=gpt-4o
MODEL_TEMPERATURE=0

然后使用简化的MCP配置（仍然需要PATH）：

{
  "text-to-graphql": {
    "command": "uv",
    "args": [
      "--directory",
      "/path/to/text-to-graphql-mcp",
      "run",
      "text-to-graphql-mcp"
    ],
    "env": {
      "PATH": "/path/to/uv/bin:/usr/bin:/bin"
    }
  }
}

5. 运行MCP服务器（可选 - 用于测试）

# 直接运行服务器进行测试
text-to-graphql-mcp

# 或者作为模块运行
python -m text_to_graphql_mcp.mcp_server

🔧 使用

可用的MCP工具

`generate_graphql_query`

将自然语言转换为GraphQL查询。

输入: "获取所有用户及其姓名和电子邮件"
输出: query { users { id name email } }

`validate_graphql_query`

根据加载的模式验证GraphQL查询。

`execute_graphql_query`

执行GraphQL查询并返回格式化的结果。

`get_query_history`

检索当前会话中所有查询的历史记录。

`get_query_examples`

获取示例查询以了解系统的功能。

示例交互

自然语言输入:

"显示我过去一周的所有博客文章及其作者和评论数量"

生成的GraphQL:

query {
  posts(where: { createdAt: { gte: "2024-06-05T00:00:00Z" } }) {
    id
    title
    content
    createdAt
    author {
      id
      name
      email
    }
    comments {
      id
    }
    _count {
      comments
    }
  }
}

🐳 使用Docker部署

💡 关键概念: 当使用Docker与MCP客户端（Claude/Cursor）一起使用时，环境变量是在容器启动时（docker run）设置的，而不是在MCP客户端配置中设置。MCP客户端只是连接到已经运行的容器。

构建Docker镜像

# 克隆仓库
git clone https://github.com/Arize-ai/text-to-graphql-mcp.git
cd text-to-graphql-mcp

# 构建Docker镜像
docker build -t text-to-graphql-mcp .

运行容器

方法1：直接使用环境变量

docker run -d \
  --name text-to-graphql-mcp \
  -p 8000:8000 \
  -e OPENAI_API_KEY="your_openai_api_key_here" \
  -e GRAPHQL_ENDPOINT="https://your-graphql-api.com/graphql" \
  -e GRAPHQL_API_KEY="your_api_key_here" \
  -e GRAPHQL_AUTH_TYPE="bearer" \
  -e MODEL_NAME="gpt-4o" \
  text-to-graphql-mcp

方法2：使用环境文件

创建一个.env文件：

OPENAI_API_KEY=your_openai_api_key_here
GRAPHQL_ENDPOINT=https://your-graphql-api.com/graphql
GRAPHQL_API_KEY=your_api_key_here
GRAPHQL_AUTH_TYPE=bearer
MODEL_NAME=gpt-4o
MODEL_TEMPERATURE=0

运行容器：

docker run -d \
  --name text-to-graphql-mcp \
  -p  8000:8000 \
  --env-file .env \
  text-to-graphql-mcp

方法3：使用Docker Compose

创建一个docker-compose.yml文件：

version: '3.8'

services:
  text-to-graphql-mcp:
    build: .
    container_name: text-to-graphql-mcp
    ports:
      - "8000:8000"
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - GRAPHQL_ENDPOINT=${GRAPHQL_ENDPOINT}
      - GRAPHQL_API_KEY=${GRAPHQL_API_KEY}
      - GRAPHQL_AUTH_TYPE=${GRAPHQL_AUTH_TYPE:-bearer}
      - MODEL_NAME=${MODEL_NAME:-gpt-4o}
      - MODEL_TEMPERATURE=${MODEL_TEMPERATURE:-0}
      - API_HOST=0.0.0.0  # 重要：绑定到容器中的所有接口
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
      interval: 30s
      timeout: 10s
      retries: 3

然后运行：

# 启动服务
docker-compose up -d

# 查看日志
docker-compose logs -f

# 停止服务
docker-compose down

使用Docker与MCP客户端

当你在Docker中运行MCP服务器时，你需要使用docker exec与容器通信：

重要: 环境变量（OPENAI_API_KEY, GRAPHQL_ENDPOINT等）必须在你第一次运行容器时使用上述方法之一设置。下面的MCP客户端配置仅连接到已运行的容器。

第一步：确保你的容器正在运行，并带有环境变量

# 示例：确保容器正在运行并带有你的环境变量
docker run -d \
  --name text-to-graphql-mcp \
  -p 8000:8000 \
  --env-file .env \
  text-to-graphql-mcp

# 验证容器是否正在运行
docker ps | grep text-to-graphql-mcp

第二步：配置Cursor

添加到.cursor/mcp.json:

{
  "text-to-graphql": {
    "command": "docker",
    "args": [
      "exec",
      "-i",
      "text-to-graphql-mcp",
      "uv",
      "run",
      "python",
      "-m",
      "src.text_to_graphql_mcp.mcp_server"
    ]
  }
}

第二步：配置Claude Desktop

添加到你的Claude Desktop配置:

{
  "mcpServers": {
    "text-to-graphql": {
      "command": "docker",
      "args": [
        "exec",
        "-i",
        "text-to-graphql-mcp",
        "uv",
        "run",
        "python",
        "-m",
        "src.text_to_graphql_mcp.mcp_server"
      ]
    }
  }
}

注意: MCP客户端配置不需要环境变量，因为它们连接到已经设置了这些变量的容器。如果你重启容器，请确保再次包含环境变量。

🏗 架构

系统使用由LangGraph构建的多代理架构：

意图识别: 理解用户想要完成的任务
模式管理: 加载和管理GraphQL模式信息
查询构造: 从自然语言构建GraphQL查询
查询验证: 确保查询符合模式
查询执行: 对GraphQL端点执行查询
数据可视化: 提供结果可视化的建议

⚙️ 配置

环境变量

变量	描述	默认值
`OPENAI_API_KEY`	OpenAI API密钥用于LLM操作	必需
`GRAPHQL_ENDPOINT`	GraphQL API端点URL	必需
`GRAPHQL_API_KEY`	你的GraphQL服务的API密钥	必需
`GRAPHQL_AUTH_TYPE`	认证方法：`bearer`，`apikey`或`direct`	`bearer`
`GRAPHQL_HEADERS`	自定义头部作为JSON（覆盖自动认证）	`{}`
`MODEL_NAME`	要使用的OpenAI模型	`gpt-4o`
`MODEL_TEMPERATURE`	模型响应的温度	`0`
`API_HOST`	服务器主机地址	`127.0.0.1`
`API_PORT`	服务器端口	`8000`
`RECURSION_LIMIT`	代理工作流的最大递归	`10`

认证类型

bearer（默认）: 使用Authorization: Bearer <token> - 大多数GraphQL API的标准
apikey: 使用X-API-Key: <key> - 一些API如Arize使用
direct: 使用Authorization: <token> - 直接令牌，没有Bearer前缀
自定义: 设置GRAPHQL_HEADERS以覆盖任何自定义认证格式

常见GraphQL API示例

GitHub GraphQL API:

GRAPHQL_ENDPOINT=https://api.github.com/graphql
GRAPHQL_API_KEY=ghp_your_github_personal_access_token
GRAPHQL_AUTH_TYPE=bearer

Shopify GraphQL API:

GRAPHQL_ENDPOINT=https://your-shop.myshopify.com/admin/api/2023-10/graphql.json
GRAPHQL_API_KEY=your_shopify_access_token
GRAPHQL_AUTH_TYPE=bearer

Arize GraphQL API:

GRAPHQL_ENDPOINT=https://app.arize.com/graphql
GRAPHQL_API_KEY=your_arize_developer_api_key
# Arize的认证类型自动检测

Hasura:

GRAPHQL_ENDPOINT=https://your-app.hasura.app/v1/graphql
GRAPHQL_HEADERS={"x-hasura-admin-secret": "your_admin_secret"}

🔍 可观察性和代理开发

想快速构建更好的AI代理吗？查看**Arize Phoenix** - 一个专门为LLM应用和代理设计的开源可观察性平台。Phoenix提供了：

实时监控你的代理性能和行为
追踪可视化以理解复杂的代理工作流程
评估框架用于测试和改进代理响应
数据质量洞察以识别训练数据的问题
成本跟踪优化LLM API使用

Phoenix与LangChain和LangGraph（此项目使用）无缝集成，可以帮助你：

调试查询生成不正确的代理行为
监控GraphQL查询质量和成功率
跟踪用户满意度和查询复杂度
优化代理的提示工程

开始使用Phoenix:

pip install arize-phoenix
phoenix serve

访问docs.arize.com/phoenix以获得关于代理可观察性和开发最佳实践的全面指南。