virtfusion-mcp/CLAUDE.md

VirtFusion MCP Server

Overview

MCP server wrapping the VirtFusion virtualization control panel REST API (84 endpoints). Built with TypeScript, @modelcontextprotocol/sdk, and Zod for input validation.

Architecture

src/
  index.ts          — Entry point: env validation, McpServer + StdioServerTransport setup
  client.ts         — VirtFusionClient: fetch wrapper with Bearer auth, query param filtering
  errors.ts         — VirtFusionApiError class + formatErrorResponse() for MCP error results
  types.ts          — Shared interfaces (PaginatedResponse, QueryParams)
  tools/
    index.ts        — Barrel: registerAllTools() wires all 17 modules to McpServer
    general.ts      — 1 tool (test connection)
    hypervisors.ts  — 2 tools
    hypervisor-groups.ts — 3 tools
    servers.ts      — 18 tools (largest module)
    servers-power.ts — 4 tools
    servers-network.ts — 5 tools
    servers-firewall.ts — 4 tools
    servers-traffic.ts — 4 tools
    ip-blocks.ts    — 3 tools
    backups.ts      — 1 tool
    dns.ts          — 1 tool
    media.ts        — 2 tools
    packages.ts     — 2 tools
    queue.ts        — 1 tool
    ssh-keys.ts     — 4 tools
    users.ts        — 7 tools
    self-service.ts — 19 tools

Conventions

Tool naming

• snake_case: {category}_{action}_{noun} (e.g., servers_power_boot, ip_blocks_list)
• Every tool gets a human-readable description as second arg to server.tool()

Module pattern

Each src/tools/*.ts file exports one function:

export function registerXxxTools(server: McpServer, client: VirtFusionClient): void {
  server.tool('tool_name', 'Description', { ...zodSchema }, async (params) => { ... });
}

Error handling

• All tool handlers wrap logic in try/catch
• Catch block returns formatErrorResponse(error) which produces { isError: true, content: [...] }
• VirtFusionApiError carries statusCode, statusText, and errorBody

HTTP client

• VirtFusionClient methods: get(), post(), put(), delete()
• All accept (path, body?, query?) — query params with undefined values are filtered out
• 204 responses return { success: true }

How to add a new tool

1. Identify the API endpoint in openapi.yaml
2. Find (or create) the matching src/tools/*.ts module by tag
3. Add a server.tool() call following the existing pattern
4. Register it in src/tools/index.ts if it's a new module
5. Update endpoint-manifest.json: npm run extract-endpoints > endpoint-manifest.json
6. Update the tool count in README.md

Commands

npm run build              # Compile TypeScript to dist/
npm run dev                # Run with tsx (development)
npm run extract-endpoints  # Parse openapi.yaml → stdout JSON
npm run check-endpoint-drift  # Compare spec vs manifest

Environment variables

• VIRTFUSION_API_URL — Required. e.g., https://cp.example.com/api/v1
• VIRTFUSION_API_TOKEN — Required. Bearer token from VirtFusion admin panel.