@suzko/mcp-server 0.1.0

package/GUIDE.md

@@ -0,0 +1,952 @@
+# Suzko MCP Server — Usage Guide
+
+Complete guide for using the Suzko MCP Server with VS Code Copilot, Claude Desktop, Claude Code, Cursor, and other MCP-compatible AI clients.
+
+---
+
+## Table of Contents
+
+- [What is MCP?](#what-is-mcp)
+- [Installation](#installation)
+- [Authentication](#authentication)
+- [IDE Setup](#ide-setup)
+  - [VS Code (GitHub Copilot)](#vs-code-github-copilot)
+  - [Claude Desktop](#claude-desktop)
+  - [Claude Code CLI](#claude-code-cli)
+  - [Cursor](#cursor)
+  - [Windsurf](#windsurf)
+- [Tool Categories](#tool-categories)
+  - [Deploy Tools](#deploy-tools)
+  - [Domain Tools](#domain-tools)
+  - [DNS Tools](#dns-tools)
+  - [Account & Billing Tools](#account--billing-tools)
+  - [Service Tools](#service-tools)
+  - [Support Tools](#support-tools)
+  - [Server Admin (BYOS) Tools](#server-admin-byos-tools)
+- [Resources](#resources)
+- [Prompts (Workflow Templates)](#prompts-workflow-templates)
+- [Human-in-the-Loop Confirmation](#human-in-the-loop-confirmation)
+- [Example Conversations](#example-conversations)
+- [Configuration](#configuration)
+- [Troubleshooting](#troubleshooting)
+
+---
+
+## What is MCP?
+
+The [Model Context Protocol](https://modelcontextprotocol.io) (MCP) is an open standard that lets AI assistants call tools, access data, and perform actions on your behalf. The Suzko MCP Server exposes 57 tools across 7 categories, giving your AI assistant the ability to manage your entire hosting infrastructure through natural language.
+
+**What you can do:**
+
+- Deploy apps and databases in seconds
+- Search, register, and manage domains
+- Configure DNS records
+- Manage hosting services and billing
+- Open and manage support tickets
+- Administer your own servers via SSH
+- All from a chat conversation with your AI assistant
+
+---
+
+## Installation
+
+The MCP server runs as a local process that communicates with your IDE via stdio. No global install is needed — your IDE launches it automatically.
+
+**Prerequisites:**
+
+- Node.js 18 or later
+- A Suzko account (free tier works)
+
+**Optional (for BYOS server admin):**
+
+- SSH key pair (`~/.ssh/id_ed25519` by default)
+- Servers you want to manage
+
+---
+
+## Authentication
+
+Before using the MCP server, you need to log in once. This stores credentials locally at `~/.suzko/mcp-credentials.json`.
+
+### Login
+
+```bash
+npx @suzko/mcp-server auth login
+```
+
+This prints a URL — open it in your browser, log in to your Suzko account, copy the auth code, and paste it back in the terminal.
+
+### Check Status
+
+```bash
+npx @suzko/mcp-server auth status
+```
+
+Output:
+
+```
+✓ Logged in
+  API: https://www.suzko.com
+  Token: Valid (expires 4/16/2026, 3:00:00 PM)
+```
+
+### Logout
+
+```bash
+npx @suzko/mcp-server auth logout
+```
+
+### How Auth Works
+
+- Uses the same device token flow as the desktop and mobile apps
+- Access tokens auto-refresh when they're within 1 hour of expiring
+- Credentials are stored with restricted file permissions (0600 on Unix)
+- The `~/.suzko/` directory is created automatically on first login
+
+---
+
+## IDE Setup
+
+### VS Code (GitHub Copilot)
+
+Add to your **User** or **Workspace** `settings.json`:
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "suzko": {
+        "command": "npx",
+        "args": ["-y", "@suzko/mcp-server"]
+      }
+    }
+  }
+}
+```
+
+Then in Copilot Chat (agent mode), tools appear automatically. Try:
+
+> Deploy a PostgreSQL database for my project
+
+### Claude Desktop
+
+Edit `claude_desktop_config.json`:
+
+- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "suzko": {
+      "command": "npx",
+      "args": ["-y", "@suzko/mcp-server"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop. You'll see a hammer icon (🔨) indicating tools are available.
+
+### Claude Code CLI
+
+```bash
+claude mcp add suzko -- npx -y @suzko/mcp-server
+```
+
+This adds it to your project's `.mcp.json`. To add globally:
+
+```bash
+claude mcp add --scope user suzko -- npx -y @suzko/mcp-server
+```
+
+### Cursor
+
+Add to `.cursor/mcp.json` in your project root:
+
+```json
+{
+  "mcpServers": {
+    "suzko": {
+      "command": "npx",
+      "args": ["-y", "@suzko/mcp-server"]
+    }
+  }
+}
+```
+
+### Windsurf
+
+Add to `~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "suzko": {
+      "command": "npx",
+      "args": ["-y", "@suzko/mcp-server"]
+    }
+  }
+}
+```
+
+---
+
+## Tool Categories
+
+### Deploy Tools
+
+Create and manage cloud deployments — containers, databases, and full application stacks.
+
+#### `list_deploy_templates`
+
+Browse available templates (PostgreSQL, MySQL, Redis, Node.js, etc.).
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `category` | No | Filter by category (e.g., "database", "runtime") |
+
+**Example prompt:** *"What databases can I deploy?"*
+
+#### `create_deploy_project`
+
+Create a new deployment. Returns a cost preview and confirmation token.
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `name` | Yes | Project name (lowercase, alphanumeric, hyphens) |
+| `templateId` | Yes | Template to deploy (from `list_deploy_templates`) |
+| `tier` | Yes | Resource tier: `nano` (256MB), `micro` (512MB), `small` (1GB), `medium` (2GB), `large` (4GB), `xlarge` (8GB) |
+| `stackId` | No | Pre-configured stack (e.g., "nextjs-postgres") |
+| `subdomain` | No | Custom subdomain (auto-generated if omitted) |
+| `envVars` | No | Environment variables as key-value pairs |
+
+**Example prompt:** *"Deploy a PostgreSQL database called my-app-db on the small tier"*
+
+#### `confirm_deploy_project`
+
+Execute a pending project creation after reviewing the cost preview.
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `confirmationId` | Yes | Token from `create_deploy_project` (valid for 5 minutes) |
+
+#### `get_deploy_project`
+
+Get full project details — status, URL, services, domains, resource usage.
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `projectId` | Yes | Project ID |
+
+#### `control_deploy_project`
+
+Start, stop, restart, or delete a project.
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `projectId` | Yes | Project ID |
+| `action` | Yes | One of: `start`, `stop`, `restart`, `delete` |
+
+**Example prompt:** *"Restart my-app-db"*
+
+#### `get_deploy_logs`
+
+Read runtime container logs.
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `projectId` | Yes | Project ID |
+| `tail` | No | Number of lines (default: 100) |
+| `since` | No | ISO 8601 timestamp to start from |
+
+**Example prompt:** *"Show me the last 50 lines of logs for my-app-db"*
+
+#### `get_deploy_build_logs`
+
+Read build output from the last deployment.
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `projectId` | Yes | Project ID |
+
+#### `redeploy_project`
+
+Trigger a full rebuild and restart.
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `projectId` | Yes | Project ID |
+
+#### `set_deploy_env`
+
+Set environment variables on a project. Overwrites existing keys; unmentioned keys are preserved.
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `projectId` | Yes | Project ID |
+| `envVars` | Yes | Key-value pairs to set |
+
+**Example prompt:** *"Set DATABASE_URL on my-web-app to the connection string from my-app-db"*
+
+#### `check_subdomain`
+
+Check if a subdomain is available.
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `subdomain` | Yes | Subdomain to check (e.g., "my-app") |
+
+#### `get_deploy_usage`
+
+Get deploy usage statistics, project counts, and plan limits.
+
+No parameters required.
+
+---
+
+### Domain Tools
+
+Search, register, transfer, and manage domain names.
+
+#### `search_domains`
+
+Batch check availability and pricing for up to 20 domains at once.
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `domains` | Yes | Array of domain names to check (1–20) |
+
+**Example prompt:** *"Check if example.com, example.io, and example.dev are available"*
+
+#### `get_tld_pricing`
+
+Get pricing for all supported TLDs — registration, renewal, and transfer costs.
+
+No parameters required.
+
+#### `suggest_domain_names`
+
+AI-powered creative domain name suggestions based on keywords.
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `keywords` | Yes | Descriptive keywords (e.g., "fast cloud hosting") |
+| `tld` | No | Preferred TLD (e.g., ".com", ".dev") |
+
+**Example prompt:** *"Suggest domain names for my AI startup that does image generation"*
+
+#### `register_domain`
+
+Register a domain. Returns a cost preview and confirmation token.
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `domain` | Yes | Full domain name (e.g., "example.com") |
+| `period` | Yes | Registration period in years (1–10) |
+| `nameservers` | No | Custom nameservers (array of 2–5) |
+
+#### `confirm_domain_registration`
+
+Execute a pending domain registration.
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `confirmationId` | Yes | Token from `register_domain` |
+
+#### `transfer_domain` / `confirm_domain_transfer`
+
+Transfer a domain from another registrar. Same two-step confirmation flow.
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `domain` | Yes | Domain to transfer |
+| `eppCode` | Yes | Authorization/EPP code from current registrar |
+
+#### `list_domains`
+
+List all your domains with status, expiry dates, and auto-renew settings.
+
+#### `get_domain_details`
+
+Get full domain info — nameservers, dates, lock status, DNS/email/ID protection.
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `domainId` | Yes | Domain ID (number) |
+
+#### `update_domain_nameservers`
+
+Change nameservers for a domain.
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `domainId` | Yes | Domain ID |
+| `nameservers` | Yes | Array of 2–5 nameserver hostnames |
+
+#### `get_domain_lock_status` / `toggle_domain_lock`
+
+Check or toggle the registrar transfer lock on a domain.
+
+---
+
+### DNS Tools
+
+Manage DNS records for your domains.
+
+> **Note:** You must enable DNS management on a domain before creating records.
+
+#### `enable_dns_management`
+
+Enable DNS management for a domain (one-time setup).
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `domainId` | Yes | Domain ID |
+
+#### `list_dns_records`
+
+List all DNS records for a domain.
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `domainId` | Yes | Domain ID |
+
+#### `create_dns_record`
+
+Create a DNS record.
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `domainId` | Yes | Domain ID |
+| `type` | Yes | Record type: `A`, `AAAA`, `CNAME`, `TXT`, `MX`, `NS`, `SRV`, `CAA` |
+| `name` | Yes | Record name (e.g., "@", "www", "api") |
+| `content` | Yes | Record value (IP, hostname, text) |
+| `ttl` | No | Time-to-live in seconds (min: 60) |
+| `priority` | No | Priority (required for MX, SRV) |
+
+**Example prompt:** *"Add an A record pointing api.example.com to 203.0.113.50"*
+
+#### `update_dns_record`
+
+Update an existing DNS record. At least one field must change.
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `domainId` | Yes | Domain ID |
+| `recordId` | Yes | Record ID (from `list_dns_records`) |
+| `type` | No | New record type |
+| `name` | No | New name |
+| `content` | No | New value |
+| `ttl` | No | New TTL |
+| `priority` | No | New priority |
+
+#### `delete_dns_record`
+
+Delete a DNS record. This is irreversible.
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `domainId` | Yes | Domain ID |
+| `recordId` | Yes | Record ID |
+
+---
+
+### Account & Billing Tools
+
+View your profile, invoices, subscriptions, and billing information.
+
+#### `get_account_info`
+
+Get your profile — name, email, company, client ID, currency, and credit balance.
+
+#### `list_invoices`
+
+List invoices with optional status filter.
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `status` | No | Filter: `Paid`, `Unpaid`, `Cancelled`, `Refunded` |
+| `page` | No | Page number for pagination |
+
+#### `get_invoice`
+
+Get invoice details including line items, totals, and payment info.
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `invoiceId` | Yes | Invoice ID (number) |
+
+#### `list_subscriptions`
+
+List your active local subscriptions (AI Studio, Deploy, VoIP, etc.).
+
+#### `check_perks`
+
+Check which subscription perks are active on your account (e.g., `deploy_hobby`, `studio_pro`, `voip_basic`).
+
+#### `list_orders`
+
+List recent orders.
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `page` | No | Page number |
+
+#### `get_account_balance`
+
+Get your account credit balance.
+
+---
+
+### Service Tools
+
+Manage WHMCS hosting and server services.
+
+#### `list_services`
+
+List all your hosting services with status, domain, IP, and billing info.
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `page` | No | Page number |
+
+#### `get_service_details`
+
+Get full service details — configuration options, server info, custom fields.
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `serviceId` | Yes | Service ID (number) |
+
+#### `get_service_sso_url`
+
+Get a single sign-on URL to access your service's control panel (Plesk, Pterodactyl, etc.) without logging in separately.
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `serviceId` | Yes | Service ID |
+
+**Example prompt:** *"Give me a login link for my game server"*
+
+#### `upgrade_service`
+
+Get upgrade/downgrade options and a link to manage the service.
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `serviceId` | Yes | Service ID |
+
+---
+
+### Support Tools
+
+Create and manage support tickets.
+
+#### `list_tickets`
+
+List support tickets with optional status filter.
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `status` | No | `Open`, `Answered`, `Customer-Reply`, `Closed`, `On Hold` |
+| `page` | No | Page number |
+
+#### `get_ticket`
+
+Get full ticket details including all replies.
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `ticketId` | Yes | Ticket ID (number) |
+
+#### `open_support_ticket`
+
+Open a new support ticket.
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `deptid` | Yes | Department ID (number) |
+| `subject` | Yes | Ticket subject |
+| `message` | Yes | Ticket body |
+| `priority` | No | `Low`, `Medium`, `High` |
+| `serviceId` | No | Related service ID |
+
+**Example prompt:** *"Open a support ticket about my web hosting service being slow"*
+
+#### `reply_to_ticket`
+
+Add a reply to an existing ticket.
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `ticketId` | Yes | Ticket ID |
+| `message` | Yes | Reply text |
+
+#### `close_ticket`
+
+Close a ticket with an optional closing message.
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `ticketId` | Yes | Ticket ID |
+| `message` | No | Closing message |
+
+---
+
+### Server Admin (BYOS) Tools
+
+Manage your own servers via SSH. These tools work entirely locally — no Suzko account is needed for server admin. Server connections are stored in `~/.suzko/servers.json`.
+
+> **Security:** Dangerous commands (like `rm -rf /`, `dd`, `mkfs`, fork bombs) are blocked automatically.
+
+#### `connect_server`
+
+Register a server and test the SSH connection.
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `alias` | Yes | Friendly name for the server (e.g., "prod-web") |
+| `host` | Yes | IP address or hostname |
+| `user` | No | SSH username (default: `root`) |
+| `port` | No | SSH port (default: `22`) |
+| `keyPath` | No | Path to SSH key (default: `~/.ssh/id_ed25519`) |
+
+**Example prompt:** *"Connect to my server at 203.0.113.10 as root and call it prod-web"*
+
+#### `list_servers`
+
+List all registered servers from the local registry.
+
+#### `inspect_server`
+
+Run diagnostics — OS, uptime, CPU, memory, disk, Docker status, network.
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `alias` | Yes | Server alias |
+
+**Example prompt:** *"What's the status of my prod-web server?"*
+
+#### `run_server_command`
+
+Execute a shell command on a server via SSH.
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `alias` | Yes | Server alias |
+| `command` | Yes | Shell command to run |
+| `timeout` | No | Timeout in ms (default: 60000) |
+
+**Example prompt:** *"Run 'nginx -t' on prod-web to check the config"*
+
+#### `install_docker`
+
+Install Docker and the compose plugin via the official install script.
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `alias` | Yes | Server alias |
+
+#### `deploy_to_server`
+
+Upload a local directory via SCP and run `docker compose up -d`.
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `alias` | Yes | Server alias |
+| `localPath` | Yes | Local directory to upload |
+| `remotePath` | No | Remote destination (default: `/opt/deploy`) |
+
+**Example prompt:** *"Deploy my project at ./my-app to prod-web"*
+
+#### `list_server_containers`
+
+List Docker containers on a server.
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `alias` | Yes | Server alias |
+| `all` | No | Include stopped containers (default: `true`) |
+
+#### `manage_server_container`
+
+Start, stop, restart, or remove a Docker container.
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `alias` | Yes | Server alias |
+| `container` | Yes | Container name or ID |
+| `action` | Yes | `start`, `stop`, `restart`, or `remove` |
+
+#### `setup_ssl`
+
+Install Certbot and obtain a Let's Encrypt SSL certificate.
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `alias` | Yes | Server alias |
+| `domain` | Yes | Domain for the certificate |
+| `email` | No | Email for renewal notifications |
+| `mode` | No | `nginx` or `standalone` (default: `standalone`) |
+
+#### `get_server_status`
+
+Get live system status — CPU, memory, disk, load average, top processes, network connections.
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `alias` | Yes | Server alias |
+
+#### `get_server_logs`
+
+Read logs from various sources.
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `alias` | Yes | Server alias |
+| `source` | Yes | `journalctl`, `docker`, or `file` |
+| `target` | No | Container name (for docker) or file path (for file) |
+| `lines` | No | Number of lines (default: 50) |
+
+**Example prompt:** *"Show me nginx logs on prod-web"*
+
+#### `manage_env_file`
+
+Read or write `.env` files on a server. In `set` mode, merges with existing keys.
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `alias` | Yes | Server alias |
+| `remotePath` | Yes | Path to `.env` file |
+| `mode` | Yes | `get` (read) or `set` (write) |
+| `values` | No | Key-value pairs to set (required for `set` mode) |
+
+---
+
+## Resources
+
+Resources are read-only data that your AI can reference during a conversation. They're loaded on demand via `suzko://` URIs.
+
+| URI | Description |
+|-----|-------------|
+| `suzko://services` | Your active hosting services |
+| `suzko://deploy/projects` | Your deployed projects and containers |
+| `suzko://domains` | Your registered domains |
+| `suzko://invoices` | Billing history and outstanding invoices |
+| `suzko://perks` | Your active subscription perks |
+
+In Claude Desktop, you can attach resources by clicking the 📎 icon and selecting from the `suzko://` list.
+
+---
+
+## Prompts (Workflow Templates)
+
+Prompts are pre-built conversation starters for common workflows. They set up the right context so your AI knows which tools to use.
+
+### `deploy-app`
+
+Deploy an application end-to-end.
+
+| Parameter | Description |
+|-----------|-------------|
+| `appType` | Type of app: "next.js", "express", "static", "docker" |
+| `database` | Database needed: "postgres", "mysql", "mongodb", "none" |
+
+**What it does:** Lists templates → creates project → sets up database → configures env vars → verifies everything runs.
+
+### `find-domain`
+
+Search and register a domain name.
+
+| Parameter | Description |
+|-----------|-------------|
+| `keywords` | Keywords for the domain (e.g., "my startup", "tech blog") |
+| `tld` | Preferred TLD (e.g., ".com", ".dev") |
+
+**What it does:** Searches availability → suggests alternatives → shows pricing → handles registration.
+
+### `troubleshoot-service`
+
+Diagnose issues with a deployed service.
+
+| Parameter | Description |
+|-----------|-------------|
+| `projectId` | Project ID or name |
+| `issue` | Description of the problem |
+
+**What it does:** Finds the project → checks status → reads logs → reads build logs → suggests fixes.
+
+### `setup-server`
+
+Set up a new BYOS server.
+
+| Parameter | Description |
+|-----------|-------------|
+| `host` | Server IP or hostname |
+| `user` | SSH username (default: root) |
+| `purpose` | What the server is for |
+
+**What it does:** Connects via SSH → inspects system → installs Docker → sets up services → configures SSL → hardens security.
+
+---
+
+## Human-in-the-Loop Confirmation
+
+Operations that cost money or create resources use a **two-step confirmation** flow to prevent accidental charges:
+
+1. You ask the AI to do something (e.g., "Register example.com")
+2. The tool returns a **cost preview** with a confirmation token
+3. The AI presents the cost to you: *"example.com costs $12.99/yr. Shall I proceed?"*
+4. You confirm → the AI calls the confirm tool with the token
+5. The action is executed
+
+**Confirmation tokens:**
+- Valid for **5 minutes** from creation
+- **Single-use** — each token can only be used once
+- Stored in memory on the MCP server process (not persisted)
+
+**Operations that require confirmation:**
+- `create_deploy_project` → `confirm_deploy_project`
+- `register_domain` → `confirm_domain_registration`
+- `transfer_domain` → `confirm_domain_transfer`
+
+---
+
+## Example Conversations
+
+### Deploy a Full-Stack App
+
+> **You:** I need to deploy a Next.js app with a PostgreSQL database
+> 
+> **AI:** Let me check what's available...
+> *(calls `list_deploy_templates`)*
+> 
+> I see PostgreSQL and Node.js templates. Let me set up the database first.
+> *(calls `create_deploy_project` with name="my-app-db", templateId="postgres", tier="small")*
+> 
+> Here's the cost: **PostgreSQL on small tier (1GB RAM, shared CPU) — $0/mo** (included in your Deploy Pro plan). Want me to proceed?
+> 
+> **You:** Yes, go ahead
+> 
+> **AI:** *(calls `confirm_deploy_project`)*
+> 
+> Database is running! Connection: `postgres://postgres:abc123@my-app-db.suzko.io:5432/postgres`
+> 
+> Now let me set up your Next.js app...
+> *(calls `create_deploy_project` with templateId="nodejs", envVars={"DATABASE_URL": "..."})*
+
+### Register a Domain + Configure DNS
+
+> **You:** Find me a cool domain for my AI coding tool
+> 
+> **AI:** *(calls `suggest_domain_names` with keywords="AI coding tool")*
+> 
+> Here are some suggestions:
+> - codesmith.dev — $12.99/yr ✅ Available
+> - aicodecraft.io — $39.99/yr ✅ Available
+> - codecopilot.com — ❌ Taken
+> 
+> **You:** Register codesmith.dev for 2 years
+> 
+> **AI:** *(calls `register_domain`)*
+> 
+> Cost: **codesmith.dev — $25.98** (2 years). Confirm?
+> 
+> **You:** Yes
+> 
+> **AI:** *(calls `confirm_domain_registration`)*
+> 
+> Done! Now let me point it to your deploy project...
+> *(calls `enable_dns_management`, then `create_dns_record` with CNAME)*
+
+### Manage Your Own Server
+
+> **You:** I just got a VPS at 198.51.100.25, set it up for Docker hosting
+> 
+> **AI:** *(calls `connect_server` with alias="my-vps", host="198.51.100.25")*
+> 
+> Connected! Let me check what's installed...
+> *(calls `inspect_server`)*
+> 
+> Ubuntu 22.04, no Docker yet. Installing...
+> *(calls `install_docker`)*
+> 
+> Docker installed! Now let me deploy your project...
+> *(calls `deploy_to_server` with localPath="./my-app")*
+
+### Troubleshoot a Deployment
+
+> **You:** My web app is returning 502 errors
+> 
+> **AI:** Let me check your projects...
+> *(calls `list_deploy_projects`)*
+> *(calls `get_deploy_logs` with tail=50)*
+> 
+> I see the issue — your app is crashing on startup because `DATABASE_URL` is not set. Let me fix that...
+> *(calls `set_deploy_env` with envVars={"DATABASE_URL": "..."})*
+> *(calls `control_deploy_project` with action="restart")*
+> 
+> Restarted! Checking logs... it's running now. ✅
+
+---
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `SUZKO_API_BASE` | `https://www.suzko.com` | API base URL. Change for development. |
+
+### File Locations
+
+| File | Purpose |
+|------|---------|
+| `~/.suzko/mcp-credentials.json` | Auth tokens (auto-managed) |
+| `~/.suzko/servers.json` | BYOS server registry (managed by server admin tools) |
+
+---
+
+## Troubleshooting
+
+### "Not authenticated" errors
+
+Run `npx @suzko/mcp-server auth login` to log in, or `auth status` to check your token.
+
+### Tools not appearing in IDE
+
+1. Verify the MCP config is valid JSON
+2. Restart your IDE after changing MCP config
+3. Check the MCP server logs in your IDE's output panel
+4. Run `npx @suzko/mcp-server --help` to verify the package works
+
+### "API error 401"
+
+Your token may have expired and auto-refresh failed. Run `auth login` again.
+
+### "API error 403" on deploy tools
+
+You may need a Deploy subscription. Check with `check_perks` — you need at least `deploy_hobby`.
+
+### Server admin SSH failures
+
+- Verify your SSH key exists at the configured path
+- Check the server accepts key-based authentication
+- Try connecting manually: `ssh -i ~/.ssh/id_ed25519 root@your-server`
+- Ensure the server's SSH port is reachable (not blocked by firewall)
+
+### Slow tool responses
+
+The MCP server calls the Suzko API over HTTPS. If responses are slow:
+- Check your internet connection
+- The first call may be slower (token refresh)
+- Deploy operations (create, build) are async and may take 10–30 seconds
+
+### IDE-specific issues
+
+**VS Code:** Make sure you're in **agent mode** (not ask/edit mode) for tool execution.
+
+**Claude Desktop:** After editing config, fully quit and reopen (not just close the window).
+
+**Cursor:** MCP tools appear in Composer, not regular chat.