GitHub Action 触发 MCP 服务器

一个用于 GitHub Actions 集成的 Model Context Protocol 服务器。

概述

这是一个基于 TypeScript 的 MCP 服务器，专为 GitHub Actions 集成设计。它提供了以下功能：

• 从仓库获取可用的 GitHub Actions 工具
• 获取特定 GitHub Action 的详细信息工具
• 触发 GitHub 工作流调度事件工具
• 从 GitHub 仓库获取最新发布的工具

功能

工具

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

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

• 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 个发布的信息

安装

推荐安装方法：使用 npx

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

json
{
"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. 安装包：
   bash
   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

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 配置文件中设置令牌：

json
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "your_github_token_here"
}#### 方法2：全局环境变量

设置 GITHUB_TOKEN 环境变量：

bash

在 Linux/MacOS 上

export GITHUB_TOKEN=your_github_token

在 Windows 上

set GITHUB_TOKEN=your_github_token

方法3：本地配置文件

编辑配置文件：

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

设置你的 GitHub 令牌：

json
{
"githubToken": "your_github_token"
}

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

开发

安装依赖项：
bash
npm install

构建服务器：
bash
npm run build

在开发过程中自动重建：
bash
npm run watch

调试

使用 MCP Inspector 进行调试：

bash
npm run inspector

Inspector 将提供一个 URL，以便您在浏览器中访问调试工具。

发布到 npm

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

1. 确保您已登录 npm 并具有向 @nextdrive 组织发布的权限：
   bash
   npm login

2. 构建项目：
   bash
   npm run build

3. 发布到 npm（组织范围内的包默认为私有，使用 --access public 可以使其公开）：
   bash
   npm publish --access public

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

使用示例

获取 GitHub Actions 列表

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

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

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

示例响应：

json
[
{
"id": 12345678,
"name": "CI",
"path": ".github/workflows/ci.yml",
"state": "active",
"url": "https://github.com/owner/repo/actions/workflows/ci.yml",
"content": "name: CI

on:
push:
branches: [ main ]
pull_request:
branches: [ main ]

jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Setup Node.js
uses: actions/setup-node@v2
with:
node-version: 16.x
- name: Install dependencies
run: npm ci
- name: Build
run: npm run build
- name: Test
run: npm test
"
}
]

获取详细的 GitHub Action 信息

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

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

示例响应：

json
{
"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 Workflow

使用 trigger_github_action 工具触发 GitHub workflow：

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

示例响应：

json
{
"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个版本：

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

示例响应：

json
{
"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": "版本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": "预发布版本0.9.0的发布说明",
"assets": [],
"author": {
"login": "username",
"html_url": "https://github.com/username"
}
}
]
}