# Rundeck MCP Server

A Model Context Protocol (MCP) server that provides seamless integration between AI assistants and Rundeck automation platform. This server exposes 9 comprehensive Rundeck tools through the MCP protocol, enabling AI assistants to interact with Rundeck servers in real-time.

## 🚀 Features

- **9 Rundeck Tools**: Complete set of tools for Rundeck management
- **Real-time Data**: Live connection to Rundeck API
- **Docker Integration**: Containerized deployment with Rundeck
- **Kubernetes Ready**: Production-grade K8s manifests with NetworkPolicies
- **MCP Protocol**: Standard interface for AI assistant integration
- **AI Assistant Compatible**: Works with any MCP-compatible AI assistant
- **Production Ready**: Tested and verified working integration

## 📋 Available Tools

| Tool | Description |
|------|-------------|
| `get_rundeck_system_info` | Get server status, version, memory, CPU stats |
| `list_rundeck_projects` | List all available Rundeck projects |
| `list_rundeck_jobs` | List jobs in a specific project |
| `get_rundeck_job` | Get detailed job information |
| `execute_rundeck_job` | Execute jobs with optional arguments |
| `get_rundeck_execution` | Get execution status and details |
| `list_rundeck_job_executions` | View job execution history |
| `analyze_rundeck_job_performance` | Performance analytics for jobs |
| `abort_rundeck_execution` | Stop running job executions |

## 🏗️ Architecture

```
┌─────────────┐    MCP Protocol    ┌──────────────┐    Rundeck API    ┌─────────────┐
│ AI Assistant│◄──────────────────►│  MCP Server  │◄─────────────────►│   Rundeck   │
│             │                    │   (Docker)   │                   │   Server    │
└─────────────┘                    └──────────────┘                   └─────────────┘
```

## 🐳 Quick Start

### Option 1: Docker Compose (Recommended for Development)

```bash
# Clone and navigate to directory
git clone <repository>
cd rundeck-mcp

# Set your Rundeck API token
echo "RUNDECK_API_TOKEN=YOUR_RUNDECK_API_TOKEN_HERE" > .env

# Deploy containers
docker-compose up -d

# Check status
docker-compose ps
```

### Option 2: Kubernetes (Recommended for Production)

```bash
# Clone and navigate to directory
git clone <repository>
cd rundeck-mcp

# Update API token in k8s/secret.yaml
echo -n "your-actual-token" | base64
# Replace the value in k8s/secret.yaml

# Deploy to Kubernetes
./k8s/deploy.sh

# Or with specific network policy mode
NETWORK_POLICY_MODE=strict ./k8s/deploy.sh
```

## ☸️ Kubernetes Deployment

### Quick Deploy

```bash
# Standard deployment
./k8s/deploy.sh

# Strict security mode
NETWORK_POLICY_MODE=strict ./k8s/deploy.sh

# With monitoring support
NETWORK_POLICY_MODE=monitoring ./k8s/deploy.sh
```

### Network Policy Modes

| Mode | Description | Use Case |
|------|-------------|----------|
| `standard` | Basic network isolation with external access | Development/Testing |
| `strict` | Maximum security, minimal network access | High-security environments |
| `monitoring` | Standard + monitoring namespace access | Production with observability |

### Kubernetes Resources

| Resource | Description |
|----------|-------------|
| `namespace.yaml` | Dedicated rundeck-mcp namespace |
| `configmap.yaml` | Non-sensitive configuration |
| `secret.yaml` | API tokens and sensitive data |
| `pvc.yaml` | Persistent storage for Rundeck data |
| `rundeck-deployment.yaml` | Rundeck server deployment |
| `rundeck-service.yaml` | ClusterIP + NodePort services |
| `mcp-deployment.yaml` | MCP server deployment |
| `ingress.yaml` | External access via Ingress |
| `network-policy*.yaml` | Network security policies |

### Access Methods

