@rarecloudio/mcp-server 0.1.0

package/README.md

@@ -0,0 +1,155 @@
+# @rarecloudio/mcp-server
+
+Model Context Protocol server for the [RareCloud](https://rarecloud.io) API.
+
+Drop into [Claude Code](https://claude.com/claude-code), Claude Desktop, [Cursor](https://cursor.com), or your own MCP client to let AI agents inspect and reason about your RareCloud account — list servers, browse the catalog, check billing, plan deployments.
+
+## What it does
+
+Exposes **20 read-only tools** wrapping the RareCloud REST API:
+
+| Category | Tool | Purpose |
+|---|---|---|
+| Catalog | `list_catalog_products` | Browse orderable plans, filter by kind/backend |
+| | `get_catalog_plan` | Full plan detail: specs + pricing + billing tracks |
+| | `list_regions` | Available datacenter regions |
+| | `list_images` | OS images (Ubuntu / Debian / Windows / ...) |
+| Services | `list_services` | All your running services (filter by category) |
+| | `get_service` | Detail on one service |
+| | `get_service_metrics` | CPU / RAM / disk / bandwidth time series |
+| | `list_backups` | Backups for one legacy VPS |
+| | `get_provisioning_state` | Setup state of a pending service (paid / unprovisioned / stuck) |
+| | `list_os_templates` | OS templates a legacy VPS can be reinstalled with |
+| | `list_upgrade_options` | Plans+cycles a service could upgrade/downgrade to |
+| Billing | `list_invoices` | Invoice history |
+| | `get_invoice` | Detail on one invoice |
+| | `get_credit_balance` | Current prepaid credit |
+| | `get_credit_ledger` | Credit movements (top-ups, vouchers, metering) |
+| Support | `list_tickets` | Support tickets (filter by status) |
+| | `get_ticket` | One ticket with its full thread |
+| Account | `get_account` | Profile (email, name, country) |
+| | `list_ssh_keys` | SSH keys on a server (per-service) |
+| | `get_account_limits` | Resource caps + current usage |
+
+## Read-only by design
+
+This release is **read-only**. No `create_server`, no `destroy`, no `snapshot create`. The reason is architectural: mutating actions need a derived, scoped token plus a mandatory plan-and-approve step before they're safe to expose to an LLM. That ships in a future release.
+
+In the meantime: the agent can read, recommend, and generate Terraform/CLI commands. The user copy-pastes them or runs them via [the RareCloud CLI](https://github.com/RareCloudio/rarecloud-io/tree/main/cli).
+
+## Install
+
+Requires Node.js 20+.
+
+```bash
+npm install -g @rarecloudio/mcp-server
+```
+
+Or run directly with `npx`:
+
+```bash
+npx @rarecloudio/mcp-server
+```
+
+## Configure
+
+Get an API token: **Dashboard → Account → API tokens → New token**. Scope it to read-only (`services:read`, `billing:read`, `account:read`, `catalog:read`). Copy it — shown once.
+
+Set the env var:
+
+```bash
+export RARECLOUD_API_TOKEN="rc_pat_..."
+```
+
+Optional, for self-hosted / staging instances:
+
+```bash
+export RARECLOUD_API_ENDPOINT="https://your-instance.example.com"
+```
+
+## Use with Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "rarecloud": {
+      "command": "npx",
+      "args": ["-y", "@rarecloudio/mcp-server"],
+      "env": {
+        "RARECLOUD_API_TOKEN": "rc_pat_..."
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop. The 20 tools become available under the 🔌 menu.
+
+## Use with Claude Code
+
+```bash
+claude mcp add rarecloud npx -- -y @rarecloudio/mcp-server \
+  -e RARECLOUD_API_TOKEN=rc_pat_...
+```
+
+## Use with Cursor
+
+Edit `~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "rarecloud": {
+      "command": "npx",
+      "args": ["-y", "@rarecloudio/mcp-server"],
+      "env": { "RARECLOUD_API_TOKEN": "rc_pat_..." }
+    }
+  }
+}
+```
+
+## Example prompts
+
+Once configured, try:
+
+- *"What VPS plans do you offer in Frankfurt?"* → uses `list_catalog_products` + `list_regions`
+- *"List my running servers and their monthly cost"* → `list_services` + per-service spec lookup
+- *"Am I close to any resource limits?"* → `get_account_limits`
+- *"Give me a Terraform config for a 2 vCPU / 4 GB VPS in The Hague"* → `get_catalog_plan` + composition
+
+## Develop locally
+
+```bash
+git clone https://github.com/RareCloudio/rarecloud-io
+cd rarecloud-io/mcp-server
+npm install
+npm run dev      # runs from source via tsx
+npm run build    # compiles to dist/
+```
+
+Then point Claude Desktop at your local checkout:
+
+```json
+{
+  "mcpServers": {
+    "rarecloud-dev": {
+      "command": "node",
+      "args": ["/absolute/path/to/rarecloud-io/mcp-server/dist/index.js"],
+      "env": { "RARECLOUD_API_TOKEN": "rc_pat_..." }
+    }
+  }
+}
+```
+
+## Security
+
+- Tokens never touch shell history (we use env vars, not CLI flags).
+- Each tool maps 1:1 to a RareCloud API endpoint; the MCP server doesn't aggregate or transform data beyond what the API returns.
+- Read-only scope — there is no path for an agent to mutate state via this server, even on a compromised token.
+- Revoke a token at any time: **Dashboard → Account → API tokens**. Revocation is instant, no propagation delay.
+
+## License
+
+MIT.

package/dist/client.d.ts

@@ -0,0 +1,23 @@
+export interface RareCloudClientConfig {
+    endpoint: string;
+    token: string;
+    userAgent?: string;
+}
+export interface APIErrorPayload {
+    code: string;
+    message: string;
+}
+export declare class APIError extends Error {
+    readonly code: string;
+    constructor(payload: APIErrorPayload);
+}
+export declare class RareCloudClient {
+    private readonly config;
+    constructor(config: RareCloudClientConfig);
+    get<T = unknown>(path: string, query?: Record<string, string | number | undefined>): Promise<T>;
+    post<T = unknown>(path: string, body?: unknown): Promise<T>;
+    delete<T = unknown>(path: string): Promise<T>;
+    private url;
+    private do;
+}
+export declare function clientFromEnv(): RareCloudClient;

package/dist/client.js

@@ -0,0 +1,83 @@
+// Tiny HTTP client for the RareCloud /v1 surface. Same envelope shape
+// the CLI + Terraform provider use: { ok: true, data: ... } or
+// { ok: false, error: { code, message } }.
+export class APIError extends Error {
+    code;
+    constructor(payload) {
+        super(`[${payload.code}] ${payload.message}`);
+        this.code = payload.code;
+    }
+}
+export class RareCloudClient {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    async get(path, query) {
+        const url = this.url(path, query);
+        return this.do('GET', url);
+    }
+    async post(path, body) {
+        return this.do('POST', this.url(path), body);
+    }
+    async delete(path) {
+        return this.do('DELETE', this.url(path));
+    }
+    url(path, query) {
+        const url = new URL(this.config.endpoint + path);
+        if (query) {
+            for (const [k, v] of Object.entries(query)) {
+                if (v === undefined || v === null || v === '')
+                    continue;
+                url.searchParams.set(k, String(v));
+            }
+        }
+        return url.toString();
+    }
+    async do(method, url, body) {
+        const headers = {
+            Authorization: `Bearer ${this.config.token}`,
+            'User-Agent': this.config.userAgent ?? 'rarecloud-mcp/0.1.0',
+        };
+        if (body !== undefined)
+            headers['Content-Type'] = 'application/json';
+        let resp;
+        try {
+            resp = await fetch(url, {
+                method,
+                headers,
+                body: body !== undefined ? JSON.stringify(body) : undefined,
+            });
+        }
+        catch (e) {
+            throw new APIError({ code: 'NETWORK_ERROR', message: e.message });
+        }
+        const text = await resp.text();
+        let env;
+        try {
+            env = JSON.parse(text);
+        }
+        catch {
+            throw new APIError({
+                code: 'INVALID_RESPONSE',
+                message: `Non-JSON response (HTTP ${resp.status}): ${text.slice(0, 200)}`,
+            });
+        }
+        if (!env.ok) {
+            throw new APIError(env.error ?? { code: 'UNKNOWN', message: `HTTP ${resp.status}` });
+        }
+        return (env.data ?? {});
+    }
+}
+export function clientFromEnv() {
+    const endpoint = process.env.RARECLOUD_API_ENDPOINT?.replace(/\/$/, '') ?? 'https://api.rarecloud.io';
+    const token = process.env.RARECLOUD_API_TOKEN;
+    if (!token) {
+        throw new APIError({
+            code: 'MISSING_TOKEN',
+            message: 'Set RARECLOUD_API_TOKEN to your personal access token (Dashboard → Account → API tokens).',
+        });
+    }
+    return new RareCloudClient({ endpoint, token });
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+// MCP server for RareCloud — exposes a read-only tool surface that lets
+// AI agents (Claude Code, Claude Desktop, Cursor, custom agents) inspect
+// a RareCloud account and reason about it.
+//
+// Design notes:
+//   - READ-ONLY by design. No create / destroy / mutate tools yet.
+//     Mutating actions need the derived-token + plan-and-approve flow
+//     described in docs/ideas/2026-05-22-agent-ai-architecture.md.
+//     Until that ships, the agent suggests and the user confirms in
+//     dashboard / CLI / Terraform.
+//   - Authenticates with a personal access token (Dashboard → Account →
+//     API tokens). Scope the token to *:read for safety.
+//   - Speaks stdio. To use with Claude Desktop, see README.md for the
+//     mcpServers config snippet.
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { clientFromEnv } from './client.js';
+import { TOOLS, findTool } from './tools/index.js';
+const SERVER_NAME = 'rarecloud';
+const SERVER_VERSION = '0.1.0';
+async function main() {
+    // Validate config early so the user sees a clear error instead of
+    // every tool call failing with the same MISSING_TOKEN.
+    try {
+        clientFromEnv();
+    }
+    catch (e) {
+        process.stderr.write(`${e.message}\n`);
+        process.exit(1);
+    }
+    const server = new Server({ name: SERVER_NAME, version: SERVER_VERSION }, { capabilities: { tools: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: TOOLS.map((t) => ({
+            name: t.name,
+            description: t.description,
+            inputSchema: t.inputSchema,
+        })),
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (req) => {
+        const tool = findTool(req.params.name);
+        if (!tool) {
+            return {
+                content: [{ type: 'text', text: `Unknown tool: ${req.params.name}` }],
+                isError: true,
+            };
+        }
+        const client = clientFromEnv();
+        const args = (req.params.arguments ?? {});
+        const result = await tool.handler(client, args);
+        // ServerResult is a union over sync/async/task shapes — our handlers
+        // are always sync-completion (content + isError). Cast keeps the
+        // SDK happy without forcing every tool to declare task metadata.
+        return result;
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // Stay alive until stdio closes.
+    process.stderr.write(`${SERVER_NAME} MCP server v${SERVER_VERSION} ready (${TOOLS.length} tools)\n`);
+}
+main().catch((e) => {
+    process.stderr.write(`Fatal: ${e.message}\n`);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/tools/account.d.ts

@@ -0,0 +1,4 @@
+import { type ToolDefinition } from './types.js';
+export declare const getAccount: ToolDefinition;
+export declare const listSshKeys: ToolDefinition;
+export declare const getAccountLimits: ToolDefinition;

package/dist/tools/account.js

@@ -0,0 +1,66 @@
+// Account tools — profile, SSH keys, limits. Read-only.
+import { APIError } from '../client.js';
+import { jsonResult, errorResult } from './types.js';
+export const getAccount = {
+    name: 'get_account',
+    description: 'Get the authenticated user\'s profile: email, name, country, billing currency, account creation date. Use for "what account am I on?" or to confirm identity before suggesting cross-account actions.',
+    inputSchema: {
+        type: 'object',
+        properties: {},
+        additionalProperties: false,
+    },
+    async handler(client) {
+        try {
+            const data = await client.get('/v1/account');
+            return jsonResult(data);
+        }
+        catch (e) {
+            return errorResult(e instanceof APIError ? e.message : e.message);
+        }
+    },
+};
+export const listSshKeys = {
+    name: 'list_ssh_keys',
+    description: 'List the SSH keys on a specific server (legacy VPS). SSH keys are per-server in the API, not account-wide. Pass a service_id from list_services.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            service_id: {
+                type: 'string',
+                description: 'Server ID from list_services.',
+            },
+        },
+        required: ['service_id'],
+        additionalProperties: false,
+    },
+    async handler(client, args) {
+        try {
+            // There is no account-wide ssh-keys endpoint; keys are per-service.
+            const id = args.service_id;
+            const data = await client.get(`/v1/services/${encodeURIComponent(id)}/ssh-keys`);
+            return jsonResult(data);
+        }
+        catch (e) {
+            return errorResult(e instanceof APIError ? e.message : e.message);
+        }
+    },
+};
+export const getAccountLimits = {
+    name: 'get_account_limits',
+    description: 'Get account resource limits and current usage (servers / vCPUs / snapshots / IPs / volumes / DNS zones / etc). Use before recommending a deploy to make sure the user has headroom.',
+    inputSchema: {
+        type: 'object',
+        properties: {},
+        additionalProperties: false,
+    },
+    async handler(client) {
+        try {
+            const data = await client.get('/v1/account/limits');
+            return jsonResult(data);
+        }
+        catch (e) {
+            return errorResult(e instanceof APIError ? e.message : e.message);
+        }
+    },
+};
+//# sourceMappingURL=account.js.map

package/dist/tools/account.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"account.js","sourceRoot":"","sources":["../../src/tools/account.ts"],"names":[],"mappings":"AAAA,wDAAwD;AAExD,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AACxC,OAAO,EAAuB,UAAU,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE1E,MAAM,CAAC,MAAM,UAAU,GAAmB;IACxC,IAAI,EAAE,aAAa;IACnB,WAAW,EAAE,uMAAuM;IACpN,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE,EAAE;QACd,oBAAoB,EAAE,KAAK;KAC5B;IACD,KAAK,CAAC,OAAO,CAAC,MAAM;QAClB,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;YAC7C,OAAO,UAAU,CAAC,IAAI,CAAC,CAAC;QAC1B,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,OAAO,WAAW,CAAC,CAAC,YAAY,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAE,CAAW,CAAC,OAAO,CAAC,CAAC;QAC/E,CAAC;IACH,CAAC;CACF,CAAC;AAEF,MAAM,CAAC,MAAM,WAAW,GAAmB;IACzC,IAAI,EAAE,eAAe;IACrB,WAAW,EAAE,kJAAkJ;IAC/J,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACV,UAAU,EAAE;gBACV,IAAI,EAAE,QAAQ;gBACd,WAAW,EAAE,+BAA+B;aAC7C;SACF;QACD,QAAQ,EAAE,CAAC,YAAY,CAAC;QACxB,oBAAoB,EAAE,KAAK;KAC5B;IACD,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,IAAI;QACxB,IAAI,CAAC;YACH,oEAAoE;YACpE,MAAM,EAAE,GAAG,IAAI,CAAC,UAAoB,CAAC;YACrC,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,GAAG,CAAC,gBAAgB,kBAAkB,CAAC,EAAE,CAAC,WAAW,CAAC,CAAC;YACjF,OAAO,UAAU,CAAC,IAAI,CAAC,CAAC;QAC1B,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,OAAO,WAAW,CAAC,CAAC,YAAY,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAE,CAAW,CAAC,OAAO,CAAC,CAAC;QAC/E,CAAC;IACH,CAAC;CACF,CAAC;AAEF,MAAM,CAAC,MAAM,gBAAgB,GAAmB;IAC9C,IAAI,EAAE,oBAAoB;IAC1B,WAAW,EAAE,qLAAqL;IAClM,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE,EAAE;QACd,oBAAoB,EAAE,KAAK;KAC5B;IACD,KAAK,CAAC,OAAO,CAAC,MAAM;QAClB,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,GAAG,CAAC,oBAAoB,CAAC,CAAC;YACpD,OAAO,UAAU,CAAC,IAAI,CAAC,CAAC;QAC1B,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,OAAO,WAAW,CAAC,CAAC,YAAY,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAE,CAAW,CAAC,OAAO,CAAC,CAAC;QAC/E,CAAC;IACH,CAAC;CACF,CAAC"}

package/dist/tools/billing.d.ts

@@ -0,0 +1,5 @@
+import { type ToolDefinition } from './types.js';
+export declare const listInvoices: ToolDefinition;
+export declare const getInvoice: ToolDefinition;
+export declare const getCreditBalance: ToolDefinition;
+export declare const getCreditLedger: ToolDefinition;

package/dist/tools/billing.js

@@ -0,0 +1,97 @@
+// Billing tools — invoices, credit balance, payment methods.
+// Read-only. AddFunds / payment-method mutations stay manual.
+import { APIError } from '../client.js';
+import { jsonResult, errorResult } from './types.js';
+export const listInvoices = {
+    name: 'list_invoices',
+    description: 'List invoices for the authenticated account: number, status (paid / unpaid / cancelled), issued date, total. Use for "summarize my last 6 months of spend" or "which invoices are unpaid".',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            status: {
+                type: 'string',
+                enum: ['unpaid', 'paid', 'cancelled', 'refunded', 'collections'],
+                description: 'Optional filter on invoice status.',
+            },
+            limit: {
+                type: 'number',
+                description: 'Cap results (default: 50, max: 200).',
+            },
+        },
+        additionalProperties: false,
+    },
+    async handler(client, args) {
+        try {
+            const data = await client.get('/v1/billing/invoices', {
+                status: args.status,
+                limit: args.limit,
+            });
+            return jsonResult(data);
+        }
+        catch (e) {
+            return errorResult(e instanceof APIError ? e.message : e.message);
+        }
+    },
+};
+export const getInvoice = {
+    name: 'get_invoice',
+    description: 'Get full details for a single invoice: every line item, taxes, payment method used, payment timestamp. Use after list_invoices when more detail is needed.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            invoice_id: {
+                type: 'string',
+                description: 'Invoice ID from list_invoices.',
+            },
+        },
+        required: ['invoice_id'],
+        additionalProperties: false,
+    },
+    async handler(client, args) {
+        try {
+            const id = args.invoice_id;
+            const data = await client.get(`/v1/billing/invoices/${encodeURIComponent(id)}`);
+            return jsonResult(data);
+        }
+        catch (e) {
+            return errorResult(e instanceof APIError ? e.message : e.message);
+        }
+    },
+};
+export const getCreditBalance = {
+    name: 'get_credit_balance',
+    description: 'Get the current account credit balance (Pattern A v2 prepaid credit). Use for "how much do I have left?", or to check before suggesting actions that would consume credit (cloud-compute hourly billing).',
+    inputSchema: {
+        type: 'object',
+        properties: {},
+        additionalProperties: false,
+    },
+    async handler(client) {
+        try {
+            const data = await client.get('/v1/billing/credit');
+            return jsonResult(data);
+        }
+        catch (e) {
+            return errorResult(e instanceof APIError ? e.message : e.message);
+        }
+    },
+};
+export const getCreditLedger = {
+    name: 'get_credit_ledger',
+    description: 'List credit ledger entries (top-ups, voucher redemptions, hourly metering debits, refunds) for the authenticated account. Use to explain "where did my credit go?" or to reconcile a balance.',
+    inputSchema: {
+        type: 'object',
+        properties: {},
+        additionalProperties: false,
+    },
+    async handler(client) {
+        try {
+            const data = await client.get('/v1/billing/credit/ledger');
+            return jsonResult(data);
+        }
+        catch (e) {
+            return errorResult(e instanceof APIError ? e.message : e.message);
+        }
+    },
+};
+//# sourceMappingURL=billing.js.map

package/dist/tools/billing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"billing.js","sourceRoot":"","sources":["../../src/tools/billing.ts"],"names":[],"mappings":"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"}

package/dist/tools/catalog.d.ts

@@ -0,0 +1,5 @@
+import { type ToolDefinition } from './types.js';
+export declare const listCatalogProducts: ToolDefinition;
+export declare const getCatalogPlan: ToolDefinition;
+export declare const listRegions: ToolDefinition;
+export declare const listImages: ToolDefinition;

package/dist/tools/catalog.js

@@ -0,0 +1,104 @@
+// Catalog tools — un-authed endpoints, useful for "what can we deploy?"
+// queries. Token is still passed so we use the same client; the API
+// ignores it on these routes.
+import { APIError } from '../client.js';
+import { jsonResult, errorResult } from './types.js';
+export const listCatalogProducts = {
+    name: 'list_catalog_products',
+    description: 'List orderable products from the RareCloud catalog. Use to answer "what plans can I deploy?" Returns SKU, kind (legacy_vps / cloud_compute / proxy / ...), category, display name. Filter by kind or backend to narrow results.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            kind: {
+                type: 'string',
+                enum: ['legacy_vps', 'cloud_compute', 'cloud_k8s', 'cloud_volume', 'cloud_network', 'dedicated_server', 'proxy', 'hosting', 'domain', 'app_hosting'],
+                description: 'Filter by product kind. Most users want legacy_vps (KVM VPS) or cloud_compute (hourly OpenStack VMs).',
+            },
+            backend: {
+                type: 'string',
+                enum: ['whmcs', 'virtualizor', 'openstack', 'gardener'],
+                description: 'Filter by underlying backend. Usually you do NOT need this — pick by kind instead.',
+            },
+            category: {
+                type: 'string',
+                description: 'Filter by category name (e.g. "KVM Servers", "Proxies").',
+            },
+        },
+        additionalProperties: false,
+    },
+    async handler(client, args) {
+        try {
+            const data = await client.get('/v1/catalog/products', {
+                kind: args.kind,
+                backend: args.backend,
+                category: args.category,
+            });
+            return jsonResult(data);
+        }
+        catch (e) {
+            return errorResult(e instanceof APIError ? e.message : e.message);
+        }
+    },
+};
+export const getCatalogPlan = {
+    name: 'get_catalog_plan',
+    description: 'Get full details for a single catalog product including all plans (sizes), their specs (vCPU, RAM, disk, bandwidth), pricing for every supported billing cycle, and supported billing tracks. Use before generating a Terraform plan or before recommending a specific SKU.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            sku: {
+                type: 'string',
+                description: 'Product SKU from list_catalog_products (e.g. "whmcs.kvm-servers-plus-vps").',
+            },
+        },
+        required: ['sku'],
+        additionalProperties: false,
+    },
+    async handler(client, args) {
+        try {
+            const sku = args.sku;
+            const data = await client.get(`/v1/catalog/products/${encodeURIComponent(sku)}`);
+            return jsonResult(data);
+        }
+        catch (e) {
+            return errorResult(e instanceof APIError ? e.message : e.message);
+        }
+    },
+};
+export const listRegions = {
+    name: 'list_regions',
+    description: 'List available RareCloud datacenter regions. Each region has a slug (e.g. "frankfurt-de"), display name, country code, and which backends can provision there.',
+    inputSchema: {
+        type: 'object',
+        properties: {},
+        additionalProperties: false,
+    },
+    async handler(client) {
+        try {
+            const data = await client.get('/v1/catalog/regions');
+            return jsonResult(data);
+        }
+        catch (e) {
+            return errorResult(e instanceof APIError ? e.message : e.message);
+        }
+    },
+};
+export const listImages = {
+    name: 'list_images',
+    description: 'List available OS images (Ubuntu / Debian / Rocky / Windows Server / etc) that can be installed on new servers. Use to validate an image slug before recommending it.',
+    inputSchema: {
+        type: 'object',
+        properties: {},
+        additionalProperties: false,
+    },
+    async handler(client) {
+        try {
+            const data = await client.get('/v1/catalog/images');
+            return jsonResult(data);
+        }
+        catch (e) {
+            return errorResult(e instanceof APIError ? e.message : e.message);
+        }
+    },
+};
+//# sourceMappingURL=catalog.js.map

