# 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:
```typescript
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

```bash
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.