Hugging Face 的 LOGO

MCP 课程文档

模块 2：GitHub Actions 集成

Hugging Face's logo
加入 Hugging Face 社区

并获得增强的文档体验

开始使用

模块 2：GitHub Actions 集成

静默故障的袭击

CodeCraft Studios 第二周。您在模块 1 中构建的 PR 代理已经在帮助开发人员编写更好的拉取请求——Sarah 最新的 PR 有一个清晰的描述，为 Mike 节省了 20 分钟的调查时间。团队欢欣鼓舞！

但随后灾难降临。

周五下午，一个关键的 bug 达到了生产环境。支付系统崩溃，客户抱怨，团队争先恐后地进行调查。经过两个小时的紧张工作，他们发现了根本原因：周二 CI 运行中的一个测试失败，但没有人注意到。

“我们怎么会漏掉这个？”团队负责人一边滚动 GitHub Actions 一边问道。“测试显然失败了，但是有 47 个仓库和每天几十次提交，谁有时间检查每个构建？”

团队意识到他们需要对其 CI/CD 管道的实时可见性，但手动检查所有项目中的 GitHub Actions 是不可扩展的。他们需要自动化来监控问题并立即发出警报。

您的任务：扩展您的 MCP 服务器，使其具备 Webhook 功能，以监控 GitHub Actions，绝不再让任何故障悄然溜走。

您将构建什么

本模块弥合了静态文件分析（模块 1）和动态团队通知（模块 3）之间的鸿沟。您将添加实时功能，将您的 PR 代理转变为一个全面的开发监控系统。

在模块 1 中创建的基础之上，您将添加

  • Webhook 服务器，用于接收 GitHub Actions 事件
  • 新工具，用于监控 CI/CD 状态
  • MCP 提示，提供一致的工作流模式
  • 与您的 GitHub 仓库的实时集成

截屏：实时 CI/CD 监控实战！🎯

设置：观看 CodeCraft Studios 的新系统如何在故障到达生产环境之前捕获它们

  1. GitHub Webhooks - 查看向您的服务器发送事件的实际 Webhook 配置
  2. 失败测试 - 那些以前未被注意到的红色 X？不再是了！
  3. 本地开发 - Webhook 服务器和 Cloudflare Tunnel 协同工作

实时 MCP 魔法：Claude 响应三个关键请求

  • “我们收到了哪些 GitHub Actions 事件？” - Claude 使用您的新工具检查近期活动
  • “分析 CI 结果” - 观看 Claude 深入分析测试失败并提供可操作的见解
  • “创建部署摘要” - 查看 MCP 提示如何引导 Claude 创建团队友好的更新

静默故障不再 🚨：还记得周二测试失败中的那个关键 bug 吗？有了这个系统，Claude 会立即捕获它。截屏准确展示了您的 MCP 服务器如何将 GitHub 的原始 Webhook 数据转化为清晰、可操作的警报。

是什么让这变得特别：您的模块 1 PR 代理是静态的——它在被要求时分析代码。而模块 2 的增强是动态的——它 24/7 监控您的 CI/CD 管道，并帮助 Claude 提供实时见解。不再有周五下午的惊喜！

学习目标

本模块结束时，您将理解

  1. 如何与 MCP 服务器一起运行 Webhook 服务器
  2. 如何接收和处理 GitHub Webhook
  3. 如何为标准化工作流创建 MCP 提示
  4. 如何使用 Cloudflare Tunnel 进行本地 Webhook 测试

先决条件

您将直接在模块 1 的工作基础上进行构建，因此请确保您已具备以下条件：

  • 完成模块 1：构建 MCP 服务器 - 您将扩展相同的代码库
  • 对 GitHub Actions 的基本理解 - 您应该了解 CI/CD 工作流是什么
  • 一个启用了 Actions 的 GitHub 仓库 - 即使是简单的 workflow 文件也可以
  • 已安装 Cloudflare Tunnel (cloudflared) - 这将把您的本地 Webhook 服务器暴露给 GitHub

