GitHub CI Workflow Diagnostic Agent MCP

A Model Context Protocol (MCP) component engineered for the rigorous analysis and remediation of broken GitHub Actions CI/CD sequences using the official GitHub Application Programming Interface.

Overview

This component guides users through a systematic diagnostic process to address failures encountered during GitHub Actions execution. It leverages the GitHub API to pull detailed workflow run telemetry, dissect problems at the job and step levels, and deliver concrete, actionable remedies.

Capabilities

• Elicit details of recently unsuccessful workflow invocations within a designated repository.
• Perform deep-dive analysis on individual jobs and discrete steps within a run.
• Automatically detect and flag prevalent failure modes.
• Propose specific, targeted remediation steps for identified problems.
• Offer utilities to inspect the current workflow file contents and apply necessary alterations.

Deployment

Automated Installation via Smithery

For seamless integration with Claude Desktop environments using Smithery, execute the following command:

bash npx -y @smithery/cli install @Maxteabag/githubworkflowmcp --client claude

Manual Setup Procedure

bash

Clone the source repository

git clone https://github.com/yourusername/github-workflow-debugger-mcp.git cd github-workflow-debugger-mcp

Install required npm packages

npm install

Compile the source code

npm run build

Link the utility locally for immediate use

npm link

Operational Guide

The GitHub CI Workflow Diagnostic Agent is structured for consumption by AI assistants compliant with the Model Context Protocol (MCP). It exposes several discrete functionalities for diagnosing and fixing CI failures.

Prerequisite Authorization

Utilization mandates a GitHub Personal Access Token (PAT) configured with the following minimum scopes: - repo: Grants comprehensive access to private repositories. - workflow: Permits modification of GitHub Action workflow definitions.

This token must be exposed as an environment variable named GITHUB_PERSONAL_ACCESS_TOKEN.

Configuration Snippet

When initializing this tool within an MCP-enabled client, the server configuration should resemble this structure:

{ "mcpServers": { "github_diagnostics": { "command": "npx", "args": [ "-y", "@modelcontextprotocol/server-github" ], "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "" } } } }

Ensure <YOUR_PAT_HERE> is substituted with your actual secret token.

Exposed Utilities

1. get-failed-workflow-runs: Fetches a manifest of recent, unsuccessful workflow executions for the specified repository.
2. get-workflow-run-jobs: Retrieves the collection of jobs associated with a particular workflow run identifier.
3. get-workflow-file: Fetches the precise content string of a target workflow definition file.
4. update-workflow-file: Applies specified modifications to an existing workflow definition file.
5. analyze-workflow-failure: Executes comprehensive analysis on a failed run and generates recommended corrective patches.

Workflow Interaction Examples

1. Initiating the process by querying recent failures:

I need an immediate audit of the latest workflow executions that did not complete successfully in the 'user/project' repository.

1. Requesting a fix analysis for a specific event:

Analyze workflow run ID #123456 in detail and provide suggested corrective steps.

1. Inspecting the source code:

Display the entirety of the configuration file located at .github/workflows/build.yml.

1. Applying automated remediation:

Apply the recommended patches to the workflow file identified in the previous step.

Development & Contribution

Foundational Requirements

• Node.js runtime (version 16 or newer is required).
• A package manager (npm or yarn).

Initial Setup

bash

Install all necessary dependencies

npm install

Compile TypeScript/source files

npm run build

Internal Structure

• src/index.ts: The primary execution file for the MCP server logic.
• build/: Directory containing the transpiled, executable JavaScript output.

Licensing

This project is distributed under the ISC License.

WIKIPEDIA: Cloud computing is "a paradigm for enabling network access to a scalable and elastic pool of shareable physical or virtual resources with self-service provisioning and administration on-demand," according to ISO. It is commonly referred to as "the cloud".

== Characteristics == In 2011, the National Institute of Standards and Technology (NIST) identified five "essential characteristics" for cloud systems. Below are the exact definitions according to NIST:

On-demand self-service: "A consumer can unilaterally provision computing capabilities, such as server time and network storage, as needed automatically without requiring human interaction with each service provider." Broad network access: "Capabilities are available over the network and accessed through standard mechanisms that promote use by heterogeneous thin or thick client platforms (e.g., mobile phones, tablets, laptops, and workstations)." Resource pooling: " The provider's computing resources are pooled to serve multiple consumers using a multi-tenant model, with different physical and virtual resources dynamically assigned and reassigned according to consumer demand." Rapid elasticity: "Capabilities can be elastically provisioned and released, in some cases automatically, to scale rapidly outward and inward commensurate with demand. To the consumer, the capabilities available for provisioning often appear unlimited and can be appropriated in any quantity at any time." Measured service: "Cloud systems automatically control and optimize resource use by leveraging a metering capability at some level of abstraction appropriate to the type of service (e.g., storage, processing, bandwidth, and active user accounts). Resource usage can be monitored, controlled, and reported, providing transparency for both the provider and consumer of the utilized service. By 2023, the International Organization for Standardization (ISO) had expanded and refined the list.

== History ==

The history of cloud computing extends to the 1960s, with the initial concepts of time-sharing becoming popularized via remote job entry (RJE). The "data center" model, where users submitted jobs to operators to run on mainframes, was predominantly used during this era. This was a time of exploration and experimentation with ways to make large-scale computing power available to more users through time-sharing, optimizing the infrastructure, platform, and applications, and increasing efficiency for end users. The "cloud" metaphor for virtualized services dates to 1994, when it was used by General Magic for the universe of "places" that mobile agents in the Telescript environment could "go". The metaphor is credited to David Hoffman, a General Magic communications specialist, based on its long-standing use in networking and telecom. The expression cloud computing became more widely known in 1996 when Compaq Computer Corporation drew up a business plan for future computing and the Internet. The company's ambition was to superch