@suzko/mcp-server 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Suzko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,171 @@
+# @suzko/mcp-server
+
+AI-powered infrastructure management for VS Code, Claude, and Cursor.
+
+## Quick Start
+
+### VS Code (Copilot agent mode)
+
+Add to your `settings.json`:
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "suzko": {
+        "command": "npx",
+        "args": ["-y", "@suzko/mcp-server"],
+        "env": {
+          "SUZKO_API_BASE": "https://www.suzko.com"
+        }
+      }
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "suzko": {
+      "command": "npx",
+      "args": ["-y", "@suzko/mcp-server"]
+    }
+  }
+}
+```
+
+### Claude Code CLI
+
+```bash
+claude mcp add suzko -- npx -y @suzko/mcp-server
+```
+
+## Authentication
+
+```bash
+# Login (opens browser)
+npx @suzko/mcp-server auth login
+
+# Check status
+npx @suzko/mcp-server auth status
+
+# Logout
+npx @suzko/mcp-server auth logout
+```
+
+Credentials are stored in `~/.suzko/mcp-credentials.json`.
+
+## Tools
+
+### Deploy (12 tools)
+- `list_deploy_templates` — Browse available service templates
+- `list_deploy_projects` — List your deployed projects
+- `create_deploy_project` — Create a new project (with cost confirmation)
+- `confirm_deploy_project` — Confirm project creation
+- `get_deploy_project` — Project details and status
+- `control_deploy_project` — Start/stop/restart/delete
+- `get_deploy_logs` — Runtime logs
+- `get_deploy_build_logs` — Build output
+- `redeploy_project` — Trigger redeployment
+- `set_deploy_env` — Set environment variables
+- `check_subdomain` — Check subdomain availability
+- `get_deploy_usage` — Usage stats and billing
+
+### Domains (12 tools)
+- `search_domains` — Check domain availability
+- `get_tld_pricing` — TLD pricing table
+- `suggest_domain_names` — AI domain name suggestions
+- `register_domain` / `confirm_domain_registration` — Register with confirmation
+- `transfer_domain` / `confirm_domain_transfer` — Transfer with confirmation
+- `list_domains` — Your owned domains
+- `get_domain_details` — Full domain info
+- `update_domain_nameservers` — Update NS records
+- `get_domain_lock_status` / `toggle_domain_lock` — Lock management
+
+### DNS (5 tools)
+- `enable_dns_management` — Enable DNS for a domain
+- `list_dns_records` — List all records
+- `create_dns_record` — Create A/AAAA/CNAME/TXT/MX/NS/SRV/CAA
+- `update_dns_record` — Update records
+- `delete_dns_record` — Delete records
+
+### Account & Billing (7 tools)
+- `get_account_info` — Profile and account details
+- `list_invoices` / `get_invoice` — Billing history
+- `list_subscriptions` — Active subscriptions
+- `check_perks` — Feature access
+- `list_orders` — Order history
+- `get_account_balance` — Credit balance
+
+### Services (4 tools)
+- `list_services` — WHMCS hosting services
+- `get_service_details` — Service configuration
+- `get_service_sso_url` — Control panel SSO link
+- `upgrade_service` — Upgrade guidance
+
+### Support (5 tools)
+- `list_tickets` / `get_ticket` — Ticket management
+- `open_support_ticket` — Create tickets
+- `reply_to_ticket` — Reply to tickets
+- `close_ticket` — Close tickets
+
+### BYOS Server Admin (12 tools)
+- `connect_server` — Register a server via SSH
+- `list_servers` — List registered servers
+- `inspect_server` — System diagnostics
+- `run_server_command` — Execute commands (with safety checks)
+- `install_docker` — Install Docker
+- `deploy_to_server` — Deploy via SCP + docker-compose
+- `list_server_containers` / `manage_server_container` — Docker management
+- `setup_ssl` — SSL certificate setup
+- `get_server_status` — System status
+- `get_server_logs` — Log reading
+- `manage_env_file` — .env file management
+
+## Resources
+
+The server exposes read-only resources via `suzko://` URIs:
+- `suzko://services` — Active hosting services
+- `suzko://deploy/projects` — Deploy projects
+- `suzko://domains` — Registered domains
+- `suzko://invoices` — Billing history
+- `suzko://perks` — Subscription perks
+
+## Prompts
+
+Pre-built workflow templates:
+- `deploy-app` — Deploy an application
+- `find-domain` — Search and register domains
+- `troubleshoot-service` — Diagnose service issues
+- `setup-server` — Set up a new server (BYOS)
+
+## Human-in-the-Loop
+
+Tools that create resources or cost money use a two-step confirmation:
+
+1. Tool returns a cost preview with a confirmation token
+2. AI presents the cost to the user
+3. User approves → AI calls the confirm tool with the token
+4. Action is executed
+
+Confirmation tokens expire after 5 minutes and are single-use.
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `SUZKO_API_BASE` | `https://www.suzko.com` | API base URL |
+
+## Development
+
+```bash
+cd packages/mcp-server
+bun install
+bun run build    # Compile TypeScript
+bun run dev      # Watch mode
+```