关键概念

MCP 提示

提示是可重用的模板，用于引导 Claude 完成复杂的工作流。与工具（Claude 自动调用）不同，提示是由用户启动的，并提供结构化的指导。

示例用例

  • 一致地分析 CI/CD 结果
  • 创建标准化的部署摘要
  • 系统地排除故障

Webhook 集成

您的 MCP 服务器将运行两个服务

  1. MCP 服务器（与 Claude 通信）
  2. 一个运行在 8080 端口的 Webhook 服务器（接收 GitHub 事件）

这使得 Claude 能够对实时 CI/CD 事件做出反应！

架构洞察：为 MCP 通信和 Webhook 处理运行独立的服务是一种清晰的关注点分离。Webhook 服务器处理 HTTP 的复杂性，而您的 MCP 服务器专注于数据分析和 Claude 集成。

项目结构

github-actions-integration/
├── starter/          # Your starting point
│   ├── server.py     # Module 1 code + TODOs
│   ├── pyproject.toml
│   └── README.md
└── solution/         # Complete implementation
    ├── server.py     # Full webhook + prompts
    ├── pyproject.toml
    └── README.md

实施步骤

步骤 1：设置并运行 Webhook 服务器

与模块 1 中您使用现有文件不同，本模块引入了实时事件处理。起始代码包含：

  • 您的模块 1 实现 - 您所有的现有 PR 分析工具
  • 一个完整的 Webhook 服务器 (webhook_server.py) - 已准备好接收 GitHub 事件

  1. 安装依赖项（与模块 1 相同）

    uv sync

  2. 启动 Webhook 服务器（在新终端中）

    python webhook_server.py

该服务器将接收 GitHub Webhook 并将其存储在 github_events.json 中。

Webhook 事件存储的工作原理

  • 每个传入的 GitHub Webhook（push、pull request、workflow 完成等）都会附加到 JSON 文件中
  • 事件与时间戳一起存储，便于查找近期活动
  • 该文件充当一个简单的事件日志，您的 MCP 工具可以读取和分析它
  • 无需数据库 - 所有内容都以简单、可读的 JSON 格式存储

步骤 2：连接到事件存储

现在，您将您的 MCP 服务器（来自模块 1）连接到 Webhook 数据。这比直接处理 HTTP 请求简单得多——Webhook 服务器承担了所有繁重的工作，并将事件存储在 JSON 文件中。

添加读取 Webhook 事件的路径

# File where webhook server stores events
EVENTS_FILE = Path(__file__).parent / "github_events.json"

Webhook 服务器处理所有 HTTP 细节——您只需读取 JSON 文件即可！这种关注点分离使您的 MCP 服务器专注于其最擅长的领域。

开发提示：使用文件而不是 HTTP 请求可以使测试变得更容易。您可以手动向 github_events.json 中添加事件，无需设置 Webhook 即可测试您的工具。

步骤 3：添加 GitHub Actions 工具

就像模块 1 中您创建用于文件分析的工具一样，现在您将创建用于 CI/CD 分析的工具。这些工具将与您现有的 PR 分析工具协同工作，为 Claude 提供代码更改和构建状态的完整视图。

注意：起始代码已经包含了模块 1 中的输出限制修复，因此您不会遇到令牌限制错误。请专注于本模块中的新概念！

实施两个新工具

  1. get_recent_actions_events:

    • 从 EVENTS_FILE 读取
    • 返回最新事件（最多限制数量）
    • 如果文件不存在，则返回空列表

  2. get_workflow_status:

    • 从文件读取所有事件
    • 按 workflow_run 事件筛选
    • 按工作流名称分组并显示最新状态

这些工具让 Claude 可以分析您的 CI/CD 管道。

步骤 4：创建 MCP 提示