package/dist/tools/catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.js","sourceRoot":"","sources":["../../src/tools/catalog.ts"],"names":[],"mappings":"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"}

package/dist/tools/index.d.ts

@@ -0,0 +1,3 @@
+import type { ToolDefinition } from './types.js';
+export declare const TOOLS: ToolDefinition[];
+export declare function findTool(name: string): ToolDefinition | undefined;

package/dist/tools/index.js

@@ -0,0 +1,38 @@
+// Single registry of all tools exposed by this MCP server. Keep this file
+// short — adding a new tool = import + push.
+import { listCatalogProducts, getCatalogPlan, listRegions, listImages, } from './catalog.js';
+import { listServices, getService, getServiceMetrics, listBackups, getProvisioningState, listOsTemplates, listUpgradeOptions } from './services.js';
+import { listInvoices, getInvoice, getCreditBalance, getCreditLedger } from './billing.js';
+import { getAccount, listSshKeys, getAccountLimits } from './account.js';
+import { listTickets, getTicket } from './tickets.js';
+export const TOOLS = [
+    // Catalog (un-authed surface, "what can I deploy?")
+    listCatalogProducts,
+    getCatalogPlan,
+    listRegions,
+    listImages,
+    // Services ("what do I have running?")
+    listServices,
+    getService,
+    getServiceMetrics,
+    listBackups,
+    getProvisioningState,
+    listOsTemplates,
+    listUpgradeOptions,
+    // Billing ("how much am I spending?")
+    listInvoices,
+    getInvoice,
+    getCreditBalance,
+    getCreditLedger,
+    // Support ("any open tickets?")
+    listTickets,
+    getTicket,
+    // Account ("who am I + what are my keys?")
+    getAccount,
+    listSshKeys,
+    getAccountLimits,
+];
+export function findTool(name) {
+    return TOOLS.find((t) => t.name === name);
+}
+//# sourceMappingURL=index.js.map

