@rebasepro/mcp 0.17.3 → 0.18.1

package/dist/index.js

@@ -131,6 +131,14 @@ async function loadClientSdk() {
 const REGISTRY_PATH = resolve(homedir(), ".rebase", "projects.json");
 /** In-memory project registry. */
 let registry = { projects: {}, activeProject: null };
+/**
+ * Whether this run's `default` was computed from the environment or the
+ * working directory rather than read from disk. A derived `default` is never
+ * written back: it is recomputed at every start, and persisting it puts one
+ * project's directory, URL and dev service key in a machine-wide file that
+ * every other project on the machine reads.
+ */
+let defaultIsDerived = false;
 /**
  * Load the project registry from disk. Creates the file if it doesn't exist.
  */
@@ -152,6 +160,13 @@ function loadRegistry() {
 }
 /**
  * Save the project registry to disk.
+ *
+ * A `default` that this run derived (from the env block or from a `rebase.json`
+ * in the working directory) is left out. `~/.rebase/projects.json` is
+ * machine-wide, so persisting a derived `default` writes one project's
+ * directory, backend URL and dev service key into the file every other project
+ * on the machine reads at startup — which is how project A's admin key became
+ * project B's. It costs nothing to leave out: it is recomputed at every start.
  */
 function saveRegistry() {
     try {
@@ -159,9 +174,34 @@ function saveRegistry() {
         if (!existsSync(dir)) {
             mkdirSync(dir, { recursive: true });
         }
+        // Leaving the derived `default` out is not the same as deleting the
+        // key: the file may already hold somebody's registered `default`, and
+        // dropping it lost that project's URL and token the first time any
+        // other project's server saved. Whatever was there is put back.
+        const onDisk = defaultIsDerived
+            ? (() => {
+                let persisted;
+                try {
+                    persisted = JSON.parse(readFileSync(REGISTRY_PATH, "utf-8"))
+                        .projects?.["default"];
+                }
+                catch {
+                    // No file yet, or unreadable — nothing to preserve.
+                }
+                const projects = Object.fromEntries(Object.entries(registry.projects).filter(([name]) => name !== "default"));
+                if (persisted)
+                    projects["default"] = persisted;
+                return {
+                    projects,
+                    activeProject: registry.activeProject === "default" && !persisted
+                        ? null
+                        : registry.activeProject
+                };
+            })()
+            : registry;
         // Owner-only: this file holds bearer tokens (service keys / API keys).
         // `mode` only applies on create, so chmod covers pre-existing files.
-        writeFileSync(REGISTRY_PATH, JSON.stringify(registry, null, 2), { encoding: "utf-8", mode: 0o600 });
+        writeFileSync(REGISTRY_PATH, JSON.stringify(onDisk, null, 2), { encoding: "utf-8", mode: 0o600 });
         chmodSync(REGISTRY_PATH, 0o600);
     }
     catch {
@@ -200,26 +240,53 @@ function readDevState(projectDir) {
         return null;
     }
 }
+/** Warn about a discovered/registered `baseUrl` disagreement at most once. */
+const warnedBaseUrlMismatch = new Set();
 /**
  * Try to auto-discover the backend from `.rebase/state.json` in the project dir.
  * Updates the project config in the registry if a running server is found.
+ *
+ * Discovery fills gaps. It never overrules what the operator wrote down —
+ * neither the token nor the URL. Overruling the URL was worse than overruling
+ * the token: a project registered against staging or production had its
+ * `baseUrl` replaced by `http://localhost:<devport>` for as long as
+ * `rebase dev` happened to be running in that directory, and every tool then
+ * delivered that project's `rk_live_` key to the local backend. The registered
+ * value is the deliberate one; the state file is a convenience.
+ *
+ * @param devState - Injected for tests; read from the project dir by default.
  */
-function autoDiscoverLocal(project) {
-    if (!project.projectDir)
-        return project;
-    const devState = readDevState(project.projectDir);
-    if (!devState)
+export function autoDiscoverLocal(project, devState = undefined) {
+    const state = devState !== undefined
+        ? devState
+        : project.projectDir
+            ? readDevState(project.projectDir)
+            : null;
+    if (!state)
         return project;
+    if (project.baseUrl && state.baseUrl && project.baseUrl !== state.baseUrl) {
+        // stderr, not stdout: stdout is the MCP framing channel.
+        const key = `${project.name}::${project.baseUrl}::${state.baseUrl}`;
+        if (!warnedBaseUrlMismatch.has(key)) {
+            warnedBaseUrlMismatch.add(key);
+            process.stderr.write(`[rebase-mcp] project "${project.name}" is registered against ${project.baseUrl}, ` +
+                `but a dev server is running at ${state.baseUrl}. The registered URL wins — ` +
+                `call rebase_project_switch with a project whose baseUrl is the dev server, ` +
+                `or rebase_project_add one, to target it.\n`);
+        }
+    }
     return {
         ...project,
-        baseUrl: devState.baseUrl,
+        // A registered baseUrl wins over the discovered one, for the same
+        // reason the token does.
+        baseUrl: project.baseUrl || state.baseUrl,
         // A registered token wins over the discovered one. What discovery finds
         // is the dev server's *service key* — the unscoped admin secret — so
         // letting it win meant a deliberately narrow API key registered for
         // this project was silently upgraded to full admin on every call.
         // Discovery now only fills a gap, which is all the zero-config story
         // ever needed it to do.
-        token: project.token || devState.serviceKey || ""
+        token: project.token || state.serviceKey || ""
     };
 }
 /**
@@ -263,7 +330,17 @@ function readServiceKeyFromEnv(projectDir) {
     return readEnvVarFromProject(projectDir, "REBASE_SERVICE_KEY", (v) => v.length >= 32);
 }
 // ── Environment & Initialization ────────────────────────────────────────────
-const ENV_PROJECT_DIR = process.env.REBASE_PROJECT_DIR || process.cwd();
+/**
+ * The project this server run is about.
+ *
+ * `resolve` is not decoration: the scaffolded `.mcp.json` sets
+ * `REBASE_PROJECT_DIR: "."` — relative to the client's cwd, which for a
+ * project-level `.mcp.json` is the project — and a relative path stored in a
+ * machine-wide registry would mean a different directory in every terminal.
+ */
+const ENV_PROJECT_DIR = resolve(process.env.REBASE_PROJECT_DIR || process.cwd());
+/** `true` when the server's working directory is itself a Rebase project. */
+const CWD_IS_PROJECT = existsSync(resolve(process.cwd(), "rebase.json"));
 // Try to load .env from the project directory
 for (const envPath of [
     resolve(ENV_PROJECT_DIR, ".env"),
@@ -276,24 +353,76 @@ for (const envPath of [
 }
 const ENV_BASE_URL = process.env.REBASE_BASE_URL || "";
 const ENV_API_TOKEN = process.env.REBASE_API_TOKEN || process.env.REBASE_TOKEN || "";
+/**
+ * The env vars that describe a `default` project, or `null` when the client
+ * declared none of them.
+ *
+ * `ENV_PROJECT_DIR` cannot answer this on its own: it falls back to
+ * `process.cwd()`, so it is always truthy and "was it set?" has to be asked of
+ * `process.env` directly.
+ */
+export function envDeclaredProject(env = process.env) {
+    const projectDir = env.REBASE_PROJECT_DIR || undefined;
+    const baseUrl = env.REBASE_BASE_URL || undefined;
+    const token = env.REBASE_API_TOKEN || env.REBASE_TOKEN || undefined;
+    if (!projectDir && !baseUrl && !token)
+        return null;
+    return { projectDir, baseUrl, token };
+}
 /**
  * Initialize the project registry.
  *
- * Priority:
- * 1. REBASE_PROJECT_DIR env → single-project mode (backward-compatible)
- * 2. Load ~/.rebase/projects.json
- * 3. Auto-discover from .rebase/state.json in the project dir
+ * One precedence, and it holds everywhere this is written down (the docs, the
+ * README and this comment):
+ *
+ * 1. `REBASE_PROJECT_DIR` / `REBASE_BASE_URL` / `REBASE_API_TOKEN` — the block
+ *    in the client's own MCP config. If any of them is set, the `default`
+ *    project is rebuilt from them on **every** start.
+ * 2. The server's working directory, when it holds a `rebase.json`. That is a
+ *    project the person is standing in; nothing in a home-directory cache
+ *    outranks it.
+ * 3. The persisted `default` in `~/.rebase/projects.json`, when neither of the
+ *    first two says anything.
+ *
+ * Auto-discovery from `.rebase/state.json` fills the gaps in every case; it
+ * never overrules a value one of the three supplied.
+ *
+ * Step 2 exists because the registry is machine-wide and `default` is one
+ * entry in it. The scaffold shipped no env block, so the first project on the
+ * machine to call `rebase_project_add` persisted a `default` carrying *its*
+ * directory, URL and dev service key — and every other project on that machine
+ * then resolved to it, silently. A derived `default` is therefore also never
+ * written back to disk (`saveRegistry`): it is recomputed at every start, so
+ * persisting it only leaks one project's admin key into another's session.
+ *
+ * Step 1 used to be `if (!registry.projects["default"])` — the env vars seeded
+ * the registry once and were dead ever after. That is the wrong way round:
+ * the env block is what the person editing `.mcp.json` just wrote, and
+ * `~/.rebase/projects.json` is a cache in their home directory they have
+ * probably forgotten exists. Pointing `REBASE_PROJECT_DIR` at a second project
+ * silently kept talking to the first one, which is the failure this file can
+ * least afford: every tool here acts on whatever `default` resolves to.
+ *
+ * The rebuild is whole-entry, not per-field, on purpose. A token registered
+ * for one `projectDir` is a credential for *that* backend; carrying it over
+ * because the new env block only named a directory would hand the wrong
+ * project an admin key.
  */
 function initializeRegistry() {
     registry = loadRegistry();
-    // Ensure a "default" project exists from env vars or CWD
-    if (!registry.projects["default"]) {
-        const devState = readDevState(ENV_PROJECT_DIR);
+    const fromEnv = envDeclaredProject();
+    if (fromEnv || CWD_IS_PROJECT || !registry.projects["default"]) {
+        defaultIsDerived = true;
         const envServiceKey = readServiceKeyFromEnv(ENV_PROJECT_DIR);
         registry.projects["default"] = {
             name: "default",
             projectDir: ENV_PROJECT_DIR,
-            baseUrl: ENV_BASE_URL || devState?.baseUrl || "http://localhost:3001",
+            // Deliberately no `devState.baseUrl` here either, for the same
+            // reason: `autoDiscoverLocal` fills an empty `baseUrl` per call, so
+            // a dev server started (or restarted on a new port) after this
+            // process booted is still found. `DEFAULT_BASE_URL` is applied by
+            // `getActiveProject` when discovery finds nothing.
+            baseUrl: ENV_BASE_URL || "",
             // Deliberately no `devState.serviceKey` here: this runs once, at
             // startup, and a key baked in now would outrank the freshly
             // discovered one for the rest of the process — so a dev server
@@ -306,10 +435,71 @@ function initializeRegistry() {
     if (!registry.activeProject || !registry.projects[registry.activeProject]) {
         registry.activeProject = "default";
     }
+    // A sticky `activeProject` is machine-wide too. Remembering that the last
+    // session switched to "staging" is the point of a registry — but only
+    // inside the project that registered it. When this run resolves a project
+    // of its own and the remembered entry belongs to a different directory,
+    // the remembered one is somebody else's backend and somebody else's token.
+    const active = registry.activeProject ? registry.projects[registry.activeProject] : undefined;
+    if (defaultIsDerived &&
+        registry.activeProject !== "default" &&
+        active?.projectDir &&
+        resolve(active.projectDir) !== ENV_PROJECT_DIR) {
+        process.stderr.write(`[rebase-mcp] the remembered project "${registry.activeProject}" is registered under ` +
+            `${active.projectDir}, but this server runs in ${ENV_PROJECT_DIR}. Targeting "default" ` +
+            `(this directory) instead; call rebase_project_switch to change that.\n`);
+        registry.activeProject = "default";
+    }
+    warnIfEnvIgnored(fromEnv);
+}
+/**
+ * Say so on stderr if the environment asked for something the registry is not
+ * doing.
+ *
+ * Two cases, and only the second one is reachable now:
+ *
+ * - The `default` entry does not carry the env values. That is the bug fixed
+ *   above; the check stays as a canary, because the symptom of the old
+ *   behaviour was an assistant confidently reading the wrong database with no
+ *   output anywhere saying so.
+ * - The env block is set but a *different* project is active, because a
+ *   previous session called `rebase_project_switch` and the registry remembers
+ *   it. Tools target `activeProject`, so the env block really is inert — the
+ *   registry is not overruled here, since sticky project selection is the
+ *   point of having a registry, but silence is not an option either.
+ *
+ * stderr, not stdout: stdout is the MCP framing channel.
+ */
+function warnIfEnvIgnored(fromEnv) {
+    if (!fromEnv)
+        return;
+    const def = registry.projects["default"];
+    const mismatched = [];
+    if (fromEnv.projectDir && def?.projectDir !== fromEnv.projectDir)
+        mismatched.push("REBASE_PROJECT_DIR");
+    if (fromEnv.baseUrl && def?.baseUrl !== fromEnv.baseUrl)
+        mismatched.push("REBASE_BASE_URL");
+    if (fromEnv.token && def?.token !== fromEnv.token)
+        mismatched.push("REBASE_API_TOKEN");
+    if (mismatched.length) {
+        process.stderr.write(`[rebase-mcp] ${mismatched.join(", ")} set but not reflected in the "default" project — ` +
+            `this is a bug in the server; report it.\n`);
+    }
+    if (registry.activeProject && registry.activeProject !== "default") {
+        process.stderr.write(`[rebase-mcp] the environment describes the "default" project, but "${registry.activeProject}" ` +
+            `is the active one, so tools target it instead. Call rebase_project_switch with "default" ` +
+            `to use the environment's values.\n`);
+    }
 }
 initializeRegistry();
 /** Client instances keyed by project name. */
 const clientCache = new Map();
+/**
+ * Where a project points when nobody said and no dev server is running.
+ * The last resort, applied after discovery — never written into the registry,
+ * because a stored value would then outrank the dev server discovery is for.
+ */
+export const DEFAULT_BASE_URL = "http://localhost:3001";
 /** Get the active project config, with auto-discovery applied. */
 function getActiveProject() {
     const name = registry.activeProject || "default";
@@ -317,7 +507,8 @@ function getActiveProject() {
     if (!project) {
         throw new Error(`No active project configured. Use rebase_project_add to register one.`);
     }
-    return autoDiscoverLocal(project);
+    const discovered = autoDiscoverLocal(project);
+    return discovered.baseUrl ? discovered : { ...discovered, baseUrl: DEFAULT_BASE_URL };
 }
 /** Get the project directory for the active project. */
 function getProjectDir() {
@@ -358,8 +549,13 @@ function clearClientCache() {
  * auditable at a glance and a new tool now arrives protected.
  */
 export const READ_ONLY_TOOLS = new Set([
-    // CLI tools that only inspect the database
-    "rebase_schema_introspect",
+    // `rebase_schema_plan` posts to `/api/admin/schema/plan`, the live schema
+    // editor's planner: it computes the statements and returns them, and
+    // `apply` is a different route. It used to be `db push --dry-run`, which
+    // was a read of the database and a *write* of three generated files into
+    // the repository — the half that made "applies nothing" untrue.
+    "rebase_schema_plan",
+    // CLI tools that only inspect the database.
     "rebase_doctor",
     "rebase_db_branch_list",
     "rebase_db_branch_info",
@@ -369,11 +565,11 @@ export const READ_ONLY_TOOLS = new Set([
     // Admin
     "list_users",
     "list_roles",
-    // Storage. `storage_get_metadata` mints a signed URL, which is a bearer
+    // Storage. `storage_get_download_url` mints a signed URL, which is a bearer
     // capability rather than a plain read — see L2 in the unit-67 audit — but
     // it does not change the environment, so it belongs here.
     "storage_list_objects",
-    "storage_get_metadata",
+    "storage_get_download_url",
     // Cron
     "cron_list_jobs",
     "cron_get_job",
@@ -392,6 +588,16 @@ export const READ_ONLY_TOOLS = new Set([
  * open question 2).
  */
 export const LOCAL_ONLY_TOOLS = new Set([
+    // `rebase_schema_introspect` reads the database and *writes collection
+    // definition files* into the project. It was classified as a read, which is
+    // half true and the wrong half: the half that matters lands on this machine,
+    // overwriting hand-written collection files with generated ones. Local-only
+    // is what it is.
+    "rebase_schema_introspect",
+    // `rebase_db_branch_switch` writes a branch pointer under `.rebase/` and
+    // never touches `.env` or the database. Like `rebase_project_switch`, it
+    // retargets everything else rather than acting on a target itself.
+    "rebase_db_branch_switch",
     "rebase_schema_generate",
     "rebase_db_generate",
     "rebase_generate_sdk",
@@ -629,7 +835,7 @@ const CLI_TOOLS = [
     },
     {
         name: "rebase_db_push",
-        description: "Apply the current Drizzle schema directly to the database (development shortcut, skips migration files).",
+        description: "Apply the current Drizzle schema directly to the database (development shortcut, skips migration files). Refuses changes that destroy data — use rebase_schema_plan first, then ask the human to run `rebase db push --allow-destructive`.",
         inputSchema: { type: "object",
             properties: {} },
         cmd: ["db", "push"]
@@ -710,6 +916,22 @@ const CLI_TOOLS = [
             required: ["name"]
         },
         cmd: ["db", "branch", "info"]
+    },
+    {
+        // create/delete/info/list without switch meant an agent could make a
+        // branch it had no way to use: the only route onto one was hand-editing
+        // `DATABASE_URL`, which is not a thing to ask an assistant to do.
+        name: "rebase_db_branch_switch",
+        description: "Point this checkout at a database branch, or back at the main database (Admins only). " +
+            "With no name, reports which branch is active. Writes a local pointer, never `.env`.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                name: { type: "string", description: "Branch to switch to. Omit to report the active branch." },
+                off: { type: "boolean", description: "Switch back to the main database instead of a branch." }
+            }
+        },
+        cmd: ["db", "branch", "switch"]
     }
 ];
 const DATA_TOOLS = [
@@ -922,8 +1144,8 @@ const STORAGE_TOOLS = [
         }
     },
     {
-        name: "storage_get_metadata",
-        description: "Get metadata and a temporary signed download URL for a file in Rebase storage.",
+        name: "storage_get_download_url",
+        description: "Mint a temporary signed download URL for a file in Rebase storage. It returns the URL and its expiry, not object metadata — the URL is a bearer capability that outlives the tool call.",
         inputSchema: {
             type: "object",
             properties: {
@@ -987,6 +1209,51 @@ const CRON_TOOLS = [
         }
     }
 ];
+/**
+ * Showing a schema change before making it.
+ *
+ * This was `rebase db push --dry-run`, and that was wrong twice over. `db push`
+ * runs `schema generate` first, so a tool documented as "applies nothing" wrote
+ * `backend/drizzle/schema.sql`, `backend/drizzle/policies.sql` and a rewritten
+ * `backend/src/schema.generated.ts` into the repository on every call. And
+ * `db push` plans with Atlas, which needs a second empty database — the managed
+ * development database serves exactly one, so on the default scaffold the tool
+ * that `rebase_db_push`'s own refusal points at exited 1.
+ *
+ * `POST /api/admin/schema/plan` is the live schema editor's planner: it builds
+ * the statements with `generateSchemaCommit`, not Atlas, so it answers on
+ * PGlite; it has no side effects by construction (the route's own comment says
+ * so, and `apply` is a separate route); and it works over the backend the other
+ * HTTP tools already talk to, so there is no project checkout to write into.
+ *
+ * The cost is that a plan now needs a subject. That is honest: `db push
+ * --dry-run` diffed whatever the working tree happened to contain, which is not
+ * a question an agent asked.
+ */
+const SCHEMA_TOOLS = [
+    {
+        name: "rebase_schema_plan",
+        description: "Show the SQL a collection change would run, without running any of it. Posts to " +
+            "/api/admin/schema/plan — it changes nothing, writes no files, and works on the " +
+            "managed development database. Read this before proposing a schema change: it names " +
+            "every statement and marks the ones that destroy data.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                collectionId: {
+                    type: "string",
+                    description: "The collection's id — the filename under config/collections/, without the extension."
+                },
+                collection: {
+                    type: "object",
+                    description: "The whole collection as it should be AFTER the edit, in the shape defineCollection takes.",
+                    additionalProperties: true
+                }
+            },
+            required: ["collectionId", "collection"]
+        }
+    }
+];
 const FUNCTION_TOOLS = [
     {
         name: "invoke_function",
@@ -1058,6 +1325,7 @@ const PROJECT_TOOLS = [
 ];
 export const ALL_TOOLS = [
     ...CLI_TOOLS.map(({ cmd: _c, ...rest }) => rest),
+    ...SCHEMA_TOOLS,
     ...DATA_TOOLS,
     ...ADMIN_TOOLS,
     ...DEV_TOOLS,
@@ -1070,7 +1338,15 @@ export const ALL_TOOLS = [
 server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: ALL_TOOLS
 }));
-/** Spawn the rebase CLI using the project's detected package manager. */
+/**
+ * Spawn the rebase CLI using the project's detected package manager.
+ *
+ * The exit code comes back with the output. It used to be folded into a string
+ * — `Command exited with code 1\n\n…` — and handed over as an ordinary result,
+ * so a failed migration and a successful one differed only in prose. MCP has
+ * `isError` for exactly this, and a model that has to parse a sentence to learn
+ * whether a command worked will eventually parse it wrong.
+ */
 function runRebaseCmd(commandArgs) {
     const projectDir = getProjectDir();
     const pm = detectPackageManager(projectDir);
@@ -1089,17 +1365,83 @@ function runRebaseCmd(commandArgs) {
         const chunks = [];
         child.stdout?.on("data", (d) => chunks.push(d.toString()));
         child.stderr?.on("data", (d) => chunks.push(d.toString()));
-        child.on("error", (err) => resolve(`Error spawning command: ${err.message}`));
+        child.on("error", (err) => resolve({ output: `Error spawning command: ${err.message}`, code: -1 }));
         child.on("close", (code) => {
             const output = chunks.join("").trim();
-            resolve(code !== 0 ? `Command exited with code ${code}\n\n${output}` : output || "(no output)");
+            resolve({
+                output: code !== 0 ? `Command exited with code ${code}\n\n${output}` : output || "(no output)",
+                code: code ?? -1
+            });
         });
     });
 }
+/**
+ * The one refusal an agent cannot act on alone, spelled out.
+ *
+ * `db push` refuses a destructive change on a non-TTY, which every MCP call is,
+ * and prints the plan while exiting 1. Without this the model sees a failure
+ * with a flag buried in it and its next move is to find a way to pass the flag
+ * — which is the wrong move: dropping a column is a decision, and the person
+ * whose data it is has to make it. Naming the command *for the human* is what
+ * turns a dead end into a handoff.
+ */
+function destructiveRefusalHint(toolName, output) {
+    if (toolName !== "rebase_db_push")
+        return null;
+    if (!/destructive changes require confirmation|--allow-destructive/.test(output))
+        return null;
+    return ("\n\nThis push was refused because it destroys data, and that is not yours to approve. " +
+        "Show the planned SQL above (rebase_schema_plan prints one collection's statements " +
+        "without running anything), " +
+        "say which statements drop data, and ask the person you are working with to run:\n\n" +
+        "    rebase db backup\n" +
+        "    rebase db push --allow-destructive\n");
+}
 // Dev server management
 let devProcess = null;
 const devLogs = [];
 const MAX_DEV_LOG_LINES = 500;
+/** The last `count` lines of a blob of output, without its trailing blank. */
+export function lastLines(text, count) {
+    if (!text)
+        return "";
+    const lines = text.replace(/\n$/, "").split("\n");
+    return lines.slice(-Math.max(1, count)).join("\n");
+}
+/**
+ * A dev server this process did not spawn, named rather than denied.
+ *
+ * `devProcess` is only the child `rebase_dev_start` made, so "Dev server is not
+ * running." was what `rebase_dev_logs` and `rebase_dev_stop` answered while one
+ * was running in a terminal — in the same session where
+ * `rebase_project_current` was reporting that server's URL, discovered from the
+ * same `.rebase/state.json` these two never read. The output belongs to the
+ * terminal that started it, and so does the decision to stop it.
+ *
+ * @returns The sentence to answer with, or `null` when nothing is running.
+ */
+export function describeForeignDevServer(action, state = undefined) {
+    const project = (() => {
+        try {
+            return getActiveProject();
+        }
+        catch {
+            return null;
+        }
+    })();
+    const dir = project?.projectDir;
+    const found = state !== undefined ? state : dir ? readDevState(dir) : null;
+    if (!found)
+        return null;
+    const where = `${found.baseUrl}${found.pid ? ` (PID ${found.pid})` : ""}`;
+    return action === "logs"
+        ? `A dev server is running at ${where}, but this session did not start it — ` +
+            "its output goes to the terminal that did. Only a server started with " +
+            "`rebase_dev_start` has logs here."
+        : `A dev server is running at ${where}, but this session did not start it. ` +
+            "Stop it in the terminal that did (Ctrl-C); this tool only stops a server " +
+            "`rebase_dev_start` spawned.";
+}
 function appendDevLog(line) {
     devLogs.push(line);
     if (devLogs.length > MAX_DEV_LOG_LINES) {
@@ -1136,9 +1478,84 @@ export function untrustedEnvelope(source, body) {
 function untrustedJsonResult(source, data) {
     return textResult(untrustedEnvelope(source, JSON.stringify(data, null, 2)));
 }
+/**
+ * A tool error with the two facts a caller needs to act on it.
+ *
+ * `fetch failed` is what Node says when nothing is listening, and on its own it
+ * is the least useful sentence in this file: it names no host, no port and no
+ * next step. The agent's actual situation — nine times out of ten — is that
+ * `rebase dev` is not running, and it holds the tool that starts it.
+ *
+ * The URL matters as much as the remedy. The active project is sticky and lives
+ * outside the repository, so "which backend did it even try?" is a real
+ * question, and answering it is how somebody notices they are pointed at the
+ * wrong project rather than at a stopped one.
+ */
+export function explainToolError(err, baseUrl, toolName) {
+    const msg = err instanceof Error ? err.message : String(err);
+    const url = baseUrl ?? safeActiveBaseUrl();
+    const surface = toolName ? surfaceNotMounted(err, toolName) : null;
+    if (surface)
+        return surface;
+    const networkish = /fetch failed|ECONNREFUSED|ENOTFOUND|EAI_AGAIN|socket hang up|network error/i;
+    if (!networkish.test(msg))
+        return msg;
+    const where = url ? ` while calling ${url}` : "";
+    return (`${msg}${where}. Nothing answered there — is \`rebase dev\` running? ` +
+        "Start it with `rebase_dev_start`, or check `rebase_project_current`: " +
+        "the active project is sticky and lives outside your repository.");
+}
+/**
+ * A whole API surface a project never turned on, told apart from a missing row.
+ *
+ * `surfaces.cron` gates the mount, so on a project with no cron jobs — which is
+ * every fresh scaffold — `/api/admin/cron` does not exist and the client raises
+ * a bare `Not Found`. Passed through, that is the least useful sentence
+ * available: no URL, no cause, and nothing an agent can do next except guess
+ * that a *job* is missing and go looking for one. What is missing is the
+ * surface, and the way to get it is a file.
+ *
+ * Keyed by tool prefix rather than by URL because the client raises the error,
+ * not this process, and the prefix is the one fact that is certainly here.
+ */
+const SURFACE_BY_TOOL_PREFIX = [
+    {
+        // `cron_list_jobs` only, not every `cron_` tool. The row tools take a
+        // `jobId`, and the server answers a missing job with the same 404 —
+        // `Cron job "nightly" not found`. Mapped by prefix, that sentence was
+        // replaced with "this project declares no cron jobs" on a project that
+        // has five, which is a worse answer than the one it hid. A tool that
+        // addresses no row is the only one whose 404 can only be the surface.
+        tool: "cron_list_jobs",
+        message: "this project declares no cron jobs, so the cron surface is not mounted — " +
+            "`/api/admin/cron` does not exist on this backend. Add a job at " +
+            "`backend/crons/<name>.ts`, default-exporting a `CronJobDefinition`, and restart " +
+            "`rebase dev`. (An older backend answers 404 here even when jobs exist; a current " +
+            "one answers with an empty list.)"
+    }
+];
+function surfaceNotMounted(err, toolName) {
+    const status = err?.status;
+    const msg = err instanceof Error ? err.message : String(err);
+    // `status` when the client supplied one; the message is the fallback for a
+    // client old enough not to carry it.
+    if (status !== 404 && !/^not found$/i.test(msg.trim()))
+        return null;
+    const surface = SURFACE_BY_TOOL_PREFIX.find((s) => s.tool === toolName);
+    return surface ? surface.message : null;
+}
+/** The active project's baseUrl, or undefined if even that cannot be resolved. */
+function safeActiveBaseUrl() {
+    try {
+        return getActiveProject().baseUrl;
+    }
+    catch {
+        return undefined;
+    }
+}
 /** Raw text from the target environment (CLI stdout, dev-server logs), marked as untrusted. */
-function untrustedTextResult(source, text) {
-    return textResult(untrustedEnvelope(source, text));
+function untrustedTextResult(source, text, isError = false) {
+    return { ...textResult(untrustedEnvelope(source, text)), ...(isError ? { isError: true } : {}) };
 }
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
     try {
@@ -1168,11 +1585,52 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 const argsObj = args;
                 cmdArgs.push(assertValidBranchName(argsObj.name, "name"));
             }
-            const result = await runRebaseCmd(cmdArgs);
-            return untrustedTextResult(`the "${name}" CLI command`, result);
+            else if (name === "rebase_db_branch_switch") {
+                // Both optional, and mutually exclusive in effect: with neither the
+                // command reports the active branch, which is the question asked
+                // most often.
+                const argsObj = args;
+                if (argsObj.off)
+                    cmdArgs.push("--off");
+                else if (argsObj.name)
+                    cmdArgs.push(assertValidBranchName(argsObj.name, "name"));
+            }
+            const { output, code } = await runRebaseCmd(cmdArgs);
+            const hint = destructiveRefusalHint(name, output);
+            return untrustedTextResult(`the "${name}" CLI command`, output + (hint ?? ""), code !== 0);
         }
         // ── Project management tools ────────────────────────────────────────
         switch (name) {
+            case "rebase_schema_plan": {
+                const argsObj = args;
+                const project = getActiveProject();
+                const res = await fetch(`${project.baseUrl}/api/admin/schema/plan`, {
+                    method: "POST",
+                    headers: {
+                        "Content-Type": "application/json",
+                        ...(project.token ? { Authorization: `Bearer ${project.token}` } : {})
+                    },
+                    body: JSON.stringify({
+                        collectionId: argsObj.collectionId,
+                        collection: argsObj.collection
+                    })
+                });
+                const body = await res.text();
+                if (!res.ok) {
+                    // 501 is the one refusal worth translating: the surface is
+                    // mounted but the server was started without a collections
+                    // directory or a repository, so there is nothing to plan
+                    // against. Every other status carries the server's own message,
+                    // which is written for a person.
+                    const hint = res.status === 501
+                        ? "\n\nThis backend was started without `collectionsDir` or `liveSchema.repository`, " +
+                            "so it has no collection source to plan against. `rebase dev` supplies one; a " +
+                            "deployment running from a built bundle does not."
+                        : "";
+                    return untrustedTextResult(`POST ${project.baseUrl}/api/admin/schema/plan`, `HTTP ${res.status}\n${body}${hint}`, true);
+                }
+                return untrustedJsonResult(`POST ${project.baseUrl}/api/admin/schema/plan`, JSON.parse(body));
+            }
             case "rebase_project_list": {
                 const projects = Object.values(registry.projects).map((p) => ({
                     name: p.name,
@@ -1222,7 +1680,16 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     }
                 }
                 if (!baseUrl) {
-                    return textResult("Error: Could not determine baseUrl. Provide --baseUrl or ensure the dev server is running in the project directory.");
+                    // `--baseUrl` is a CLI flag, and this is not a CLI. The
+                    // model was being told to pass an option this tool has no
+                    // notion of, in a message it could not act on.
+                    return {
+                        ...textResult(`Cannot register "${projectName}": no baseUrl. Pass \`baseUrl\` ` +
+                            '(for example "http://localhost:3001"), or pass a `projectDir` ' +
+                            "where `rebase dev` is running so it can be discovered from " +
+                            "`.rebase/state.json`."),
+                        isError: true
+                    };
                 }
                 registry.projects[projectName] = {
                     name: projectName,
@@ -1231,6 +1698,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     token,
                     addedAt: new Date().toISOString()
                 };
+                // Registering one *by name* is the operator saying it out loud, so
+                // it is no longer derived and `saveRegistry` must write it. Without
+                // this, `rebase_project_add` with the name "default" answered
+                // "registered" and persisted nothing at all.
+                if (projectName === "default")
+                    defaultIsDerived = false;
                 saveRegistry();
                 return jsonResult({
                     message: `Project "${projectName}" registered`,
@@ -1419,7 +1892,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 await client.storage.deleteObject(key, bucket);
                 return textResult(`Deleted object "${key}" successfully.`);
             }
-            case "storage_get_metadata": {
+            case "storage_get_download_url": {
                 const argsObj = args;
                 const { key, bucket } = argsObj;
                 const result = await client.storage.getSignedUrl(key, bucket);
@@ -1428,6 +1901,14 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             // ── Cron Tools ─────────────────────────────────────────────────────
             case "cron_list_jobs": {
                 const result = await client.cron.listJobs();
+                // An empty list is the same situation as an unmounted surface, and
+                // `{ "jobs": [] }` on its own reads as a failure to an agent that
+                // asked what runs on a schedule. Say what a job is made of.
+                if (!result?.jobs?.length) {
+                    return textResult("This project declares no cron jobs. Add one at `backend/crons/<name>.ts`, " +
+                        "default-exporting a `CronJobDefinition`, and restart `rebase dev` — the " +
+                        "filename becomes the job id.");
+                }
                 return untrustedJsonResult("the cron scheduler", result);
             }
             case "cron_get_job": {
@@ -1493,15 +1974,22 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             case "rebase_dev_logs": {
                 const argsObj = args;
                 const lineCount = argsObj?.lines ?? 50;
-                const recent = devLogs.slice(-lineCount);
-                if (recent.length === 0) {
-                    return textResult(devProcess ? "No output captured yet." : "Dev server is not running.");
+                // `devLogs` holds stdout *chunks*, not lines: one `data` event can
+                // carry a hundred lines or half of one. Slicing the chunk array by
+                // `lines` therefore returned an amount of output unrelated to the
+                // number asked for — usually far more — while the tool description
+                // and the docs both promised lines.
+                const recent = lastLines(devLogs.join(""), lineCount);
+                if (!recent) {
+                    if (devProcess)
+                        return textResult("No output captured yet.");
+                    return textResult(describeForeignDevServer("logs") ?? "Dev server is not running.");
                 }
-                return untrustedTextResult("the dev server's output", recent.join(""));
+                return untrustedTextResult("the dev server's output", recent);
             }
             case "rebase_dev_stop": {
                 if (!devProcess || devProcess.killed) {
-                    return textResult("Dev server is not running.");
+                    return textResult(describeForeignDevServer("stop") ?? "Dev server is not running.");
                 }
                 devProcess.kill("SIGTERM");
                 return textResult("Dev server stopped.");
@@ -1511,11 +1999,10 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         }
     }
     catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
         return {
             content: [{
                     type: "text",
-                    text: `Error: ${msg}`
+                    text: `Error: ${explainToolError(err, undefined, request.params.name)}`
                 }],
             isError: true
         };
@@ -1647,7 +2134,40 @@ server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
     throw new Error(`Unknown resource: ${uri}`);
 });
 // ── Start ───────────────────────────────────────────────────────────────────
+/**
+ * `--help` and `--version`, answered before anything connects.
+ *
+ * A stdio MCP server run by hand is the normal way to check that a config block
+ * works, and this one answered `--version` by opening a transport and waiting
+ * for a client that was never coming — a hang with no output, which reads as a
+ * broken install rather than as a server doing exactly what it was told.
+ *
+ * @returns true when the process has answered and should exit.
+ */
+export function answerCliFlags(argv = process.argv.slice(2)) {
+    if (argv.includes("--version") || argv.includes("-v")) {
+        process.stdout.write(`${MCP_SERVER_VERSION}\n`);
+        return true;
+    }
+    if (argv.includes("--help") || argv.includes("-h")) {
+        process.stdout.write("rebase-mcp — the Rebase MCP server\n\n" +
+            "It speaks MCP over stdio and has no other interface: an MCP client\n" +
+            "spawns it, and there is nothing to run interactively.\n\n" +
+            "  npx -y @rebasepro/mcp\n\n" +
+            "Environment\n" +
+            "  REBASE_PROJECT_DIR                the directory holding rebase.json\n" +
+            "  REBASE_BASE_URL                   backend URL (default http://localhost:3001)\n" +
+            "  REBASE_API_TOKEN                  a scoped rk_ API key, or a service key\n" +
+            "  REBASE_MCP_ALLOW_REMOTE_WRITES    allow write tools off the loopback interface\n\n" +
+            "Setup blocks for Claude Code, Cursor, Gemini CLI, Codex and Kiro:\n" +
+            "  https://rebase.pro/docs/ai/mcp\n");
+        return true;
+    }
+    return false;
+}
 async function main() {
+    if (answerCliFlags())
+        return;
     const transport = new StdioServerTransport();
     await server.connect(transport);
 }