QuerySculptor

⚒️ QuerySculptor

🚀 面向 AI Agent 的 GraphQL 查询生成工具

一个 MCP 服务，帮助 AI Agent 通过结构化工具而非直接生成原始查询来与 GraphQL API 交互。

QuerySculptor 通过 Model Context Protocol（MCP）提供 26 个工具，让 Agent 能够逐步构建、验证并执行 GraphQL 查询，而不是直接生成完整的查询字符串。

工作原理

传统方式：

• 硬编码查询缺乏灵活性，难以维护
• 直接生成原始 GraphQL 查询容易出错，且语法要求复杂
• Agent 难以应对复杂的架构关系
• 缺少验证会导致运行时故障
• 单体查询必须一次性完整构建

QuerySculptor 方式：

• 通过逐步构建和验证来引导查询构建
• 支持架构感知，可实时进行自省并确保类型安全
• 在构建期间而非执行期间发现问题，防止错误
• 渐进式构建适用于对话式 AI 工作流
• 兼容 MCP 标准，可与 Claude、Cursor 和其他 MCP 客户端配合使用

使用 Claude Sonnet 模型效果最佳；使用其他大模型时，结果可能有所不同。

📖 面向 AI Agent

刚开始使用 QuerySculptor？

• 📋 Agent 系统提示词 - AI Agent 完整指南
• ⚡ 快速参考 - 核心工作流和工具

🎯 问题与解决方案

之前：复杂的 GraphQL 查询生成

# Agent tries to generate this complex query in one go:
query GetUserWithPostsAndComments($userId: ID!, $postLimit: Int = 10) {
  user(id: $userId) {
    id
    name
    email
    posts(first: $postLimit) {
      edges {
        node {
          id
          title
          content
          comments(first: 5) {
            edges {
              node {
                id
                content
                author {
                  name
                }
              }
            }
          }
        }
      }
    }
  }
}

结果： 语法错误、类型错误、字段缺失，开发者苦不堪言

之后：QuerySculptor 方式

// Agent builds this incrementally with guided tools:
1. startQuerySession() 
2. introspectSchema()
3. selectField("user") 
4. setTypedArgument("id", userId)
5. selectField("user.name")
6. selectField("user.posts")
7. setTypedArgument("user.posts", "first", 10)
// ... continue building step by step
8. validateQuery() ✅
9. executeQuery() 🎉

结果： 查询格式正确，语法错误减少，并且内置验证

🌟 功能

🧠 架构自省

• 实时发现架构并了解 API
• 映射复杂架构中的类型关系
• 提供字段级信息，展示可用字段和要求

🔧 引导式查询构建

• 26 个工具分为 7 类
• 适用于 AI 推理工作流的分步构建
• 实时验证，在执行前发现错误
• 支持可复用查询组件的片段

⚡ 架构

• 基于 Redis 的会话支持跨交互持久保存状态
• 通过速率限制保护 API
• 可部署到 Vercel
• 全面的测试覆盖，包括模拟 Agent 工作流的测试
• 修复会话持久化问题，确保内联片段操作可靠

🤝 兼容性

• MCP 标准——可与 Claude Desktop、Cursor 和其他 MCP 客户端配合使用
• 原生 TypeScript，具备完整的类型安全

📋 要求

QuerySculptor 需要 Redis 来管理会话并持久保存查询状态。

Redis 选项：

• Upstash - 无服务器 Redis（推荐用于生产环境）
• 本地 Redis - 用于开发（redis-server）
• Docker Redis - docker run -d -p 6379:6379 redis:alpine
• 任意 Redis 提供商 - AWS ElastiCache、Google Cloud Memorystore 等

🎪 演示与设置

🌍 公开演示

MCP 端点： https://querysculptor.com/mcp

该演示已预先配置为使用 Pokemon API 测试 QuerySculptor 功能。

💬 Query Sculptor Chat Pokemon GraphQL API： QuerySculptor Chat - 使用 QuerySculptor MCP 服务驱动的 Pokemon GraphQL API 进行聊天

🎮 演示：Pokemon API 示例