package/dist/tools/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,6CAA6C;AAG7C,OAAO,EACL,mBAAmB,EACnB,cAAc,EACd,WAAW,EACX,UAAU,GACX,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,iBAAiB,EAAE,WAAW,EAAE,oBAAoB,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACpJ,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC3F,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACzE,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEtD,MAAM,CAAC,MAAM,KAAK,GAAqB;IACrC,oDAAoD;IACpD,mBAAmB;IACnB,cAAc;IACd,WAAW;IACX,UAAU;IACV,uCAAuC;IACvC,YAAY;IACZ,UAAU;IACV,iBAAiB;IACjB,WAAW;IACX,oBAAoB;IACpB,eAAe;IACf,kBAAkB;IAClB,sCAAsC;IACtC,YAAY;IACZ,UAAU;IACV,gBAAgB;IAChB,eAAe;IACf,gCAAgC;IAChC,WAAW;IACX,SAAS;IACT,2CAA2C;IAC3C,UAAU;IACV,WAAW;IACX,gBAAgB;CACjB,CAAC;AAEF,MAAM,UAAU,QAAQ,CAAC,IAAY;IACnC,OAAO,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;AAC5C,CAAC"}

package/dist/tools/services.d.ts

@@ -0,0 +1,8 @@
+import { type ToolDefinition } from './types.js';
+export declare const listServices: ToolDefinition;
+export declare const getService: ToolDefinition;
+export declare const getServiceMetrics: ToolDefinition;
+export declare const listBackups: ToolDefinition;
+export declare const getProvisioningState: ToolDefinition;
+export declare const listOsTemplates: ToolDefinition;
+export declare const listUpgradeOptions: ToolDefinition;

