# VyOS MCP Server

![VyOS Logo](https://docs.vyos.io/en/latest/_static/vyos-logo.png)

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.