@rebasepro/mcp 0.17.3 → 0.18.0

package/README.md

@@ -8,10 +8,14 @@ Model Context Protocol (MCP) server that exposes Rebase schema, database, docume
 pnpm add @rebasepro/mcp
 ```
 
+ESM-only: `"type": "module"` with no CommonJS build, so it is loaded with
+`import`. `require()` of it resolves only on Node 22.12+, which supports
+`require(esm)`.
+
 Or run directly:
 
 ```bash
-npx rebase-mcp
+npx -y @rebasepro/mcp
 ```
 
 ## What This Package Does
@@ -24,9 +28,20 @@ The MCP server supports managing multiple Rebase projects simultaneously. This i
 
 - **Registry**: Project configurations are stored in `~/.rebase/projects.json`.
 - **Auto-Discovery**: If `rebase dev` is running locally, the MCP server automatically discovers the active development port and service key from `.rebase/state.json` inside the project directory, giving you **zero-config local development**.
-- **Default Project**: If no project registry exists, a default project named `default` is created using `REBASE_PROJECT_DIR` (or current working directory), `REBASE_BASE_URL`, and `REBASE_API_TOKEN`.
 
-A token registered for a project **takes precedence over auto-discovery**. Discovery reads the dev server's *service key*, which is an unscoped admin secret — so if you deliberately register a narrow `rk_live_*` API key for a project, that key is what gets used, even while `rebase dev` is running. Discovery only fills in a token when none is registered.
+### Which project a run resolves to
+
+One precedence, in this order:
+
+1. **The environment block** — `REBASE_PROJECT_DIR`, `REBASE_BASE_URL`, `REBASE_API_TOKEN` / `REBASE_TOKEN`. If any of them is set, the `default` project is rebuilt from them on **every** start. The rebuild is whole-entry: a token registered against the old `projectDir` is dropped rather than carried into a directory it was never issued for.
+2. **The server's working directory**, when it holds a `rebase.json`. `~/.rebase/projects.json` is machine-wide, and a project you are standing in outranks a home-directory cache.
+3. **The persisted `default`**, when neither of the first two says anything.
+
+A `default` derived from 1 or 2 is never written back to the registry: it is recomputed at every start, and persisting it would put one project's directory, backend URL and dev service key in the file every other project on the machine reads.
+
+Auto-discovery fills gaps in all three cases and **never overrules** a value one of them supplied — not the token and not the `baseUrl`. Discovery reads the dev server's *service key*, which is an unscoped admin secret, so a narrow `rk_live_*` key you registered is what gets used even while `rebase dev` is running; likewise a project registered against `https://staging.example.com` stays there rather than being silently redirected to the local dev port. A disagreement between the two is reported on stderr.
+
+`rebase init` writes `"env": { "REBASE_PROJECT_DIR": "." }` into the scaffolded `.mcp.json` — relative to the client's working directory, which for a project-level config file is the project.
 
 ## Configuration
 
@@ -34,9 +49,9 @@ The server reads configuration from environment variables and `.env` files:
 
 | Variable | Default | Description |
 |---|---|---|
-| `REBASE_PROJECT_DIR` | `process.cwd()` | Project root directory (fallback if no registry) |
-| `REBASE_BASE_URL` | `http://localhost:3001` | Rebase backend URL (fallback if no registry) |
-| `REBASE_API_TOKEN` / `REBASE_TOKEN` | (empty) | Auth token for API calls (fallback if no registry) |
+| `REBASE_PROJECT_DIR` | `process.cwd()` | Project root directory (the `rebase.json` directory) |
+| `REBASE_BASE_URL` | `http://localhost:3001` | Rebase backend URL, when discovery finds no dev server |
+| `REBASE_API_TOKEN` / `REBASE_TOKEN` | (empty) | Auth token for API calls |
 | `REBASE_MCP_ALLOW_REMOTE_WRITES` | `false` | Allow destructive tools to run against non-local targets (see below) |
 
 The server attempts to load `.env` from `$REBASE_PROJECT_DIR/.env` or `$REBASE_PROJECT_DIR/app/.env`.
@@ -68,69 +83,105 @@ Rows, user records, storage listings, cron jobs, function responses and CLI outp
 
 ## Tools
 
-### Project Management Tools (6) [NEW]
+<!-- generated: mcp tool tables — pnpm generate:mcp-readme -->
+
+42 tools, in 9 groups. Tools marked ⚠ are refused against a non-local
+target unless `REBASE_MCP_ALLOW_REMOTE_WRITES=true` — see the gate above.
+
+### Schema & database (12)
 
-Manage multiple local projects or remote environments.
+Spawn the Rebase CLI in the active project directory.
 
-| Tool | Required Args | Description |
+| Tool | Required | Description |
 |---|---|---|
