@suzko/mcp-server 0.1.0

package/dist/src/prompts/index.js

@@ -0,0 +1,87 @@
+/**
+ * MCP Prompts — workflow templates for common tasks.
+ */
+import { z } from "zod";
+export function registerPrompts(server) {
+    server.prompt("deploy-app", "Deploy an application to Suzko cloud", {
+        appType: z.string().optional().describe("Type of app (e.g., next.js, express, static, docker)"),
+        database: z.string().optional().describe("Database needed (postgres, mysql, mongodb, none)"),
+    }, async ({ appType, database }) => ({
+        messages: [{
+                role: "user",
+                content: {
+                    type: "text",
+                    text: `I want to deploy ${appType || "my application"} to Suzko's cloud platform.${database && database !== "none"
+                        ? ` I need a ${database} database.`
+                        : ""}
+
+Please help me:
+1. Check what templates are available using list_deploy_templates
+2. Create a deploy project with the right template
+3. If I need a database, set one up and give me the connection string
+4. Help me configure environment variables
+5. Make sure everything is running
+
+Start by listing the available templates.`,
+                },
+            }],
+    }));
+    server.prompt("find-domain", "Search and register a domain name", {
+        keywords: z.string().describe("Keywords for the domain (e.g., 'my startup', 'tech blog')"),
+        tld: z.string().optional().describe("Preferred TLD (e.g., .com, .dev, .io)"),
+    }, async ({ keywords, tld }) => ({
+        messages: [{
+                role: "user",
+                content: {
+                    type: "text",
+                    text: `I'm looking for a domain name. My keywords are: "${keywords}"${tld ? `. I prefer ${tld} domains.` : ""}
+
+Please:
+1. Search for available domains using search_domains
+2. Suggest creative alternatives using suggest_domain_names  
+3. Show me pricing for the best options
+4. Help me register my favorite one`,
+                },
+            }],
+    }));
+    server.prompt("troubleshoot-service", "Diagnose and fix issues with a deployed service", {
+        projectId: z.string().optional().describe("Deploy project ID or name"),
+        issue: z.string().optional().describe("Description of the problem"),
+    }, async ({ projectId, issue }) => ({
+        messages: [{
+                role: "user",
+                content: {
+                    type: "text",
+                    text: `I'm having issues with ${projectId ? `project ${projectId}` : "one of my deployed services"}.${issue ? ` The problem: ${issue}` : ""}
+
+Please help me troubleshoot:
+1. List my projects to find the right one
+2. Check the project status and details
+3. Read the logs for errors
+4. Check build logs if it's a deployment issue
+5. Suggest fixes based on what you find`,
+                },
+            }],
+    }));
+    server.prompt("setup-server", "Set up a new server (BYOS - Bring Your Own Server)", {
+        host: z.string().describe("Server IP or hostname"),
+        user: z.string().optional().describe("SSH username (default: root)"),
+        purpose: z.string().optional().describe("What the server is for (e.g., web app, database, docker host)"),
+    }, async ({ host, user, purpose }) => ({
+        messages: [{
+                role: "user",
+                content: {
+                    type: "text",
+                    text: `I have a server at ${host} (user: ${user || "root"}).${purpose ? ` I want to use it for: ${purpose}` : ""}
+
+Please help me set it up:
+1. Connect to the server using connect_server
+2. Inspect it to see what's already installed
+3. Install Docker if needed
+4. Set up the appropriate services for my use case
+5. Configure SSL if it's a web server
+6. Make sure everything is secure (firewall, etc.)`,
+                },
+            }],
+    }));
+}

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