package/dist/tools/services.js

@@ -0,0 +1,191 @@
+// Services tools — wrap /v1/services. Read-only for v1: list, get,
+// list snapshots. No create/destroy/snapshot-create until we ship the
+// derived-token + plan-and-approve flow described in
+// docs/ideas/2026-05-22-agent-ai-architecture.md.
+import { APIError } from '../client.js';
+import { jsonResult, errorResult } from './types.js';
+export const listServices = {
+    name: 'list_services',
+    description: 'List all services in the authenticated account: VPS servers, cloud VMs, proxies, hosting, domains. Returns each service\'s id, kind, name, status, IPv4, region, specs, billing cycle. Use to answer "what do I have running?" or to find a service ID for follow-up calls.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            category: {
+                type: 'string',
+                description: 'Optional filter by service category: "server" (legacy VPS), "cloud-vm", "cloud-k8s", "proxy", "hosting", "domain". Omit to return all.',
+            },
+        },
+        additionalProperties: false,
+    },
+    async handler(client, args) {
+        try {
+            // The /v1/services route filters by `category` (not `kind`).
+            const data = await client.get('/v1/services', {
+                category: args.category,
+            });
+            return jsonResult(data);
+        }
+        catch (e) {
+            return errorResult(e instanceof APIError ? e.message : e.message);
+        }
+    },
+};
+export const getService = {
+    name: 'get_service',
+    description: 'Get full details for a single service by ID: status, network config, billing state, current-month usage. Use when you need more than the list_services summary (e.g. to inspect logs, current cost, attached resources).',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            service_id: {
+                type: 'string',
+                description: 'Service ID from list_services (e.g. "srv_01H8E9...").',
+            },
+        },
+        required: ['service_id'],
+        additionalProperties: false,
+    },
+    async handler(client, args) {
+        try {
+            const id = args.service_id;
+            const data = await client.get(`/v1/services/${encodeURIComponent(id)}`);
+            return jsonResult(data);
+        }
+        catch (e) {
+            return errorResult(e instanceof APIError ? e.message : e.message);
+        }
+    },
+};
+export const getServiceMetrics = {
+    name: 'get_service_metrics',
+    description: 'Get resource metrics (CPU / RAM / disk / bandwidth time series) for a single service. Use to answer "is my server busy?" or "how much bandwidth have I used?".',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            service_id: {
+                type: 'string',
+                description: 'Service ID from list_services.',
+            },
+            period: {
+                type: 'string',
+                enum: ['hour', 'day', 'week', 'month'],
+                description: 'Aggregation window (default: hour).',
+            },
+        },
+        required: ['service_id'],
+        additionalProperties: false,
+    },
+    async handler(client, args) {
+        try {
+            const id = args.service_id;
+            const data = await client.get(`/v1/services/${encodeURIComponent(id)}/metrics`, {
+                period: args.period,
+            });
+            return jsonResult(data);
+        }
+        catch (e) {
+            return errorResult(e instanceof APIError ? e.message : e.message);
+        }
+    },
+};
+export const listBackups = {
+    name: 'list_backups',
+    description: 'List existing backups for a single legacy VPS server. Use to check whether a recent backup exists before a risky change, or to find a backup ID for restore.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            service_id: {
+                type: 'string',
+                description: 'Server ID from list_services.',
+            },
+        },
+        required: ['service_id'],
+        additionalProperties: false,
+    },
+    async handler(client, args) {
+        try {
+            const id = args.service_id;
+            // /snapshots doesn't exist in v1; backups is the real read endpoint.
+            const data = await client.get(`/v1/services/${encodeURIComponent(id)}/backups`);
+            return jsonResult(data);
+        }
+        catch (e) {
+            return errorResult(e instanceof APIError ? e.message : e.message);
+        }
+    },
+};
+export const getProvisioningState = {
+    name: 'get_provisioning_state',
+    description: 'Setup state of a pending service: whether its order is paid, whether the VM exists yet, and whether provisioning looks stuck (paid but unprovisioned past the grace period). Use after a deploy to watch it land, or to diagnose a service that stays pending.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            service_id: {
+                type: 'string',
+                description: 'Service ID from list_services.',
+            },
+        },
+        required: ['service_id'],
+        additionalProperties: false,
+    },
+    async handler(client, args) {
+        try {
+            const id = args.service_id;
+            const data = await client.get(`/v1/services/${encodeURIComponent(id)}/provisioning`);
+            return jsonResult(data);
+        }
+        catch (e) {
+            return errorResult(e instanceof APIError ? e.message : e.message);
+        }
+    },
+};
+export const listOsTemplates = {
+    name: 'list_os_templates',
+    description: 'Operating systems a legacy VPS can be reinstalled with (Virtualizor templates). Read-only; the reinstall itself is a destructive write and is not exposed as an MCP tool.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            service_id: {
+                type: 'string',
+                description: 'Server ID from list_services.',
+            },
+        },
+        required: ['service_id'],
+        additionalProperties: false,
+    },
+    async handler(client, args) {
+        try {
+            const id = args.service_id;
+            const data = await client.get(`/v1/services/${encodeURIComponent(id)}/os-templates`);
+            return jsonResult(data);
+        }
+        catch (e) {
+            return errorResult(e instanceof APIError ? e.message : e.message);
+        }
+    },
+};
+export const listUpgradeOptions = {
+    name: 'list_upgrade_options',
+    description: 'Plans (and billing cycles with prices) a service could be upgraded/downgraded to, from its product group. Read-only; the actual upgrade creates an invoice and is not exposed as an MCP tool.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            service_id: {
+                type: 'string',
+                description: 'Service ID from list_services.',
+            },
+        },
+        required: ['service_id'],
+        additionalProperties: false,
+    },
+    async handler(client, args) {
+        try {
+            const id = args.service_id;
+            const data = await client.get(`/v1/services/${encodeURIComponent(id)}/upgrade`);
+            return jsonResult(data);
+        }
+        catch (e) {
+            return errorResult(e instanceof APIError ? e.message : e.message);
+        }
+    },
+};
+//# sourceMappingURL=services.js.map

