@daylight-labs/sharedb-mcp 0.1.0 → 0.1.2

package/dist/api-client.d.ts

@@ -75,7 +75,111 @@ export interface PostgRESTInfo {
     containerName?: string;
     startedAt?: string;
 }
+export interface LogEntry {
+    id: string;
+    database_id: string;
+    level: 'error' | 'debug';
+    message: string;
+    metadata: Record<string, unknown>;
+    source: 'admin-api' | 'admin-ui' | 'user-app' | 'postgrest';
+    request_id: string | null;
+    created_at: string;
+}
+export interface LogQueryOptions {
+    level?: string;
+    source?: string;
+    since?: string;
+    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[];
@@ -172,4 +276,20 @@ export declare const api: {
             helperFunction: string;
         }>;
     };
+    logs: {
+        query: (dbId: string, options?: LogQueryOptions) => Promise<{
+            logs: LogEntry[];
+            total: number;
+            limit: number;
+            offset: number;
+        }>;
+        get: (dbId: string, logId: string) => Promise<{
+            log: LogEntry;
+        }>;
+    };
 };
+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}`),
@@ -62,4 +75,41 @@ export const api = {
     auth: {
         config: () => request('/admin/auth/config'),
     },
+    logs: {
+        query: (dbId, options = {}) => {
+            const params = new URLSearchParams();
+            if (options.level)
+                params.append('level', options.level);
+            if (options.source)
+                params.append('source', options.source);
+            if (options.since)
+                params.append('since', options.since);
+            if (options.until)
+                params.append('until', options.until);
+            if (options.limit)
+                params.append('limit', options.limit.toString());
+            const query = params.toString();
+            return request(`/admin/databases/${dbId}/logs${query ? `?${query}` : ''}`);
+        },
+        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/config.js

@@ -1,5 +1,6 @@
+const domain = process.env.SHAREDB_DOMAIN;
 export const config = {
-    adminApiUrl: process.env.SHAREDB_API_URL || 'http://localhost:3002',
-    authApiUrl: process.env.SHAREDB_AUTH_URL || 'http://localhost:3000',
+    adminApiUrl: process.env.SHAREDB_API_URL || (domain ? `https://${domain}/api` : 'http://localhost:3002'),
+    authApiUrl: process.env.SHAREDB_AUTH_URL || (domain ? `https://${domain}/api` : 'http://localhost:3000'),
     token: process.env.SHAREDB_TOKEN || '',
 };

package/dist/index.js

@@ -6,6 +6,7 @@ import { schemaTools, handleSchemaTool } from './tools/schema.js';
 import { migrationTools, handleMigrationTool } from './tools/migrations.js';
 import { authTools, handleAuthTool } from './tools/auth.js';
 import { dataTools, handleDataTool } from './tools/data.js';