-| `rebase_project_list` | (none) | List all registered projects and show which one is currently active |
-| `rebase_project_switch` | `name` | Switch the active project to another registered project |
-| `rebase_project_add` | `name` | Register a new project (requires `baseUrl` and optional `projectDir`, `token`/`serviceKey`) |
-| `rebase_project_remove` | `name` | Remove a project from the registry (cannot remove the default project) |
-| `rebase_project_current` | (none) | Show details of the active project (name, directory, base URL, auth token status) |
-| `rebase_project_status` | (none) | Perform a health check on the active project's backend URL |
+| `rebase_schema_generate` | — | Generate Drizzle schema from Rebase TypeScript collection definitions |
+| `rebase_db_push` ⚠ | — | Apply the current Drizzle schema directly to the database (development shortcut, skips migration files) |
+| `rebase_schema_introspect` | — | Introspect the live database and generate Rebase collection definitions from existing tables |
+| `rebase_db_generate` | — | Generate SQL migration files from schema changes (compares current Drizzle schema against the last entity) |
+| `rebase_db_migrate` ⚠ | — | Run all pending SQL migrations against the database |
+| `rebase_generate_sdk` | — | Generate a fully-typed JavaScript/TypeScript SDK from collection definitions |
+| `rebase_doctor` | — | Detect schema drift between collection definitions, generated Drizzle schema, and the live PostgreSQL database |
+| `rebase_db_branch_create` ⚠ | `name` | Create a new database branch (Admins only) |
+| `rebase_db_branch_list` | — | List all database branches (Admins only) |
+| `rebase_db_branch_delete` ⚠ | `name` | Delete an existing database branch (Admins only) |
+| `rebase_db_branch_info` | `name` | Show information and status for a database branch (Admins only) |
+| `rebase_db_branch_switch` | — | Point this checkout at a database branch, or back at the main database (Admins only) |
+
+### Schema planning (1)
+
+Ask the backend what a change would do. No CLI, no files written.
+
+| Tool | Required | Description |
+|---|---|---|
+| `rebase_schema_plan` | `collectionId`, `collection` | Show the SQL a collection change would run, without running any of it |
 
-### CLI Tools (6)
+### Documents (5)
 
-Spawn `npx rebase <command>` in the active project directory.
+CRUD over a collection through `@rebasepro/client`.
 
-| Tool | Description |
-|---|---|
-| `rebase_schema_generate` | Generate Drizzle schema from collection definitions |
-| `rebase_db_push` | Apply schema directly to DB (dev shortcut) |
-| `rebase_schema_introspect` | Introspect live DB → collection definitions |
-| `rebase_db_generate` | Generate SQL migration files from schema diff |
-| `rebase_db_migrate` | Run pending SQL migrations |
-| `rebase_generate_sdk` | Generate typed TypeScript SDK |
+| Tool | Required | Description |
+|---|---|---|
+| `list_documents` | `collection` | List documents from a Rebase collection with optional filtering, sorting, and pagination |
+| `get_document` | `collection`, `id` | Get a single document by ID from a Rebase collection |
+| `create_document` ⚠ | `collection`, `data` | Create a new document in a Rebase collection |
+| `update_document` ⚠ | `collection`, `id`, `data` | Update an existing document in a Rebase collection |
+| `delete_document` ⚠ | `collection`, `id` | Delete a document from a Rebase collection |
+
+### Users & roles (6)
 
-### Data Tools (5)
+| Tool | Required | Description |
+|---|---|---|
+| `list_users` | — | List all users registered in the Rebase backend, including their roles |
+| `create_user` ⚠ | `email` | Create a new user in the Rebase backend |
+| `update_user` ⚠ | `uid` | Update an existing user (email, display name, roles) |
+| `delete_user` ⚠ | `uid` | Delete a user from the Rebase backend |
+| `list_roles` | — | List all roles defined in the Rebase backend |
+| `rebase_auth_reset_password` ⚠ | `email` | Reset a user's password via the admin API |
 
-CRUD operations via `@rebasepro/client` on the active project.
+### Dev server (3)
 
-| Tool | Required Args | Description |
+| Tool | Required | Description |
 |---|---|---|
-| `list_documents` | `collection` | List with optional `limit`, `offset`, `orderBy`, `where` |
-| `get_document` | `collection`, `id` | Get single document by ID |
-| `create_document` | `collection`, `data` | Create a new document |
-| `update_document` | `collection`, `id`, `data` | Update existing document |
-| `delete_document` | `collection`, `id` | Delete a document |
+| `rebase_dev_start` | — | Start the Rebase development server (frontend + backend) |
+| `rebase_dev_logs` | — | Read recent output from the running Rebase dev server |
+| `rebase_dev_stop` | — | Stop the running Rebase development server |
 
-### Admin Tools (6)
+### Storage (3)
+
+| Tool | Required | Description |
+|---|---|---|
+| `storage_list_objects` | — | List files/objects stored in Rebase storage |
+| `storage_delete_object` ⚠ | `key` | Delete an object/file from Rebase storage |
+| `storage_get_download_url` | `key` | Mint a temporary signed download URL for a file in Rebase storage |
 
-User and role management.
+### Cron (5)
 