package/dist/tools/services.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"services.js","sourceRoot":"","sources":["../../src/tools/services.ts"],"names":[],"mappings":"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"}

package/dist/tools/tickets.d.ts

@@ -0,0 +1,3 @@
+import { type ToolDefinition } from './types.js';
+export declare const listTickets: ToolDefinition;
+export declare const getTicket: ToolDefinition;

package/dist/tools/tickets.js

@@ -0,0 +1,56 @@
+// Support ticket tools — read-only. Opening / replying to tickets stays manual
+// until the write-tool (plan-then-approve) flow ships.
+import { APIError } from '../client.js';
+import { jsonResult, errorResult } from './types.js';
+export const listTickets = {
+    name: 'list_tickets',
+    description: 'List support tickets for the authenticated account: id, subject, status (open / awaiting-staff / awaiting-client / closed), department, last-updated. Use for "do I have any open tickets?".',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            status: {
+                type: 'string',
+                enum: ['open', 'awaiting-staff', 'awaiting-client', 'closed'],
+                description: 'Optional filter on ticket status.',
+            },
+        },
+        additionalProperties: false,
+    },
+    async handler(client, args) {
+        try {
+            const data = await client.get('/v1/tickets', {
+                status: args.status,
+            });
+            return jsonResult(data);
+        }
+        catch (e) {
+            return errorResult(e instanceof APIError ? e.message : e.message);
+        }
+    },
+};
+export const getTicket = {
+    name: 'get_ticket',
+    description: 'Get a single support ticket with its full message thread. Use after list_tickets to read the conversation or check the latest staff reply.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            ticket_id: {
+                type: 'string',
+                description: 'Ticket ID from list_tickets.',
+            },
+        },
+        required: ['ticket_id'],
+        additionalProperties: false,
+    },
+    async handler(client, args) {
+        try {
+            const id = args.ticket_id;
+            const data = await client.get(`/v1/tickets/${encodeURIComponent(id)}`);
+            return jsonResult(data);
+        }
+        catch (e) {
+            return errorResult(e instanceof APIError ? e.message : e.message);
+        }
+    },
+};
+//# sourceMappingURL=tickets.js.map

