Prophet731
3d0eed4f17
All checks were successful
CI / build (push) Successful in 32s
Complete MCP server wrapping all 84 VirtFusion Admin API endpoints: - Core HTTP client with Bearer auth and error handling - 17 tool modules organized by API category - Endpoint drift detection scripts and Gitea Actions CI/CD - Comprehensive README with configuration examples - CLAUDE.md for AI assistant onboarding Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
82 lines
3.0 KiB
Markdown
82 lines
3.0 KiB
Markdown
# 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.
|