Integrates with GitHub API to manage GitHub Actions runners through the Actions Runner Controller, including authentication and configuration management
Provides comprehensive management of GitHub Actions runners in Kubernetes clusters, including installation, scaling, monitoring, and troubleshooting of self-hosted runners
Enables deployment and management of GitHub Actions Runner Controller (ARC) in Kubernetes clusters, with tools for installation, scaling, status monitoring, and policy validation
ARC Config MCP Server
π AI-Powered GitHub Actions Runner Controller Management
A comprehensive TypeScript MCP (Model Context Protocol) server that transforms complex ARC operations into conversational AI interactions. Deploy, monitor, and manage GitHub Actions runners with natural language commands.
π― QUICK START: Add to your MCP client:
ghcr.io/tsviz/arc-config-mcp:latest
β Ask AI: "Install ARC in my cluster" β Done! β¨
π― What is ARC Config MCP Server?
ARC Config MCP Server is an enterprise-grade automation tool that bridges the gap between complex Kubernetes-based GitHub Actions runner management and intuitive AI-powered operations. Instead of memorizing kubectl commands and YAML configurations, simply tell the AI what you want to accomplish.
π Key Capabilities
π€ Natural Language Operations: Transform complex ARC tasks into simple conversations
β‘ Intelligent Installation: Zero-configuration ARC deployment with smart defaults
π Real-time Monitoring: Live status dashboards and proactive health monitoring
π Enterprise Security: Built-in policy validation and compliance enforcement
π° Cost Intelligence: Automatic scaling and resource optimization
π οΈ Self-Healing: Automated troubleshooting and remediation
π Quick Start
π― MCP Client Integration (Recommended)
The primary way to use ARC Config MCP Server is through MCP client integration with AI assistants like GitHub Copilot in VSCode.
Add this configuration to your MCP client settings:
β¨ That's it! Your AI assistant now has access to powerful ARC management capabilities. Simply ask natural language questions like:
"Install ARC controller in my cluster"
"Scale my runners to handle more load"
"Check why my runners are failing"
"Optimize costs for my GitHub Actions setup"
π³ Alternative: Docker Standalone
π οΈ Alternative: Local Development
π Natural Language Examples
Transform complex ARC operations into simple conversations:
ποΈ Architecture Overview
Components
Natural Language Processor: Converts human intent to structured operations
ARC Policy Engine: Validates configurations against enterprise policies
Kubernetes Orchestrator: Manages cluster resources and deployments
GitHub Integration: Handles runner registration and lifecycle
Monitoring Hub: Tracks performance and health metrics
π οΈ Complete Tool Catalog
π― Core ARC Operations
Tool | Purpose | Example Usage |
| Deploy ARC to Kubernetes | Install with custom config |
| Comprehensive health check | Monitor all components |
| Horizontal runner scaling | Handle load spikes |
| Full lifecycle management | Create/update/delete runners |
| Policy compliance check | Ensure security standards |
π€ AI-Powered Features
Tool | Purpose | Example Usage |
| Convert speech to action | "Scale up for deployment" |
| Automated diagnostics | Find and fix problems |
| Resource efficiency | Reduce unnecessary spending |
| Operational insights | Weekly performance summaries |
π§ Infrastructure Tools
Tool | Purpose | Example Usage |
| Network policy setup | Secure runner communication |
| Credential management | Rotate GitHub tokens |
| Configuration backup | Disaster recovery prep |
| Version management | Keep ARC up-to-date |
π Prerequisites & Requirements
System Requirements
Node.js: 18.0+ (LTS recommended)
Kubernetes: 1.24+ (tested up to 1.30)
Memory: 512MB+ for server
Storage: 100MB for installation
Kubernetes Permissions
The server requires these cluster permissions:
Namespaces: List, create, watch
Deployments: Full CRUD operations
Services: Create, update, delete
ConfigMaps/Secrets: Manage runner configurations
RBAC: Create service accounts and roles
GitHub Requirements
Personal Access Token with scopes:
repo
(for repository access)admin:org
(for organization runners)workflow
(for Actions management)
Organization/Repository admin permissions
GitHub Actions enabled
π§ Installation & Configuration
Environment Configuration
Create a .env
file with your settings:
VS Code + GitHub Copilot Integration
Configure MCP Server (already shown above): The JSON configuration from the Quick Start section works directly with VS Code + GitHub Copilot.
Enable MCP in GitHub Copilot: Add to your VS Code settings:
{ "github.copilot.enable": { "*": true, "mcp": true } }Start using natural language commands with GitHub Copilot to manage your ARC infrastructure!
Production Deployment
Kubernetes Deployment
Docker Compose
π¨ Usage Patterns & Examples
1. First-Time ARC Installation
2. Scaling for High Load
3. Troubleshooting Runner Issues
4. Security Compliance Check
π Security & Best Practices
π‘οΈ Security Framework
Our security model implements defense-in-depth principles:
π¨ Security Policies
The server includes built-in security policies:
Critical Security Rules
Container images must be from approved registries
No privileged containers allowed
Resource limits must be specified
Network policies required for all namespaces
Access Control Policies
GitHub tokens must have minimal required scopes
Kubernetes RBAC follows least-privilege principle
MCP client authentication required in production
Operational Security
All operations are logged and auditable
Sensitive data is masked in logs
Failed operations trigger security alerts
π Secure Configuration Example
β οΈ Security Notice: This tool provides administrative access to Kubernetes clusters and GitHub repositories. Always follow your organization's security policies and use appropriate access controls.
π Monitoring & Observability
π Built-in Metrics
The server exposes comprehensive metrics for monitoring:
π Health Checks
Multiple health check endpoints:
/health
- Basic server health/health/kubernetes
- Cluster connectivity/health/github
- GitHub API status/health/runners
- Runner status summary
π Grafana Dashboard
Pre-built dashboard for comprehensive monitoring:
π Advanced Features
π― Cost Optimization Engine
Intelligent cost management for runner infrastructure:
π€ Predictive Scaling
AI-powered scaling based on workload patterns:
π οΈ Self-Healing Capabilities
Automated problem detection and resolution:
π§ͺ Testing & Validation
π¬ Comprehensive Test Suite
Run the full test suite to ensure reliability:
π― Test Coverage
Current test coverage metrics:
Unit Tests: 94% line coverage
Integration Tests: 87% API coverage
E2E Tests: 78% workflow coverage
Security Tests: 100% vulnerability checks
ποΈ Local Testing Environment
Set up a complete local testing environment:
π CI/CD Integration
GitHub Actions Workflow
Example workflow for automated ARC management:
π API Reference
MCP Protocol Integration
The server implements the full MCP specification:
REST API Endpoints
When running in HTTP mode, these endpoints are available:
π€ Contributing
We welcome contributions to improve ARC Config MCP Server!
π Getting Started
Fork the repository
Create a feature branch:
git checkout -b feature/amazing-feature
Set up development environment:
npm install npm run dev:setupMake your changes
Run tests:
npm test
Submit a pull request
π Development Guidelines
Follow TypeScript best practices
Maintain 90%+ test coverage
Update documentation for new features
Follow conventional commit messages
Ensure all security checks pass
π Code Review Process
All contributions go through our review process:
Automated Checks: CI/CD pipeline validation
Security Review: Vulnerability scanning
Performance Review: Load testing for critical paths
Documentation Review: Ensure docs are updated
Maintainer Review: Final approval by core team
π Troubleshooting
Common Issues
Installation Problems
Runtime Issues
Performance Issues
π Debug Mode
Enable detailed logging for troubleshooting:
π Getting Help
Documentation: docs/
GitHub Issues: Create an issue
Discussions: GitHub Discussions
Official ARC Docs: GitHub Actions Runner Controller
Security Issues: security@tsviz.com
π Learning Resources
π Essential Reading
π₯ Video Tutorials
ARC MCP Server Quick Start (5 min)
Advanced Configuration Guide (15 min)
Troubleshooting Common Issues (10 min)
π‘ Best Practices Guide
π Roadmap
π― Upcoming Features
Version 1.6.0 (Next Release)
Multi-cluster Support: Manage ARC across multiple Kubernetes clusters
Advanced Cost Analytics: ML-powered cost prediction and optimization
Webhook Integration: Real-time event processing from GitHub
Custom Policy DSL: Domain-specific language for policy configuration
Version 1.7.0 (Q2 2024)
GitOps Integration: ArgoCD and Flux compatibility
Advanced Scheduling: Complex workload-aware runner scheduling
Integration Hub: Pre-built integrations with popular DevOps tools
Mobile Dashboard: React Native app for on-the-go monitoring
Version 2.0.0 (Q3 2024)
Multi-Cloud Support: AWS, GCP, Azure runner orchestration
AI-Powered Optimization: GPT-4 powered operational intelligence
Enterprise SSO: SAML, OIDC, and LDAP integration
Compliance Framework: SOC2, ISO27001, PCI-DSS automation
πΊοΈ Long-term Vision
Transform ARC management from manual operations to fully autonomous, AI-driven infrastructure that:
Predicts and prevents issues before they occur
Optimizes costs automatically across cloud providers
Ensures compliance with evolving security standards
Scales intelligently based on development team patterns
π License & Legal
License
This project is licensed under the MIT License - see the LICENSE file for details.
Third-Party Dependencies
Node.js Ecosystem: Various MIT and Apache 2.0 licensed packages
Kubernetes Client: Apache 2.0 License
GitHub API: Used under GitHub Terms of Service
Security Disclosure
For security vulnerabilities, please email security@tsviz.com instead of using public issues.
Contributing License Agreement
By contributing to this project, you agree that your contributions will be licensed under the same MIT License.
π Related Projects & Ecosystem
Official Projects
ARC Config Repo: Original ARC configuration and policies
K8s MCP Server: General Kubernetes management MCP server
Community Projects
Actions Runner Controller: The core ARC project
GitHub ARC Official Docs: Official GitHub documentation
Model Context Protocol: Protocol specification and tools
GitHub Copilot: AI pair programmer integration
Complementary Tools
Monitoring: Prometheus, Grafana, DataDog integration examples
Security: Falco, OPA Gatekeeper policy examples
GitOps: ArgoCD, Flux configuration templates
Cost Management: Kubecost, OpenCost integration guides
π Ready to transform your ARC operations?
Get Started β’ View Examples β’ Join Community
Transforming GitHub Actions runner management from manual kubectl commands to conversational AI-powered automation β¨
This server cannot be installed
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
Enables natural language management of GitHub Actions Runner Controller (ARC) in Kubernetes clusters. Supports automated installation, scaling, monitoring, and troubleshooting of GitHub Actions runners through conversational AI commands.
- π― What is ARC Config MCP Server?
- π Quick Start
- π Natural Language Examples
- ποΈ Architecture Overview
- π οΈ Complete Tool Catalog
- π Prerequisites & Requirements
- π§ Installation & Configuration
- π¨ Usage Patterns & Examples
- π Security & Best Practices
- π Monitoring & Observability
- π Advanced Features
- π§ͺ Testing & Validation
- π CI/CD Integration
- π API Reference
- π€ Contributing
- π Troubleshooting
- π Learning Resources
- π Roadmap
- π License & Legal
- π Related Projects & Ecosystem