+import { logsTools, handleLogsTool } from './tools/logs.js';
 import { resources, readResource } from './resources/index.js';
 const server = new Server({
     name: 'sharedb',
@@ -16,7 +17,7 @@ const server = new Server({
         resources: {},
     },
 });
-const allTools = [...schemaTools, ...migrationTools, ...authTools, ...dataTools];
+const allTools = [...schemaTools, ...migrationTools, ...authTools, ...dataTools, ...logsTools];
 server.setRequestHandler(ListToolsRequestSchema, async () => {
     return { tools: allTools };
 });
@@ -38,6 +39,10 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     if (dataTool) {
         return handleDataTool(name, args || {});
     }
+    const logsTool = logsTools.find((t) => t.name === name);
+    if (logsTool) {
+        return handleLogsTool(name, args || {});
+    }
     return {
         content: [{ type: 'text', text: `Unknown tool: ${name}` }],
         isError: true,

package/dist/tools/auth.js

@@ -69,6 +69,11 @@ export async function handleAuthTool(name, args) {
                             logout: `POST ${config.authApiUrl}/auth/logout`,
                             me: `GET ${config.authApiUrl}/auth/me`,
                         },
+                        importantNotes: [
+                            'After login, store the accessToken and user object (contains user.id)',
+                            'Include accessToken in all API requests: Authorization: Bearer <accessToken>',
+                            'Use GET /auth/me to fetch current user if needed (returns { user: { id, email, name } })',
+                        ],
                     },
                     postgrest: {
                         baseUrl: postgrestUrl,
@@ -83,6 +88,36 @@ export async function handleAuthTool(name, args) {
                                 delete: `DELETE ${postgrestUrl}/<table>?id=eq.<uuid>`,
                             },
                         },
+                        importantNotes: [
+                            'CRITICAL: user_id is NOT automatically set! When creating records with a user_id column, the client MUST include user_id in the request body.',
+                            'Get the user ID from login response (user.id) or GET /auth/me, then include it: POST /todos { "title": "...", "user_id": "<user-id-from-auth>" }',
+                            'RLS policies filter BY user_id but do not SET it - the client must always send user_id explicitly.',
+                        ],
+                    },
+                    logging: {
+                        description: 'DEVELOPER DEBUGGING ONLY - Error and debug logging for app development. Use this to catch and debug errors during development. Logs are stored for 7 days and viewable in the admin UI. NOT for end-user analytics or production user tracking.',
+                        endpoint: `POST ${config.adminApiUrl}/logs`,
+                        authentication: 'None required (public endpoint, rate limited to 100/min per database)',
+                        requestBody: {
+                            database_id: '<your-database-uuid> (required)',
+                            level: '"error" | "debug" (required)',
+                            message: 'string (required)',
+                            metadata: 'object (optional) - additional context like stack traces, component names, etc.',
+                            source: '"user-app" (required for client apps)',
+                            request_id: 'string (optional) - for correlating related logs',
+                        },
+                        example: `fetch('${config.adminApiUrl}/logs', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({
+    database_id: '<your-database-uuid>',
+    level: 'error',
+    message: 'Failed to load user data',
+    metadata: { component: 'UserProfile', error: err.message, stack: err.stack },
+    source: 'user-app'
+  })
+})`,
+                        recommendation: 'Add to your global error handler (window.onerror, React error boundaries) during development to catch unhandled errors.',
                     },
                 };
                 return {

package/dist/tools/logs.d.ts

@@ -0,0 +1,66 @@
+export declare const logsTools: ({
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            database_id: {
+                type: string;
+                description: string;
+            };
+            level: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            source: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            since: {
+                type: string;
+                description: string;
+            };
+            until: {
+                type: string;
+                description: string;
+            };
+            limit: {
+                type: string;
+                description: string;
+            };
+            log_id?: undefined;
+        };
+        required: string[];
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            database_id: {
+                type: string;
+                description: string;
+            };
+            log_id: {
+                type: string;
+                description: string;
+            };
+            level?: undefined;
+            source?: undefined;
+            since?: undefined;
+            until?: undefined;
+            limit?: undefined;
+        };
+        required: string[];
+    };
+})[];
+export declare function handleLogsTool(name: string, args: Record<string, unknown>): Promise<{
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+    isError?: boolean;
+}>;

package/dist/tools/logs.js

