Github Action Trigger Mcp

GitHub Action Trigger MCP 服务

用于集成 GitHub Actions 的模型上下文协议服务。

概述

这是一个基于 TypeScript 构建、用于集成 GitHub Actions 的 MCP 服务。它提供以下功能：

• 用于获取仓库中可用 GitHub Actions 的工具
• 用于获取特定 GitHub Action 详细信息的工具
• 用于触发 GitHub 工作流分发事件的工具
• 用于获取 GitHub 仓库最新发布版本的工具
• 用于为拉取请求启用自动合并的工具

功能

工具

• get_github_actions - 获取仓库中可用的 GitHub Actions

  • 必需参数：owner（仓库所有者、用户名或组织）和 repo（仓库名称）
  • 可选参数：token（GitHub 个人访问令牌，用于访问私有仓库或提高 API 速率限制）
  • 返回包含工作流 ID、名称、路径、状态、URL 和内容的 JSON 数据

• get_github_action - 获取特定 GitHub Action 的详细信息，包括输入项及其要求

  • 必需参数：owner（Action 所有者、用户名或组织）和 repo（Action 所属仓库名称）
  • 可选参数：
    • path：Action 定义文件的路径（默认值：'action.yml'）
    • ref：Git 引用（分支、标签或提交 SHA，默认值：'main'）
    • token：GitHub 个人访问令牌（可选）
  • 返回 Action 的详细信息，包括名称、描述、作者、输入项（以及是否为必需项）等。

• trigger_github_action - 触发 GitHub 工作流并传递相关参数

  • 必需参数：
    • owner：仓库所有者（用户名或组织）
    • repo：仓库名称
    • workflow_id：要触发的工作流 ID 或文件名
  • 可选参数：
    • ref：用于触发工作流的 Git 引用（默认值：'main'）
    • inputs：要传递给工作流的输入项（必须与工作流定义的输入项匹配）
    • token：GitHub 个人访问令牌（必须具有 workflow 权限范围）
  • 返回工作流运行信息，包括状态、URL 等。

• get_github_release - 获取 GitHub 仓库最新的 2 个发布版本

  • 必需参数：owner（仓库所有者、用户名或组织）和 repo（仓库名称）
  • 可选参数：token（GitHub 个人访问令牌，可选）
  • 返回最新 2 个发布版本的信息

• enable_pull_request_automerge - 为特定拉取请求启用自动合并

  • 必需参数：
    • owner：仓库所有者（用户名或组织）
    • repo：仓库名称
    • pull_number：拉取请求编号
  • 可选参数：
    • merge_method：要使用的合并方法（MERGE、SQUASH 或 REBASE，默认值：MERGE）
    • token：GitHub 个人访问令牌（可选）
  • 返回成功状态和拉取请求信息
  • 注意：所有必需检查通过且满足审批要求后，将自动合并 PR

安装

推荐安装方式：使用 npx

最简单的安装和使用方式是在 Claude Desktop 配置文件中使用 npx 命令，无需手动在本地安装：

{
  "mcpServers": {
    "github-action-trigger-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@nextdrive/github-action-trigger-mcp"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your_github_token_here"
      }
    }
  }
}

此方法的优势：

• 无需在本地安装软件包
• 自动使用最新版本
• 一次设置，即可使用
• 内置 GitHub 令牌配置

本地安装

如果你更倾向于手动安装，请按以下步骤操作：

1. 安装软件包：

npm install -g @nextdrive/github-action-trigger-mcp

2. 在 Claude Desktop 配置中使用：

MacOS：~/Library/Application Support/Claude/claude_desktop_config.json Windows：%APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "github-action-trigger-mcp": {
      "command": "@nextdrive/github-action-trigger-mcp",
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your_github_token_here"
      }
    }
  }
}

GitHub 令牌配置

要访问 GitHub API，尤其是访问私有仓库或触发工作流时，需要配置 GitHub 个人访问令牌。可以通过以下几种方式进行配置：

方法 1（推荐）：在 Claude Desktop 中直接配置

通过 env 字段在 Claude Desktop 配置文件中直接设置令牌：

"env": {
  "GITHUB_PERSONAL_ACCESS_TOKEN": "your_github_token_here"
}

方法 2：全局环境变量

设置 GITHUB_TOKEN 环境变量：

# On Linux/MacOS
export GITHUB_TOKEN=your_github_token

# On Windows
set GITHUB_TOKEN=your_github_token

方法 3：本地配置文件

编辑配置文件：

~/.nextdrive-github-action-trigger-mcp/config.json

设置你的 GitHub 令牌：

{
  "githubToken": "your_github_token"
}

首次启动服务时，系统会自动创建此配置文件的模板。

开发

安装依赖：

npm install

构建服务：

npm run build

在开发过程中自动重新构建：

npm run watch

调试

使用 MCP Inspector 进行调试：

npm run inspector

Inspector 会提供一个 URL，供你在浏览器中访问调试工具。

发布到 npm

如果你想将此软件包发布到 npm，请按以下步骤操作：

1. 确保你已登录 npm，并有权限向 @nextdrive 组织发布：

   npm login
   

2. 构建项目：

   npm run build
   

3. 发布到 npm（组织范围的软件包默认为私有，使用 --access public 将其设为公开）：

   npm publish --access public
   

