VyOS MCP Server

# VyOS MCP Container Setup This directory contains the containerization setup for running a local VyOS instance alongside the VyOS MCP server for development and testing. ## Architecture The setup consists of three containers: 1. **vyos-router**: VyOS router instance with HTTPS API enabled 2. **vyos-mcp-server**: The MCP server that connects to VyOS 3. **vyos-client**: Alpine Linux container for testing and management ## Quick Start ```bash # Start all services podman-compose up -d # Or with Docker Compose docker-compose up -d # Check status podman-compose ps ``` ## Container Details ### VyOS Router (`vyos-router`) - **Image**: `vyos/vyos-build:current` (VyOS 1.5 complete system) - **IP**: `192.168.100.10` - **Ports**: - `2222:22` (SSH) - `8443:443` (HTTPS API) - **API Key**: `vyos-mcp-secret-key` **✅ Note**: The `vyos/vyos-build:current` image contains a complete VyOS 1.5 system with all functionality including the HTTPS API. ### MCP Server (`vyos-mcp-server`) - **Image**: Built from local Containerfile - **IP**: `192.168.100.20` - **Ports**: `8080:8080` (MCP server) - **Connects to**: VyOS router at `vyos-router:443` ### Client Container (`vyos-client`) - **Image**: `alpine:latest` - **IP**: `192.168.100.30` - **Tools**: curl, jq, openssh-client - **Purpose**: Testing and management ## Usage ### Accessing VyOS ```bash # SSH to VyOS ssh vyos@localhost -p 2222 # Or from client container podman exec -it vyos-client ssh vyos@vyos-router # Test HTTPS API curl -k -X POST https://localhost:8443/rest/get/version \ -H "Content-Type: application/json" \ -d '{"key": "vyos-mcp-secret-key"}' ``` ### Using MCP Server ```bash # Test MCP server health curl http://localhost:8080/health # Access MCP server from client container podman exec -it vyos-client curl http://vyos-mcp-server:8080/health ``` ### Development For live development with code changes: ```bash # Start with development volume mount podman-compose up -d # Make changes to src/ - they will be reflected in the container # Restart only the MCP server podman-compose restart vyos-mcp ``` ## Configuration ### VyOS Configuration The VyOS instance is automatically configured via the `vyos-config/boot.sh` script with: - Management interface: `eth0` with IP `192.168.100.10/24` - HTTPS API enabled on port 443 - API key: `vyos-mcp-secret-key` - SSH service on port 22 - Basic firewall rules ## Building Proper VyOS Runtime Image The current `compose.yml` uses `vyos/vyos-build:current` which is a **build environment**, not a runtime VyOS image. For proper VyOS functionality with API access, you need to build a runtime image from a VyOS ISO. ### Quick Setup (Recommended) Use the provided script to build a proper VyOS runtime image: ```bash # Build VyOS runtime image (requires sudo for loop device access) sudo ./scripts/build-vyos-image.sh # Or specify a version sudo ./scripts/build-vyos-image.sh 1.5-rolling-202507120000 # Update compose.yml to use the built image # Replace: image: vyos/vyos-build:current # With: image: vyos-runtime:1.5-rolling-202507120000 ``` ### Manual Setup Following the [official VyOS Docker documentation](https://docs.vyos.io/en/latest/installation/virtual/docker.html): 1. **Download VyOS ISO**: ```bash curl -L -o vyos-1.5-rolling.iso \ https://github.com/vyos/vyos-rolling-nightly-builds/releases/download/1.5-rolling-202507120000/vyos-1.5-rolling-202507120000-generic-amd64.iso ``` 2. **Extract and Import**: ```bash # Mount ISO sudo losetup -P /dev/loop0 vyos-1.5-rolling.iso sudo mount /dev/loop0 /mnt # Extract filesystem sudo unsquashfs -d vyos-root /mnt/live/filesystem.squashfs # Import as Docker image cd vyos-root sudo tar -c . | docker import - vyos-runtime:1.5-rolling # Cleanup sudo umount /mnt sudo losetup -d /dev/loop0 ``` 3. **Update compose.yml**: ```yaml services: vyos-router: image: vyos-runtime:1.4-rolling # Use built image command: ["/sbin/init"] # ... rest of configuration ``` ### Production vs Development Images | Image Type | Purpose | VyOS API | Performance | Use Case | |------------|---------|-----------|-------------|-----------| | `vyos/vyos-build:current` | Build environment | ❌ No | Slow | Development only | | `vyos-runtime:*` (from ISO) | Runtime VyOS | ✅ Yes | Fast | Production/Testing | **Note**: The build environment is provided for convenience but lacks the actual VyOS runtime with API support. ### Environment Variables You can customize the setup by modifying environment variables in `compose.yml`: ```yaml environment: - VYOS_API_KEY=your-custom-key - VYOS_HOST=vyos-router - VYOS_PORT=443 - VYOS_PROTOCOL=https ``` ## Networking All containers are on the `vyos-network` bridge network: - Subnet: `192.168.100.0/24` - Gateway: `192.168.100.1` ## Volumes - `vyos-config`: Persistent VyOS configuration storage - Local `src/` directory mounted for development ## Troubleshooting ### Check container logs ```bash podman-compose logs vyos-router podman-compose logs vyos-mcp ``` ### Check VyOS status ```bash podman exec -it vyos-router vtysh -c "show version" ``` ### Verify API connectivity ```bash podman exec -it vyos-client curl -k https://vyos-router:443/rest/get/version \ -H "Content-Type: application/json" \ -d '{"key": "vyos-mcp-secret-key"}' ``` ### Reset VyOS configuration ```bash podman-compose down podman volume rm vyos-mcp_vyos-config podman-compose up -d ``` ## Container-Based Testing This project includes comprehensive container-based testing using testcontainers to ensure proper functionality against real VyOS instances. ### Test Types #### Unit Tests ```bash # Run unit tests (without containers) bun run test:unit ``` #### Container Tests ```bash # Run basic container smoke tests bun run test:container # Or use the test management script bun run scripts/test-containers.ts --type basic # Run full integration tests bun run scripts/test-containers.ts --type integration # Run MCP server tests against real VyOS bun run scripts/test-containers.ts --type mcp-server # Run all container tests bun run scripts/test-containers.ts --type all ``` ### Test Script Options The `scripts/test-containers.ts` script provides advanced container test management: ```bash # Basic usage bun run scripts/test-containers.ts # Options --type <type> # Test type: basic, integration, mcp-server, all --timeout <ms> # Test timeout in milliseconds --no-cleanup # Skip container cleanup after tests --verbose # Enable verbose test output --help # Show help message # Examples bun run scripts/test-containers.ts --type basic --timeout 300000 bun run scripts/test-containers.ts --type all --no-cleanup --verbose ``` ### Container Test Architecture The container tests use testcontainers to: 1. **Spin up real VyOS containers** with proper API configuration 2. **Test actual VyOS API interactions** (not mocked) 3. **Validate MCP server functionality** against real systems 4. **Ensure proper error handling** with real network conditions 5. **Test complete workflows** end-to-end ### Test Files - `tests/container-basic.test.ts` - Lightweight smoke tests for CI - `tests/container-integration.test.ts` - Comprehensive VyOS API testing - `tests/container-mcp-server.test.ts` - MCP server functionality testing - `tests/utils/container-manager.ts` - Container management utilities ### CI/CD Integration For CI environments, the basic container tests are designed to: - Start quickly (under 3 minutes) - Use minimal resources - Provide essential coverage - Clean up automatically ### Development Workflow 1. **Unit Tests First**: Always run `bun run test:unit` for fast feedback 2. **Container Tests**: Run container tests for integration validation 3. **Manual Testing**: Use `podman-compose up -d` for manual testing 4. **Cleanup**: Use `bun run container:reset` to reset state ## Security Notes - The API key `vyos-mcp-secret-key` is for development only - VyOS runs in privileged mode for network functionality - All containers are on an isolated bridge network - For production, use proper secrets management and network policies - Container tests use temporary, isolated VyOS instances