我们的演示使用 Pokemon API，以下是你可以询问的内容：

发现 Pokemon：

• “显示前 10 个 Pokemon 及其属性类型和精灵图”
• “查找同时具有 Fire 和 Flying 属性类型的所有 Pokemon”
• “Charizard 的属性数据是什么？”

探索特性与招式：

• “列出所有 Pokemon 特性及其效果”
• “Pikachu 可以学会哪些招式？”
• “显示所有 Electric 属性招式及其威力和命中率”

地区与物种数据：

• “列出所有来自 Kanto 地区的 Pokemon”
• “显示 Pokemon 物种及其进化链”
• “有哪些树果可用，它们有什么作用？”

复杂查询：

• “查找拥有危急时刻可提升攻击力的特性的 Pokemon”
• “显示所有传说中的 Pokemon 及其属性类型和基础属性”
• “列出可以学会 Water 和 Ice 招式的 Pokemon”

添加到你的 Cursor mcp.json：

{
  "mcpServers": {
    "graphql-query-builder-demo": {
      "url": "https://querysculptor.com/mcp"
    }
  }
}

🏃‍♂️ 本地设置

# Clone and setup
git clone https://github.com/flinstonedev/querysculptor.git
cd querysculptor
pnpm install

# Configure (copy example.env to .env and customize)
cp example.env .env

# Launch
vercel dev
# 🚀 Your MCP server is live at http://localhost:3000/mcp

要设置自定义端点和 bearer token，请编辑你的 .env 文件：

DEFAULT_GRAPHQL_ENDPOINT=https://your-api.com/graphql
DEFAULT_GRAPHQL_HEADERS={"Authorization": "Bearer your_token"}

🎯 使用场景

🔍 数据发现

“Agent，查找过去一周发布过内容的所有用户，并显示他们最热门的评论。”

Agent 使用 QuerySculptor 来：

1. 检查任何 GraphQL API
2. 构建针对用户、帖子和评论的查询
3. 使用正确的语法和结构执行查询

💬 自然语言转 GraphQL

将聊天机器人转变为能够使用 GraphQL 的 Agent：

• 用户：“显示 $20 以下的近期小说”
• **Agent：**使用 QuerySculptor 工具查询书店 API
• **结果：**无需手动编写查询即可检索结构化数据

📊 自动化报告

创建可生成业务洞察的 Agent：

• 从电商 API 获取销售仪表板数据
• 从社交媒体 API 获取用户互动数据
• 从任何 GraphQL 数据源获取性能指标

🛠️ 开发者工具

• IDE 集成 - 帮助编写查询的 AI 助手
• API 探索 - 发现并了解任何 GraphQL API
• 查询优化 - AI 提供的性能改进建议

🏗️ 可用工具

7 个类别中的 26 个工具：

🔍 架构智能（5 个工具）

• introspect-schema - API 架构理解
• get-root-operation-types - 发现入口点
• get-type-info - 类型分析
• get-field-info - 字段级信息
• get-input-object-help - 输入对象指南

🎯 会话管理（4 个工具）

• start-query-session - 初始化会话
• end-query-session - 清理资源
• get-current-query - 查询可视化
• get-selections - 字段建议

⚡ 字段选择（3 个工具）

• select-field - 选择目标字段
• select-multiple-fields - 批量操作
• select-field-simple - 简单选择

🧬 变量管理（3 个工具）

• set-query-variable - 定义变量
• set-variable-value - 赋值
• remove-query-variable - 移除变量

🎪 参数处理（4 个工具）

• set-string-argument - 处理字符串和枚举
• set-typed-argument - 处理数字、布尔值和复杂类型
• set-input-object-argument - 构建嵌套对象
• set-variable-argument - 引用变量

🎭 片段支持（3 个工具）

• define-named-fragment - 定义可复用的查询组件
• apply-named-fragment - 应用片段
• apply-inline-fragment - 基于类型的条件选择

🔮 指令支持（2 个工具）

• set-field-directive - 字段级指令（@include、@skip）
• set-operation-directive - 操作级指令

✅ 验证与执行（2 个工具）