@@ -0,0 +1,132 @@
+import { api } from '../api-client.js';
+export const logsTools = [
+    {
+        name: 'query_logs',
+        description: 'Query error and debug logs for a database. FOR DEVELOPER DEBUGGING ONLY - helps you debug issues during app development. View client-side errors, PostgREST API errors, or backend failures. Logs are retained for 7 days. Filter by source: "user-app" for client app errors, "postgrest" for API errors, "admin-api" for backend errors.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                database_id: {
+                    type: 'string',
+                    description: 'The database ID or name to query logs for',
+                },
+                level: {
+                    type: 'string',
+                    enum: ['error', 'debug'],
+                    description: 'Filter by log level',
+                },
+                source: {
+                    type: 'string',
+                    enum: ['admin-api', 'admin-ui', 'user-app', 'postgrest'],
+                    description: 'Filter by log source: user-app (client apps), postgrest (API errors), admin-api (backend), admin-ui (admin dashboard)',
+                },
+                since: {
+                    type: 'string',
+                    description: 'ISO 8601 datetime to filter logs after (e.g., "2024-01-01T00:00:00Z")',
+                },
+                until: {
+                    type: 'string',
+                    description: 'ISO 8601 datetime to filter logs before',
+                },
+                limit: {
+                    type: 'number',
+                    description: 'Maximum number of logs to return (default: 100, max: 1000)',
+                },
+            },
+            required: ['database_id'],
+        },
+    },
+    {
+        name: 'get_log_details',
+        description: 'Get full details of a specific log entry including all metadata (stack traces, request context, etc.).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                database_id: {
+                    type: 'string',
+                    description: 'The database ID or name',
+                },
+                log_id: {
+                    type: 'string',
+                    description: 'The log entry ID',
+                },
+            },
+            required: ['database_id', 'log_id'],
+        },
+    },
+];
+export async function handleLogsTool(name, args) {
+    try {
+        switch (name) {
+            case 'query_logs': {
+                const databaseId = args.database_id;
+                const level = args.level;
+                const source = args.source;
+                const since = args.since;
+                const until = args.until;
+                const limit = args.limit;
+                const result = await api.logs.query(databaseId, {
+                    level,
+                    source,
+                    since,
+                    until,
+                    limit,
+                });
+                if (result.logs.length === 0) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `No logs found for database "${databaseId}" with the specified filters.`,
+                            },
+                        ],
+                    };
+                }
+                const summary = result.logs.map((log) => ({
+                    id: log.id,
+                    level: log.level,
+                    source: log.source,
+                    message: log.message.substring(0, 200) + (log.message.length > 200 ? '...' : ''),
+                    created_at: log.created_at,
+                }));
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Found ${result.total} logs (showing ${result.logs.length}):\n\n${JSON.stringify(summary, null, 2)}`,
+                        },
+                    ],
+                };
+            }
+            case 'get_log_details': {
+                const databaseId = args.database_id;
+                const logId = args.log_id;
+                const result = await api.logs.get(databaseId, logId);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Log details:\n\n${JSON.stringify(result.log, null, 2)}`,
+                        },
+                    ],
+                };
+            }
+            default:
+                return {
+                    content: [{ type: 'text', text: `Unknown logs tool: ${name}` }],
+                    isError: true,
+                };
+        }
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Error: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+}

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,70 +128,161 @@ 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.
+---
+
+## Environment Configuration
+
+**Set up separate build scripts for staging and production deployments.**
+
+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 for your app
+## API Endpoints
 
-**Auth API** (${config.authApiUrl}):
+**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
-- 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>
 
+**CRITICAL - user_id handling:**
+- 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 \${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
+- Guide them step-by-step through running their app locally
+- If something fails, check logs with query_logs and explain the issue clearly`,
                         },
                     ],
                 };
             }
             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
@@ -185,7 +290,52 @@ Use the Database ID for all ShareDB tools (stage_change, apply_changes, insert_r
 **Auth API**: ${config.authApiUrl}
 **PostgREST API**: Each database has its own PostgREST instance (use start_postgrest to get the URL).
 
-Use get_api_endpoints with database_id for full endpoint documentation.`,
+Use get_api_endpoints with database_id for full endpoint documentation.
+
+---
+**NOTE FOR ASSISTANT:** ShareDB users are often non-technical builders. Proactively help them with technical tasks like running commands, starting dev servers, and debugging. Explain things in simple terms.`,
+                        },
+                    ],
+                };
+            }
+            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.`,
                         },
                     ],
                 };
@@ -237,15 +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.`,
+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:
+- 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.0",
+  "version": "0.1.2",
   "description": "MCP server for ShareDB schema management and development",
   "type": "module",
   "main": "./dist/index.js",