package/dist/tools/tickets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tickets.js","sourceRoot":"","sources":["../../src/tools/tickets.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,uDAAuD;AAEvD,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AACxC,OAAO,EAAuB,UAAU,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE1E,MAAM,CAAC,MAAM,WAAW,GAAmB;IACzC,IAAI,EAAE,cAAc;IACpB,WAAW,EAAE,8LAA8L;IAC3M,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACV,MAAM,EAAE;gBACN,IAAI,EAAE,QAAQ;gBACd,IAAI,EAAE,CAAC,MAAM,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,QAAQ,CAAC;gBAC7D,WAAW,EAAE,mCAAmC;aACjD;SACF;QACD,oBAAoB,EAAE,KAAK;KAC5B;IACD,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,IAAI;QACxB,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,GAAG,CAAC,aAAa,EAAE;gBAC3C,MAAM,EAAE,IAAI,CAAC,MAA4B;aAC1C,CAAC,CAAC;YACH,OAAO,UAAU,CAAC,IAAI,CAAC,CAAC;QAC1B,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,OAAO,WAAW,CAAC,CAAC,YAAY,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAE,CAAW,CAAC,OAAO,CAAC,CAAC;QAC/E,CAAC;IACH,CAAC;CACF,CAAC;AAEF,MAAM,CAAC,MAAM,SAAS,GAAmB;IACvC,IAAI,EAAE,YAAY;IAClB,WAAW,EAAE,4IAA4I;IACzJ,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACV,SAAS,EAAE;gBACT,IAAI,EAAE,QAAQ;gBACd,WAAW,EAAE,8BAA8B;aAC5C;SACF;QACD,QAAQ,EAAE,CAAC,WAAW,CAAC;QACvB,oBAAoB,EAAE,KAAK;KAC5B;IACD,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,IAAI;QACxB,IAAI,CAAC;YACH,MAAM,EAAE,GAAG,IAAI,CAAC,SAAmB,CAAC;YACpC,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,GAAG,CAAC,eAAe,kBAAkB,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;YACvE,OAAO,UAAU,CAAC,IAAI,CAAC,CAAC;QAC1B,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,OAAO,WAAW,CAAC,CAAC,YAAY,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAE,CAAW,CAAC,OAAO,CAAC,CAAC;QAC/E,CAAC;IACH,CAAC;CACF,CAAC"}

