README.md•7.55 kB
# VyOS MCP Server
A comprehensive **Model Context Provider (MCP)** server for **VyOS** network operating system automation. This server provides complete access to VyOS functionality through 25+ tools covering configuration management, operational commands, system administration, network diagnostics, and monitoring.
## 🚀 Features
- **Complete VyOS API Coverage**: All endpoints from VyOS HTTPS API
- **Type Safety**: Full TypeScript with Zod schema validation
- **MCP Compatible**: Works with Claude Desktop and other MCP clients
- **Streaming Support**: SSE transport for real-time communication
- **OpenAPI v3.1**: Auto-generated API documentation
- **Error Handling**: Robust error management with proper HTTP status codes
## 📋 Requirements
- **Bun** v1.0+ (JavaScript runtime and package manager)
- **TypeScript** v5.6+ with strict configuration
- **VyOS** system with HTTPS API enabled
- **MCP Client** (Claude Desktop, etc.)
## 🛠️ Installation
### From JSR (Recommended)
```bash
# Install from JSR
bunx jsr add @danielbodnar/vyos-mcp
# Or with other package managers
npx jsr add @danielbodnar/vyos-mcp
pnpm dlx jsr add @danielbodnar/vyos-mcp
yarn dlx jsr add @danielbodnar/vyos-mcp
```
### From Source
```bash
# Clone or navigate to project directory
cd vyos-mcp
# Install dependencies
bun install
# Generate OpenAPI specification
bun run openapi
# Generate documentation
bun run docs
# Start development server
bun run dev
```
### Using as a Library (JSR)
```typescript
import { VyOSClient } from "@danielbodnar/vyos-mcp";
// Create client instance
const client = new VyOSClient({
host: "https://vyos.example.com",
apiKey: "your-api-key",
timeout: 30000,
verifySSL: false
});
// Configure interface
await client.setConfig(["interfaces", "ethernet", "eth0", "address"], "192.168.1.1/24");
await client.commit("Configure LAN interface");
await client.save();
```
## 🔧 Configuration
### VyOS System Setup
Enable the HTTPS API on your VyOS system:
```bash
# Enter configuration mode
configure
# Enable HTTPS API
set service https api keys id my-api-key key 'your-secure-api-key-here'
# Configure HTTPS certificates (optional, for production)
set service https certificates system-generated-certificate
# Commit and save
commit
save
exit
```
### MCP Client Configuration
Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
```json
{
"mcpServers": {
"vyos": {
"command": "bun",
"args": ["run", "/path/to/vyos-mcp/src/index.ts"],
"env": {}
}
}
}
```
## 🎯 Usage
### 1. Connect to VyOS System
```typescript
// Use the vyos-connect tool
const connection = await vyosConnect({
host: "https://192.168.1.1",
apiKey: "your-api-key",
timeout: 30000,
verifySSL: false // For self-signed certificates
});
```
### 2. Configuration Management
```typescript
// Show configuration
await vyosShowConfig({
path: ["interfaces", "ethernet"],
format: "json"
});
// Set configuration values
await vyosSetConfig({
path: ["interfaces", "ethernet", "eth0", "address"],
value: "192.168.1.1/24",
comment: "LAN interface configuration"
});
// Commit changes
await vyosCommit({
comment: "Updated interface configuration",
confirmTimeout: 10 // Auto-rollback in 10 minutes if not confirmed
});
// Save to startup config
await vyosSaveConfig();
```
### 3. Network Diagnostics
```typescript
// Ping connectivity test
await vyosPing({
host: "8.8.8.8",
count: 5,
timeout: 3
});
// Traceroute analysis
await vyosTraceroute({
host: "google.com",
maxHops: 30
});
```
### 4. System Monitoring
```typescript
// Comprehensive health check
await vyosHealthCheck({
includeInterfaces: true,
includeRouting: true,
includeServices: true,
includeResources: true
});
// Interface statistics
await vyosInterfaceStats();
// BGP status
await vyosBgpStatus();
```
## 🔍 Available Tools
### Authentication
- `vyos-connect` - Connect to VyOS system
### Configuration Management
- `vyos-show-config` - Retrieve configuration
- `vyos-set-config` - Set configuration values
- `vyos-delete-config` - Delete configuration nodes
- `vyos-config-exists` - Check configuration existence
- `vyos-return-values` - Get configuration values
- `vyos-commit` - Commit pending changes
- `vyos-save-config` - Save to startup config
### Operational Commands
- `vyos-show-operational` - Execute show commands
- `vyos-reset` - Execute reset commands
- `vyos-generate` - Execute generate commands
### System Management
- `vyos-system-info` - Get system information
- `vyos-reboot` - Reboot system
- `vyos-poweroff` - Power off system
- `vyos-health-check` - Comprehensive health assessment
### Network Interface Management
- `vyos-configure-interface` - Configure interface settings
- `vyos-interface-stats` - Get interface statistics
### Routing
- `vyos-configure-static-route` - Configure static routes
- `vyos-routing-table` - Display routing table
- `vyos-bgp-status` - Get BGP status
### Network Diagnostic Tools
- `vyos-ping` - Ping connectivity test
- `vyos-traceroute` - Traceroute network analysis
## 📖 Documentation
- **[API Documentation](./docs/index.html)** - Complete TypeDoc-generated documentation
- **[OpenAPI Specification](./openapi.json)** - REST API specification
- **[VyOS Official Docs](https://docs.vyos.io/)** - VyOS documentation
### Scripts
```bash
# Development
bun run dev # Start with hot reloading
bun run build # Build for production
bun run start # Start production server
# Documentation (Pure Bun/TypeScript)
bun run docs # Generate TypeDoc documentation
bun run docs:serve # Generate and serve docs on :8080
bun run docs:dev # Serve existing docs (no rebuild)
bun run docs:watch # Watch source files and rebuild docs
bun run docs:open # Generate, serve, and open in browser
bun run docs:clean # Clean generated documentation
bun run openapi # Generate OpenAPI specification
# Quality
bun run typecheck # TypeScript type checking
bun run lint # ESLint code quality
```
## 🏗️ Architecture
### Type Safety
- **Zod Schemas**: All API operations use Zod for runtime validation
- **TypeScript**: Strict typing throughout the codebase
- **Generated Types**: Type definitions derived from schemas
### Error Handling
- **HTTP Status Codes**: Proper 200/400/500 responses
- **VyOS API Errors**: Translated to meaningful messages
- **Network Timeouts**: Configurable timeout handling
- **Connection Management**: Automatic retry and reconnection
### Streaming
- **SSE Transport**: Server-Sent Events for real-time communication
- **Bridge Pattern**: Connects MCP server to transport layer
- **CORS Support**: Cross-origin requests for web clients
## 🤝 Contributing
1. Fork the repository
2. Create a feature branch
3. Add comprehensive JSDoc documentation
4. Include TypeScript type definitions
5. Add error handling and validation
6. Update tests and documentation
7. Submit a pull request
## 📄 License
MIT License - see [LICENSE](LICENSE) file for details.
## 🆘 Support
- **Issues**: [GitHub Issues](https://github.com/bitbuilder-io/vyos-mcp/issues)
- **VyOS Documentation**: [docs.vyos.io](https://docs.vyos.io/)
- **MCP Specification**: [Model Context Protocol](https://modelcontextprotocol.io/)
---
Built with ❤️ for network automation and infrastructure management.