package/dist/bin/mcp-server.d.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+/**
+ * Suzko MCP Server CLI
+ *
+ * Usage:
+ *   npx @suzko/mcp-server           — Start MCP server (stdio transport)
+ *   npx @suzko/mcp-server auth login — Login to Suzko account
+ *   npx @suzko/mcp-server auth status — Check auth status
+ *   npx @suzko/mcp-server auth logout — Remove saved credentials
+ */
+export {};

package/dist/bin/mcp-server.js

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+/**
+ * Suzko MCP Server CLI
+ *
+ * Usage:
+ *   npx @suzko/mcp-server           — Start MCP server (stdio transport)
+ *   npx @suzko/mcp-server auth login — Login to Suzko account
+ *   npx @suzko/mcp-server auth status — Check auth status
+ *   npx @suzko/mcp-server auth logout — Remove saved credentials
+ */
+import { login, loadCredentials, resolveApiBase } from "../src/auth.js";
+import { unlink } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+async function main() {
+    const args = process.argv.slice(2);
+    let apiBase;
+    try {
+        // Throws (and we exit) if SUZKO_API_BASE is malicious.
+        apiBase = resolveApiBase();
+    }
+    catch (e) {
+        console.error(e instanceof Error ? e.message : String(e));
+        process.exit(1);
+    }
+    // No args = start MCP server
+    if (args.length === 0) {
+        // Dynamic import to avoid loading MCP SDK for CLI commands
+        await import("../src/index.js");
+        return;
+    }
+    const command = args[0];
+    const subcommand = args[1];
+    if (command === "auth") {
+        switch (subcommand) {
+            case "login": {
+                await login(apiBase);
+                break;
+            }
+            case "status": {
+                const creds = await loadCredentials();
+                if (!creds) {
+                    console.log("Not logged in. Run: npx @suzko/mcp-server auth login");
+                }
+                else {
+                    const expiresAt = new Date(creds.expiresAt);
+                    const isExpired = expiresAt.getTime() < Date.now();
+                    console.log(`✓ Logged in`);
+                    console.log(`  API: ${creds.apiBase}`);
+                    console.log(`  Token: ${isExpired ? "EXPIRED" : "Valid"} (expires ${expiresAt.toLocaleString()})`);
+                }
+                break;
+            }
+            case "logout": {
+                const credFile = join(homedir(), ".suzko", "mcp-credentials.json");
+                try {
+                    await unlink(credFile);
+                    console.log("✓ Credentials removed.");
+                }
+                catch {
+                    console.log("No credentials to remove.");
+                }
+                break;
+            }
+            default:
+                console.log("Usage: npx @suzko/mcp-server auth [login|status|logout]");
+        }
+    }
+    else if (command === "help" || command === "--help" || command === "-h") {
+        console.log(`
+Suzko MCP Server — AI-powered infrastructure management
+
+Usage:
+  npx @suzko/mcp-server               Start MCP server (stdio transport)
+  npx @suzko/mcp-server auth login     Login to your Suzko account
+  npx @suzko/mcp-server auth status    Check authentication status
+  npx @suzko/mcp-server auth logout    Remove saved credentials
+
+Configuration (VS Code settings.json):
+  {
+    "mcp": {
+      "servers": {
+        "suzko": {
+          "command": "npx",
+          "args": ["-y", "@suzko/mcp-server"]
+        }
+      }
+    }
+  }
+
+Environment:
+  SUZKO_API_BASE    API base URL (default: https://www.suzko.com)
+`);
+    }
+    else {
+        console.error(`Unknown command: ${command}`);
+        console.log("Run: npx @suzko/mcp-server --help");
+        process.exit(1);
+    }
+}
+main().then(() => {
+    // CLI commands should exit; MCP server stays running (handled by stdio transport)
+    if (process.argv.length > 2)
+        process.exit(0);
+}).catch((error) => {
+    console.error("Error:", error.message || error);
+    process.exit(1);
+});

