GitHub Workflow Orchestration Utility Service

This TypeScript-based MCP component facilitates deep interaction with GitHub repositories, specifically targeting workflow management, artifact retrieval, and release metadata access.

Core Capabilities

This service exposes several discrete tools for automating GitHub operations:

• Workflow Discovery: Retrieve listings of defined GitHub Actions within a specified repository structure.
• Action Inspection: Obtain granular details regarding the configuration and required inputs for any specific GitHub Action definition file.
• Workflow Invocation: Dispatch runtime executions for workflows configured to respond to the workflow_dispatch event, optionally supplying runtime parameters.
• Release Polling: Fetch summaries for the most recent two published software releases associated with a project.
• PR Merge Control: Programmatically enable or enforce auto-merge policies on open Pull Requests.

Tool Definitions

list_repository_workflows

Retrieves all discoverable GitHub Actions workflows for a given repository.

• Mandatory Arguments: owner (Account name), repo (Project name)
• Optional Arguments: token (PAT for private repo access/rate limiting)
• Output: Workflow metadata including path, name, current status, and source content.

inspect_single_action

Fetches comprehensive metadata for a singular GitHub Action file (e.g., its inputs, requirements, execution runtime).

• Mandatory Arguments: owner, repo
• Optional Arguments: path (Defaults to 'action.yml'), ref (Git reference, defaults to 'main'), token
• Output: Detailed action schema, including input definitions (name, requirement status, defaults).

dispatch_workflow_run

Initiates an on-demand execution of a GitHub workflow.

• Mandatory Arguments: owner, repo, workflow_id (Filename or ID)
• Optional Arguments: ref (Branch/tag, default 'main'), inputs (Map of parameters matching workflow definition), token (Token must have workflow scope)
• Output: Details of the newly created workflow run (ID, status, execution URL).

fetch_latest_releases

Retrieves information pertaining to the two most recent official software releases.

• Mandatory Arguments: owner, repo
• Optional Arguments: token
• Output: A collection containing details for the top two releases, including tag names, publication dates, and associated assets.

set_pull_request_automerge

Configures a specified Pull Request to merge automatically upon fulfillment of all checks and approvals.

• Mandatory Arguments: owner, repo, pull_number
• Optional Arguments: merge_method (e.g., MERGE, SQUASH, REBASE; default MERGE), token
• Output: Confirmation status and updated PR metadata indicating auto-merge activation.

Deployment and Configuration

Integration into the system is streamlined, supporting both direct execution via package runners and static configuration embedding.

Recommended Initialization (npx)

This method bypasses manual dependency management:

{ "mcpServers": { "gh-automation-svc": { "command": "npx", "args": [ "-y", "@nextdrive/gh-workflow-automation-interface" ], "env": { "GITHUB_TOKEN_ENV_VAR": "your_provided_github_pat" } } } }

Authentication Strategy

Accessing protected resources (private repos, triggering workflows) requires authorization via a GitHub Personal Access Token (PAT). The service prioritizes tokens found via the following mechanisms:

1. Direct Environment Variable: GITHUB_TOKEN_ENV_VAR (as shown above).
2. Standard Environment Variable: GITHUB_TOKEN.
3. Local Configuration File: ~/.nextdrive-gh-interface/settings.json containing a githubToken field.

Development Lifecycle

Standard Node.js tooling is utilized for local development and building:

• Install Dependencies: npm install
• Build Artifact: npm run build
• Watch Mode for Iteration: npm run watch
• Debugging Utility: Launch the integrated MCP Inspector via npm run inspector.

Usage Illustrations

Example: Triggering a Deployment Workflow

To initiate a production deployment run:

{ "owner": "acme-corp", "repo": "app-service", "workflow_id": "deploy.yml", "inputs": { "target_env": "production", "skip_tests": "false" } }