关键词

GraphQLAI工具API集成函数调用

项目简介

gqai 是一个轻量级代理，它将您的 GraphQL 后端操作（查询和变更）暴露为 Model Context Protocol (MCP) 工具，供大型语言模型（LLM）客户端（如 Claude, Cursor, ChatGPT 等）使用。通过简单的配置文件定义工具，无需编写额外的代码，即可将现有的 GraphQL 服务转化为AI可理解和调用的能力层。

主要功能点

  • GraphQL操作转工具： 直接使用标准的 '.graphql' 文件定义查询和变更，gqai 会自动将它们识别并封装成AI工具。
  • 自动发现工具： 基于 '.graphqlrc.yml' 文件配置的文档路径，gqai 可以自动扫描并发现所有可用的GraphQL操作，生成对应的工具定义。
  • 兼容AI函数调用： 生成的工具定义 metadata 兼容 OpenAI 函数调用及 MCP 规范，方便与主流LLM模型集成。
  • 多种服务模式： 支持通过标准输入输出（Stdio）作为 MCP 服务器运行，也支持 HTTP 服务模式进行测试和集成。

安装步骤

gqai 使用 Go 语言编写，可以通过 Go 命令轻松安装：

go install github.com/fotoetienne/gqai@latest

确保您的 Go 环境已正确配置，并且 '$GOPATH/bin' 或 '$GOBIN' 路径已添加到系统的 PATH 环境变量中，以便可以直接运行 'gqai' 命令。

服务器配置 (供 MCP 客户端使用)

gqai 作为 MCP 服务器运行时，通常通过标准输入输出（Stdio）与 MCP 客户端通信。LLM 客户端（如 Claude Desktop）需要知道如何启动 gqai 服务器进程。这通常在客户端的 MCP 配置文件中指定，例如一个 'mcp.json' 文件。

以下是 MCP 客户端配置 gqai 的关键信息：

  • Server Name: 'gqai' (这是一个标识符，您可以在客户端配置中自定义)
  • Command: 'gqai' (用于启动 gqai 可执行文件的命令)
  • Arguments: 'run', '--config', 后接 '.graphqlrc.yml' 配置文件的路径 (传递给 'gqai' 命令的参数，'run' 启动 MCP 服务器模式，'--config' 指定 GraphQL 配置文件的位置)。

例如，在 MCP 客户端的配置中，您需要添加类似以下内容的配置项（请注意：这里仅说明配置内容，具体格式取决于您的MCP客户端）：

配置项名称 (例如 "gqai") - 启动命令: 'gqai' - 命令参数列表: - 'run' - '--config' - '.graphqlrc.yml' (或其他您的 GraphQL 配置文件的路径)

这个配置告诉 MCP 客户端：要使用名为 "gqai" 的 MCP 服务器，请执行命令 'gqai run --config .graphqlrc.yml'。

基本使用方法

  1. 创建 GraphQL 配置文件: 在您的项目根目录创建 '.graphqlrc.yml' 文件，指定您的 GraphQL API 端点（schema）和存放 GraphQL 操作文件的目录（documents）。 
    schema: https://graphql.org/graphql/  # 您的GraphQL API地址
documents: ./operations              # 存放.graphql文件的目录
  2. 定义 GraphQL 操作: 在 'documents' 指定的目录下创建 '.graphql' 文件，编写您想暴露为工具的查询（query）或变更（mutation）。操作的名称将成为工具的名称。 
    # operations/get_film_by_id.graphql
# 获取指定ID的电影信息
query GetFilm($id: ID!) {
  film(filmID: $id) {
    episodeID
    title
    director
    releaseDate
  }
}
    变量 ('$id: ID!') 会被gqai自动转换为工具的输入参数，并生成对应的 JSON Schema。
  3. 配置 MCP 客户端: 按照上一节“服务器配置”的说明，在您的 MCP 客户端（如 Claude Desktop）的配置文件 ('mcp.json' 等）中添加 gqai 的启动配置。
  4. 运行 MCP 客户端： 启动您的 MCP 客户端。客户端会自动启动 gqai 作为其上下文服务器，并发现定义在 '.graphql' 文件中的工具（例如 'GetFilm'）。
  5. 通过 AI 使用工具： LLM 模型现在可以通过函数调用机制来调用您暴露的 GraphQL 工具，例如根据用户的请求调用 'GetFilm' 工具并提供电影 ID。

您也可以使用 gqai 提供的 CLI 命令进行测试，例如列出工具：

gqai --config .graphqlrc.yml tools/list

或调用工具：

gqai --config .graphqlrc.yml tools/call GetFilm '{"id": "1"}'

信息

分类

AI与计算

访问项目