@@ -0,0 +1,7 @@
+/**
+ * MCP Resources — read-only data the AI can reference.
+ * Uses suzko:// URI scheme.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { SuzkoClient } from "../client.js";
+export declare function registerResources(server: McpServer, client: SuzkoClient): void;

package/dist/src/resources/index.js

@@ -0,0 +1,86 @@
+/**
+ * MCP Resources — read-only data the AI can reference.
+ * Uses suzko:// URI scheme.
+ */
+export function registerResources(server, client) {
+    // Resource: List of active services
+    server.resource("services", "suzko://services", { description: "Your active hosting services" }, async () => {
+        try {
+            const res = await client.get("/api/client/services");
+            return {
+                contents: [{
+                        uri: "suzko://services",
+                        mimeType: "application/json",
+                        text: JSON.stringify(res.data || [], null, 2),
+                    }],
+            };
+        }
+        catch {
+            return { contents: [{ uri: "suzko://services", mimeType: "text/plain", text: "Failed to load services" }] };
+        }
+    });
+    // Resource: Deploy projects 
+    server.resource("deploy-projects", "suzko://deploy/projects", { description: "Your deployed projects and containers" }, async () => {
+        try {
+            const res = await client.get("/api/deploy/projects");
+            return {
+                contents: [{
+                        uri: "suzko://deploy/projects",
+                        mimeType: "application/json",
+                        text: JSON.stringify(res.data || [], null, 2),
+                    }],
+            };
+        }
+        catch {
+            return { contents: [{ uri: "suzko://deploy/projects", mimeType: "text/plain", text: "Failed to load projects" }] };
+        }
+    });
+    // Resource: Domains
+    server.resource("domains", "suzko://domains", { description: "Your registered domains" }, async () => {
+        try {
+            const res = await client.get("/api/client/domains");
+            return {
+                contents: [{
+                        uri: "suzko://domains",
+                        mimeType: "application/json",
+                        text: JSON.stringify(res.data || [], null, 2),
+                    }],
+            };
+        }
+        catch {
+            return { contents: [{ uri: "suzko://domains", mimeType: "text/plain", text: "Failed to load domains" }] };
+        }
+    });
+    // Resource: Invoices
+    server.resource("invoices", "suzko://invoices", { description: "Your billing history and outstanding invoices" }, async () => {
+        try {
+            const res = await client.get("/api/client/invoices");
+            return {
+                contents: [{
+                        uri: "suzko://invoices",
+                        mimeType: "application/json",
+                        text: JSON.stringify(res.invoices || [], null, 2),
+                    }],
+            };
+        }
+        catch {
+            return { contents: [{ uri: "suzko://invoices", mimeType: "text/plain", text: "Failed to load invoices" }] };
+        }
+    });
+    // Resource: Subscription perks
+    server.resource("perks", "suzko://perks", { description: "Your active subscription perks and features" }, async () => {
+        try {
+            const res = await client.get("/api/store/subscriptions/perks");
+            return {
+                contents: [{
+                        uri: "suzko://perks",
+                        mimeType: "application/json",
+                        text: JSON.stringify(res.data || {}, null, 2),
+                    }],
+            };
+        }
+        catch {
+            return { contents: [{ uri: "suzko://perks", mimeType: "text/plain", text: "Failed to load perks" }] };
+        }
+    });
+}

package/dist/src/security.d.ts

@@ -0,0 +1,18 @@
+/** Validate the API base URL: must be HTTPS on an allowlisted host. */
+export declare function validateApiBase(input: string | undefined | null): string;
+/** POSIX single-quote escape for shell command interpolation. */
+export declare function shellQuote(value: string): string;
+/** Validate an absolute POSIX path. Rejects traversal, NULs, newlines. */
+export declare function assertSafePath(path: string, opts?: {
+    allowedPrefixes?: string[];
+}): string;
+/** Validate a fully-qualified domain name. */
+export declare function assertSafeDomain(domain: string): string;
+/** Validate an email address. */
+export declare function assertSafeEmail(email: string): string;
+/** Validate a single DNS label (1-63 chars, alnum + hyphen). */
+export declare function assertSafeSubdomain(subdomain: string): string;
+/** Validate a DNS record name. */
+export declare function assertSafeDnsName(name: string): string;
+/** Validate a DNS record value. */
+export declare function assertSafeDnsContent(content: string, maxLen?: number): string;

package/dist/src/security.js