```bash
# NodePort (immediate access)
http://localhost:30440

# Port-forward (secure tunnel)
kubectl port-forward service/rundeck-service 4440:4440 -n rundeck-mcp

# Ingress (with DNS setup)
http://rundeck.local
```

### Useful Commands

```bash
# Check deployment status
kubectl get pods -n rundeck-mcp

# View logs
kubectl logs -f deployment/rundeck -n rundeck-mcp
kubectl logs -f deployment/rundeck-mcp-server -n rundeck-mcp

# Check network policies
kubectl get networkpolicies -n rundeck-mcp

# Scale deployments
kubectl scale deployment rundeck --replicas=2 -n rundeck-mcp

# Cleanup
./k8s/cleanup.sh
```

### 2. Configure MCP Client

#### For Kiro IDE

Create `.kiro/settings/mcp.json` in your workspace:

```json
{
  "mcpServers": {
    "rundeck": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--network=rundeck-mcp_rundeck-network",
        "-e", "RUNDECK_URL=http://rundeck:4440",
        "-e", "RUNDECK_API_TOKEN=admin_token_change_me",
        "-e", "RUNDECK_API_VERSION=50",
        "-e", "PYTHONUNBUFFERED=1",
        "rundeck-mcp-rundeck-mcp"
      ],
      "disabled": false,
      "autoApprove": [
        "list_projects",
        "list_jobs",
        "get_job",
        "get_execution",
        "list_job_executions",
        "analyze_job_performance",
        "get_system_info"
      ]
    }
  }
}
```

**Note**: Environment variables (RUNDECK_URL, RUNDECK_API_TOKEN, etc.) are automatically loaded from the Docker container's environment, so you don't need to specify them in the MCP configuration.

#### For Other MCP-Compatible Clients

```json
{
  "mcpServers": {
    "rundeck": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--network=rundeck-mcp_rundeck-network",
        "-e", "RUNDECK_URL=http://rundeck:4440",
        "-e", "RUNDECK_API_TOKEN=admin_token_change_me",
        "-e", "RUNDECK_API_VERSION=50",
        "-e", "PYTHONUNBUFFERED=1",
        "rundeck-mcp-rundeck-mcp"
      ],
      "disabled": false,
      "autoApprove": []
    }
  }
}
```

### 3. Test the Integration

#### Using Kiro IDE

Once the MCP server is configured, you can use the Rundeck MCP tools directly:

```bash
# List available MCP tools
mcp_rundeck_list_projects
mcp_rundeck_list_jobs
mcp_rundeck_get_system_info
```

Or ask Kiro naturally:
- **"Get my Rundeck system information"**
- **"List my Rundeck projects"** 
- **"Show me jobs in the TRIVAGO project"**
- **"Execute the TEST job"**

#### Using Other MCP Clients

Using your MCP-compatible AI assistant, ask:
- **"Get my Rundeck system information"**
- **"List my Rundeck projects"**
- **"Show me job execution history"**

## 📁 Project Structure

```
rundeck-mcp/
├── rundeck_mcp_server.py    # Main MCP server implementation
├── docker-compose.yml       # Docker services configuration
├── Dockerfile              # Container build configuration
├── entrypoint.sh           # Container startup script
├── requirements.txt        # Python dependencies
├── .env                    # Environment variables
├── k8s/                    # Kubernetes deployment manifests
│   ├── deploy.sh           # Automated deployment script
│   ├── cleanup.sh          # Cleanup script
│   ├── namespace.yaml      # Kubernetes namespace
│   ├── configmap.yaml      # Configuration data
│   ├── secret.yaml         # Sensitive data (API tokens)
│   ├── pvc.yaml            # Persistent volume claims
│   ├── rundeck-deployment.yaml    # Rundeck server deployment
│   ├── rundeck-service.yaml       # Rundeck services
│   ├── mcp-deployment.yaml        # MCP server deployment
│   ├── ingress.yaml               # External access
│   ├── network-policy.yaml        # Standard network policies
│   ├── network-policy-strict.yaml # Strict security policies
│   └── network-policy-monitoring.yaml # Monitoring support
└── README.md              # This file
```