发布后，任何人都可以使用 npx @nextdrive/github-action-trigger-mcp 命令运行此工具，或在 Claude Desktop 配置中使用它。

使用示例

获取 GitHub Actions 列表

使用 get_github_actions 工具获取仓库的 GitHub Actions：

{
  "owner": "username-or-org",
  "repo": "repository-name"
}

如果配置了默认令牌，访问私有仓库时将自动使用该令牌。

响应示例：

[
  {
    "id": 12345678,
    "name": "CI",
    "path": ".github/workflows/ci.yml",
    "state": "active",
    "url": "https://github.com/owner/repo/actions/workflows/ci.yml",
    "content": "name: CI\n\non:\n  push:\n    branches: [ main ]\n  pull_request:\n    branches: [ main ]\n\njobs:\n  build:\n    runs-on: ubuntu-latest\n    steps:\n    - uses: actions/checkout@v2\n    - name: Setup Node.js\n      uses: actions/setup-node@v2\n      with:\n        node-version: 16.x\n    - name: Install dependencies\n      run: npm ci\n    - name: Build\n      run: npm run build\n    - name: Test\n      run: npm test\n"
  }
]

获取 GitHub Action 详细信息

使用 get_github_action 工具获取特定 Action 的详细信息：

{
  "owner": "actions",
  "repo": "checkout",
  "ref": "v4"
}

响应示例：

{
  "name": "Checkout",
  "description": "Check out a Git repository at a particular version",
  "author": "GitHub",
  "inputs": [
    {
      "name": "repository",
      "description": "Repository name with owner. For example, actions/checkout",
      "default": "",
      "required": false
    },
    {
      "name": "ref",
      "description": "The branch, tag or SHA to checkout.",
      "default": "",
      "required": false
    }
  ],
  "runs": {
    "using": "node20",
    "main": "dist/index.js"
  }
}

触发 GitHub 工作流

使用 trigger_github_action 工具触发 GitHub 工作流：

{
  "owner": "username-or-org",
  "repo": "repository-name",
  "workflow_id": "ci.yml",
  "inputs": {
    "deploy_environment": "production",
    "debug_enabled": "true"
  }
}

响应示例：

{
  "success": true,
  "message": "Workflow dispatch event triggered successfully",
  "run": {
    "id": 12345678,
    "url": "https://github.com/owner/repo/actions/runs/12345678",
    "status": "queued",
    "conclusion": null,
    "created_at": "2025-03-19T06:45:12Z",
    "triggered_by": "API"
  }
}

注意：触发工作流需要满足以下条件：

1. 工作流必须配置为支持 workflow_dispatch 事件
2. GitHub 令牌必须拥有 workflow 范围的权限
3. 传入的输入参数必须与工作流中定义的参数相匹配

获取最新发布版本

使用 get_github_release 工具获取仓库最新的 2 个发布版本：

{
  "owner": "username-or-org",
  "repo": "repository-name"
}

响应示例：

{
  "count": 2,
  "releases": [
    {
      "id": 12345678,
      "name": "v1.0.0",
      "tag_name": "v1.0.0",
      "published_at": "2025-03-15T10:00:00Z",
      "draft": false,
      "prerelease": false,
      "html_url": "https://github.com/owner/repo/releases/tag/v1.0.0",
      "body": "Release notes for version 1.0.0",
      "assets": [
        {
          "name": "app-v1.0.0.zip",
          "size": 1234567,
          "download_count": 42,
          "browser_download_url": "https://github.com/owner/repo/releases/download/v1.0.0/app-v1.0.0.zip",
          "created_at": "2025-03-15T10:05:00Z",
          "updated_at": "2025-03-15T10:05:00Z"
        }
      ],
      "author": {
        "login": "username",
        "html_url": "https://github.com/username"
      }
    },
    {
      "id": 87654321,
      "name": "v0.9.0",
      "tag_name": "v0.9.0",
      "published_at": "2025-03-01T10:00:00Z",
      "draft": false,
      "prerelease": true,
      "html_url": "https://github.com/owner/repo/releases/tag/v0.9.0",
      "body": "Pre-release notes for version 0.9.0",
      "assets": [],
      "author": {
        "login": "username",
        "html_url": "https://github.com/username"
      }
    }
  ]
}

为拉取请求启用自动合并

使用 enable_pull_request_automerge 工具为特定拉取请求启用自动合并：

{
  "owner": "username-or-org",
  "repo": "repository-name",
  "pull_number": 123,
  "merge_method": "SQUASH"
}

响应示例：

{
  "success": true,
  "message": "Auto-merge enabled successfully",
  "pullRequest": {
    "id": "PR_kwDOABCD123_456",
    "title": "Add new feature",
    "number": 123,
    "autoMergeEnabled": true,
    "enabledAt": "2025-08-21T03:00:00Z",
    "mergeMethod": "SQUASH"
  }
}

注意：启用自动合并需要满足以下条件：

1. 必须在仓库设置中启用自动合并
2. GitHub 令牌必须拥有该仓库的写入权限
3. 拉取请求必须处于开放状态，且尚未启用自动合并
4. 启用后，当所有必需的状态检查通过且审批条件满足时，PR 将自动合并