package/dist/src/auth.d.ts

@@ -0,0 +1,14 @@
+interface Credentials {
+    accessToken: string;
+    refreshToken: string;
+    expiresAt: string;
+    apiBase: string;
+}
+/** Resolve the API base from env, validating it against the allowlist. */
+export declare function resolveApiBase(override?: string): string;
+export declare function loadCredentials(): Promise<Credentials | null>;
+export declare function saveCredentials(creds: Credentials): Promise<void>;
+export declare function getValidToken(apiBase: string): Promise<string | null>;
+/** Interactive CLI login. Opens browser for auth, exchanges code for tokens. */
+export declare function login(apiBase: string): Promise<boolean>;
+export {};

package/dist/src/auth.js

@@ -0,0 +1,140 @@
+// Device-token authentication. Credentials stored in ~/.suzko/mcp-credentials.json.
+import { readFile, writeFile, mkdir, chmod } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { validateApiBase } from "./security.js";
+const CONFIG_DIR = join(homedir(), ".suzko");
+const CREDENTIALS_FILE = join(CONFIG_DIR, "mcp-credentials.json");
+const DEFAULT_API_BASE = "https://www.suzko.com";
+/** Resolve the API base from env, validating it against the allowlist. */
+export function resolveApiBase(override) {
+    return validateApiBase(override || process.env.SUZKO_API_BASE || DEFAULT_API_BASE);
+}
+export async function loadCredentials() {
+    try {
+        const raw = await readFile(CREDENTIALS_FILE, "utf-8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+export async function saveCredentials(creds) {
+    validateApiBase(creds.apiBase);
+    await mkdir(CONFIG_DIR, { recursive: true });
+    try {
+        await chmod(CONFIG_DIR, 0o700);
+    }
+    catch {
+        // chmod unsupported on Windows.
+    }
+    await writeFile(CREDENTIALS_FILE, JSON.stringify(creds, null, 2), "utf-8");
+    try {
+        await chmod(CREDENTIALS_FILE, 0o600);
+    }
+    catch {
+        // chmod unsupported on Windows.
+    }
+}
+// Shared in-flight refresh so parallel callers don't double-spend the refresh token.
+let refreshingPromise = null;
+export async function getValidToken(apiBase) {
+    const creds = await loadCredentials();
+    if (!creds)
+        return null;
+    // Check expiry — auto-refresh if within 1 hour of expiration
+    const expiresAt = new Date(creds.expiresAt).getTime();
+    const now = Date.now();
+    const oneHour = 60 * 60 * 1000;
+    if (now > expiresAt) {
+        return refreshTokenShared(apiBase, creds);
+    }
+    if (expiresAt - now < oneHour) {
+        refreshTokenShared(apiBase, creds).catch(() => { });
+    }
+    return creds.accessToken;
+}
+function refreshTokenShared(apiBase, creds) {
+    if (refreshingPromise)
+        return refreshingPromise;
+    refreshingPromise = refreshToken(apiBase, creds).finally(() => {
+        refreshingPromise = null;
+    });
+    return refreshingPromise;
+}
+async function refreshToken(apiBase, creds) {
+    try {
+        const res = await fetch(`${apiBase}/api/auth/device-refresh`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ refreshToken: creds.refreshToken }),
+        });
+        if (!res.ok)
+            return null;
+        const data = await res.json();
+        if (!data.success || !data.data?.accessToken)
+            return null;
+        const expiresInMs = (data.data.expiresIn || 7 * 24 * 60 * 60) * 1000;
+        const updated = {
+            accessToken: data.data.accessToken,
+            refreshToken: data.data.refreshToken || creds.refreshToken,
+            expiresAt: new Date(Date.now() + expiresInMs).toISOString(),
+            apiBase,
+        };
+        await saveCredentials(updated);
+        return updated.accessToken;
+    }
+    catch {
+        return null;
+    }
+}
+/** Interactive CLI login. Opens browser for auth, exchanges code for tokens. */
+export async function login(apiBase) {
+    validateApiBase(apiBase);
+    const loginUrl = `${apiBase}/auth/device?client=mcp`;
+    console.log(`\nOpen this URL in your browser to log in:\n\n  ${loginUrl}\n`);
+    console.log("Verify the URL is on https://www.suzko.com before pasting your code.\n");
+    // Prompt for the auth code
+    const code = await promptInput("Paste your auth code: ");
+    if (!code) {
+        console.error("No code provided.");
+        return false;
+    }
+    try {
+        const res = await fetch(`${apiBase}/api/auth/device-token`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ code, client: "mcp" }),
+        });
+        const data = await res.json();
+        if (!data.success || !data.data?.accessToken) {
+            console.error("Login failed:", data.error || "Unknown error");
+            return false;
+        }
+        const expiresInMs = (data.data.expiresIn || 7 * 24 * 60 * 60) * 1000;
+        await saveCredentials({
+            accessToken: data.data.accessToken,
+            refreshToken: data.data.refreshToken,
+            expiresAt: new Date(Date.now() + expiresInMs).toISOString(),
+            apiBase,
+        });
+        console.log("✓ Login successful! Credentials saved.");
+        return true;
+    }
+    catch (e) {
+        console.error("Login failed:", e instanceof Error ? e.message : String(e));
+        return false;
+    }
+}
+function promptInput(message) {
+    return new Promise((resolve) => {
+        process.stdout.write(message);
+        process.stdin.setEncoding("utf-8");
+        process.stdin.resume();
+        process.stdin.once("data", (chunk) => {
+            process.stdin.pause();
+            process.stdin.unref();
+            resolve(chunk.toString().trim());
+        });
+    });
+}

