@offlocal/mcp 0.3.0 → 0.3.2

package/dist/client.js

@@ -1,7 +1,13 @@
+import { MCP_VERSION } from "./version.js";
 const API_URL = process.env.OFFLOCAL_API_URL?.replace(/\/+$/, "") ?? "http://localhost:4000";
 const AGENT_KEY = process.env.OFFLOCAL_AGENT_KEY ?? "";
 function authHeaders() {
-    return AGENT_KEY ? { Authorization: `Bearer ${AGENT_KEY}` } : {};
+    const headers = {
+        "x-offlocal-mcp-version": MCP_VERSION,
+    };
+    if (AGENT_KEY)
+        headers.Authorization = `Bearer ${AGENT_KEY}`;
+    return headers;
 }
 export async function pingApi() {
     if (!AGENT_KEY) {
@@ -14,6 +20,15 @@ export async function pingApi() {
             headers: { "content-type": "application/json", ...authHeaders() },
             body: "{}",
         });
+        if (res.status === 426) {
+            const body = await res.text().catch(() => "");
+            return {
+                ok: false,
+                mustUpdate: true,
+                reason: body.slice(0, 300) ||
+                    "This Offlocal MCP version is no longer supported. Update with: npx -y @offlocal/mcp@latest",
+            };
+        }
         if (!res.ok) {
             const body = await res.text().catch(() => "");
             return {
@@ -22,7 +37,11 @@ export async function pingApi() {
             };
         }
         const data = (await res.json());
-        return { ok: true, user: data.user };
+        return {
+            ok: true,
+            user: data.user,
+            updateAvailable: res.headers.get("x-offlocal-mcp-update"),
+        };
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);

package/dist/detect.js

@@ -124,6 +124,7 @@ const WEB_FRAMEWORKS = new Set([
     "remix",
     "astro",
     "vite",
+    "cra",
     "static",
 ]);
 const API_FRAMEWORKS = new Set(["fastify", "hono", "express", "koa", "nestjs"]);
@@ -214,6 +215,8 @@ export function apiUrlEnvVar(framework) {
             return { key: "NEXT_PUBLIC_API_URL", buildTime: true };
         case "vite":
             return { key: "VITE_API_URL", buildTime: true };
+        case "cra":
+            return { key: "REACT_APP_API_URL", buildTime: true };
         case "nuxt":
             return { key: "NUXT_PUBLIC_API_URL", buildTime: true };
         case "astro":
@@ -279,9 +282,12 @@ async function detectPython(sourceDir, appName) {
     const hasManage = await fileExists(join(sourceDir, "manage.py"));
     let framework = "python";
     let startCommand = "python app.py";
+    const notes = [];
     if (hasManage || manifest.includes("django")) {
         framework = "django";
-        startCommand = "python manage.py runserver 0.0.0.0:$PORT";
+        const wsgi = await findDjangoWsgiModule(sourceDir);
+        startCommand = `python manage.py migrate --noinput && gunicorn ${wsgi}:application --bind 0.0.0.0:$PORT`;
+        notes.push("Django runs under gunicorn (production) and migrates on start. IMPORTANT: a default project's `ALLOWED_HOSTS` is empty and will 400 every request. Make settings.py read it from the environment — e.g. `ALLOWED_HOSTS = os.environ.get('ALLOWED_HOSTS', '').split(',')` — and offlocal will set ALLOWED_HOSTS to the live host automatically. Use a real database (SQLite resets on every cold start), and run `collectstatic` in a build step if you serve static files.");
     }
     else if (manifest.includes("fastapi")) {
         framework = "fastapi";
@@ -302,8 +308,27 @@ async function detectPython(sourceDir, appName) {
         startCommand,
         port: 8000,
         strategy: "template",
+        notes: notes.length ? notes : undefined,
     };
 }
+async function findDjangoWsgiModule(sourceDir) {
+    const manage = await readTextSafe(join(sourceDir, "manage.py"));
+    const m = /DJANGO_SETTINGS_MODULE['"]\s*,\s*['"]([\w.]+)\.settings['"]/.exec(manage);
+    if (m?.[1])
+        return `${m[1]}.wsgi`;
+    try {
+        const entries = await readdir(sourceDir, { withFileTypes: true });
+        for (const e of entries) {
+            if (e.isDirectory() &&
+                (await fileExists(join(sourceDir, e.name, "wsgi.py")))) {
+                return `${e.name}.wsgi`;
+            }
+        }
+    }
+    catch {
+    }
+    return "wsgi";
+}
 function pickNodeFramework(deps) {
     if ("next" in deps)
         return "nextjs";
@@ -313,6 +338,10 @@ function pickNodeFramework(deps) {
         return "remix";
     if ("astro" in deps)
         return "astro";
+    if ("vite" in deps)
+        return "vite";
+    if ("react-scripts" in deps || "@craco/craco" in deps)
+        return "cra";
     if ("fastify" in deps)
         return "fastify";
     if ("hono" in deps)
@@ -321,8 +350,6 @@ function pickNodeFramework(deps) {
         return "express";
     if ("koa" in deps)
         return "koa";
-    if ("vite" in deps)
-        return "vite";
     return "node";
 }
 function nodePort(framework) {
@@ -331,6 +358,8 @@ function nodePort(framework) {
             return 4321;
         case "vite":
             return 4173;
+        case "cra":
+            return 80;
         default:
             return 3000;
     }

package/dist/index.js

@@ -3,6 +3,7 @@ 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 { MCP_VERSION } from "./version.js";
 import { DeployInputShape, RollbackInputShape, deployHandler, rollbackHandler, } from "./tools/deploy.js";
 import { PlansInputShape, plansHandler } from "./tools/plans.js";
 import { StatusInputShape, statusHandler } from "./tools/status.js";
@@ -27,7 +28,7 @@ const PlansSchema = z.object(PlansInputShape);
 async function main() {
     const server = new McpServer({
         name: "offlocal",
-        version: "0.1.0",
+        version: MCP_VERSION,
     });
     server.tool("offlocal_ping", "Verify the Offlocal connection. Returns the signed-in email if connected, or an error message if not. This tool does NOT deploy anything, upload anything, or provision any resources - it is the right tool to call when the user asks to 'check my Offlocal connection' or similar.", PingInputShape, async (args) => pingHandler(PingSchema.parse(args)));
     server.tool("offlocal_plan", "START HERE when the user asks to deploy/ship/set up a project. Detects the app + the resources it needs (e.g. a Postgres database), applies the user's saved platform preferences, and returns a complete proposed plan (which platform for each piece — Offlocal.ai by default, or Supabase/PlanetScale/DigitalOcean/Railway). Present the plan to the user verbatim and let them confirm with 'go' or switch any line. Then execute the steps the plan lists. Do NOT deploy or provision anything until the user confirms the plan.", PlanInputShape, async (args) => planHandler(PlanSchema.parse(args)));
@@ -50,7 +51,16 @@ async function main() {
     process.on("unhandledRejection", (reason) => {
         console.error("offlocal-mcp unhandled rejection (continuing):", reason);
     });
-    pingApi().catch(() => { });
+    pingApi()
+        .then((r) => {
+        if (!r.ok && r.mustUpdate) {
+            console.error(`offlocal-mcp: ${r.reason}`);
+        }
+        else if (r.ok && r.updateAvailable) {
+            console.error(`offlocal-mcp: a newer version (v${r.updateAvailable}) is available — update with: npx -y @offlocal/mcp@latest`);
+        }
+    })
+        .catch(() => { });
     const transport = new StdioServerTransport();
     await server.connect(transport);
 }

package/dist/tools/deploy.js

@@ -72,13 +72,21 @@ 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"
+                        : "") +
+                    (detected.notes?.length
+                        ? detected.notes.map((n) => `${ICON.warn} ${n}`).join("\n\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.`,
             },
         ],

package/dist/tools/ping.js

@@ -4,6 +4,19 @@ export const PingInputShape = {};
 export async function pingHandler(_input) {
     const result = await pingApi();
     if (!result.ok) {
+        if (result.mustUpdate) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `⚠️ Your Offlocal MCP is out of date and no longer supported.\n\n` +
+                            `${result.reason}\n\n` +
+                            "Update it with: npx -y @offlocal/mcp@latest (then restart the agent).",
+                    },
+                ],
+                structuredContent: { connected: false, mustUpdate: true, reason: result.reason },
+            };
+        }
         return {
             content: [
                 {
@@ -20,14 +33,21 @@ export async function pingHandler(_input) {
         };
     }
     const email = result.user?.email ?? "(unknown)";
+    const updateNote = result.updateAvailable
+        ? `\n\nℹ️ A newer Offlocal MCP (v${result.updateAvailable}) is available — update with: npx -y @offlocal/mcp@latest`
+        : "";
     return {
         content: [
             {
                 type: "text",
-                text: `Connected to Offlocal as ${email}.`,
+                text: `Connected to Offlocal as ${email}.${updateNote}`,
             },
         ],
-        structuredContent: { connected: true, email },
+        structuredContent: {
+            connected: true,
+            email,
+            updateAvailable: result.updateAvailable ?? null,
+        },
     };
 }
 void z;

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,
@@ -214,7 +222,7 @@ export async function createManagedDatabaseHandler(input) {
     const res = await createManagedDatabase(input.projectId);
     if (res.error) {
         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."
+            ? ` Two options: add a managed Postgres by upgrading at /billing, or connect your own database with \`offlocal_connect_provider\` (capability "postgres").`
             : "";
         return text(`${ICON.fail} Couldn't create the managed database: ${res.message ?? res.error}.${planHint}`, 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,
@@ -55,15 +60,29 @@ export async function statusHandler(input) {
             lines.push(dep.errorMessage.slice(0, 2000));
             lines.push("```");
         }
+        if (dep.errorType === "build_failed" || dep.errorType === "build_error") {
+            lines.push("");
+            lines.push(`Call \`offlocal_logs({ deploymentId: "${dep.id}" })\` for the full build output, fix the cause, then re-run \`offlocal_deploy\`.`);
+        }
     }
     else {
         lines.push(`${ICON.busy} **${phase}**`);
         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/version.js

@@ -0,0 +1,9 @@
+import { createRequire } from "node:module";
+let version = "0.0.0";
+try {
+    const req = createRequire(import.meta.url);
+    version = req("../package.json").version ?? version;
+}
+catch {
+}
+export const MCP_VERSION = version;

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.3.0",
+  "version": "0.3.2",
   "description": "MCP server for Offlocal - lets your AI coding agent deploy apps via offlocal_deploy, offlocal_status, offlocal_logs, offlocal_ping.",
   "keywords": [
     "mcp",