package/dist/tools/types.d.ts

@@ -0,0 +1,28 @@
+import type { RareCloudClient } from '../client.js';
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: 'object';
+        properties: Record<string, unknown>;
+        required?: string[];
+        additionalProperties?: boolean;
+    };
+    handler: (client: RareCloudClient, args: Record<string, unknown>) => Promise<ToolCallResult>;
+}
+export interface ToolCallResult {
+    content: Array<{
+        type: 'text';
+        text: string;
+    } | {
+        type: 'resource';
+        resource: {
+            uri: string;
+            mimeType?: string;
+            text?: string;
+        };
+    }>;
+    isError?: boolean;
+}
+export declare function jsonResult(data: unknown): ToolCallResult;
+export declare function errorResult(message: string): ToolCallResult;

package/dist/tools/types.js

@@ -0,0 +1,21 @@
+// Each MCP tool: a JSON Schema for inputs + a handler that returns the
+// shape MCP expects (`content` array, each block typed).
+//
+// We keep handlers small and uniform — they always return either a JSON
+// payload or a friendly error message. The actual HTTP work lives in
+// client.ts. Tool descriptions are tuned for LLM consumption: lead with
+// the verb, mention the resource, hint at when to use it.
+// Helper: wrap JSON in a text block (the de-facto MCP convention until
+// structured outputs land in the spec).
+export function jsonResult(data) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+    };
+}
+export function errorResult(message) {
+    return {
+        content: [{ type: 'text', text: `Error: ${message}` }],
+        isError: true,
+    };
+}
+//# sourceMappingURL=types.js.map

package/dist/tools/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/tools/types.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,yDAAyD;AACzD,EAAE;AACF,wEAAwE;AACxE,qEAAqE;AACrE,wEAAwE;AACxE,0DAA0D;AA2B1D,uEAAuE;AACvE,wCAAwC;AACxC,MAAM,UAAU,UAAU,CAAC,IAAa;IACtC,OAAO;QACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;KACjE,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,OAAe;IACzC,OAAO;QACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,OAAO,EAAE,EAAE,CAAC;QACtD,OAAO,EAAE,IAAI;KACd,CAAC;AACJ,CAAC"}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@rarecloudio/mcp-server",
+  "version": "0.1.0",
+  "description": "Model Context Protocol server for the RareCloud API. Drop into Claude Code / Claude Desktop / Cursor to let AI agents inspect and reason about your RareCloud account.",
+  "type": "module",
+  "bin": {
+    "rarecloud-mcp": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "files": [
+    "dist/",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "test": "node --test --import tsx/esm src/**/*.test.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "rarecloud",
+    "cloud",
+    "ai-agents"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/RareCloudio/rarecloud-cli"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://console.rarecloud.io/docs/api"
+}