package/dist/src/client.d.ts

@@ -0,0 +1,18 @@
+export declare class SuzkoClient {
+    private apiBase;
+    constructor(apiBase?: string);
+    /** Make an authenticated GET request */
+    get<T = unknown>(path: string, params?: Record<string, string>): Promise<T>;
+    /** Make an authenticated POST request */
+    post<T = unknown>(path: string, body?: unknown): Promise<T>;
+    /** Make an authenticated PUT request */
+    put<T = unknown>(path: string, body?: unknown): Promise<T>;
+    /** Make an authenticated DELETE request */
+    del<T = unknown>(path: string, body?: unknown): Promise<T>;
+    /** Make an authenticated PATCH request */
+    patch<T = unknown>(path: string, body?: unknown): Promise<T>;
+    private request;
+    /** Check if we have valid credentials */
+    isAuthenticated(): Promise<boolean>;
+}
+export declare function getClient(): SuzkoClient;

package/dist/src/client.js

@@ -0,0 +1,78 @@
+// Authenticated client for the Suzko API. Auto-refreshes tokens on expiry.
+import { getValidToken, resolveApiBase } from "./auth.js";
+export class SuzkoClient {
+    apiBase;
+    constructor(apiBase) {
+        this.apiBase = resolveApiBase(apiBase);
+    }
+    /** Make an authenticated GET request */
+    async get(path, params) {
+        const url = new URL(path, this.apiBase);
+        if (params) {
+            for (const [k, v] of Object.entries(params)) {
+                url.searchParams.set(k, v);
+            }
+        }
+        return this.request("GET", url.toString());
+    }
+    /** Make an authenticated POST request */
+    async post(path, body) {
+        const url = new URL(path, this.apiBase);
+        return this.request("POST", url.toString(), body);
+    }
+    /** Make an authenticated PUT request */
+    async put(path, body) {
+        const url = new URL(path, this.apiBase);
+        return this.request("PUT", url.toString(), body);
+    }
+    /** Make an authenticated DELETE request */
+    async del(path, body) {
+        const url = new URL(path, this.apiBase);
+        return this.request("DELETE", url.toString(), body);
+    }
+    /** Make an authenticated PATCH request */
+    async patch(path, body) {
+        const url = new URL(path, this.apiBase);
+        return this.request("PATCH", url.toString(), body);
+    }
+    async request(method, url, body) {
+        const token = await getValidToken(this.apiBase);
+        const headers = {
+            "X-Client": "mcp-server",
+        };
+        if (token) {
+            headers["Authorization"] = `Bearer ${token}`;
+        }
+        if (body !== undefined) {
+            headers["Content-Type"] = "application/json";
+        }
+        const res = await fetch(url, {
+            method,
+            headers,
+            body: body !== undefined ? JSON.stringify(body) : undefined,
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => "");
+            const trimmed = text.trim();
+            const looksLikeHtml = trimmed.startsWith("<") || /<html|<!doctype/i.test(trimmed.slice(0, 64));
+            const msg = looksLikeHtml
+                ? `Backend returned an HTML error page (${res.status}).`
+                : trimmed.slice(0, 200) || res.statusText;
+            throw new Error(`API error ${res.status}: ${msg}`);
+        }
+        return res.json();
+    }
+    /** Check if we have valid credentials */
+    async isAuthenticated() {
+        const token = await getValidToken(this.apiBase);
+        return token !== null;
+    }
+}
+/** Singleton client instance */
+let _client = null;
+export function getClient() {
+    if (!_client) {
+        _client = new SuzkoClient();
+    }
+    return _client;
+}

