CLAUDE.md•5.26 kB
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Project Overview
This is a VyOS Model Context Provider (MCP) server built with the Muppet SDK. It provides MCP tools for interacting with VyOS network operating system configurations and operations. The project uses:
- **Muppet SDK**: For creating MCP servers with tool endpoints
- **Hono**: Web framework for HTTP routing and middleware
- **TypeScript**: Strict typing with ESNext features
- **Bun**: Runtime and package manager
- **SSE Transport**: Server-Sent Events for MCP communication
## Architecture
### Core Components
- `src/index.ts`: Main MCP server implementation with Hono routes
- `package.json`: Project configuration with Muppet, Hono, and MCP SDK dependencies
- `tsconfig.json`: TypeScript configuration with strict mode and ESNext target
### MCP Structure
The server follows the Muppet pattern:
1. **Tool Definition**: Routes with `describeTool()` for MCP tool metadata
2. **Validation**: Zod schemas with `mValidator()` for request validation
3. **Transport**: SSE transport layer for streaming MCP communication
4. **Bridge**: Connects MCP server to transport for client communication
## Development Commands
```bash
# Run development server with hot reloading
bun run dev
# Install dependencies
bun install
# Run TypeScript directly
bun --bun src/index.ts
```
## MCP Tool Development
### Adding New Tools
1. Create a new route with tool description:
```typescript
app.post(
"/tool-endpoint",
describeTool({
name: "tool-name",
description: "Tool description for MCP clients"
}),
mValidator("json", schema),
handler
);
```
2. Use Zod for input validation:
```typescript
const schema = z.object({
parameter: z.string()
});
```
3. Return properly typed responses:
```typescript
return c.json<ToolResponseType>([
{
type: "text",
text: "Response content"
}
]);
```
### VyOS Integration
When adding VyOS-specific tools:
- Use VyOS operational and configuration commands
- Handle VyOS CLI modes (operational vs configuration)
- Validate VyOS configuration syntax
- Consider VyOS version compatibility
- Use proper error handling for network operations
## Code Style
- Prefix Node.js imports with `node:` (e.g., `node:fs`)
- Use ESNext features and async/await
- Follow strict TypeScript configuration
- Use functional programming patterns
- Implement proper error handling with typed exceptions
## Dependencies
Core dependencies are aligned with Muppet ecosystem:
- `muppet`: Latest version for MCP server functionality
- `@modelcontextprotocol/sdk`: Official MCP TypeScript SDK
- `hono`: Web framework for API routing
- `@hono/standard-validator`: Hono validation middleware
- `@hono/zod-openapi`: OpenAPI integration for Hono
- `zod`: Schema validation and type safety
- `@asteasolutions/zod-to-openapi`: OpenAPI v3.1 specification generation
## VyOS API Coverage
This MCP server provides complete coverage of the VyOS HTTPS API with the following tools:
### Authentication
- `vyos-connect`: Connect to VyOS system with API credentials
### Configuration Management
- `vyos-show-config`: Retrieve configuration (full or partial paths)
- `vyos-set-config`: Set configuration values
- `vyos-delete-config`: Delete configuration nodes
- `vyos-config-exists`: Check if configuration path exists
- `vyos-return-values`: Get configuration values for a path
- `vyos-commit`: Commit pending changes (with optional confirm timeout)
- `vyos-save-config`: Save configuration to startup config
### Operational Commands
- `vyos-show-operational`: Execute show commands in operational mode
- `vyos-reset`: Execute reset commands
- `vyos-generate`: Execute generate commands
### System Management
- `vyos-system-info`: Get system information, version, and hardware details
- `vyos-reboot`: Reboot the system
- `vyos-poweroff`: Power off the system
- `vyos-health-check`: Comprehensive system health assessment
### Network Interface Management
- `vyos-configure-interface`: Configure interface settings (IP, MTU, description)
- `vyos-interface-stats`: Get interface statistics and status
### Routing
- `vyos-configure-static-route`: Configure static routing entries
- `vyos-routing-table`: Display routing table information
- `vyos-bgp-status`: Get BGP protocol status and neighbor information
### Network Diagnostic Tools
- `vyos-ping`: Execute ping connectivity tests
- `vyos-traceroute`: Execute traceroute network path analysis
## OpenAPI Specification
The server automatically generates a complete OpenAPI v3.1 specification that covers all endpoints:
```bash
# Generate OpenAPI spec
bun run openapi
```
This creates `openapi.json` with full documentation for:
- Authentication schemas
- Request/response models
- Error handling
- All VyOS API operations
- MCP tool definitions
## Architecture Highlights
- **Type-Safe**: Full TypeScript with Zod validation
- **Comprehensive**: Covers entire VyOS HTTPS API surface
- **Standards-Based**: OpenAPI v3.1 compliant
- **MCP Compatible**: Works with Claude Desktop and other MCP clients
- **Error Handling**: Robust error handling with proper HTTP status codes
- **Streaming**: SSE transport for real-time MCP communication