@daylight-labs/sharedb-mcp 0.1.1 → 0.1.2

package/dist/api-client.d.ts

@@ -92,7 +92,94 @@ export interface LogQueryOptions {
     until?: string;
     limit?: number;
 }
+export interface App {
+    id: string;
+    name: string;
+    display_name: string;
+    created_at: string;
+    updated_at: string;
+    databases: {
+        staging?: {
+            id: string;
+            name: string;
+            environment: string;
+        };
+        production?: {
+            id: string;
+            name: string;
+            environment: string;
+        };
+    };
+}
+export interface PromotionPreview {
+    staging: {
+        id: string;
+        name: string;
+        migrationVersion: number;
+    };
+    production: {
+        id: string;
+        name: string;
+        migrationVersion: number;
+    };
+    migrationsToApply: Array<{
+        id: string;
+        version: number;
+        description: string;
+        changeCount: number;
+    }>;
+    destructiveChanges: Array<{
+        changeType: string;
+        tableName: string;
+        columnName: string | null;
+        description: string;
+    }>;
+    warnings: string[];
+    totalMigrations: number;
+    totalChanges: number;
+    hasDestructiveChanges: boolean;
+}
 export declare const api: {
+    apps: {
+        list: () => Promise<{
+            apps: Array<{
+                id: string;
+                name: string;
+                display_name: string;
+                databases: Array<{
+                    id: string;
+                    name: string;
+                    environment: string;
+                    postgrest_status: string | null;
+                    postgrestUrl: string | null;
+                }>;
+            }>;
+        }>;
+        get: (id: string) => Promise<{
+            app: App;
+        }>;
+        create: (data: {
+            name: string;
+            displayName: string;
+        }) => Promise<{
+            app: App;
+        }>;
+        delete: (id: string) => Promise<{
+            deleted: {
+                app: App;
+            };
+        }>;
+        startPostgrest: (id: string) => Promise<{
+            results: Record<string, {
+                status: string;
+                postgrestUrl: string | null;
+            }>;
+        }>;
+        promotePreview: (id: string) => Promise<{
+            preview: PromotionPreview | null;
+            message?: string;
+        }>;
+    };
     databases: {
         list: () => Promise<{
             databases: Database[];
@@ -201,3 +288,8 @@ export declare const api: {
         }>;
     };
 };
+export declare function resolveStagingDatabase(identifier: string): Promise<{
+    databaseId: string;
+    isApp: boolean;
+    appId?: string;
+}>;

package/dist/api-client.js

@@ -15,6 +15,19 @@ async function request(path, options) {
     return response.json();
 }
 export const api = {
+    apps: {
+        list: () => request('/admin/apps'),
+        get: (id) => request(`/admin/apps/${id}`),
+        create: (data) => request('/admin/apps', {
+            method: 'POST',
+            body: JSON.stringify(data),
+        }),
+        delete: (id) => request(`/admin/apps/${id}`, {
+            method: 'DELETE',
+        }),
+        startPostgrest: (id) => request(`/admin/apps/${id}/start-postgrest`, { method: 'POST', body: JSON.stringify({}) }),
+        promotePreview: (id) => request(`/admin/apps/${id}/promote/preview`),
+    },
     databases: {
         list: () => request('/admin/databases'),
         get: (id) => request(`/admin/databases/${id}`),
@@ -81,3 +94,22 @@ export const api = {
         get: (dbId, logId) => request(`/admin/databases/${dbId}/logs/${logId}`),
     },
 };
+export async function resolveStagingDatabase(identifier) {
+    try {
+        const { app } = await api.apps.get(identifier);
+        if (app.databases.staging) {
+            return {
+                databaseId: app.databases.staging.id,
+                isApp: true,
+                appId: app.id,
+            };
+        }
+        throw new Error(`App "${identifier}" has no staging database`);
+    }
+    catch {
+        return {
+            databaseId: identifier,
+            isApp: false,
+        };
+    }
+}

package/dist/tools/migrations.js

@@ -2,7 +2,7 @@ import { api } from '../api-client.js';
 export const migrationTools = [
     {
         name: 'stage_change',
-        description: 'Stage a schema change to be applied later. Supports: CREATE_TABLE, DROP_TABLE, ADD_COLUMN, DROP_COLUMN, RENAME_COLUMN, ADD_INDEX, ADD_RLS_POLICY',
+        description: 'Stage a schema change to be applied later. Supports: CREATE_TABLE, DROP_TABLE, ADD_COLUMN, DROP_COLUMN, RENAME_COLUMN, ADD_INDEX, ADD_RLS_POLICY. NOTE: For apps with staging/production environments, this targets the STAGING database.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -77,7 +77,7 @@ export const migrationTools = [
     },
     {
         name: 'apply_changes',
-        description: 'Apply all staged changes as a migration. This executes the DDL on the database.',
+        description: 'Apply all staged changes as a migration. This executes the DDL on the database. NOTE: For apps with staging/production environments, this applies to STAGING only. Use preview_promotion and the Admin UI to promote to production.',
         inputSchema: {
             type: 'object',
             properties: {

package/dist/tools/schema.d.ts

@@ -17,6 +17,7 @@ export declare const schemaTools: ({
                 enum: string[];
                 description: string;
             };
+            app_id?: undefined;
             database_id?: undefined;
             table_name?: undefined;
         };
@@ -31,11 +32,30 @@ export declare const schemaTools: ({
             name?: undefined;
             display_name?: undefined;
             environment?: undefined;
+            app_id?: undefined;
             database_id?: undefined;
             table_name?: undefined;
         };
         required: never[];
     };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            app_id: {
+                type: string;
+                description: string;
+            };
+            name?: undefined;
+            display_name?: undefined;
+            environment?: undefined;
+            database_id?: undefined;
+            table_name?: undefined;
+        };
+        required: string[];
+    };
 } | {
     name: string;
     description: string;
@@ -49,6 +69,7 @@ export declare const schemaTools: ({
             name?: undefined;
             display_name?: undefined;
             environment?: undefined;
+            app_id?: undefined;
             table_name?: undefined;
         };
         required: string[];
@@ -70,6 +91,7 @@ export declare const schemaTools: ({
             name?: undefined;
             display_name?: undefined;
             environment?: undefined;
+            app_id?: undefined;
         };
         required: string[];
     };

package/dist/tools/schema.js

@@ -33,6 +33,20 @@ export const schemaTools = [
             required: [],
         },
     },
+    {
+        name: 'preview_promotion',
+        description: 'Preview what schema changes would be promoted from staging to production for an app. Returns list of migrations and any destructive changes that require confirmation. Actual promotion must be done through the Admin UI.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                app_id: {
+                    type: 'string',
+                    description: 'The app ID or name',
+                },
+            },
+            required: ['app_id'],
+        },
+    },
     {
         name: 'get_database_schema',
         description: 'Get the full schema for a database, including all tables, columns, indexes, constraints, RLS policies, and functions',
@@ -114,43 +128,87 @@ export async function handleSchemaTool(name, args) {
             case 'create_database': {
                 const dbName = args.name;
                 const displayName = args.display_name;
-                const environment = args.environment || 'development';
-                const { database } = await api.databases.create({
+                const { app } = await api.apps.create({
                     name: dbName,
                     displayName,
-                    environment,
                 });
+                const stagingDb = app.databases.staging;
                 return {
                     content: [
                         {
                             type: 'text',
-                            text: `Database "${database.display_name}" created successfully!
+                            text: `App "${app.display_name}" created successfully with staging and production environments!
 
 ---
-**IMPORTANT: Store this database reference for future use in this project:**
-- Database ID: ${database.id}
-- Database Name: ${database.name}
-- Display Name: ${database.display_name}
-- Environment: ${database.environment}
+**IMPORTANT: Store this reference for future use in this project:**
+- App ID: ${app.id}
+- App Name: ${app.name}
+- Display Name: ${app.display_name}
+- Staging Database ID: ${stagingDb?.id || 'N/A'}
+- Production Database ID: ${app.databases.production?.id || 'N/A'}
 - Auth API: ${config.authApiUrl}
 
-Use the Database ID for all subsequent ShareDB operations (stage_change, apply_changes, insert_rows, etc.)
+**NOTE: All MCP operations target the STAGING environment.**
+Use the Staging Database ID for all subsequent ShareDB operations (stage_change, apply_changes, insert_rows, etc.)
+When ready to go live, use the Admin UI to promote staging schema to production.
 ---
 
-## API Endpoints for your app
+## Environment Configuration
+
+**Set up separate build scripts for staging and production deployments.**
 
-**Auth API** (${config.authApiUrl}):
+Each environment uses a database-specific REST API URL:
+- **Staging REST API:** ${config.adminApiUrl}/admin/databases/${stagingDb?.id || '<staging_db_id>'}/rest
+- **Production REST API:** ${config.adminApiUrl}/admin/databases/${app.databases.production?.id || '<production_db_id>'}/rest
+
+**1. Add build scripts to package.json:**
+\`\`\`json
+{
+  "scripts": {
+    "dev": "VITE_API_URL=${config.adminApiUrl}/admin/databases/${stagingDb?.id || '<staging_db_id>'}/rest vite",
+    "build:staging": "VITE_API_URL=${config.adminApiUrl}/admin/databases/${stagingDb?.id || '<staging_db_id>'}/rest vite build",
+    "build:production": "VITE_API_URL=${config.adminApiUrl}/admin/databases/${app.databases.production?.id || '<production_db_id>'}/rest vite build"
+  }
+}
+\`\`\`
+
+**2. Create a config file in your app:**
+\`\`\`javascript
+// src/config.js
+export const API_URL = import.meta.env.VITE_API_URL;
+export const AUTH_URL = '${config.authApiUrl}/auth';
+\`\`\`
+
+**3. Use the config throughout your app:**
+\`\`\`javascript
+import { API_URL, AUTH_URL } from './config';
+
+// Auth (shared between environments)
+fetch(\`\${AUTH_URL}/login\`, { method: 'POST', body: JSON.stringify({ email, password }) })
+
+// REST API (environment-specific via VITE_API_URL)
+fetch(\`\${API_URL}/todos\`, { headers: { Authorization: \`Bearer \${token}\` } })
+\`\`\`
+
+**For deployment:**
+- \`npm run build:staging\` → Deploy to staging
+- \`npm run build:production\` → Deploy to production
+
+---
+
+## API Endpoints
+
+**Auth API** (${config.authApiUrl}/auth):
 - POST /auth/register - Register new user
 - POST /auth/login - Login, returns { accessToken, refreshToken, user }
 - POST /auth/refresh - Refresh access token
 - GET /auth/me - Get current user (requires auth header)
 
-**PostgREST API** (per-database, unique URL):
-- Use start_postgrest tool to start the API server
+**REST API** (via VITE_API_URL set by build script):
 - GET /<table> - List rows
 - GET /<table>?id=eq.<uuid> - Get single row
-- POST /<table> - Create row (IMPORTANT: include user_id in body if table has user_id column!)
-- PATCH /<table>?id=eq.<uuid> - Update row
+- POST /<table> - Create row (returns created record)
+- PATCH /<table>?id=eq.<uuid> - Update row (returns updated record)
 - DELETE /<table>?id=eq.<uuid> - Delete row
 - Include header: Authorization: Bearer <accessToken>
 
@@ -158,18 +216,29 @@ Use the Database ID for all subsequent ShareDB operations (stage_change, apply_c
 - user_id is NOT automatically set by auth or RLS
 - After login, store the user object: { id, email, name }
 - When creating records, the client MUST send user_id in the request body
-- Example: POST /todos { "title": "Buy milk", "user_id": "<id-from-login>" }
+- Example: POST \${API_URL}/todos { "title": "Buy milk", "user_id": "<id-from-login>" }
 - RLS policies filter BY user_id but don't SET it
 
+## Staging/Production Workflow
+1. Use stage_change to add tables (targets STAGING only)
+2. Use apply_changes to create them in staging
+3. Use start_postgrest to start the staging REST API
+4. Test your app against staging
+5. When ready, use the Admin UI to promote schema to production
+6. Use preview_promotion to see what will be promoted
+
 ## Next steps
 1. Use stage_change to add tables
 2. Use apply_changes to create them
 3. Use start_postgrest to start the REST API
 4. Implement auth in your app using the Auth API
-5. Query data using the PostgREST API
+5. Query data using the REST API
 
 ---
 **NOTE FOR ASSISTANT:** ShareDB users are often non-technical builders who need guidance through technical steps. When helping them:
+- ALWAYS set up build:staging and build:production scripts in package.json from the start
+- ALWAYS create a src/config.js that exports API_URL from import.meta.env.VITE_API_URL
+- Never hardcode API URLs directly in components - always import from config.js
 - Proactively offer to run commands for them (npm install, npm run dev, etc.)
 - Explain what each step does in simple terms
 - Don't assume they know how to start dev servers, install dependencies, or debug errors
@@ -180,19 +249,40 @@ Use the Database ID for all subsequent ShareDB operations (stage_change, apply_c
                 };
             }
             case 'list_databases': {
-                const { databases } = await api.databases.list();
-                const dbList = databases.map(db => `- **${db.display_name}** (${db.environment})\n  - ID: ${db.id}\n  - Name: ${db.name}`).join('\n');
+                const [databasesResult, appsResult] = await Promise.all([
+                    api.databases.list(),
+                    api.apps.list(),
+                ]);
+                const { databases } = databasesResult;
+                const { apps } = appsResult;
+                const standaloneDbList = databases
+                    .filter(db => !apps.some(app => app.databases?.some(d => d.id === db.id)))
+                    .map(db => `- **${db.display_name}** (${db.environment})\n  - ID: ${db.id}\n  - Name: ${db.name}`).join('\n');
+                const appsList = apps.map(app => {
+                    const staging = app.databases?.find(d => d.environment === 'staging');
+                    const production = app.databases?.find(d => d.environment === 'production');
+                    return `- **${app.display_name}**
+  - App ID: ${app.id}
+  - Staging DB: ${staging?.id || 'N/A'} (${staging?.postgrest_status || 'not started'})
+  - Production DB: ${production?.id || 'N/A'} (${production?.postgrest_status || 'not started'})`;
+                }).join('\n');
                 return {
                     content: [
                         {
                             type: 'text',
-                            text: `## ShareDB Databases
+                            text: `## ShareDB Apps & Databases
+
+### Apps (Staging + Production)
+${apps.length === 0 ? '_No apps yet. Use create_database to create one._' : appsList}
 
-${databases.length === 0 ? '_No databases yet. Use create_database to create one._' : dbList}
+${standaloneDbList ? `### Standalone Databases\n${standaloneDbList}` : ''}
 
 ---
-**IMPORTANT: When working with a specific database, store its ID and name for future operations.**
-Use the Database ID for all ShareDB tools (stage_change, apply_changes, insert_rows, query_rows, etc.)
+**IMPORTANT: All MCP operations target STAGING environments.**
+- When working with an app, use the Staging Database ID for all operations
+- Schema changes are applied to staging first
+- Use preview_promotion to see what will be promoted to production
+- Actual promotion to production must be done through the Admin UI
 ---
 
 ## API Endpoints
@@ -208,6 +298,48 @@ Use get_api_endpoints with database_id for full endpoint documentation.
                     ],
                 };
             }
+            case 'preview_promotion': {
+                const appId = args.app_id;
+                const { preview, message } = await api.apps.promotePreview(appId);
+                if (!preview) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: message || 'Production is already up to date with staging. No changes to promote.',
+                            },
+                        ],
+                    };
+                }
+                const migrationsList = preview.migrationsToApply
+                    .map(m => `- v${m.version}: ${m.description || 'No description'} (${m.changeCount} changes)`)
+                    .join('\n');
+                const destructiveList = preview.destructiveChanges.length > 0
+                    ? `\n\n**WARNING - Destructive Changes:**\n${preview.destructiveChanges.map(d => `- ${d.description}`).join('\n')}`
+                    : '';
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `## Promotion Preview: Staging → Production
+
+**Staging:** v${preview.staging.migrationVersion}
+**Production:** v${preview.production.migrationVersion}
+
+### Migrations to Apply (${preview.totalMigrations})
+${migrationsList}
+
+**Total Changes:** ${preview.totalChanges}
+${destructiveList}
+${preview.hasDestructiveChanges ? '\n**This promotion includes destructive changes that will delete data from production.**' : ''}
+
+---
+**To promote these changes to production, use the Admin UI.**
+The Admin UI will show a confirmation dialog for destructive changes.`,
+                        },
+                    ],
+                };
+            }
             case 'get_database_schema': {
                 const databaseId = args.database_id;
                 const schema = await api.databases.schema(databaseId);
@@ -255,21 +387,21 @@ Use get_api_endpoints with database_id for full endpoint documentation.
                             text: `${result.message}
 
 ---
-**Store this PostgREST URL for this database:**
-- PostgREST URL: ${result.postgrestUrl}
-- Port: ${result.port}
+**PostgREST is now running:**
+- Direct URL (for MCP tools): ${result.postgrestUrl}
 - Status: ${result.status}
 
-This URL is used for direct REST API access to the database tables.
+**In the app, use the API_URL from config.js** (which reads from VITE_API_URL set by the build script).
 ---
 
 You can now use insert_rows, query_rows, update_rows, and delete_rows with this database.
 
-**NOTE FOR ASSISTANT:** The backend is now ready. If the user has a frontend app, help them start it:
-- For React/Vite: \`npm install\` then \`npm run dev\`
-- For Next.js: \`npm install\` then \`npm run dev\`
-- Offer to run these commands for them and explain what's happening
-- If errors occur, help debug and check query_logs for backend issues`,
+**NOTE FOR ASSISTANT:** The backend is now ready. If the user has a frontend app:
+- Ensure package.json has build:staging and build:production scripts
+- Ensure src/config.js exports API_URL from import.meta.env.VITE_API_URL
+- Run \`npm install\` then \`npm run dev\`
+- Offer to run these commands for them
+- If errors occur, check query_logs for backend issues`,
                         },
                     ],
                 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@daylight-labs/sharedb-mcp",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "MCP server for ShareDB schema management and development",
   "type": "module",
   "main": "./dist/index.js",