package/dist/src/index.d.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+/**
+ * Suzko MCP Server
+ *
+ * AI-powered infrastructure management for VS Code, Claude, and Cursor.
+ * Uses stdio transport for universal IDE compatibility.
+ */
+export {};

package/dist/src/index.js

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+/**
+ * Suzko MCP Server
+ *
+ * AI-powered infrastructure management for VS Code, Claude, and Cursor.
+ * Uses stdio transport for universal IDE compatibility.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { getClient } from "./client.js";
+import { registerDeployTools } from "./tools/deploy.js";
+import { registerDomainTools } from "./tools/domains.js";
+import { registerAccountTools } from "./tools/account.js";
+import { registerServicesTools } from "./tools/services.js";
+import { registerDnsTools } from "./tools/dns.js";
+import { registerSupportTools } from "./tools/support.js";
+import { registerServerAdminTools } from "./tools/server-admin.js";
+import { registerResources } from "./resources/index.js";
+import { registerPrompts } from "./prompts/index.js";
+async function main() {
+    const server = new McpServer({
+        name: "suzko",
+        version: "0.1.0",
+    });
+    const client = getClient();
+    // Register all tool categories
+    registerDeployTools(server, client);
+    registerDomainTools(server, client);
+    registerDnsTools(server, client);
+    registerAccountTools(server, client);
+    registerServicesTools(server, client);
+    registerSupportTools(server, client);
+    registerServerAdminTools(server, client);
+    // Register resources and prompts
+    registerResources(server, client);
+    registerPrompts(server);
+    // Connect via stdio
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((error) => {
+    console.error("MCP Server failed to start:", error);
+    process.exit(1);
+});

package/dist/src/prompts/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * MCP Prompts — workflow templates for common tasks.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerPrompts(server: McpServer): void;