Text-to-GraphQL MCP Server

文本到GraphQL MCP服务器

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


Claude Demo

🚀 概述

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

✨ 特性

• 从自然语言到GraphQL：将纯英语查询转换为有效的GraphQL
• 模式管理：自动加载和自检GraphQL架构
• 查询验证：根据加载的架构验证生成的查询
• 查询执行：使用身份验证对GraphQL端点执行查询
• 查询历史：跨会话跟踪和管理查询历史记录
• MCP协议：与Claude Desktop、Cursor和其他MCP客户端完全兼容
• 错误处理：优雅的错误处理，包含详细的调试信息
• 缓存：为模式和常用查询内置缓存

🛠 安装

先决条件：安装UV（推荐）

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

macOS/Linux：

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

窗户：

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

查找您的UV安装路径：

# Find where uv is installed
which uv

# Common locations:
# macOS/Linux: ~/.local/bin/uv
# Windows: %APPDATA%\uv\bin\uv.exe

重要：您需要MCP配置的UV路径。典型的路径是 ~/.local/bin 在macOS/Linux上，翻译为 /Users/yourusername/.local/bin （替换 yourusername 使用您的实际用户名）。

MCP使用设置

# Clone the repository
git clone https://github.com/Arize-ai/text-to-graphql-mcp.git
cd text-to-graphql-mcp

# Install dependencies (UV automatically creates virtual environment)
uv sync

# Test the installation
uv run text-to-graphql-mcp --help

备注：The uv run 模式自动处理虚拟环境，使MCP配置比传统pip安装更清晰、更可靠。

替代安装方法

来自PyPI（发布时）：

pip install text-to-graphql-mcp

开发设置：

# For contributing to the project
uv sync --dev

🏃‍♂️ 快速开始

1.使用游标配置（推荐）

添加到您的 .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安装路径（通常 /Users/yourusername/.local/bin 在macOS上） - 这 PATH 环境变量为 必需的 让MCP客户端找到 uv 命令

2.使用Claude Desktop进行配置

添加到您的Claude Desktop MCP配置文件中：

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json 窗户： %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"
      }
    }
  }
}

安装说明： 1. 找到你的紫外线路径：运行 which uv 在终端（通常 /Users/yourusername/.local/bin/uv) 1. 设置路径：使用包含以下内容的目录 uv （例如。， /Users/yourusername/.local/bin) 1. 替换路径：更新两者 --directory 论证和 PATH 环境变量与实际路径 1. 添加API密钥：将占位符值替换为实际的API键

3.常见UV路径示例

# Find your UV installation
which uv

# Common paths by OS:
# macOS: /Users/yourusername/.local/bin/uv
# Linux: /home/yourusername/.local/bin/uv  
# Windows: C:\Users\yourusername\AppData\Roaming\uv\bin\uv.exe

# For MCP config, use the directory path:
# macOS: /Users/yourusername/.local/bin
# Linux: /home/yourusername/.local/bin
# Windows: C:\Users\yourusername\AppData\Roaming\uv\bin

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

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

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

# Optional - Authentication method (bearer|apikey|direct)
GRAPHQL_AUTH_TYPE=bearer

# Optional - Model settings
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服务器（可选-用于测试）

# Run the server directly for testing
text-to-graphql-mcp

# Or run as a module
python -m text_to_graphql_mcp.mcp_server

🔧 用法

可用的MCP工具

generate_graphql_query

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

Input: "Get all users with their names and emails"
Output: query { users { id name email } }

validate_graphql_query

根据加载的架构验证GraphQL查询。

execute_graphql_query

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

get_query_history

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

get_query_examples

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

交互示例

自然语言输入：

"Show me all blog posts from the last week with their authors and comment counts"

生成的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镜像

# Clone the repository
git clone https://github.com/Arize-ai/text-to-graphql-mcp.git
cd text-to-graphql-mcp

# Build the Docker image
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  # Important: bind to all interfaces in container
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
      interval: 30s
      timeout: 10s
      retries: 3

然后运行：

# Start the service
docker-compose up -d

# View logs
docker-compose logs -f

# Stop the service
docker-compose down

在MCP客户端上使用Docker

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

重要：当您 首先运行容器 使用上述方法之一。下面的MCP客户端配置仅连接到已运行的容器。

步骤1：首先，确保您的容器正在使用环境变量运行

# Example: Make sure the container is running with your environment variables
docker run -d \
  --name text-to-graphql-mcp \
  -p 8000:8000 \
  --env-file .env \
  text-to-graphql-mcp

# Verify the container is running
docker ps | grep text-to-graphql-mcp

步骤2：配置游标

增添 .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"
    ]
  }
}

步骤2：配置Claude桌面

添加到您的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构建的多代理架构：

1. 意图识别：了解用户想要实现的目标
2. 模式管理：加载和管理GraphQL架构信息
3. 查询构造：从自然语言构建GraphQL查询
4. 查询验证：确保查询对架构有效
5. 查询执行：对GraphQL端点执行查询
6. 数据可视化：为可视化结果提供建议

⚙️ 配置

环境变量

身份验证类型

• bearer （默认）：使用 Authorization: Bearer -大多数GraphQL API的标准
• apikey：用途 X-API-Key: -由Arize等API使用
• direct：用途 Authorization: -不带承载前缀的直接令牌
• 自定义：设置 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
# Auth type auto-detected for Arize

Hasura：

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

🔍 可观察性和代理开发

想要快速构建更好的AI代理吗？结账 干旱凤凰 -一个专门为LLM应用程序和代理设计的开源可观察性平台。Phoenix提供：

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

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

• 查询未正确生成时的调试代理行为
• 监控GraphQL查询质量和成功率
• 跟踪用户满意度和查询复杂性
• 优化代理的快速工程

开始使用Phoenix：

pip install arize-phoenix
phoenix serve

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

🧪 发展

设置开发环境

# Install development dependencies
uv pip install -e ".[dev]"

# Run tests
pytest

# Format code
black .
isort .

# Type checking
mypy src/

项目结构

text-to-graphql-mcp/
├── src/text_to_graphql_mcp/     # Main package
│   ├── mcp_server.py            # MCP server implementation
│   ├── agent.py                 # LangGraph agent logic
│   ├── config.py                # Configuration management
│   ├── logger.py                # Logging utilities
│   ├── tools/                   # Agent tools
│   └── ...
├── tests/                       # Test suite
├── docs/                        # Documentation
├── pyproject.toml              # Package configuration
└── README.md

🤝 贡献

我们欢迎捐款！请参阅我们的投稿指南以了解详细信息。

1. 分叉存储库
2. 创建要素分支(git checkout -b feature/amazing-feature)
3. 提交您的更改(git commit -m 'Add some amazing feature')
4. 推到分支(git push origin feature/amazing-feature)
5. 打开拉取请求

📝 许可证

此项目根据弹性许可证2.0（ELv2）获得许可-请参阅 许可证 文件以获取详细信息。

🐛 故障排除

常见问题

“没有名为'text_to_graphql_mcp'的模块”

• 确保您已安装该软件包： pip install text-to-graphql-mcp

“找不到OpenAI API密钥”

• 设置您的 OPENAI_API_KEY 环境变量
• 检查你的 .env 文件配置

“无法访问GraphQL终结点”

• 验证您的 GRAPHQL_ENDPOINT 统一资源定位符
• 检查网络连接和身份验证

“架构自检失败”

• 确保GraphQL端点支持自检
• 如果需要，请检查身份验证标头

🔗 链接

• 问题和Bug报告
• MCP协议文件

🙏 致谢

• 用途 FastMCP 用于MCP服务器实现

______________________________________________________________________