## 🔧 Configuration

### Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `RUNDECK_URL` | Rundeck server URL | `http://rundeck:4440` |
| `RUNDECK_API_TOKEN` | Rundeck API authentication token | Required |
| `RUNDECK_API_VERSION` | Rundeck API version | `50` |

### Docker Services

| Service | Port | Description |
|---------|------|-------------|
| `rundeck` | 4440 | Rundeck server web interface |
| `rundeck-mcp` | - | MCP server (internal) |

## 🧪 Testing & Verification

### ✅ Verified Working Integration

The integration has been tested and verified working with:
- **Kiro IDE**: Full MCP integration with Docker-based server
- **Rundeck**: 5.8.0-20241205
- **API Version**: 50
- **MCP Protocol**: Compatible with MCP-enabled AI assistants
- **Real-time Data**: Live system information retrieval
- **Docker**: Containerized deployment with automatic environment configuration
- **Kubernetes**: Production-ready deployment with NetworkPolicies

### Test MCP Server Connection

```bash
# Check container status
docker-compose ps

# View MCP server logs
docker logs rundeck-mcp-server

# Test Rundeck connectivity
docker exec rundeck-mcp-server python3 -c "
import asyncio, os
from rundeck_mcp_server import RundeckMCPServer
os.environ['RUNDECK_URL'] = 'http://rundeck:4440'
os.environ['RUNDECK_API_TOKEN'] = 'YOUR_RUNDECK_API_TOKEN_HERE'
os.environ['RUNDECK_API_VERSION'] = '50'
server = RundeckMCPServer()
print(asyncio.run(server.get_system_info()))
"
```

### Test with Kiro IDE

1. Ensure Docker containers are running: `docker-compose ps`
2. Open Kiro IDE in the project directory
3. Verify MCP configuration is loaded in `.kiro/settings/mcp.json`
4. Use MCP tools directly:
   ```bash
   mcp_rundeck_get_system_info
   mcp_rundeck_list_projects
   mcp_rundeck_list_jobs project="TRIVAGO"
   ```
5. Or ask Kiro: **"Get my Rundeck system information"**

### Test with Other AI Assistants

1. Open your MCP-compatible AI assistant
2. Ensure MCP configuration is loaded
3. Ask: **"Get my Rundeck system information"**
4. Verify real-time data is returned

### Expected Output

```json
{
  "system": {
    "rundeck": {
      "version": "5.8.0-20241205",
      "apiversion": "50",
      "build": "5.8.0-20241205",
      "serverUUID": "a14bc3e6-75e8-4fe4-a90d-a16dcc976bf6"
    },
    "stats": {
      "memory": {
        "free": 428099752,
        "total": 918552576,
        "unit": "byte"
      },
      "cpu": {
        "processors": 12,
        "loadAverage": {
          "average": 0,
          "unit": "percent"
        }
      }
    },
    "os": {
      "name": "Linux",
      "version": "6.10.14-linuxkit",
      "arch": "amd64"
    }
  }
}
```

## 🔍 Troubleshooting

### Common Issues

**MCP Server Not Starting**
```bash
# Check logs
docker logs rundeck-mcp-server

# Restart container
docker restart rundeck-mcp-server
```

**Rundeck Connection Failed**
```bash
# Verify Rundeck is running
curl http://localhost:4440

# Check API token
docker exec rundeck-mcp-server env | grep RUNDECK
```

**AI Assistant MCP Not Working**
1. Verify MCP configuration file exists (`.kiro/settings/mcp.json` for Kiro)
2. Check MCP server logs in your AI assistant
3. Restart AI assistant to reload MCP configuration
4. For Kiro: Check the MCP Server view in the feature panel

### Health Checks

