关键词

GraphQLAPI 工具LLM 集成AI 函数调用数据上下文

项目简介

Apollo MCP 服务器是一个实现了 Model Context Protocol (MCP) 的应用后端。它的主要目的是将现有的 GraphQL API 转换为可供兼容 MCP 的大型语言模型客户端直接调用和交互的工具。通过将 GraphQL 操作暴露为结构化的 MCP 工具，LLM 能够理解如何访问和利用这些 API 提供的功能和数据。

主要功能点

  • GraphQL 操作转化为 MCP 工具： 自动或通过配置将 GraphQL 查询、Mutation 等操作定义为 MCP 工具。
  • 支持多种操作源： 可以从本地 '.graphql' 文件、Apollo Persisted Queries Manifest 文件或直接从 Apollo GraphOS Uplink 加载 GraphQL 操作。
  • 支持多种 Schema 源： 可以从本地 Schema 文件或 Apollo GraphOS Uplink 获取 GraphQL Schema。
  • 生成工具描述和输入 Schema： 根据 GraphQL Schema 和操作定义，自动生成工具的自然语言描述和 JSON Schema 格式的输入规范，帮助 LLM 理解如何使用工具。
  • 执行 GraphQL 操作： 作为 MCP 工具的执行后端，接收 LLM 发送的工具调用请求，将其转化为对指定 GraphQL Endpoint 的 HTTP 请求，并返回结果。
  • 支持多种传输协议： 支持通过标准输入/输出 (Stdio) 或 HTTP+Server-Sent Events (SSE) 与 MCP 客户端通信。
  • 会话管理和能力声明： 实现 MCP 服务器端逻辑，管理与客户端的会话，并声明服务器支持的能力（如工具列表）。
  • 可选的内置工具： 可选择暴露 'schema' 工具（返回 GraphQL Schema）、'execute' 工具（允许 LLM 根据 Schema 自行构建和执行 GraphQL 查询）和 'explorer' 工具（在 Apollo Explorer 中打开查询）。
  • 热重载： 支持对本地文件 Schema 和 Persisted Query Manifest 的热重载。

安装步骤

该服务器使用 Rust 语言编写。您需要先安装 Rust 开发环境和 Cargo 构建工具。

  1. 克隆仓库： 
    git clone https://github.com/apollographql/apollo-mcp-server.git
cd apollo-mcp-server
  2. 构建项目： 
    cargo build --release
    构建成功后，可执行文件将在 'target/release/mcp-apollo-server' 路径下生成。您也可以使用 Docker 容器运行。

服务器配置（面向 MCP 客户端）

Apollo MCP 服务器本身通过命令行参数启动。您需要在您的 MCP 客户端（例如 Claude Desktop 或 Cursor）的配置文件中指定如何启动和连接到这个 MCP 服务器。配置信息通常是 JSON 格式，包含服务器名称、启动命令、参数等。

以下是 MCP 客户端配置中需要提供的关键信息及常用参数说明（请根据您的实际文件路径和需求填写）：

  • 'mcpServers' 配置块： 在客户端配置文件的 'mcpServers' 部分添加一个新的配置对象。
  • 服务器名称 ('<server name>'): 为您的 MCP 服务器连接指定一个易于识别的名称，例如 'weather'。
  • 传输协议配置：
    • Stdio 传输：
      • 'command': MCP 服务器可执行文件的绝对路径。例如：'/path/to/your/repo/target/release/mcp-apollo-server'
      • 'args': 一个字符串数组，包含传递给服务器可执行文件的命令行参数。
    • HTTP+SSE 传输：
      • 'url': MCP 服务器监听的 HTTP+SSE 地址。例如：'http://127.0.0.1:5000/sse' (需要服务器启动时指定 '--sse-port 5000')。如果您使用 'mcp-remote' 工具转发 SSE，'command' 和 'args' 配置会有所不同，请参考仓库 README 中的示例。
  • 常用命令行参数 ('args' 数组中提供)：
    • '--directory <absolute path>': 指定服务器的工作目录，Schema 和操作文件路径通常相对于此目录。
    • '--schema <relative path>': 指定 GraphQL API Schema 文件的路径（相对于 '--directory'）。
    • '--operations <relative path>': 指定包含 GraphQL 操作的 '.graphql' 文件路径（可以指定多个）。
    • '--manifest <relative path>': 指定 Apollo Persisted Queries Manifest 文件的路径。
    • '--uplink': 从 Apollo GraphOS Uplink 获取 Schema 和 Persisted Queries (需要设置 'APOLLO_KEY' 和 'APOLLO_GRAPH_REF' 环境变量)。
    • '--endpoint <url>': 指定 GraphQL API 的 HTTP/S Endpoint 地址。默认是 'http://127.0.0.1:4000'。
    • '--header "<name>: <value>"': 添加要发送到 GraphQL Endpoint 的 HTTP Header (可以指定多个)。
    • '--sse-port <port>': 仅用于服务器启动时，指定使用 HTTP+SSE 传输并在特定端口监听。此参数不应在 MCP 客户端配置的 'args' 中出现，而是在您手动或通过脚本启动服务器时使用。
    • '--introspection': 启用 'schema' 和 'execute' 这两个内置工具。
    • '--explorer': 启用 'explorer' 内置工具 (需要配置 Uplink)。
    • '--custom-scalars-config <relative path>': 指定自定义 Scalar 类型的 JSON Schema 配置文件路径。

示例 (Stdio 传输配置描述):

假设您的仓库在 '/home/user/apollo-mcp-server'，天气示例 Schema 在 'graphql/weather/api.graphql'，操作文件在 'graphql/weather/operations/forecast.graphql' 等。

在客户端配置中，您可以这样描述：

  • 服务器名称: 'weather-server'
  • 启动方式: 'command' 设置为 '/home/user/apollo-mcp-server/target/release/mcp-apollo-server'
  • 参数 ('args'): 包含 '--directory /home/user/apollo-mcp-server'，'--schema graphql/weather/api.graphql'，以及 '--operations graphql/weather/operations/forecast.graphql', '--operations graphql/weather/operations/alerts.graphql', '--operations graphql/weather/operations/all.graphql' 等。如果您的 GraphQL Endpoint 不是默认的，还需要添加 '--endpoint <your graphql endpoint>'。

示例 (HTTP+SSE 传输配置描述):

首先，手动或通过脚本启动 MCP 服务器，指定 SSE 端口： '/home/user/apollo-mcp-server/target/release/mcp-apollo-server --directory /home/user/apollo-mcp-server --schema graphql/weather/api.graphql --operations graphql/weather/operations/*.graphql --sse-port 5000'

然后在客户端配置中：

  • 服务器名称: 'weather-sse-server'
  • 启动方式: 'url' 设置为 'http://127.0.0.1:5000/sse'

基本使用方法

  1. 根据您的 Schema 和操作文件，配置并启动 Apollo MCP 服务器。
  2. 在您的 MCP 客户端（如 Claude Desktop, Cursor）中，根据服务器的启动方式（Stdio 或 SSE）配置连接信息。
  3. 重启您的 MCP 客户端。客户端应该会自动发现并注册由 MCP 服务器暴露的工具。您通常可以在客户端界面看到工具数量的提示（例如，Claude Desktop 中的锤子图标旁边的数字）。
  4. 现在，您可以在与 LLM 交互时，通过自然语言提示来引导 LLM 调用这些工具。例如，如果您暴露了天气预报工具，您可以问 LLM “明天北京的天气怎么样？” LLM 可能会识别出这是一个天气查询的意图，并尝试调用对应的工具来获取信息。

信息

分类

AI与计算

访问项目