• validate-query - 验证是否符合架构
• execute-query - 执行查询

🌍 配置

🤝 Claude Desktop 配置

QuerySculptor 通过 mcp-remote 与 Claude Desktop 配合使用。它充当 Claude Desktop 和远程 MCP 服务之间的桥梁。

编辑配置文件：

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

用于远程演示：

{
  "mcpServers": {
    "querysculptor": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://querysculptor.com/mcp"
      ]
    }
  }
}

用于本地开发：

{
  "mcpServers": {
    "querysculptor-local": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:3000/mcp",
        "--allow-http"
      ]
    }
  }
}

要设置自定义端点和 bearer token，请在配置中添加 env：

{
  "mcpServers": {
    "querysculptor": {
      "command": "npx",
      "args": ["mcp-remote", "https://your-querysculptor.vercel.app/mcp"],
      "env": {
        "DEFAULT_GRAPHQL_ENDPOINT": "https://your-api.com/graphql",
        "DEFAULT_GRAPHQL_HEADERS": "{\"Authorization\": \"Bearer your_token\"}"
      }
    }
  }
}

🔍 故障排除

如果遇到问题：

1. 清除 mcp-remote 缓存：

   rm -rf ~/.mcp-auth
   

2. 查看日志：

   • macOS/Linux：tail -n 20 -F ~/Library/Logs/Claude/mcp*.log
   • Windows：Get-Content "C:\Users\YourUsername\AppData\Local\Claude\Logs\mcp.log" -Wait -Tail 20

3. 配置更改后，完全重启 Claude Desktop

🚀 随处部署

⚡ Vercel（推荐）

一键部署：

部署后，在 Vercel 控制面板中配置以下环境变量：

• REDIS_URL - Redis 连接字符串
• DEFAULT_GRAPHQL_ENDPOINT - GraphQL API 端点（可选）
• DEFAULT_GRAPHQL_HEADERS - 用于身份验证的标头 JSON 字符串（可选）

手动部署：

# Clone and deploy
git clone https://github.com/flinstonedev/querysculptor.git
cd querysculptor
vercel --prod

在 Vercel 控制面板中配置环境变量。

要设置自定义端点和 bearer token，请将以下变量添加到 Vercel 环境变量中：

DEFAULT_GRAPHQL_ENDPOINT=https://your-api.com/graphql
DEFAULT_GRAPHQL_HEADERS={"Authorization": "Bearer your_token"}

🧪 测试

QuerySculptor 包含全面的测试框架：

标准测试

pnpm test            # Run all tests
pnpm test:watch      # Watch mode
pnpm test:coverage   # Coverage report

类 Agent 测试

像 AI Agent 使用工具那样进行测试：

pnpm test:agent                  # Run all agent workflow tests
pnpm test:agent:basic           # Basic workflow tests
pnpm test:agent:debug           # Debug mode with detailed output
pnpm test:agent:errors          # Error scenario tests

Agent 测试框架：

• ✅ 真实 MCP 协议：通过实际的 MCP 通信层进行测试
• ✅ 会话持久性：验证由 Redis 支持的会话管理
• ✅ 工作流模拟：执行真实的多步骤 Agent 工作流
• ✅ 错误恢复：测试常见故障模式和恢复方案
• ✅ 调试工具：提供详细的分析和调试功能

增强的会话安全性

• 会话 ID 验证可防止注入攻击
• 正确处理并规范化空白字符
• 为无效会话格式提供清晰的错误消息
• 向后兼容现有实现

📈 路线图

• 添加适当的日志记录 - 用于调试和监控的结构化日志
• 查询优化 AI - 自动提升性能
• 可视化查询构建器 - 用于构建查询的 Web UI
• 增强 Agent 测试 - 扩大 Agent 工作流测试覆盖范围

🌟 欢迎社区贡献

• 改进文档 - 帮助他人了解项目
• 增强工具 - 添加新功能
• 客户端集成 - 支持更多 MCP 客户端
• 性能优化 - 提升性能
• Agent 测试场景 - 添加更多真实场景下的工作流测试