@@ -0,0 +1,108 @@
+const ALLOWED_API_HOSTS = new Set([
+    "www.suzko.com",
+    "dev.suzko.net",
+]);
+/** Validate the API base URL: must be HTTPS on an allowlisted host. */
+export function validateApiBase(input) {
+    if (!input || typeof input !== "string") {
+        throw new Error("Invalid SUZKO_API_BASE: empty or not a string.");
+    }
+    let url;
+    try {
+        url = new URL(input);
+    }
+    catch {
+        throw new Error(`Invalid SUZKO_API_BASE "${input}": not a valid URL.`);
+    }
+    if (url.protocol !== "https:") {
+        throw new Error(`Invalid SUZKO_API_BASE "${input}": must use https://.`);
+    }
+    if (!ALLOWED_API_HOSTS.has(url.hostname)) {
+        const allowed = Array.from(ALLOWED_API_HOSTS).join(", ");
+        throw new Error(`Invalid SUZKO_API_BASE "${input}": hostname "${url.hostname}" is not allowed. Expected one of: ${allowed}.`);
+    }
+    return url.origin;
+}
+/** POSIX single-quote escape for shell command interpolation. */
+export function shellQuote(value) {
+    return `'${String(value).replace(/'/g, "'\\''")}'`;
+}
+/** Validate an absolute POSIX path. Rejects traversal, NULs, newlines. */
+export function assertSafePath(path, opts = {}) {
+    if (typeof path !== "string" || path.length === 0) {
+        throw new Error("Path must be a non-empty string.");
+    }
+    if (path.includes("\0")) {
+        throw new Error("Path contains a null byte.");
+    }
+    if (/[\r\n]/.test(path)) {
+        throw new Error("Path contains a newline.");
+    }
+    if (!path.startsWith("/")) {
+        throw new Error(`Path "${path}" must be absolute.`);
+    }
+    if (path.split("/").includes("..")) {
+        throw new Error(`Path "${path}" contains a traversal segment.`);
+    }
+    if (opts.allowedPrefixes && opts.allowedPrefixes.length > 0) {
+        const ok = opts.allowedPrefixes.some((p) => path === p || path.startsWith(p.endsWith("/") ? p : p + "/"));
+        if (!ok) {
+            throw new Error(`Path "${path}" must start with one of: ${opts.allowedPrefixes.join(", ")}.`);
+        }
+    }
+    return path;
+}
+/** Validate a fully-qualified domain name. */
+export function assertSafeDomain(domain) {
+    if (typeof domain !== "string" || domain.length === 0 || domain.length > 253) {
+        throw new Error("Domain must be a non-empty string under 254 chars.");
+    }
+    if (!/^(?=.{1,253}$)(?!-)[a-z0-9-]{1,63}(?<!-)(\.(?!-)[a-z0-9-]{1,63}(?<!-))+$/i.test(domain)) {
+        throw new Error(`Invalid domain "${domain}".`);
+    }
+    return domain;
+}
+/** Validate an email address. */
+export function assertSafeEmail(email) {
+    if (typeof email !== "string" || email.length === 0 || email.length > 254) {
+        throw new Error("Email must be a non-empty string under 255 chars.");
+    }
+    if (!/^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}$/.test(email)) {
+        throw new Error(`Invalid email "${email}".`);
+    }
+    if (/[\r\n\s]/.test(email)) {
+        throw new Error("Email contains whitespace.");
+    }
+    return email;
+}
+/** Validate a single DNS label (1-63 chars, alnum + hyphen). */
+export function assertSafeSubdomain(subdomain) {
+    if (typeof subdomain !== "string" ||
+        !/^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/i.test(subdomain)) {
+        throw new Error(`Invalid subdomain "${subdomain}".`);
+    }
+    return subdomain;
+}
+/** Validate a DNS record name. */
+export function assertSafeDnsName(name) {
+    if (typeof name !== "string" || name.length === 0 || name.length > 253) {
+        throw new Error("DNS name must be 1-253 chars.");
+    }
+    if (!/^[A-Za-z0-9._@*-]+$/.test(name)) {
+        throw new Error(`Invalid DNS name "${name}".`);
+    }
+    return name;
+}
+/** Validate a DNS record value. */
+export function assertSafeDnsContent(content, maxLen = 2048) {
+    if (typeof content !== "string" || content.length === 0) {
+        throw new Error("DNS content must be a non-empty string.");
+    }
+    if (content.length > maxLen) {
+        throw new Error(`DNS content too long (max ${maxLen} chars).`);
+    }
+    if (/[\0\r\n]/.test(content)) {
+        throw new Error("DNS content contains a NUL or newline.");
+    }
+    return content;
+}

package/dist/src/tools/account.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { SuzkoClient } from "../client.js";
+export declare function registerAccountTools(server: McpServer, client: SuzkoClient): void;

package/dist/src/tools/account.js

