Apollo MCP Server 快速入门指南：构建AI与GraphQL的桥梁

概述

Apollo MCP Server 是一个创新的工具，它允许开发者将GraphQL操作转化为AI可用的工具。通过MCP（模型上下文协议），AI助手如Claude可以直接与您的GraphQL API进行交互，实现自然语言到GraphQL查询的转换。本文将带您快速搭建一个基于太空数据的AI交互系统。

核心概念

在开始之前，让我们理解几个关键概念：

1. MCP（模型上下文协议）：一种让AI模型能够发现和使用外部工具的协议
2. GraphQL操作：查询(query)、变更(mutation)和订阅(subscription)
3. AI工具：通过MCP暴露的GraphQL操作，AI可以直接调用

环境准备

在开始之前，请确保您已准备好以下环境：

1. 安装最新版本的Node.js（建议16.x或更高版本）
2. 安装Apollo Rover CLI（0.32或更高版本）
3. 获取Apollo MCP Server的代码副本

实战步骤

第一步：理解示例项目

我们使用一个太空数据API的示例项目，该项目包含：

• 一个联邦图（federated graph），连接The Space Devs API
• 四个预定义的GraphQL操作，将作为AI工具暴露：
  • ExploreCelestialBodies - 搜索行星、卫星和恒星
  • GetAstronautDetails - 获取宇航员详细信息
  • GetAstronautsCurrentlyInSpace - 查询当前在太空的宇航员
  • SearchUpcomingLaunches - 查找即将进行的火箭发射

第二步：启动MCP服务器

执行以下命令启动本地开发服务器：

rover dev --supergraph-config ./graphql/TheSpaceDevs/supergraph.yaml \
--mcp \
--mcp-operations ./graphql/TheSpaceDevs/operations/ExploreCelestialBodies.graphql \
./graphql/TheSpaceDevs/operations/GetAstronautDetails.graphql \
./graphql/TheSpaceDevs/operations/GetAstronautsCurrentlyInSpace.graphql \
./graphql/TheSpaceDevs/operations/SearchUpcomingLaunches.graphql

这个命令做了三件事：

1. 使用supergraph配置启动本地图
2. 通过--mcp标志启用MCP服务器
3. 将指定的GraphQL操作暴露为MCP工具

第三步：验证服务器运行

使用MCP Inspector工具验证服务器是否正常运行：

1. 安装并启动MCP Inspector：

   npx @modelcontextprotocol/inspector
   

2. 在浏览器中访问http://127.0.0.1:6274

3. 在Inspector中：

   • 选择Streamable HTTP作为传输类型
   • 输入http://127.0.0.1:5000/mcp作为URL
   • 点击"Connect"，然后点击"List Tools"

如果一切正常，您应该能看到服务器暴露的工具列表。

第四步：配置Claude Desktop

为了让Claude能够使用这些工具，需要进行以下配置：

1. 找到Claude的配置文件：

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • Linux: ~/.config/Claude/claude_desktop_config.json

2. 添加MCP服务器配置：

   {
     "mcpServers": {
       "thespacedevs": {
         "command": "npx",
         "args": [
           "mcp-remote",
           "http://127.0.0.1:5000/mcp"
         ]
       }
     }
   }
   

3. 重启Claude Desktop使配置生效

第五步：测试交互

现在可以测试AI与GraphQL的交互了：

1. 询问Claude可用的工具： "What MCP tools do you have available?" Claude应该列出四个太空数据工具

2. 尝试实际查询： "Who are the astronauts currently in space?" Claude应该使用GetAstronautsCurrentlyInSpace工具并返回当前在太空的宇航员信息

3. 探索其他功能： "What rocket launches are coming up?" "Tell me about the planet Mars"

常见问题排查

服务器启动问题

• 端口占用：如果5000端口被占用，可以使用--mcp-sse-port参数指定其他端口
• 配置加载失败：确保从项目根目录运行命令，并检查supergraph.yaml路径是否正确

连接问题

• Inspector无法连接：检查服务器是否运行，URL是否正确，防火墙是否阻止连接
• Claude无法识别工具：确认配置文件路径正确，JSON格式无误，并已重启Claude

操作问题

• 操作未找到：检查操作文件是否存在，操作名称是否匹配
• 模式验证失败：确保GraphQL操作与模式匹配，检查语法错误

进阶使用

替代运行方式

除了HTTP传输，MCP Server还支持STDIO传输方式，适用于需要更直接控制服务器进程的环境：

1. 下载Apollo MCP Server二进制文件

2. 使用以下命令启动：

   npx @modelcontextprotocol/inspector apollo-mcp-server \
   --directory <MCP示例目录绝对路径> \
   --schema api.graphql \
   --operations operations \
   --endpoint https://thespacedevs-production.up.railway.app/
   

3. 修改Claude配置使用STDIO方式连接

总结

通过本指南，您已经成功搭建了一个将GraphQL API转化为AI工具的系统。这种技术可以应用于任何GraphQL API，为AI助手提供强大的数据访问能力。未来，您可以：

1. 为自己的业务API创建MCP工具
2. 探索更复杂的GraphQL操作
3. 优化AI工具的提示和描述，提高交互质量

Apollo MCP Server为GraphQL和AI的集成开辟了新的可能性，期待看到您构建的创新应用！