github-actions-mcp-server

🚀 GitHub Actions MCP 服务器

本项目是基于 GitHub Actions 的 MCP 服务器，它能助力人工智能助手对 GitHub Actions 工作流进行管理与操作，极大提升工作流管理的效率与便捷性。

🚀 快速开始

克隆仓库并构建：

git clone https://github.com/ko1ynnky/github-actions-mcp-server.git
cd github-actions-mcp-server
npm install
npm run build

这将生成位于 dist 目录中的必要文件，以运行 MCP 服务器。

✨ 主要特性

• 完整工作流管理：可对工作流进行列举、查看、触发、取消和重新运行等操作。
• 工作流运行分析：能够获取工作流运行的详细信息及其作业情况。
• 全面错误处理：提供清晰的错误消息，并带有增强细节。
• 灵活类型验证：具备稳健的类型检查，能优雅处理 API 变异。
• 安全导向设计：包含超时处理、速率限制和严格 URL 验证等安全机制。

📚 详细文档

工具列表

1. list_workflows

   • 功能：列举仓库中的工作流。
   • 输入参数：
     • owner (字符串)：仓库所有者（用户名或组织）。
     • repo (字符串)：仓库名称。
     • page (可选数字)：分页页码。
     • perPage (可选数字)：每页结果数（最多 100）。
   • 返回值：仓库中的工作流列表。

2. get_workflows

   • 功能：获取指定所有者的工作流。
   • 输入参数：
     • owner (字符串)：仓库所有者。
   • 返回值：所有者的详细工作流信息。

3. trigger_workflow

   • 功能：触发指定的工作流运行。
   • 输入参数：
     • owner (字符串)：仓库所有者。
     • repo (字符串)：仓库名称。
     • workflow_id (字符串)：工作流 ID。
     • ref (字符串)：代码引用（分支、标签或提交哈希）。
     • inputs (对象)：传递给工作流的输入参数。
   • 返回值：触发运行的状态信息。

4. get_workflow_run

   • 功能：获取指定的工作流运行详细信息。
   • 输入参数：
     • owner (字符串)：仓库所有者。
     • repo (字符串)：仓库名称。
     • run_id (字符串)：运行 ID。
   • 返回值：运行的详细信息。

5. list_workflow_runs

   • 功能：列举指定工作流的所有运行。
   • 输入参数：
     • owner (字符串)：仓库所有者。
     • repo (字符串)：仓库名称。
     • workflow_id (字符串)：工作流 ID。
   • 返回值：工作流的运行列表。

💻 使用示例

基础用法

// 列举工作流
const result = await listWorkflows({
  owner: "your-username",
  repo: "your-repository"
});

// 触发工作流
const result = await triggerWorkflow({
  owner: "your-username",
  repo: "your-repository", 
  workflowId: "ci.yml",
  ref: "main",
  inputs: {
    environment: "production"
  }
});

配置示例

在 claude_desktop_config.json 中添加：

{
  "mcpServers": {
    "github-actions": {
      "command": "node",
      "args": [
        "<path-to-mcp-server>/dist/index.js"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "<YOUR_TOKEN>"
      }
    }
  }
}

📚 使用说明

常见问题

1. 身份验证错误：
   • 确保您的 GitHub 令牌具有正确的权限。
   • 检查令牌是否正确设置为环境变量。
2. 速率限制：
   • 该服务器实现速率限制以避免触及 GitHub API 的限制。
   • 如果遇到速率限制错误，请降低请求频率。
3. 类型验证错误：
   • GitHub API 响应可能与预期的架构有所不同。
   • 该服务器实现灵活验证以处理大多数变体。
   • 如果遇到持续性错误，请打开问题报告。

📄 许可证

此 MCP 服务器根据 MIT 许可证发布。