swapi_mcp

一个用于构建可观测 AI 代理的小型端到端参考项目：一个包装 Star Wars API 的 MCP 服务器、一个驱动它的 Claude 代理，以及一个 Web 聊天界面——全部通过 OpenTelemetry 和 Grafana Cloud 进行埋点（分布式追踪、RED 指标、前端 RUM 和 AI/代理可观测性）。

它旨在通过一个可运行的代码库展示各部分如何组合在一起——MCP 工具边界、代理的工具调用循环，以及从浏览器点击一路深入到上游 HTTP 调用并返回的全栈追踪。

这里有什么

两个通过 MCP（stdio）相互通信的部分：

MCP 服务器（src/index.ts、src/tools/）——将 Star Wars API 包装为横跨 6 种资源（people、planets、films、species、vehicles、starships）的 18 个工具：每种资源都有一个 search_、一个 get-all 和一个 get-by-id。它是一个纯粹的工具提供者，不做任何决策。

代理（src/agent/）——决策者：

• mcpClient.ts —— 通过 stdio 启动构建好的服务器，并以 MCP 客户端身份连接。

• agent.ts —— 手动工具调用循环：将问题和服务器的工具发送给 Claude，通过 MCP 执行每个被请求的工具，将结果反馈回去，重复此过程直到完成。

• main.ts —— CLI 入口点。

• server.ts + public/index.html —— 一个 HTTP 服务器和一个单页聊天界面。

Related MCP server: SWAPI MCP Server

可观测性

以下所有内容都是可选并由环境变量控制的——即使都没有，代理也能正常运行。

• 分布式追踪（OpenTelemetry → Tempo）：一条追踪跨 browser → POST /ask → agent.turn → llm.request / tool.call → tool.execute → swapi.fetch，涵盖三个服务（swapi-web、swapi-agent、swapi-mcp-server）。追踪上下文通过请求中的 _meta 跨 MCP 边界传播。

• RED 指标（→ Mimir）：每个工具和每次 LLM 调用的速率 / 错误 / 耗时直方图，以及一个用于统计成本的 token 使用计数器，带有 model、error 和 error.type 标签。

• 前端 RUM（Grafana Faro）：Web Vitals、JS 错误，以及浏览器→后端追踪传播。

• AI / 代理可观测性（@grafana/agent-o11y）：规范化的 LLM 生成内容和工具执行。

• 演示故障注入（src/chaos.ts）：可选地让一个资源返回模拟的 503 状态码，并让另一个资源运行速度降低 50%，以便仪表盘展示真实的错误和延迟信号。

前提条件

• Node.js 22+（使用 --env-file）

• Yarn 4（通过 Corepack）

• Anthropic API 密钥（供代理使用）

• Grafana Cloud 账户（可选——仅用于可观测性功能）

设置

yarn install
yarn build

直接使用 MCP 服务器（例如 Claude Desktop）

将你的 MCP 客户端指向构建好的服务器：

{
  "mcpServers": {
    "swapi": { "command": "node", "args": ["/absolute/path/to/swapi_mcp/build/index.js"] }
  }
}

运行代理

创建一个 .env 文件（已被 git 忽略），其中至少包含你的 Anthropic 密钥：

ANTHROPIC_API_KEY=sk-ant-...

然后：

yarn dev                              # build + serve the web UI at http://localhost:8787
yarn ask "Who is Luke's homeworld?"   # one-shot CLI

环境变量

备注

这是一个学习 / 演示项目。数据来自 SWAPI 的静态镜像，它建模的是关联关系（一个角色“出现在”某部电影中），而不是动作——因此回答也会相应措辞。

许可证

MIT