Act Testing MCP

Model Context Protocol (MCP) server for testing GitHub Actions workflows locally using nektos/act.

Purpose

This MCP provides AI assistants (like Claude) with direct access to test GitHub Actions workflows locally, eliminating trial-and-error development cycles when working with CI/CD pipelines.

Features

• 🔍 List Workflows: Discover all available GitHub Actions workflows in any repository
• ▶️ Run Workflows: Execute workflows locally with act
• ✅ Validate Syntax: Check workflow files for errors before committing
• 🎭 Custom Events: Test workflows with custom event data to simulate different scenarios
• 🐛 Debug Support: Detailed logging and error reporting
• 📊 Dependency Monitoring: Track act compatibility and detect breaking changes
• 🔐 Supply Chain Security: Published with npm provenance attestations for verifiable builds

Prerequisites

• Docker Desktop (running)
• nektos/act installed (Installation Guide)
• Node.js 20+

Installing nektos/act

# macOS
brew install act

# Linux (with curl)
curl https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash

# Windows (with chocolatey)
choco install act-cli

# Or download from releases
# https://github.com/nektos/act/releases

Installation

npm install -g act-testing-mcp

Verifying Package Integrity

This package is published with npm provenance for enhanced supply-chain security. You can verify the package's attestations:

npm audit signatures

Or clone and run locally:

git clone https://github.com/GarthDB/act-testing-mcp.git
cd act-testing-mcp
npm install

Configuration

MCP Setup

Add to your MCP configuration (e.g., .cursor/mcp.json for Cursor IDE):

Option 1: Using npx (Recommended)

{
  "mcpServers": {
    "act-testing": {
      "command": "npx",
      "args": ["act-testing-mcp"]
    }
  }
}

Option 2: Using global installation

{
  "mcpServers": {
    "act-testing": {
      "command": "act-testing-mcp"
    }
  }
}

Option 3: With custom project path (if needed)

{
  "mcpServers": {
    "act-testing": {
      "command": "npx",
      "args": ["act-testing-mcp"],
      "env": {
        "PROJECT_ROOT": "/path/to/your/project"
      }
    }
  }
}

Option 4: Local development

{
  "mcpServers": {
    "act-testing": {
      "command": "node",
      "args": ["./path/to/act-testing-mcp/index.js"],
      "env": {
        "PROJECT_ROOT": "/path/to/your/project",
        "ACT_BINARY": "act"
      }
    }
  }
}

Note: Using npx (Option 1) is recommended as it avoids PATH issues and ensures you always use the latest version. The MCP server automatically detects the current working directory, so PROJECT_ROOT is only needed if you want to override the default behavior. This approach mirrors other MCP servers like Browser MCP and resolves common NPX availability problems as mentioned in continuedev/continue#4791.

Act Configuration

Create an .actrc file in your project root (copy from the example):

# Copy example configuration and customize paths
cp mcp-config.example.json .cursor/mcp.json
# Edit .cursor/mcp.json to set your PROJECT_ROOT path

# Copy act configuration (optional)
cp .actrc /path/to/your/project/.actrc

Tools Provided

list_workflows

Lists all available GitHub Actions workflows in the repository.

Parameters: None

Example:

📋 **CI** (ci.yml)
   Job: test (test)
   Events: push, pull_request

📋 **Release** (release.yml)
   Job: release (release)
   Events: workflow_dispatch

run_workflow

Runs a workflow locally using act.

Parameters:

• workflow (required): Workflow file name or job ID
• event (optional): Event type (push, pull_request, etc.)
• dryRun (optional): Show execution plan without running
• verbose (optional): Enable detailed output
• env (optional): Environment variables
• secrets (optional): Secrets to provide
• eventData (optional): Custom event data for testing

Examples:

# Run CI workflow
run_workflow workflow="ci.yml" event="push"

# Dry run with custom event data
run_workflow workflow="ci.yml" event="pull_request" dryRun=true eventData='{"number": 123}'

# Run with environment variables
run_workflow workflow="release.yml" env='{"NODE_ENV": "production"}'

validate_workflow

Validates workflow syntax and structure.

Parameters:

• workflow (required): Workflow file name to validate

act_doctor

Checks act configuration and Docker setup.

Parameters: None

Usage Examples

With AI Assistant (Claude)

Once configured, you can ask your AI assistant to test workflows directly:

• "Test my CI workflow"
• "Run the release workflow in dry-run mode"
• "Check if my new workflow file is valid"
• "Test the pull request workflow with custom PR data"

Direct Usage

# Start the MCP server
npm start

# Run tests
npm test

# Run with coverage
npm run test:coverage

# Debug mode
npm run dev

Development

Running Tests

# Install dependencies
npm install

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run in watch mode
npm run test:watch

Testing Coverage

The tool includes comprehensive testing:

• Unit tests with AVA framework
• Integration testing with real act and Docker
• Code coverage with c8 (targeting 70%+ for core logic)
• ES modules with native Node.js support

Compatibility Monitoring

Track act compatibility over time:

# Create baseline
npm run compatibility:baseline

# Check for changes
npm run compatibility:check

# Generate detailed report
npm run compatibility:report

Project Structure

act-testing-mcp/
├── index.js              # Main MCP server
├── package.json          # Dependencies and scripts
├── README.md             # This file
├── LICENSE               # Apache 2.0 license
├── .actrc                # Act configuration example
├── ava.config.js         # Test configuration
├── mcp-config.example.json # MCP configuration example
├── utils/                # Utility modules
│   ├── act-helpers.js    # Core act integration
│   └── act-monitor.js    # Compatibility monitoring
├── scripts/              # Utility scripts
│   └── check-act-compatibility.js
├── test/                 # Test suites
│   ├── index.test.js
│   ├── act-compatibility.test.js
│   ├── act-monitor.test.js
│   └── utils.test.js
└── docs/                 # Additional documentation
    ├── SETUP.md
    ├── GUIDE.md
    ├── TESTING.md
    └── DEPENDENCY_MONITORING.md

Troubleshooting

Docker Issues

# Check Docker is running
docker ps

# Pull required images
docker pull catthehacker/ubuntu:act-latest

Act Issues

# Check act installation
act --version

# Test act with simple workflow
act --list

MCP Connection Issues

1. Verify the MCP configuration file path
2. Check that Node.js path is correct
3. Ensure PROJECT_ROOT environment variable is set
4. Check that the project has a .github/workflows/ directory

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Related Projects

• nektos/act - Run your GitHub Actions locally
• Model Context Protocol - Protocol for AI assistant tool integration

Support

• Create an issue for bug reports or feature requests
• Check the documentation for detailed guides
• Review existing issues for solutions

Note: This tool was originally developed for the Adobe Spectrum Tokens project and has been extracted as a standalone, reusable MCP server.