-| Tool | Required Args | Description |
+| Tool | Required | Description |
 |---|---|---|
-| `list_users` | (none) | List all users with roles |
-| `create_user` | `email` | Create user (optional: `displayName`, `password`, `roles`) |
-| `update_user` | `userId` | Update user (optional: `email`, `displayName`, `roles`) |
-| `delete_user` | `userId` | Delete a user |
-| `list_roles` | (none) | List all defined roles |
-| `rebase_auth_reset_password` | `email` | Reset a user's password using the admin API (optional: `password`) |
+| `cron_list_jobs` | — | List all scheduled cron jobs and their configuration status |
+| `cron_get_job` | `jobId` | Get status and details of a specific scheduled cron job |
+| `cron_trigger_job` ⚠ | `jobId` | Manually trigger a cron job run immediately |
+| `cron_get_job_logs` | `jobId` | Read execution logs for a specific cron job |
+| `cron_toggle_job` ⚠ | `jobId`, `enabled` | Enable or disable a scheduled cron job |
 
-> [!NOTE]
-> `rebase_auth_reset_password` now calls the running admin endpoint instead of performing direct database queries. This makes it compatible with both local development and remote servers.
+### Functions (1)
 
-### Dev Server Tools (3)
+| Tool | Required | Description |
+|---|---|---|
+| `invoke_function` ⚠ | `name` | Invoke a custom backend Hono function (located in api/functions/:name) |
 
-Manage the local development server.
+### Project registry (6)
 
-| Tool | Description |
-|---|---|
-| `rebase_dev_start` | Start `pnpm run dev` in the `app/` directory |
-| `rebase_dev_logs` | Read recent output (default: 50 lines, max buffer: 500) |
-| `rebase_dev_stop` | Send SIGTERM to the dev server process |
+| Tool | Required | Description |
+|---|---|---|
+| `rebase_project_list` | — | List all registered Rebase projects and show which one is active |
+| `rebase_project_switch` | `name` | Switch the active Rebase project by name |
+| `rebase_project_add` | `name` | Register a new Rebase project |
+| `rebase_project_remove` | `name` | Remove a registered project from the project registry |
+| `rebase_project_current` | — | Show details about the currently active Rebase project, including resolved URL and auth status |
+| `rebase_project_status` | — | Health-check the active project's backend by calling GET /health |
+
+<!-- /generated: mcp tool tables -->
 
 ---
 
@@ -154,7 +205,7 @@ Add to your AI assistant's MCP config (e.g. `.gemini/settings.json`):
   "mcpServers": {
     "rebase": {
       "command": "npx",
-      "args": ["rebase-mcp"],
+      "args": ["-y", "@rebasepro/mcp"],
       "env": {
         "REBASE_PROJECT_DIR": "/path/to/your/project"
       }

package/dist/index.d.ts

@@ -43,6 +43,49 @@ export interface ProjectConfig {
     /** ISO timestamp when the project was registered. */
     addedAt: string;
 }
+/**
+ * Read `.rebase/state.json` from a project directory to auto-discover
+ * a running dev server's URL and service key.
+ */
+declare function readDevState(projectDir: string): {
+    baseUrl: string;
+    serviceKey?: string;
+    pid?: number;
+} | null;
+/**
+ * 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.
+ */
+export declare function autoDiscoverLocal(project: ProjectConfig, devState?: ReturnType<typeof readDevState> | undefined): ProjectConfig;
+/**
+ * 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 declare function envDeclaredProject(env?: NodeJS.ProcessEnv): {
+    projectDir?: string;
+    baseUrl?: string;
+    token?: string;
+} | null;
+/**
+ * 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 declare const DEFAULT_BASE_URL = "http://localhost:3001";
 /**
  * Tools that only read from the target environment.
  *
@@ -187,6 +230,21 @@ interface ToolDef {
     };
 }
 export declare const ALL_TOOLS: ToolDef[];
+/** The last `count` lines of a blob of output, without its trailing blank. */
+export declare function lastLines(text: string, count: number): string;
+/**
+ * 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 declare function describeForeignDevServer(action: "logs" | "stop", state?: ReturnType<typeof readDevState> | undefined): string | null;
 /**
  * Wrap content that came out of the target environment in an explicit
  * untrusted-data envelope.
@@ -201,6 +259,20 @@ export declare const ALL_TOOLS: ToolDef[];
  * all is below the floor.
  */
 export declare function untrustedEnvelope(source: string, body: string): string;
+/**
+ * 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 declare function explainToolError(err: unknown, baseUrl?: string, toolName?: string): string;
 /**
  * Where a project's backend lives, across the two layouts that exist.
  *
@@ -228,5 +300,15 @@ export declare function findBackendDir(projectDir?: string): string | null;
  * tool call.
  */
 export declare function findDevDir(projectDir?: string): string;
+/**
+ * `--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 declare function answerCliFlags(argv?: string[]): boolean;
 export {};
-//# sourceMappingURL=index.d.ts.map