内容
[](https://mseep.ai/app/f18a0332-2186-49a9-a29d-c0de85307440)
# Act 测试 MCP
[](https://www.npmjs.com/package/act-testing-mcp)
[](https://www.npmjs.com/package/act-testing-mcp)
[](LICENSE)
[](https://github.com/GarthDB/act-testing-mcp/actions)
用于本地测试 GitHub Actions 工作流的 Model Context Protocol (MCP) 服务器，结合 [nektos/act](https://github.com/nektos/act) 使用。
## 目的
该 MCP 为 AI 助手（如 Claude）提供直接访问本地测试 GitHub Actions 工作流的能力，消除了在处理 CI/CD 管道时反复试验的开发周期。
## 功能
- **🔍 列出工作流**：发现任何存储库中所有可用的 GitHub Actions 工作流
- **▶️ 运行工作流**：使用 act 在本地执行工作流
- **✅ 验证语法**：在提交前检查工作流文件是否有错误
- **🎭 自定义事件**：使用自定义事件数据测试工作流以模拟不同场景
- **🐛 调试支持**：详细的日志记录和错误报告
- **📊 依赖监控**：跟踪 `act` 兼容性并检测破坏性更改
- **🔐 供应链安全**：使用 npm 溯源声明发布以确保可验证的构建
## 先决条件
- **Docker Desktop**（正在运行）
- **nektos/act** 已安装（[安装指南](https://github.com/nektos/act#installation)）
- **Node.js 20+**
### 安装 nektos/act
```bash
# macOS
brew install act
# Linux（使用 curl）
curl https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash
# Windows（使用 chocolatey）
choco install act-cli
# 或从发布页面下载
# https://github.com/nektos/act/releases
```
## 安装
```bash
npm install -g act-testing-mcp
```
### 验证软件包完整性
该软件包已使用 [npm 溯源](https://docs.npmjs.com/generating-provenance-statements) 发布，以增强供应链安全。您可以验证软件包的声明：
```bash
npm audit signatures
```
或克隆并在本地运行：
```bash
git clone https://github.com/GarthDB/act-testing-mcp.git
cd act-testing-mcp
npm install
```
## 配置
### MCP 设置
将以下内容添加到您的 MCP 配置文件（例如 `.cursor/mcp.json` for Cursor IDE）：
#### 选项 1：使用 npx（推荐）
```json
{
"mcpServers": {
"act-testing": {
"command": "npx",
"args": ["act-testing-mcp"]
}
}
}
```
#### 选项 2：使用全局安装
```json
{
"mcpServers": {
"act-testing": {
"command": "act-testing-mcp"
}
}
}
```
#### 选项 3：自定义项目路径（如果需要）
```json
{
"mcpServers": {
"act-testing": {
"command": "npx",
"args": ["act-testing-mcp"],
"env": {
"PROJECT_ROOT": "/path/to/your/project"
}
}
}
}
```
#### 选项 4：本地开发
```json
{
"mcpServers": {
"act-testing": {
"command": "node",
"args": ["./path/to/act-testing-mcp/index.js"],
"env": {
"PROJECT_ROOT": "/path/to/your/project",
"ACT_BINARY": "act"
}
}
}
}
```
> **注意**：使用 `npx`（选项 1）是推荐的，因为它避免了 PATH 问题，并确保您始终使用最新版本。MCP 服务器会自动检测当前工作目录，因此仅当您要覆盖默认行为时才需要 `PROJECT_ROOT`。此方法与其他 MCP 服务器（如 [Browser MCP](https://docs.browsermcp.io/setup-server#cursor)）类似，并解决了 [continuedev/continue#4791](https://github.com/continuedev/continue/issues/4791) 中提到的常见 NPX 可用性问题。
### Act 配置
在项目根目录中创建 `.actrc` 文件（复制示例文件）：
```bash
# 复制示例配置并自定义路径
cp mcp-config.example.json .cursor/mcp.json
# 编辑 .cursor/mcp.json 以设置 PROJECT_ROOT 路径
# 复制 act 配置（可选）
cp .actrc /path/to/your/project/.actrc
```
## 提供的工具
### `list_workflows`
列出存储库中所有可用的 GitHub Actions 工作流。
**参数：** 无
**示例：**
```
📋 **CI** (ci.yml)
作业：test (test)
事件：push, pull_request
📋 **Release** (release.yml)
作业：release (release)
事件：workflow_dispatch
```
### `run_workflow`
使用 act 在本地运行工作流。
**参数：
- `workflow`（必填）：工作流文件名称或作业 ID
- `event`（可选）：事件类型（push, pull_request 等）
- `dryRun`（可选）：显示执行计划而不运行
- `verbose`（可选）：启用详细输出
- `env`（可选）：环境变量
- `secrets`（可选）：提供的机密
- `eventData`（可选）：用于测试的自定义事件数据
**示例：
```bash
# 运行 CI 工作流
run_workflow workflow="ci.yml" event="push"
# 使用自定义事件数据进行 dry run
run_workflow workflow="ci.yml" event="pull_request" dryRun=true eventData='{"number": 123}'
# 使用环境变量运行
run_workflow workflow="release.yml" env='{"NODE_ENV": "production"}'
```
### `validate_workflow`
验证工作流语法和结构。
**参数：
- `workflow`（必填）：要验证的工作流文件名称
### `act_doctor`
检查 act 配置和 Docker 设置。
**参数：** 无
## 使用示例
### 与 AI 助手（Claude）
配置完成后，您可以直接询问 AI 助手来测试工作流：
- _"测试我的 CI 工作流"_
- _"以 dry-run 模式运行发布工作流"_
- _"检查我的新工作流文件是否有效"_
- _"使用自定义 PR 数据测试拉取请求工作流"_
### 直接使用
```bash
# 启动 MCP 服务器
npm start
# 运行测试
npm test
# 运行覆盖率测试
npm run test:coverage
# 调试模式
npm run dev
```
## 开发
### 运行测试
```bash
# 安装依赖
npm install
# 运行所有测试
npm test
# 运行覆盖率测试
npm run test:coverage
# 监听模式
npm run test:watch
```
### 测试覆盖率
该工具包含全面的测试：
- **单元测试**：使用 AVA 框架
- **集成测试**：使用真实的 act 和 Docker
- **代码覆盖率**：使用 c8（核心逻辑目标为 70%+）
- **ES 模块**：使用原生 Node.js 支持
### 兼容性监控
跟踪 act 兼容性随时间的变化：
```bash
# 创建基准
npm run compatibility:baseline
# 检查更改
npm run compatibility:check
# 生成详细报告
npm run compatibility:report
```
## 项目结构
```
act-testing-mcp/
├── index.js # 主 MCP 服务器
├── package.json # 依赖和脚本
├── README.md # 本文件
├── LICENSE # Apache 2.0 许可证
├── .actrc # Act 配置示例
├── ava.config.js # 测试配置
├── mcp-config.example.json # MCP 配置示例
├── utils/ # 实用工具模块
│ ├── act-helpers.js # 核心 act 集成
│ └── act-monitor.js # 兼容性监控
├── scripts/ # 实用脚本
│ └── check-act-compatibility.js
├── test/ # 测试套件
│ ├── index.test.js
│ ├── act-compatibility.test.js
│ ├── act-monitor.test.js
│ └── utils.test.js
└── docs/ # 附加文档
├── SETUP.md
├── GUIDE.md
├── TESTING.md
└── DEPENDENCY_MONITORING.md
```
## 故障排除
### Docker 问题
```bash
# 检查 Docker 是否正在运行
docker ps
# 拉取所需镜像
docker pull catthehacker/ubuntu:act-latest
```
### Act 问题
```bash
# 检查 act 安装
act --version
# 使用简单工作流测试 act
act --list
```
### MCP 连接问题
1. 验证 MCP 配置文件路径
2. 检查 Node.js 路径是否正确
3. 确保 PROJECT_ROOT 环境变量已设置
4. 检查项目是否具有 `.github/workflows/` 目录
## 贡献
1. 复刻仓库
2. 创建功能分支
3. 进行更改
4. 为新功能添加测试
5. 确保所有测试通过
6. 提交拉取请求
## 许可证
该项目使用 Apache License 2.0 许可 - 有关详细信息，请参阅 [LICENSE](LICENSE) 文件。
## 相关项目
- [nektos/act](https://github.com/nektos/act) - 在本地运行 GitHub Actions
- [Model Context Protocol](https://github.com/modelcontextprotocol) - AI 助手工具集成的协议
## 支持
- 创建一个 [issue](https://github.com/GarthDB/act-testing-mcp/issues) 以报告错误或功能请求
- 查看 [文档](docs/) 以获取详细指南
- 审查现有的 [issues](https://github.com/GarthDB/act-testing-mcp/issues) 以获取解决方案
---
**注意**：该工具最初是为 [Adobe Spectrum Tokens](https://github.com/adobe/spectrum-tokens) 项目开发的，现已作为独立的可重复使用的 MCP 服务器提取出来。
