OPNSense MCP Server

# Infrastructure as Code (IaC) Vision: MCP Ecosystem ## 🎯 Vision Statement Create a **fully AI-driven Infrastructure as Code platform** that manages your entire home network (and beyond) through natural language conversations. Think "Pulumi meets ChatGPT" - where infrastructure deployment, monitoring, and management happen through intelligent MCP servers that understand context, dependencies, and best practices. ## 🏗️ Architecture Overview ``` ┌─────────────────────────────────────────────────────────────────┐ │ AI Assistant (Claude) │ │ "Deploy a Minecraft server on VLAN 10" │ └───────────────────┬─────────────────────────────────────────────┘ │ ┌───────────────────▼─────────────────────────────────────────────┐ │ MCP Orchestrator Server │ │ • Natural language → Infrastructure intent │ │ • Dependency resolution & ordering │ │ • State management & rollback │ │ • Multi-server coordination │ └───────┬───────┬───────┬───────┬───────┬───────┬────────────────┘ │ │ │ │ │ │ ┌───────▼──┐ ┌──▼───┐ ┌▼──────┐ ┌▼─────┐ ┌▼────┐ ┌▼──────────┐ │ OPNSense │ │Docker│ │Proxmox│ │ DNS │ │Certs│ │Kubernetes │ │ MCP │ │ MCP │ │ MCP │ │ MCP │ │ MCP │ │ MCP │ └──────────┘ └──────┘ └───────┘ └──────┘ └─────┘ └───────────┘ │ │ │ │ │ │ ┌────▼───┐ ┌────▼───┐ ┌───▼──┐ ┌───▼──┐ ┌──▼──┐ ┌─────▼─────┐ │Firewall│ │Contain-│ │ VMs │ │Cloud-│ │Let's│ │ Cluster │ │ VLANs │ │ ers │ │ LXC │ │flare │ │Encr.│ │ Apps │ └────────┘ └────────┘ └──────┘ └──────┘ └─────┘ └───────────┘ ``` ## 🔧 Core Components ### 1. MCP Orchestrator (Master Server) The brain of the operation - translates high-level intents into coordinated actions across multiple MCP servers. **Key Features:** - **Intent Recognition**: Understands "Deploy a game server" means firewall rules + VLAN + container + DNS - **Dependency Graph**: Knows VLANs must exist before firewall rules reference them - **Transaction Management**: All-or-nothing deployments with automatic rollback - **State Reconciliation**: Detects drift and can restore desired state **Technology Stack:** ```typescript - Drizzle ORM + PostgreSQL (Infrastructure state) - Redis (Distributed locks & event bus) - Bull Queue (Async job processing) - Temporal (Workflow orchestration) ``` ### 2. OPNSense MCP Server (Network Foundation) ✅ **Current Implementation:** - ✅ Firewall rule management - ✅ VLAN configuration - ✅ DHCP management - ✅ Backup/restore operations - ✅ Enhanced caching with Drizzle + Redis **Next Steps:** - HAProxy load balancer configuration - WireGuard VPN automation - Traffic shaping policies - Intrusion detection rules ### 3. Docker MCP Server (Container Platform) **Planned Features:** - Container lifecycle management - Compose stack deployments - Volume & network management - Registry operations - Resource monitoring **Example Intent:** ``` "Deploy Minecraft server with 4GB RAM on gaming VLAN" → Creates container with resource limits → Attaches to correct network → Configures persistent storage ``` ### 4. Proxmox MCP Server (Virtualization) **Planned Features:** - VM creation & templates - LXC container management - Storage pool operations - Cluster management - Snapshot automation ### 5. DNS MCP Server (Name Resolution) **Planned Features:** - Cloudflare DNS management - Local DNS server config - Split-horizon DNS - DDNS updates - Certificate DNS challenges ### 6. Certificate MCP Server (TLS Management) **Planned Features:** - Let's Encrypt automation - Certificate distribution - Renewal management - Internal CA operations ## 📊 Data Architecture ### Shared PostgreSQL Schema ```sql -- Global infrastructure state CREATE TABLE infrastructure_resources ( id UUID PRIMARY KEY, type VARCHAR(50), -- 'firewall_rule', 'container', 'vm', etc provider VARCHAR(50), -- 'opnsense', 'docker', 'proxmox' name VARCHAR(255), state JSONB, dependencies UUID[], created_at TIMESTAMP, updated_at TIMESTAMP ); -- Deployment tracking CREATE TABLE deployments ( id UUID PRIMARY KEY, intent TEXT, -- Original user request plan JSONB, -- Execution plan status VARCHAR(50), started_at TIMESTAMP, completed_at TIMESTAMP, rollback_data JSONB ); -- Cross-server events CREATE TABLE infrastructure_events ( id UUID PRIMARY KEY, resource_id UUID, event_type VARCHAR(50), payload JSONB, timestamp TIMESTAMP ); ``` ### Redis Cache Strategy ``` Keys: - state:{provider}:{resource_type}:{id} - Resource state - lock:deployment:{id} - Deployment locks - queue:events:{provider} - Event queues - cache:query:{hash} - Query result cache ``` ## 🚀 Implementation Roadmap ### Phase 1: Foundation (Current) ✅ - [x] OPNSense MCP with enhanced caching - [x] PostgreSQL + Redis infrastructure - [x] Basic firewall & VLAN automation ### Phase 2: Container Platform (Q1 2025) - [ ] Docker MCP Server - [ ] Basic orchestrator for OPNSense + Docker - [ ] Simple deployment workflows ### Phase 3: Advanced Networking (Q2 2025) - [ ] DNS MCP Server - [ ] Certificate MCP Server - [ ] Load balancer automation - [ ] VPN provisioning ### Phase 4: Virtualization (Q3 2025) - [ ] Proxmox MCP Server - [ ] VM template management - [ ] Automated provisioning ### Phase 5: Intelligence Layer (Q4 2025) - [ ] ML-based resource optimization - [ ] Predictive scaling - [ ] Anomaly detection - [ ] Cost optimization ## 💡 Example Use Cases ### 1. Game Server Deployment ``` User: "Deploy a Minecraft server for 10 players" Orchestrator Actions: 1. Create VLAN 20 (Gaming) - OPNSense MCP 2. Configure DHCP range - OPNSense MCP 3. Add firewall rules (port 25565) - OPNSense MCP 4. Deploy container - Docker MCP 5. Create DNS record - DNS MCP 6. Monitor & alert setup - Monitoring MCP ``` ### 2. Development Environment ``` User: "Set up a dev environment for the web app" Orchestrator Actions: 1. Create dev VLAN - OPNSense MCP 2. Provision VM/container - Proxmox/Docker MCP 3. Install dependencies - Config MCP 4. Set up database - Database MCP 5. Configure reverse proxy - OPNSense MCP 6. Generate SSL cert - Certificate MCP ``` ### 3. Disaster Recovery ``` User: "Restore production from last Tuesday" Orchestrator Actions: 1. Identify all resources from timestamp 2. Restore network config - OPNSense MCP 3. Restore VMs/containers - Proxmox/Docker MCP 4. Restore data - Backup MCP 5. Update DNS - DNS MCP 6. Verify connectivity - Monitoring MCP ``` ## 🔐 Security Considerations ### Authentication & Authorization - mTLS between MCP servers - JWT tokens with scoped permissions - Audit logging for all operations ### Network Security - Dedicated management VLAN - Encrypted communication channels - Secret management (HashiCorp Vault integration) ### Compliance - Change tracking & approval workflows - Automated compliance checks - Policy as code enforcement ## 🎯 Success Metrics ### Technical KPIs - Deployment success rate > 99% - Mean time to provision < 2 minutes - Automatic rollback success > 95% - Cache hit ratio > 80% ### Business Value - 90% reduction in manual configuration - 75% faster incident resolution - 100% infrastructure documented as code - Zero configuration drift ## 🤝 Contributing ### Adding a New MCP Server 1. Implement base MCP interface 2. Add provider-specific logic 3. Register with orchestrator 4. Define resource schemas 5. Add integration tests ### Example MCP Interface ```typescript interface MCPProvider { // Resource operations create(resource: Resource): Promise<Resource> read(id: string): Promise<Resource> update(id: string, changes: Partial<Resource>): Promise<Resource> delete(id: string): Promise<void> // Bulk operations list(filter?: Filter): Promise<Resource[]> // Health & status health(): Promise<HealthStatus> // Provider-specific validateConfig(config: any): Promise<ValidationResult> } ``` ## 🚁 Monitoring & Observability ### Metrics (Prometheus) - Resource creation/deletion rates - API response times - Cache performance - Queue depths ### Logging (Loki) - Structured JSON logs - Correlation IDs - Request tracing ### Tracing (Jaeger) - Cross-MCP request flows - Performance bottlenecks - Dependency mapping ## 🌟 Future Vision ### AI-Driven Operations - Predictive maintenance - Anomaly detection - Auto-remediation - Capacity planning ### Multi-Cloud Extension - AWS MCP Server - Azure MCP Server - GCP MCP Server - Hybrid cloud orchestration ### Enterprise Features - RBAC with AD/LDAP - Approval workflows - Cost tracking - Compliance reporting --- **"Infrastructure as conversation, automation as intelligence"**