```bash
# Container health
docker-compose ps

# Rundeck health
curl http://localhost:4440/api/50/system/info

# MCP server process
docker exec rundeck-mcp-server ps aux | grep python
```

## 📊 Performance

- **Memory Usage**: ~50MB per container
- **Response Time**: <2 seconds for most operations
- **Concurrent Requests**: Supports multiple simultaneous MCP calls
- **API Rate Limits**: Respects Rundeck API throttling

## 🔐 Security

- API tokens stored in environment variables
- Container network isolation
- No external ports exposed for MCP server
- Rundeck authentication required

## 🚀 Production Deployment

### Resource Requirements

- **CPU**: 1 core minimum
- **Memory**: 2GB minimum (1GB Rundeck + 1GB overhead)
- **Storage**: 5GB for logs and data
- **Network**: Internal container networking

### Scaling Considerations

- Single MCP server instance per Rundeck server
- Multiple AI assistant instances can connect to same MCP server
- Rundeck handles concurrent API requests

## 📝 API Reference

### System Information
```python
# Get comprehensive system status
await server.get_system_info()
```

### Project Management
```python
# List all projects
await server.list_projects()

# List jobs in project
await server.list_jobs("project-name")
```

### Job Execution
```python
# Execute job
await server.execute_job("job-id", {"param": "value"})

# Check execution status
await server.get_execution("execution-id")
```

## 🎯 Example Usage with AI Assistant

### With Kiro IDE

Once configured, you can use both direct MCP tool calls and natural language:

**Direct MCP Tool Usage:**
```bash
# Get system information
mcp_rundeck_get_system_info

# List projects  
mcp_rundeck_list_projects

# List jobs in a project
mcp_rundeck_list_jobs project="TRIVAGO"

# Execute a job
mcp_rundeck_execute_job job_id="5a2584fb-d01f-496b-a035-830940b53025"
```

**Natural Language with Kiro:**
```
You: "Get my Rundeck system information"
Kiro: [Calls mcp_rundeck_get_system_info]
      "Your Rundeck server is version 5.8.0-20241205, running on Linux 
       with 12 CPU cores and 408 MB free memory..."

You: "List my Rundeck projects"  
Kiro: [Calls mcp_rundeck_list_projects]
      "You currently have 1 project configured: TRIVAGO project created on
       December 20, 2025"

You: "Show me jobs in the TRIVAGO project"
Kiro: [Calls mcp_rundeck_list_jobs with project="TRIVAGO"]
      "Found 1 job in TRIVAGO project: TEST job (ID: 5a2584fb-d01f-496b-a035-830940b53025)
       in the TEST group, currently enabled and scheduled"
```

### With Other MCP Clients

Once configured, you can use natural language with your AI assistant:

```
You: "Get my Rundeck system information"
AI: [Calls get_rundeck_system_info via MCP]
    "Your Rundeck server is version 5.8.0-20241205, running on Linux 
     with 12 CPU cores and 408 MB free memory..."

You: "List my Rundeck projects"  
AI: [Calls list_rundeck_projects via MCP]
    "You currently have 1 project configured: TRIVAGO project created on
     December 20, 2025"

You: "What's the server uptime?"
AI: [Calls get_rundeck_system_info via MCP]
    "Your Rundeck server has been running for 2.6 minutes, started at
     15:47:29 UTC"
```

## 🤝 Contributing

1. Fork the repository
2. Create feature branch
3. Test with Docker deployment
4. Submit pull request

## 📄 License

MIT License - see LICENSE file for details

## 🆘 Support

- **Issues**: GitHub Issues
- **Documentation**: This README
- **Testing**: Use provided test commands

---

**Status**: ✅ Production Ready & Verified Working  
**Last Updated**: December 2025  
**Version**: 1.0.0  
**Tested With**: MCP-compatible AI assistants, Rundeck 5.8.0, MCP Protocol  
**Created By**: dinfiesta@gmail.com