diff --git a/Getting-Started.-.md b/Getting-Started.-.md new file mode 100644 index 0000000..4d762ef --- /dev/null +++ b/Getting-Started.-.md @@ -0,0 +1,128 @@ +# Getting Started + +This guide walks you through installing, configuring, and verifying the VirtFusion MCP server. + +## Prerequisites + +- **Node.js** 22 or later +- **VirtFusion** panel with Admin API access +- An API token generated from your VirtFusion admin panel + +## Installation + +### Via npx (no install needed) + +The fastest way to get started. Node.js will fetch and run the server directly: + +```bash +npx git+https://git.ezscale.cloud/EZSCALE/virtfusion-mcp.git +``` + +### Global install + +```bash +npm install -g git+https://git.ezscale.cloud/EZSCALE/virtfusion-mcp.git +``` + +### From source + +```bash +git clone https://git.ezscale.cloud/EZSCALE/virtfusion-mcp.git +cd virtfusion-mcp +npm install +npm run build +``` + +The `prepare` script automatically runs `tsc` during `npm install`, so the build step is handled for you when installing from git. + +## Configuration + +The server requires two environment variables: + +| Variable | Description | Example | +|---|---|---| +| `VIRTFUSION_API_URL` | Base URL of your VirtFusion API (including `/api/v1`) | `https://cp.example.com/api/v1` | +| `VIRTFUSION_API_TOKEN` | Admin API bearer token | `your-api-token-here` | + +### Generating an API Token + +1. Log in to your VirtFusion admin panel +2. Navigate to your API token settings +3. Generate a new token with the required scopes +4. Copy the token for use in configuration below + +## MCP Client Configuration + +### Claude Desktop + +Add the following to your `claude_desktop_config.json`: + +```json +{ + "mcpServers": { + "virtfusion": { + "command": "npx", + "args": ["-y", "git+https://git.ezscale.cloud/EZSCALE/virtfusion-mcp.git"], + "env": { + "VIRTFUSION_API_URL": "https://cp.example.com/api/v1", + "VIRTFUSION_API_TOKEN": "your-api-token" + } + } + } +} +``` + +### Claude Code + +```bash +claude mcp add virtfusion -- npx -y git+https://git.ezscale.cloud/EZSCALE/virtfusion-mcp.git \ + -e VIRTFUSION_API_URL=https://cp.example.com/api/v1 \ + -e VIRTFUSION_API_TOKEN=your-api-token +``` + +### VS Code / Cursor + +Add to your `.vscode/mcp.json`: + +```json +{ + "servers": { + "virtfusion": { + "command": "npx", + "args": ["-y", "git+https://git.ezscale.cloud/EZSCALE/virtfusion-mcp.git"], + "env": { + "VIRTFUSION_API_URL": "https://cp.example.com/api/v1", + "VIRTFUSION_API_TOKEN": "your-api-token" + } + } + } +} +``` + +### Running in Development Mode + +For local development or testing: + +```bash +VIRTFUSION_API_URL=https://cp.example.com/api/v1 \ +VIRTFUSION_API_TOKEN=your-token \ +npm run dev +``` + +## Verifying the Connection + +After configuring your MCP client, use the `general_test_connection` tool to verify everything is working. This tool calls the VirtFusion `/connect` endpoint and returns the API status. + +In Claude, you can simply ask: + +> "Test the VirtFusion connection" + +A successful response confirms your API URL and token are configured correctly. + +## Next Steps + +- Browse the [[Tool-Reference]] to see all available tools +- Read the [[Architecture]] page to understand how the server works +- Check [[API-Coverage]] to see which VirtFusion endpoints are supported + +--- \ No newline at end of file