nazik/OctopusDeployMCPServerACI

Octopus MCP Server

A Model Context Protocol (MCP) server for Octopus Deploy that can be deployed to Azure Container Instances.

Features

• 🐙 Octopus Deploy Integration: Connect to your Octopus Deploy instance
• 🔄 MCP Protocol: Implements the Model Context Protocol for AI interactions
• 🚀 Azure Container Instances: Ready for cloud deployment
• 🔒 Security: Uses Azure Key Vault for secure secret storage
• 📊 Monitoring: Integrated with Azure Log Analytics
• 🔍 Health Checks: Built-in health and readiness endpoints
• 🔧 Configuration: Flexible configuration through environment variables

Quick Start

Prerequisites

• Docker installed locally
• Azure CLI installed and configured
• Azure Container Registry
• Octopus Deploy instance with API access

Local Development

1. Clone and setup:

   git clone <repository-url>
   cd octopus-mcp
   cp .env.example .env
   

2. Configure environment: Edit .env file with your Octopus Deploy and Azure settings:

   OCTOPUS_URL=https://your-octopus-instance.octopus.app
   OCTOPUS_API_KEY=API-XXXXXXXXXXXXXXXXXX
   OCTOPUS_SPACE=Default
   AZURE_SUBSCRIPTION_ID=00000000-0000-0000-0000-000000000000
   AZURE_RESOURCE_GROUP=rg-octopus-mcp-server
   

3. Install dependencies:

   npm install
   

4. Run locally:

   npm start
   

5. Test with Docker:

   docker-compose up
   

Azure Deployment

Option 1: Using the deployment script (Recommended)

1. Configure environment: Update .env file with all required variables

2. Run deployment:

   ./deploy.sh
   

Option 2: Manual deployment with Bicep

1. Build and push image:

   docker build -t your-registry.azurecr.io/octopus-mcp-server:latest .
   docker push your-registry.azurecr.io/octopus-mcp-server:latest
   

2. Deploy infrastructure:

   az deployment group create \
     --resource-group rg-octopus-mcp-server \
     --template-file infra/main.bicep \
     --parameters infra/main.parameters.json
   

Option 3: Direct YAML deployment

az container create \
  --resource-group rg-octopus-mcp-server \
  --file azure-container-instance.yml

Configuration

Environment Variables

Azure Configuration

API Endpoints

• Health Check: GET /health - Returns server health status
• Readiness Check: GET /ready - Returns readiness status
• Server Info: GET /info - Returns server information and capabilities
• Available Tools: GET /tools - Lists MCP tools

MCP Tools

The server provides the following MCP tools:

• list_projects - List all projects in the Octopus space
• list_environments - List all environments
• list_deployments - List deployments with filtering options

Security Features

• 🔐 Azure Key Vault: Secure storage for API keys and secrets
• 🛡️ Managed Identity: Azure AD identity for secure resource access
• 🔒 Helmet.js: Security headers and protections
• 🚫 CORS: Configurable cross-origin resource sharing
• 📝 Audit Logging: Comprehensive request and error logging

Monitoring & Observability

• Azure Log Analytics: Centralized logging
• Health Checks: Kubernetes-style liveness and readiness probes
• Metrics: Built-in performance and usage metrics
• Error Tracking: Structured error logging with stack traces

File Structure

octopus-mcp/
├── src/
│   ├── server.js          # Main MCP server
│   └── healthcheck.js     # Health check script
├── infra/
│   ├── main.bicep         # Azure infrastructure template
│   └── main.parameters.json # Deployment parameters
├── config/
│   └── server.json        # Server configuration
├── docker-compose.yml     # Local development
├── Dockerfile            # Container definition
├── azure-container-instance.yml # Direct ACI deployment
├── deploy.sh             # Deployment automation script
├── package.json          # Node.js dependencies
└── .env.example          # Environment template

Troubleshooting

Common Issues

1. Container fails to start:

   • Check environment variables in .env
   • Verify Octopus Deploy connectivity
   • Review container logs: az container logs --resource-group <rg> --name <container>

2. Health check failures:

   • Ensure port 8080 is accessible
   • Check network security groups
   • Verify container resource allocation

3. Authentication errors:

   • Validate Octopus API key permissions
   • Check Azure managed identity configuration
   • Verify Key Vault access policies

Viewing Logs

# Container logs
az container logs --resource-group rg-octopus-mcp-server --name octopus-mcp-server

# Log Analytics queries
az monitor log-analytics query \
  --workspace <workspace-id> \
  --analytics-query "ContainerInstanceLog_CL | where TimeGenerated > ago(1h)"

Development

Adding New MCP Tools

1. Extend the /tools endpoint in src/server.js
2. Implement the tool logic
3. Update the Docker image
4. Redeploy to Azure

Testing

# Run tests
npm test

# Lint code
npm run lint

# Local health check
npm run health

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

License

MIT License - see LICENSE file for details