@@ -0,0 +1,254 @@
+import { z } from "zod";
+export function registerAccountTools(server, client) {
+    // 1. Get account info
+    server.tool("get_account_info", "Get the authenticated user's profile information including name, email, company, and currency.", {}, async () => {
+        const res = await client.get("/api/auth/device-session");
+        if (!res.success) {
+            return {
+                content: [{ type: "text", text: `Error: ${res.error || "Failed to get account info"}` }],
+                isError: true,
+            };
+        }
+        const u = res.data;
+        if (!u) {
+            return {
+                content: [{ type: "text", text: "No user data returned." }],
+                isError: true,
+            };
+        }
+        const lines = [
+            `**Account Info**`,
+            `- **Name:** ${u.firstName} ${u.lastName}`,
+            `- **Email:** ${u.email}`,
+            u.companyName ? `- **Company:** ${u.companyName}` : null,
+            `- **Client ID:** ${u.id}`,
+            u.currencyCode ? `- **Currency:** ${u.currencyCode}` : null,
+            u.credit ? `- **Credit Balance:** ${u.credit}` : null,
+        ].filter(Boolean);
+        return {
+            content: [{ type: "text", text: lines.join("\n") }],
+        };
+    });
+    // 2. List invoices
+    server.tool("list_invoices", "List invoices for the authenticated user. Optionally filter by status (Paid, Unpaid, Cancelled, Refunded).", {
+        status: z
+            .string()
+            .optional()
+            .describe("Filter by invoice status: Paid, Unpaid, Cancelled, Refunded"),
+        page: z
+            .number()
+            .optional()
+            .describe("Page number (each page is 25 invoices, starting from 1)"),
+    }, async ({ status, page }) => {
+        const params = {};
+        if (status)
+            params.status = status;
+        if (page && page > 1)
+            params.limitstart = String((page - 1) * 25);
+        const res = await client.get("/api/invoices", params);
+        if (res.error) {
+            return {
+                content: [{ type: "text", text: `Error: ${res.error}` }],
+                isError: true,
+            };
+        }
+        const invoices = res.invoices ?? [];
+        if (invoices.length === 0) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: status
+                            ? `No invoices found with status "${status}".`
+                            : "No invoices found.",
+                    },
+                ],
+            };
+        }
+        const lines = invoices.map((inv) => {
+            const bal = inv.balance && inv.balance !== inv.total ? ` (balance: ${inv.balance})` : "";
+            return `• **#${inv.invoicenum || inv.id}** — ${inv.status} | ${inv.total}${bal} | Due: ${inv.duedate}`;
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `**Invoices (${invoices.length}${res.totalresults ? ` of ${res.totalresults}` : ""}):**\n\n${lines.join("\n")}`,
+                },
+            ],
+        };
+    });
+    // 3. Get invoice details
+    server.tool("get_invoice", "Get detailed information about a specific invoice including line items and payment info.", {
+        invoiceId: z.number().describe("The invoice ID to retrieve"),
+    }, async ({ invoiceId }) => {
+        const res = await client.get("/api/invoices", { id: String(invoiceId) });
+        if (res.error || !res.invoice) {
+            return {
+                content: [{ type: "text", text: `Error: ${res.error || "Invoice not found"}` }],
+                isError: true,
+            };
+        }
+        const inv = res.invoice;
+        const items = inv.items?.item ?? [];
+        const header = [
+            `**Invoice #${inv.invoicenum || inv.invoiceid || inv.id}**`,
+            `- **Status:** ${inv.status}`,
+            `- **Date:** ${inv.date}`,
+            `- **Due Date:** ${inv.duedate}`,
+            inv.datepaid ? `- **Date Paid:** ${inv.datepaid}` : null,
+            `- **Total:** ${inv.total}`,
+            inv.balance ? `- **Balance:** ${inv.balance}` : null,
+            inv.subtotal ? `- **Subtotal:** ${inv.subtotal}` : null,
+            inv.tax && inv.tax !== "0.00" ? `- **Tax:** ${inv.tax}` : null,
+            inv.credit && inv.credit !== "0.00" ? `- **Credit Applied:** ${inv.credit}` : null,
+            inv.paymentmethod ? `- **Payment Method:** ${inv.paymentmethod}` : null,
+            inv.notes ? `- **Notes:** ${inv.notes}` : null,
+        ].filter(Boolean);
+        let itemsText = "";
+        if (items.length > 0) {
+            const itemLines = items.map((it) => `  • ${it.description} — ${it.amount}`);
+            itemsText = `\n\n**Line Items (${items.length}):**\n${itemLines.join("\n")}`;
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: header.join("\n") + itemsText,
+                },
+            ],
+        };
+    });
+    // 4. List subscriptions
+    server.tool("list_subscriptions", "List the user's active local subscriptions (AI, Deploy, VoIP, Marketing, etc.).", {}, async () => {
+        const res = await client.get("/api/store/subscriptions");
+        if (!res.success) {
+            return {
+                content: [{ type: "text", text: `Error: ${res.error || "Failed to fetch subscriptions"}` }],
+                isError: true,
+            };
+        }
+        const subs = res.data ?? [];
+        if (subs.length === 0) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "No active subscriptions. Visit https://www.suzko.com/store to browse available plans.",
+                    },
+                ],
+            };
+        }
+        const lines = subs.map((s) => {
+            const price = s.amount != null
+                ? ` | ${s.currency || "$"}${(s.amount / 100).toFixed(2)}/${s.billingCycle || "mo"}`
+                : "";
+            const due = s.nextDueDate ? ` | Next due: ${s.nextDueDate}` : "";
+            return `• **${s.productName || s.productSlug}** — ${s.status}${price}${due}`;
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `**Active Subscriptions (${subs.length}):**\n\n${lines.join("\n")}`,
+                },
+            ],
+        };
+    });
+    // 5. Check perks
+    server.tool("check_perks", "Check which subscription perks the user currently has (deploy_hobby, studio_pro, voip_basic, marketing_automation, etc.).", {}, async () => {
+        const res = await client.get("/api/store/subscriptions/perks");
+        if (!res.success) {
+            return {
+                content: [{ type: "text", text: `Error: ${res.error || "Failed to check perks"}` }],
+                isError: true,
+            };
+        }
+        const perks = res.data ?? {};
+        const activePerks = Object.entries(perks).filter(([, v]) => v);
+        if (activePerks.length === 0) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "No active subscription perks. Subscribe to a plan at https://www.suzko.com/store to unlock features.",
+                    },
+                ],
+            };
+        }
+        const lines = activePerks.map(([key]) => `• \`${key}\``);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `**Active Perks (${activePerks.length}):**\n\n${lines.join("\n")}`,
+                },
+            ],
+        };
+    });
+    // 6. List orders (uses invoices as fallback since no dedicated orders endpoint)
+    server.tool("list_orders", "List recent orders. Shows invoices as order summary since orders map to invoices in the billing system.", {
+        page: z
+            .number()
+            .optional()
+            .describe("Page number (each page is 25 results, starting from 1)"),
+    }, async ({ page }) => {
+        const params = {};
+        if (page && page > 1)
+            params.limitstart = String((page - 1) * 25);
+        const res = await client.get("/api/invoices", params);
+        if (res.error) {
+            return {
+                content: [{ type: "text", text: `Error: ${res.error}` }],
+                isError: true,
+            };
+        }
+        const invoices = res.invoices ?? [];
+        if (invoices.length === 0) {
+            return {
+                content: [
+                    { type: "text", text: "No orders found." },
+                ],
+            };
+        }
+        const lines = invoices.map((inv) => {
+            const bal = inv.balance && inv.balance !== inv.total ? ` (balance: ${inv.balance})` : "";
+            return `• **#${inv.invoicenum || inv.id}** — ${inv.status} | ${inv.total}${bal} | ${inv.date}`;
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `**Orders — Showing invoices as order summary (${invoices.length}${res.totalresults ? ` of ${res.totalresults}` : ""}):**\n\n${lines.join("\n")}`,
+                },
+            ],
+        };
+    });
+    // 7. Get account balance
+    server.tool("get_account_balance", "Get the user's account credit balance from their profile.", {}, async () => {
+        const res = await client.get("/api/auth/device-session");
+        if (!res.success) {
+            return {
+                content: [{ type: "text", text: `Error: ${res.error || "Failed to get balance"}` }],
+                isError: true,
+            };
+        }
+        const u = res.data;
+        if (!u) {
+            return {
+                content: [{ type: "text", text: "No user data returned." }],
+                isError: true,
+            };
+        }
+        const credit = u.credit || "0.00";
+        const currency = u.currencyCode || "USD";
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `**Account Balance:** ${credit} ${currency}\n\nThis is the credit balance on your account that can be applied to invoices.`,
+                },
+            ],
+        };
+    });
+}

package/dist/src/tools/deploy.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { SuzkoClient } from "../client.js";
+export declare function registerDeployTools(server: McpServer, client: SuzkoClient): void;