mcp-server-vyos: Instructions file for Claude Code

CLAUDE.md

Project Overview

Python MCP server wrapping the VyOS HTTPS REST API. Exposes VyOS router management (config, operational commands, system management) and VyOS documentation as MCP tools.

Commands

uv sync --extra dev     # add --locked to match CI (fails on a stale uv.lock)
uv run pytest
uv run ruff check .
uv run ruff format --check .
uv run python -m vyos_mcp  # run server (stdio transport)

uv.lock is committed; CI installs with uv sync --locked. After changing dependencies in pyproject.toml, run uv lock and commit the result.

Architecture

• src/vyos_mcp/server.py — MCP server, tool registration (MCPServer)
• src/vyos_mcp/client.py — VyOS REST API client (auth, TLS, form-encoded)
• src/vyos_mcp/docs.py — VyOS docs client (GitHub API, TTL cache)

Key Design Decisions

• commit-confirm is the default for config changes (auto-rollback safety)
• VyOS API uses form-encoded POST with data (JSON) and key fields, NOT JSON body
• Self-signed TLS certs common on VyOS — skip verification by default
• API key via VYOS_API_KEY, router URL via VYOS_URL env vars
• Docs fetched live from vyos/vyos-documentation GitHub repo (branch: current)
• MCPServer shows the model only "Error executing tool " for exceptions that aren't ToolError. Register tools with @_tool() (server.py), which converts TimeoutError/RuntimeError/ValueError to ToolError so their text reaches the model

VyOS API Quirks (validated against real router)

• All POST endpoints use application/x-www-form-urlencoded with data and key fields
• Configure operations are slow (10-20s) — client uses 30s timeout
• confirm requires {"op": "confirm", "path": []} — path field is mandatory, even empty
• commit-confirm uses confirm_time as a top-level field alongside commands, not per-command (per-command is silently ignored → permanent commit). An armed response data contains "Initialized commit-confirm; N minutes to confirm before reload"
• A commit-confirm while one is pending still commits, then returns HTTP 400 "Another confirm is pending"; the pending timer reverts both on expiry
• reboot/poweroff require "path": ["now"]
• /retrieve supports three ops: showConfig, returnValues, exists
• Config diffs: /show rejects configuration compare (config-mode), and system commit diff N returns empty data for any N. system commit file N works (unknown N → success: true with a traceback in data), so config_diff diffs revision files client-side. The API has no running-vs-saved comparison
• ping/traceroute are NOT show subcommands — /show rejects them. /traceroute is a dedicated endpoint taking {"op": "traceroute", "host": ..., "vrf"?} and returns an mtr report in data (vrf is T9223, rolling ≥ 2026-08-24; older routers silently ignore unknown fields). /ping (vyos-1x T9224, rolling ≥ 2026.08.18) takes {"op": "ping", "host": ..., "count": 1–10 (default 5), "vrf"?}; older routers return 404 with an nginx HTML body. Both run the command as argv and return HTTP 400 with its output as error on a nonzero exit — for ping, any run with no reply