@offlocal/mcp 0.2.0 → 0.3.1

package/dist/client.js

@@ -157,6 +157,26 @@ export async function setProjectEnv(projectId, vars) {
         return { error: json.error ?? String(res.status), message: json.message };
     return json;
 }
+export async function rollback(projectId, toDeploymentId) {
+    const res = await fetch(`${API_URL}/api/projects/${encodeURIComponent(projectId)}/rollback`, {
+        method: "POST",
+        headers: { "content-type": "application/json", ...authHeaders() },
+        body: JSON.stringify(toDeploymentId ? { toDeploymentId } : {}),
+    });
+    const json = (await res.json().catch(() => ({})));
+    if (!res.ok) {
+        return { error: json.error ?? String(res.status), message: json.message };
+    }
+    return json;
+}
+export async function getPlanInfo() {
+    const res = await fetch(`${API_URL}/api/me/plan`, {
+        headers: { ...authHeaders() },
+    });
+    if (!res.ok)
+        throw new Error(await failureText(res, "get_plan"));
+    return (await res.json());
+}
 async function failureText(res, kind) {
     const body = await res.text().catch(() => "");
     return `${kind} failed: ${res.status} ${res.statusText}${body ? ` - ${body.slice(0, 400)}` : ""}`;

package/dist/detect.js

@@ -313,6 +313,8 @@ function pickNodeFramework(deps) {
         return "remix";
     if ("astro" in deps)
         return "astro";
+    if ("vite" in deps)
+        return "vite";
     if ("fastify" in deps)
         return "fastify";
     if ("hono" in deps)
@@ -321,8 +323,6 @@ function pickNodeFramework(deps) {
         return "express";
     if ("koa" in deps)
         return "koa";
-    if ("vite" in deps)
-        return "vite";
     return "node";
 }
 function nodePort(framework) {

package/dist/index.js

@@ -3,7 +3,8 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import { pingApi } from "./client.js";
-import { DeployInputShape, deployHandler } from "./tools/deploy.js";
+import { DeployInputShape, RollbackInputShape, deployHandler, rollbackHandler, } from "./tools/deploy.js";
+import { PlansInputShape, plansHandler } from "./tools/plans.js";
 import { StatusInputShape, statusHandler } from "./tools/status.js";
 import { LogsInputShape, logsHandler } from "./tools/logs.js";
 import { PingInputShape, pingHandler } from "./tools/ping.js";
@@ -21,6 +22,8 @@ const CreateManagedDatabaseSchema = z.object(CreateManagedDatabaseInputShape);
 const SetEnvSchema = z.object(SetEnvInputShape);
 const PlanSchema = z.object(PlanInputShape);
 const SetPreferenceSchema = z.object(SetPreferenceInputShape);
+const RollbackSchema = z.object(RollbackInputShape);
+const PlansSchema = z.object(PlansInputShape);
 async function main() {
     const server = new McpServer({
         name: "offlocal",
@@ -32,6 +35,8 @@ async function main() {
     server.tool("offlocal_deploy", "Deploy an app from a local directory to Offlocal. Returns a deploymentId you can poll with offlocal_status. Supports Node, Python, Go, Rust, and static sites out of the box (auto-detecting runtime/framework/port), and uses the project's own Dockerfile as-is when one exists. For an unrecognized stack with no Dockerfile, it returns instructions asking you to add a Dockerfile and re-run - follow them, then call this again. You can override appName and port. Only call this when the user explicitly asks to deploy.", DeployInputShape, async (args) => deployHandler(DeploySchema.parse(args)));
     server.tool("offlocal_status", "Get the current status of a deployment. Poll this every few seconds after offlocal_deploy until status is 'live' or 'failed'.", StatusInputShape, async (args) => statusHandler(StatusSchema.parse(args)));
     server.tool("offlocal_logs", "Read recent container logs for a deployment. Useful for debugging a failed deploy or watching live output.", LogsInputShape, async (args) => logsHandler(LogsSchema.parse(args)));
+    server.tool("offlocal_rollback", "Roll a project back to a previous build. Re-deploys an existing image (skips the build, ~1 min), so it's fast and safe. Defaults to the most recent prior build; pass toDeploymentId to target a specific one. Use when a new deploy is broken or the user wants the last working version back.", RollbackInputShape, async (args) => rollbackHandler(RollbackSchema.parse(args)));
+    server.tool("offlocal_plans", "Show the user's current Offlocal.ai plan, the full tier catalog (prices, limits, features), and upcoming features. Use it to answer plan and pricing questions, and to show upgrade options when the user needs more capacity (projects, databases, custom domains). Includes the billing link.", PlansInputShape, async () => plansHandler());
     server.tool("offlocal_resolve_requirement", "When a deploy needs an external resource (a database, hosting, etc.) that the project doesn't already have, call this with the capability (e.g. 'postgres') to get the providers that can supply it and their connection status. Present the options to the user and let them choose; the user can also just paste an existing connection string as an env var instead.", ResolveRequirementInputShape, async (args) => resolveRequirementHandler(ResolveRequirementSchema.parse(args)));
     server.tool("offlocal_connect", "Get a browser link for the user to connect a chosen provider via OAuth. You CANNOT complete OAuth yourself - share the link, then poll offlocal_list_connections until the provider is 'connected'. Only call this if the user chose a provider that isn't connected yet.", ConnectInputShape, async (args) => connectHandler(ConnectSchema.parse(args)));
     server.tool("offlocal_list_connections", "List the user's provider connections and their status. Use this to poll after offlocal_connect (no faster than every 5 seconds) until a provider becomes 'connected'.", ListConnectionsInputShape, async () => listConnectionsHandler());
@@ -39,6 +44,12 @@ async function main() {
     server.tool("offlocal_provision_status", "Poll an in-progress provision (DigitalOcean/Railway) by its actionId until it's ready. Poll no faster than once every ~20 seconds.", ProvisionStatusInputShape, async (args) => provisionStatusHandler(ProvisionStatusSchema.parse(args)));
     server.tool("offlocal_create_managed_database", "Create an Offlocal Managed Postgres database for a project (the 'Offlocal' platform option for postgres). Pass the projectId from offlocal_deploy. DATABASE_URL is wired into the project automatically; redeploy to apply. Requires a Hobby+ plan.", CreateManagedDatabaseInputShape, async (args) => createManagedDatabaseHandler(CreateManagedDatabaseSchema.parse(args)));
     server.tool("offlocal_set_env", "Set environment variables on a project (stored encrypted, injected on the next deploy). Use this for cross-app wiring in a monorepo — e.g. set NEXT_PUBLIC_API_URL on the web project to the API project's live URL so the frontend can reach the backend. Build-time vars (NEXT_PUBLIC_*, VITE_*) require a fresh deploy to take effect.", SetEnvInputShape, async (args) => setEnvHandler(SetEnvSchema.parse(args)));
+    process.on("uncaughtException", (err) => {
+        console.error("offlocal-mcp uncaught exception (continuing):", err);
+    });
+    process.on("unhandledRejection", (reason) => {
+        console.error("offlocal-mcp unhandled rejection (continuing):", reason);
+    });
     pingApi().catch(() => { });
     const transport = new StdioServerTransport();
     await server.connect(transport);

package/dist/tools/deploy.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
-import { createDeployment, markUploadComplete, uploadBundle, } from "../client.js";
+import { createDeployment, markUploadComplete, rollback, uploadBundle, } from "../client.js";
 import { detect } from "../detect.js";
-import { ICON } from "../ui.js";
+import { ICON, ui } from "../ui.js";
 import { bundleDirectory } from "../zip.js";
 export const DeployInputShape = {
     sourceDir: z
@@ -43,10 +43,13 @@ export async function deployHandler(input) {
     const buildSource = detected.strategy === "dockerfile"
         ? "your Dockerfile"
         : `auto-generated Dockerfile (${detected.framework})`;
+    const slug = created.slug ?? appName;
+    const expectedUrl = created.expectedUrl ?? `https://${slug}.offlocal.ai`;
     const summary = {
         deploymentId: created.deploymentId,
         projectId: created.projectId,
         appName,
+        slug,
         framework: detected.framework,
         buildSource,
         port,
@@ -55,7 +58,7 @@ export async function deployHandler(input) {
             bytes: bundle.byteSize,
         },
         status: "uploaded",
-        expectedUrl: `https://${appName}.offlocal.ai`,
+        expectedUrl,
         pollAfterSeconds: 45,
         expectedTotalSeconds: 180,
     };
@@ -69,19 +72,51 @@ export async function deployHandler(input) {
                     `| ${ICON.spark} Framework | ${summary.framework} (${summary.buildSource}) |\n` +
                     `| Port | ${summary.port} |\n` +
                     `| Bundle | ${summary.bundle.fileCount} files · ${summary.bundle.bytes} bytes |\n\n` +
+                    (bundle.warnings.length
+                        ? bundle.warnings.map((w) => `${ICON.warn} ${w}`).join("\n") + "\n\n"
+                        : "") +
                     `———\n` +
-                    `${ICON.arrow} **Next (you, the agent):** tell the user it's building (2–4 min) and you'll ` +
+                    `${ICON.arrow} **Next (you, the agent):** tell the user it's building (usually 2–8 min) and you'll ` +
                     `report back when it's live. Then:\n` +
                     `  1. Sleep 45 seconds.\n` +
                     `  2. \`offlocal_status({ deploymentId: "${summary.deploymentId}" })\`.\n` +
                     `  3. Sleep the \`pollAfterSeconds\` it returns, then call status again — exactly once per interval.\n` +
-                    `  4. Repeat until \`live\` or \`failed\`. Polling faster does NOT speed up the build.\n` +
+                    `  4. Repeat until \`live\` or \`failed\`. **Slow is normal — don't panic or declare failure on a slow deploy.** ` +
+                    `The status tool tells you if it's genuinely stuck; only then should you stop and suggest a retry.\n` +
                     `Keep the **projectId** from the live status for any database step.`,
             },
         ],
         structuredContent: summary,
     };
 }
+export const RollbackInputShape = {
+    projectId: z
+        .string()
+        .min(1)
+        .describe("The Offlocal projectId to roll back (from offlocal_deploy / offlocal_status)."),
+    toDeploymentId: z
+        .string()
+        .optional()
+        .describe("Optional: a specific previous deploymentId to roll back to. Omit to roll back to the most recent prior build."),
+};
+export async function rollbackHandler(input) {
+    const res = await rollback(input.projectId, input.toDeploymentId);
+    if (res.error || !res.deployment) {
+        const hint = res.error === "no_rollback_target" || res.error === "deployment_not_found"
+            ? " There's no earlier build with an image to roll back to (this project may only have one successful deploy)."
+            : "";
+        return ui({
+            show: `${ICON.fail} Rollback failed: ${res.message ?? res.error}.${hint}`,
+            structured: res,
+        });
+    }
+    const d = res.deployment;
+    return ui({
+        show: `${ICON.spark} **Rolling back** to the build from \`${res.rolledBackTo}\` — re-deploying that image (skips the build, ~1 min).`,
+        next: `Poll \`offlocal_status({ deploymentId: "${d.id}" })\` until it's \`live\`. It reuses the previous image, so there's no rebuild.`,
+        structured: { deployment: d, rolledBackTo: res.rolledBackTo ?? null },
+    });
+}
 function needsDockerfile(sourceDir, port) {
     const summary = {
         status: "needs_dockerfile",

package/dist/tools/plan.js

@@ -116,6 +116,9 @@ export async function planHandler(input) {
             (requirements.length
                 ? ` + ${requirements.map((r) => r.reason).join(", ")}`
                 : "");
+    const hasDatastore = requirements.some((r) => r.capability === "postgres" || r.capability === "mysql");
+    const hasServerComponent = components.some((c) => c.role !== "web");
+    const noteEphemeral = !hasDatastore && hasServerComponent;
     const show = `${ICON.search} **Offlocal.ai — deployment plan**\n\n` +
         `**Detected:** ${detectedLine}\n\n` +
         `**Plan**\n${planLines.join("\n")}\n` +
@@ -123,9 +126,13 @@ export async function planHandler(input) {
         `\n**Setup checklist**  ${progressBar(0, checklist.length)}\n${checklistLines.join("\n")}\n\n` +
         `Reply **"go"** to ship it ${ICON.rocket} — or switch any line ` +
         `(e.g. _"use Supabase for the database"_, _"host the API on Railway"_).`;
+    const persistenceCheck = noteEphemeral
+        ? `\n\nNote: this host's storage is ephemeral. Mention data persistence only if the user asks about keeping data between deploys — a database covers it.`
+        : "";
     const agentNote = `When the user switches a line, call \`offlocal_set_preference\` ` +
-        `(capability \`${multi ? "hosting:<component> or postgres/…" : "hosting/postgres/…"}\`) then re-run \`offlocal_plan\`.\n\n` +
-        `**Execution order once they confirm — walk the checklist top to bottom, ` +
+        `(capability \`${multi ? "hosting:<component> or postgres/…" : "hosting/postgres/…"}\`) then re-run \`offlocal_plan\`.` +
+        persistenceCheck +
+        `\n\n**Execution order once they confirm — walk the checklist top to bottom, ` +
         `re-showing it with ${ICON.done} on finished steps so they see live progress:**\n` +
         executionSteps(items, links, dbTarget).join("\n");
     return ui({

package/dist/tools/plans.js

@@ -0,0 +1,25 @@
+import { getPlanInfo } from "../client.js";
+import { ICON, ui } from "../ui.js";
+export const PlansInputShape = {};
+export async function plansHandler() {
+    const info = await getPlanInfo();
+    const tierLines = info.plans.map((p) => {
+        const isCurrent = p.plan === info.plan;
+        const head = isCurrent
+            ? `${ICON.connected} **${p.label} — ${p.priceLabel}** _(your plan)_`
+            : `${ICON.open} **${p.label} — ${p.priceLabel}**`;
+        const projects = `${p.projects} project${p.projects === 1 ? "" : "s"}`;
+        return `${head}\n     ${projects} · ${p.features.slice(0, 4).join(" · ")}`;
+    });
+    const upcoming = info.upcoming.length
+        ? `\n\n${ICON.soon} **On the roadmap:** ${info.upcoming.join(" · ")}`
+        : "";
+    return ui({
+        show: `${ICON.spark} **Offlocal.ai plans**\n\n` +
+            `You're on **${info.planLabel}** — using ${info.usage.projects}/${info.limits.projects} projects, ${info.limits.managedDbs} managed database${info.limits.managedDbs === 1 ? "" : "s"} included.\n\n` +
+            tierLines.join("\n\n") +
+            upcoming,
+        next: `Use this to answer the user's plan and pricing questions. If they need more capacity (projects, databases, custom domains), share ${info.billingUrl} where they can change plans.`,
+        structured: { ...info },
+    });
+}

package/dist/tools/providers.js

@@ -110,7 +110,10 @@ export async function connectHandler(input) {
     };
 }
 export const ProvisionInputShape = {
-    provider: z.string().min(1).describe("The connected provider to provision on."),
+    provider: z
+        .string()
+        .min(1)
+        .describe("The CONNECTED external provider to provision on: supabase, planetscale, digitalocean, or railway. For Offlocal's own managed Postgres, use offlocal_create_managed_database instead — not this."),
     type: z
         .enum(["project", "database", "deployment", "env_vars", "branch"])
         .describe("The kind of resource to create."),
@@ -131,6 +134,11 @@ export const ProvisionInputShape = {
 };
 export async function provisionHandler(input) {
     const { provider, confirm, projectId, ...spec } = input;
+    if (["offlocal", "offlocal.ai"].includes(provider.toLowerCase())) {
+        return text(`${ICON.warn} "offlocal" isn't a provision provider. For an Offlocal Managed Postgres database, call ` +
+            `\`offlocal_create_managed_database({ projectId })\`. \`offlocal_provision\` is only for connected external ` +
+            `providers: **supabase, planetscale, digitalocean, railway**.`);
+    }
     const res = await provisionResource(provider, spec, {
         confirm: confirm ?? false,
         projectId,
@@ -213,10 +221,10 @@ export async function setEnvHandler(input) {
 export async function createManagedDatabaseHandler(input) {
     const res = await createManagedDatabase(input.projectId);
     if (res.error) {
-        const upsell = res.error === "plan_not_allowed" || res.error === "limit_reached"
-            ? " Tell the user this needs a Hobby+ plan or they've hit their database limit — they can upgrade at /billing."
+        const planHint = res.error === "plan_not_allowed" || res.error === "limit_reached"
+            ? " A Hobby plan or higher is required, or the database limit was reached — plans can be changed at /billing."
             : "";
-        return text(`${ICON.fail} Couldn't create the managed database: ${res.message ?? res.error}.${upsell}`, res);
+        return text(`${ICON.fail} Couldn't create the managed database: ${res.message ?? res.error}.${planHint}`, res);
     }
     return text(`${ICON.db} **Offlocal Managed Postgres created** (${res.database?.status}). ` +
         `${ICON.spark} DATABASE_URL is wired into this project automatically — **redeploy** to apply.`, res);

package/dist/tools/status.js

@@ -24,6 +24,9 @@ export async function statusHandler(input) {
     const isTerminal = dep.status === "live" || dep.status === "failed";
     const pollAfterSeconds = isTerminal ? 0 : pollIntervalFor(dep.status);
     const etaSeconds = isTerminal ? 0 : etaFor(dep.status);
+    const secondsSinceUpdate = Math.max(0, Math.round((Date.now() - new Date(dep.updatedAt).getTime()) / 1000));
+    const STUCK_AFTER = 9 * 60;
+    const stalled = !isTerminal && secondsSinceUpdate > STUCK_AFTER;
     const summary = {
         deploymentId: dep.id,
         projectId: dep.projectId,
@@ -32,6 +35,8 @@ export async function statusHandler(input) {
         isTerminal,
         pollAfterSeconds,
         etaSeconds,
+        secondsSinceUpdate,
+        stalled,
         liveUrl: dep.liveUrl,
         errorType: dep.errorType,
         errorMessage: dep.errorMessage,
@@ -61,9 +66,19 @@ export async function statusHandler(input) {
         lines.push("");
         lines.push(bar);
         lines.push("");
-        lines.push(`Still in progress (typical end-to-end deploy: 2–4 min). Do NOT call this tool ` +
-            `again for at least ${pollAfterSeconds}s — polling doesn't speed it up. ` +
-            `Sleep ${pollAfterSeconds}s, then call it exactly once.`);
+        if (stalled) {
+            lines.push(`${ICON.warn} It's been at "${phase}" for ~${Math.round(secondsSinceUpdate / 60)} min with no change — ` +
+                `longer than a normal deploy. It may be stuck.\n` +
+                `Tell the user it's taking unusually long. You can wait a little longer, but do NOT keep polling indefinitely — ` +
+                `if it doesn't move within another couple of minutes, suggest re-running \`offlocal_deploy\` (a retry usually clears a stuck deploy).`);
+        }
+        else {
+            lines.push(`Building / rolling out — **this is normal and can take 2–8 minutes** (occasionally a bit more). Stay calm and don't treat slowness as failure:\n` +
+                `• A deploy is only failed when the status is literally **failed** — nothing else means it broke.\n` +
+                `• "starting container" can mean the container is already healthy but not yet promoted; it'll flip to **live** shortly.\n` +
+                `• Empty \`offlocal_logs\` during build / before live is expected (container logs only exist once it's running) — not an error.\n` +
+                `Sleep ${pollAfterSeconds}s, then call this exactly once. Polling faster does not help.`);
+        }
     }
     return {
         content: [{ type: "text", text: lines.join("\n") }],

package/dist/zip.js

@@ -20,13 +20,16 @@ const IGNORED_DIRS = new Set([
     ".idea",
     ".vscode",
 ]);
-const IGNORED_FILE_RE = /^(\.env(\..+)?|.*\.log|\.DS_Store|Thumbs\.db|.*\.tsbuildinfo)$/;
+const IGNORED_FILE_RE = /^(\.env(\..+)?|\.DS_Store|Thumbs\.db)$|\.(log|tsbuildinfo|exe|dll|dylib|so|msi|dmg|pdb|class|o|obj|lib)$/i;
 const MAX_FILE_BYTES = 50 * 1024 * 1024;
 const MAX_BUNDLE_BYTES = 250 * 1024 * 1024;
+const WARN_BUNDLE_BYTES = 25 * 1024 * 1024;
+const WARN_FILE_BYTES = 5 * 1024 * 1024;
 export async function bundleDirectory(sourceDir) {
     const zip = new AdmZip();
     let fileCount = 0;
     let totalBytes = 0;
+    const bigFiles = [];
     await walk(sourceDir, async (absolute) => {
         const rel = relative(sourceDir, absolute);
         if (!rel)
@@ -42,14 +45,26 @@ export async function bundleDirectory(sourceDir) {
         zip.addFile(zipPath, content);
         fileCount++;
         totalBytes += st.size;
+        if (st.size > WARN_FILE_BYTES)
+            bigFiles.push({ rel: zipPath, bytes: st.size });
         if (totalBytes > MAX_BUNDLE_BYTES) {
-            throw new Error(`bundle exceeds ${MAX_BUNDLE_BYTES} bytes. Trim node_modules-like outputs or add a .offlocalignore.`);
+            throw new Error(`bundle exceeds ${MAX_BUNDLE_BYTES} bytes. Trim node_modules-like outputs or add a .gitignore.`);
         }
     });
     if (fileCount === 0) {
         throw new Error(`no files to bundle under ${sourceDir}`);
     }
-    return { buffer: zip.toBuffer(), fileCount, byteSize: totalBytes };
+    const warnings = [];
+    if (totalBytes > WARN_BUNDLE_BYTES) {
+        warnings.push(`Bundle is ${mb(totalBytes)} — large for a deploy. Add a .gitignore for build output/binaries you don't need to ship.`);
+    }
+    for (const f of bigFiles.sort((a, b) => b.bytes - a.bytes).slice(0, 3)) {
+        warnings.push(`Large file bundled: ${f.rel} (${mb(f.bytes)}). Gitignore it if it isn't needed at runtime.`);
+    }
+    return { buffer: zip.toBuffer(), fileCount, byteSize: totalBytes, warnings };
+}
+function mb(bytes) {
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
 }
 async function walk(root, onFile) {
     const stack = [root];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@offlocal/mcp",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "MCP server for Offlocal - lets your AI coding agent deploy apps via offlocal_deploy, offlocal_status, offlocal_logs, offlocal_ping.",
   "keywords": [
     "mcp",