现在您将添加您的第一个 MCP 提示！与工具（Claude 自动调用）不同，提示是帮助用户与 Claude 持续交互的模板。将它们视为引导 Claude 完成复杂工作流的“对话启动器”。

模块 1 专注于数据访问工具，而本模块则引入了工作流指导提示。

实施四个演示不同工作流模式的提示

  1. analyze_ci_results：全面的 CI/CD 分析
  2. create_deployment_summary：团队友好的更新
  3. generate_pr_status_report：组合代码 + CI 报告
  4. troubleshoot_workflow_failure：系统化调试

每个提示都应返回一个字符串，其中包含 Claude 要遵循的清晰指令。

步骤 5：使用 Cloudflare Tunnel 进行测试

现在是激动人心的部分——使用真实的 GitHub 事件测试您扩展的 MCP 服务器！您将同时运行多个服务，就像在真实的开发环境中一样。

  1. 启动您的 MCP 服务器（与模块 1 相同的命令）

    uv run server.py

  2. 在另一个终端中，启动 Cloudflare Tunnel

    cloudflared tunnel --url https://:8080

  3. 使用隧道 URL 配置 GitHub webhook

  4. 使用提示与 Claude Code 进行测试

练习

练习 1：自定义工作流提示

创建一个新提示，通过结合以下内容来帮助进行 PR 审查

  • 模块 1 工具中的代码更改
  • 模块 2 工具中的 CI/CD 状态
  • 审查人员的清单格式

练习 2：事件过滤

增强 get_workflow_status 以

  • 按工作流结论（成功/失败）筛选
  • 按仓库分组
  • 显示上次运行以来的时间

练习 3：通知系统

添加一个工具，该工具可用于

  • 跟踪哪些事件已被“查看”
  • 突出显示新故障
  • 建议通知哪个团队成员

常见问题

Webhook 未接收到事件

  • 确保 Cloudflare Tunnel 正在运行
  • 检查 GitHub webhook 设置（应显示最近的交付）
  • 验证 payload URL 是否包含 /webhook/github

提示不起作用

  • FastMCP 提示只是返回字符串
  • 确保您的函数用 @mcp.prompt() 装饰

Webhook 服务器问题

  • 确保 webhook_server.py 在单独的终端中运行
  • 检查 8080 端口是否空闲：lsof -i :8080
  • 事件文件将在接收到第一个事件时自动创建

下一步

干得漂亮！您已成功为 MCP 服务器添加了实时功能。您现在拥有一个可以执行以下操作的系统：

  • 分析代码更改（来自模块 1）
  • 实时监控 CI/CD 事件（来自本模块）
  • 使用 MCP 提示提供一致的工作流指导
  • 通过清晰的基于文件的架构处理 Webhook 事件

模块 2 中的主要成就：

  • 构建了您的第一个 Webhook 集成
  • 学习了用于工作流标准化的 MCP 提示
  • 创建了处理实时数据的工具
  • 建立了事件驱动自动化的模式

接下来要做什么：

  1. 查阅解决方案，路径为 /projects/unit3/github-actions-integration/solution/，以了解不同的实现方法
  2. 实验您的提示 - 尝试将它们用于不同类型的 GitHub 事件
  3. 测试集成 - 将您的模块 1 文件分析工具与模块 2 事件监控在一个对话中结合使用
  4. 进入模块 3 - 您将在其中通过 Slack 集成添加团队通知来完成自动化管道

模块 3 将把所有内容整合到一个您的团队可以实际使用的完整工作流中！

故事继续……

您的监控系统正在运行！CodeCraft Studios 现在可以实时捕获 CI/CD 故障，团队对他们的部署更有信心。但下周将迎来新的挑战：信息孤岛正在导致重复工作和错失机会。模块 3 将通过智能团队通知来完善自动化系统，让每个人都随时了解最新情况。

附加资源

< > 在 GitHub 上更新

←模块 1：构建 MCP 服务器 模块 3：Slack 通知→