Apollo MCP Server 使用指南：构建AI友好的GraphQL网关

Apollo MCP Server 使用指南：构建AI友好的GraphQL网关

apollo-mcp-server Apollo MCP Server 项目地址: https://gitcode.com/gh_mirrors/ap/apollo-mcp-server

项目概述

Apollo MCP Server 是一个创新的GraphQL网关服务，专为AI应用场景设计。它基于Model Context Protocol (MCP)协议，能够将GraphQL操作封装成AI模型可调用的工具接口，为构建AI驱动的应用提供了强大支持。

核心特性

1. 实验性功能：当前版本仍处于实验阶段，但已展现出强大的潜力
2. 多操作来源支持：支持从多种来源加载GraphQL操作
3. 热重载能力：配置变更无需重启服务
4. 容器化部署：提供标准Docker镜像
5. 调试工具集成：内置MCP Inspector调试工具

安装指南

Linux/MacOS系统安装

推荐使用以下命令安装最新版本：

curl -sSL https://mcp.apollo.dev/download/nix/latest | sh

对于生产环境，建议安装特定版本以确保稳定性：

curl -sSL https://mcp.apollo.dev/download/nix/v0.3.0 | sh

注意：当前版本暂不支持Intel芯片的Mac设备，相关支持将在未来版本中提供。

配置GraphQL服务

Apollo MCP Server需要了解其所代理的GraphQL API的schema信息。可以通过两种方式提供schema：

1. --schema选项：直接指定schema文件路径
2. --uplink选项：通过Apollo Uplink获取schema

schema主要用于三个目的：

• 生成工具描述信息
• 输入参数验证
• 支持GraphQL自省查询

定义GraphQL操作

MCP Server支持多种方式定义GraphQL操作：

1. 操作文件方式

创建.graphql文件，每个文件包含一个GraphQL操作：

query GetWeather($location: String!) {
  weather(location: $location) {
    temperature
    conditions
  }
}

使用--operations选项指定操作文件或目录，支持热重载。

2. 持久化查询清单

支持Apollo格式的持久化查询清单文件：

apollo-mcp-server --manifest queries.json

3. GraphOS托管查询

对于使用GraphOS管理的GraphQL服务：

export APOLLO_KEY=your_key
export APOLLO_GRAPH_REF=your_graph_ref
apollo-mcp-server --uplink

4. 自省查询模式

启用--introspection选项后，AI模型可以动态探索schema并执行操作：

apollo-mcp-server --introspection

这会暴露两个新工具：

• introspect：获取schema类型信息
• execute：执行GraphQL操作

容器化部署

Apollo MCP Server提供标准Docker镜像：

docker run -p 5000:5000 \
  -v /path/to/schema:/data \
  ghcr.io/apollographql/apollo-mcp-server:latest \
  --schema api.graphql \
  --operations operations/ \
  --endpoint https://your-graphql-endpoint.com/

调试技巧

使用MCP Inspector工具进行调试：

1. 本地stdio传输调试：

npx @modelcontextprotocol/inspector \
  apollo-mcp-server --schema schema.graphql

2. HTTP传输调试：

# 启动服务
apollo-mcp-server --http-port 5000

# 启动Inspector
npx @modelcontextprotocol/inspector

在浏览器中连接后，可以查看所有可用工具并测试调用。

最佳实践

1. 生产环境建议使用特定版本而非latest标签
2. 考虑使用合约变体控制AI对GraphQL schema的访问权限
3. 为重要操作添加描述注释，提高AI调用的准确性
4. 持久化查询清单适合固定操作集合的场景
5. 自省模式适合需要动态探索schema的AI应用

通过合理配置Apollo MCP Server，开发者可以构建强大的AI-GraphQL集成方案，为智能应用提供结构化数据访问能力。

apollo-mcp-server Apollo MCP Server 项目地址: https://gitcode.com/gh_mirrors/ap/apollo-mcp-server