{"id":31559079,"url":"https://github.com/garthdb/act-testing-mcp","last_synced_at":"2026-01-20T16:51:48.907Z","repository":{"id":312320280,"uuid":"1047095382","full_name":"GarthDB/act-testing-mcp","owner":"GarthDB","description":"MCP server for testing GitHub Actions workflows locally using nektos/act. Provides AI assistants with direct access to run, validate, and debug workflows without trial-and-error cycles.","archived":false,"fork":false,"pushed_at":"2025-09-01T21:18:03.000Z","size":125,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-05T01:19:23.858Z","etag":null,"topics":["act","ai-tools","ci-cd","claude","cursor","github-actions","mcp","model-context-protocol","nektos-act","testing","workflow-testing"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/GarthDB.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-29T18:23:44.000Z","updated_at":"2025-09-01T21:18:05.000Z","dependencies_parsed_at":"2025-08-29T21:14:06.101Z","dependency_job_id":"2cfd8299-f352-4561-bc26-2c1089f920a6","html_url":"https://github.com/GarthDB/act-testing-mcp","commit_stats":null,"previous_names":["garthdb/act-testing-mcp"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/GarthDB/act-testing-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GarthDB%2Fact-testing-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GarthDB%2Fact-testing-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GarthDB%2Fact-testing-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GarthDB%2Fact-testing-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GarthDB","download_url":"https://codeload.github.com/GarthDB/act-testing-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GarthDB%2Fact-testing-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279043267,"owners_count":26091414,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-15T02:00:07.814Z","response_time":56,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["act","ai-tools","ci-cd","claude","cursor","github-actions","mcp","model-context-protocol","nektos-act","testing","workflow-testing"],"created_at":"2025-10-05T01:13:38.485Z","updated_at":"2025-10-15T03:33:25.160Z","avatar_url":"https://github.com/GarthDB.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Verified on MseeP](https://mseep.ai/badge.svg)](https://mseep.ai/app/f18a0332-2186-49a9-a29d-c0de85307440)\n\n# Act Testing MCP\n\n[![npm version](https://img.shields.io/npm/v/act-testing-mcp.svg)](https://www.npmjs.com/package/act-testing-mcp)\n[![npm downloads](https://img.shields.io/npm/dm/act-testing-mcp.svg)](https://www.npmjs.com/package/act-testing-mcp)\n[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)\n[![CI](https://github.com/GarthDB/act-testing-mcp/workflows/CI/badge.svg)](https://github.com/GarthDB/act-testing-mcp/actions)\n\nModel Context Protocol (MCP) server for testing GitHub Actions workflows locally using [nektos/act](https://github.com/nektos/act).\n\n## Purpose\n\nThis 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.\n\n## Features\n\n- **🔍 List Workflows**: Discover all available GitHub Actions workflows in any repository\n- **▶️ Run Workflows**: Execute workflows locally with act\n- **✅ Validate Syntax**: Check workflow files for errors before committing\n- **🎭 Custom Events**: Test workflows with custom event data to simulate different scenarios\n- **🐛 Debug Support**: Detailed logging and error reporting\n- **📊 Dependency Monitoring**: Track `act` compatibility and detect breaking changes\n- **🔐 Supply Chain Security**: Published with npm provenance attestations for verifiable builds\n\n## Prerequisites\n\n- **Docker Desktop** (running)\n- **nektos/act** installed ([Installation Guide](https://github.com/nektos/act#installation))\n- **Node.js 20+**\n\n### Installing nektos/act\n\n```bash\n# macOS\nbrew install act\n\n# Linux (with curl)\ncurl https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash\n\n# Windows (with chocolatey)\nchoco install act-cli\n\n# Or download from releases\n# https://github.com/nektos/act/releases\n```\n\n## Installation\n\n```bash\nnpm install -g act-testing-mcp\n```\n\n### Verifying Package Integrity\n\nThis package is published with [npm provenance](https://docs.npmjs.com/generating-provenance-statements) for enhanced supply-chain security. You can verify the package's attestations:\n\n```bash\nnpm audit signatures\n```\n\nOr clone and run locally:\n\n```bash\ngit clone https://github.com/GarthDB/act-testing-mcp.git\ncd act-testing-mcp\nnpm install\n```\n\n## Configuration\n\n### MCP Setup\n\nAdd to your MCP configuration (e.g., `.cursor/mcp.json` for Cursor IDE):\n\n#### Option 1: Using npx (Recommended)\n\n```json\n{\n  \"mcpServers\": {\n    \"act-testing\": {\n      \"command\": \"npx\",\n      \"args\": [\"act-testing-mcp\"]\n    }\n  }\n}\n```\n\n#### Option 2: Using global installation\n\n```json\n{\n  \"mcpServers\": {\n    \"act-testing\": {\n      \"command\": \"act-testing-mcp\"\n    }\n  }\n}\n```\n\n#### Option 3: With custom project path (if needed)\n\n```json\n{\n  \"mcpServers\": {\n    \"act-testing\": {\n      \"command\": \"npx\",\n      \"args\": [\"act-testing-mcp\"],\n      \"env\": {\n        \"PROJECT_ROOT\": \"/path/to/your/project\"\n      }\n    }\n  }\n}\n```\n\n#### Option 4: Local development\n\n```json\n{\n  \"mcpServers\": {\n    \"act-testing\": {\n      \"command\": \"node\",\n      \"args\": [\"./path/to/act-testing-mcp/index.js\"],\n      \"env\": {\n        \"PROJECT_ROOT\": \"/path/to/your/project\",\n        \"ACT_BINARY\": \"act\"\n      }\n    }\n  }\n}\n```\n\n\u003e **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](https://docs.browsermcp.io/setup-server#cursor) and resolves common NPX availability problems as mentioned in [continuedev/continue#4791](https://github.com/continuedev/continue/issues/4791).\n\n### Act Configuration\n\nCreate an `.actrc` file in your project root (copy from the example):\n\n```bash\n# Copy example configuration and customize paths\ncp mcp-config.example.json .cursor/mcp.json\n# Edit .cursor/mcp.json to set your PROJECT_ROOT path\n\n# Copy act configuration (optional)\ncp .actrc /path/to/your/project/.actrc\n```\n\n## Tools Provided\n\n### `list_workflows`\n\nLists all available GitHub Actions workflows in the repository.\n\n**Parameters:** None\n\n**Example:**\n\n```\n📋 **CI** (ci.yml)\n   Job: test (test)\n   Events: push, pull_request\n\n📋 **Release** (release.yml)\n   Job: release (release)\n   Events: workflow_dispatch\n```\n\n### `run_workflow`\n\nRuns a workflow locally using act.\n\n**Parameters:**\n\n- `workflow` (required): Workflow file name or job ID\n- `event` (optional): Event type (push, pull_request, etc.)\n- `dryRun` (optional): Show execution plan without running\n- `verbose` (optional): Enable detailed output\n- `env` (optional): Environment variables\n- `secrets` (optional): Secrets to provide\n- `eventData` (optional): Custom event data for testing\n\n**Examples:**\n\n```bash\n# Run CI workflow\nrun_workflow workflow=\"ci.yml\" event=\"push\"\n\n# Dry run with custom event data\nrun_workflow workflow=\"ci.yml\" event=\"pull_request\" dryRun=true eventData='{\"number\": 123}'\n\n# Run with environment variables\nrun_workflow workflow=\"release.yml\" env='{\"NODE_ENV\": \"production\"}'\n```\n\n### `validate_workflow`\n\nValidates workflow syntax and structure.\n\n**Parameters:**\n\n- `workflow` (required): Workflow file name to validate\n\n### `act_doctor`\n\nChecks act configuration and Docker setup.\n\n**Parameters:** None\n\n## Usage Examples\n\n### With AI Assistant (Claude)\n\nOnce configured, you can ask your AI assistant to test workflows directly:\n\n- _\"Test my CI workflow\"_\n- _\"Run the release workflow in dry-run mode\"_\n- _\"Check if my new workflow file is valid\"_\n- _\"Test the pull request workflow with custom PR data\"_\n\n### Direct Usage\n\n```bash\n# Start the MCP server\nnpm start\n\n# Run tests\nnpm test\n\n# Run with coverage\nnpm run test:coverage\n\n# Debug mode\nnpm run dev\n```\n\n## Development\n\n### Running Tests\n\n```bash\n# Install dependencies\nnpm install\n\n# Run all tests\nnpm test\n\n# Run with coverage\nnpm run test:coverage\n\n# Run in watch mode\nnpm run test:watch\n```\n\n### Testing Coverage\n\nThe tool includes comprehensive testing:\n\n- **Unit tests** with AVA framework\n- **Integration testing** with real act and Docker\n- **Code coverage** with c8 (targeting 70%+ for core logic)\n- **ES modules** with native Node.js support\n\n### Compatibility Monitoring\n\nTrack act compatibility over time:\n\n```bash\n# Create baseline\nnpm run compatibility:baseline\n\n# Check for changes\nnpm run compatibility:check\n\n# Generate detailed report\nnpm run compatibility:report\n```\n\n## Project Structure\n\n```\nact-testing-mcp/\n├── index.js              # Main MCP server\n├── package.json          # Dependencies and scripts\n├── README.md             # This file\n├── LICENSE               # Apache 2.0 license\n├── .actrc                # Act configuration example\n├── ava.config.js         # Test configuration\n├── mcp-config.example.json # MCP configuration example\n├── utils/                # Utility modules\n│   ├── act-helpers.js    # Core act integration\n│   └── act-monitor.js    # Compatibility monitoring\n├── scripts/              # Utility scripts\n│   └── check-act-compatibility.js\n├── test/                 # Test suites\n│   ├── index.test.js\n│   ├── act-compatibility.test.js\n│   ├── act-monitor.test.js\n│   └── utils.test.js\n└── docs/                 # Additional documentation\n    ├── SETUP.md\n    ├── GUIDE.md\n    ├── TESTING.md\n    └── DEPENDENCY_MONITORING.md\n```\n\n## Troubleshooting\n\n### Docker Issues\n\n```bash\n# Check Docker is running\ndocker ps\n\n# Pull required images\ndocker pull catthehacker/ubuntu:act-latest\n```\n\n### Act Issues\n\n```bash\n# Check act installation\nact --version\n\n# Test act with simple workflow\nact --list\n```\n\n### MCP Connection Issues\n\n1. Verify the MCP configuration file path\n2. Check that Node.js path is correct\n3. Ensure PROJECT_ROOT environment variable is set\n4. Check that the project has a `.github/workflows/` directory\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests for new functionality\n5. Ensure all tests pass\n6. Submit a pull request\n\n## License\n\nThis project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.\n\n## Related Projects\n\n- [nektos/act](https://github.com/nektos/act) - Run your GitHub Actions locally\n- [Model Context Protocol](https://github.com/modelcontextprotocol) - Protocol for AI assistant tool integration\n\n## Support\n\n- Create an [issue](https://github.com/GarthDB/act-testing-mcp/issues) for bug reports or feature requests\n- Check the [documentation](docs/) for detailed guides\n- Review existing [issues](https://github.com/GarthDB/act-testing-mcp/issues) for solutions\n\n---\n\n**Note**: This tool was originally developed for the [Adobe Spectrum Tokens](https://github.com/adobe/spectrum-tokens) project and has been extracted as a standalone, reusable MCP server.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgarthdb%2Fact-testing-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgarthdb%2Fact-testing-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgarthdb%2Fact-testing-mcp/lists"}