@daylight-labs/sharedb-mcp 0.1.0

package/dist/tools/migrations.js

@@ -0,0 +1,272 @@
+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',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                database_id: {
+                    type: 'string',
+                    description: 'The database ID or name',
+                },
+                operation: {
+                    type: 'string',
+                    enum: [
+                        'CREATE_TABLE',
+                        'DROP_TABLE',
+                        'RENAME_TABLE',
+                        'ADD_COLUMN',
+                        'DROP_COLUMN',
+                        'RENAME_COLUMN',
+                        'ADD_INDEX',
+                        'ADD_RLS_POLICY',
+                    ],
+                    description: 'The type of schema change',
+                },
+                params: {
+                    type: 'object',
+                    description: `Parameters for the operation:
+- CREATE_TABLE: { tableName, columns: [{ name, type, nullable?, defaultValue?, primaryKey? }], enableRls?: true, userIdColumn?: "user_id" }
+- ADD_COLUMN: { tableName, columnName, type, nullable?, defaultValue? }
+- ADD_INDEX: { tableName, indexName, columns: [...], unique? }
+- ADD_RLS_POLICY: Row Level Security policy. Two role types exist:
+  * Regular users: authenticated app users
+  * Admins: app builders who manage reference data
+
+  Common patterns:
+  1. User-owned data (e.g., user's workouts): { tableName, policyName, userIdColumn: "user_id" }
+  2. Admin-managed reference data (e.g., exercise library): Users can READ, only admins can INSERT/UPDATE/DELETE:
+     - First: { tableName, policyName: "table_read", command: "SELECT", using: "true" }
+     - Then: { tableName, policyName: "table_admin_write", command: "INSERT", using: "public.current_user_is_admin()" }
+     - And: { tableName, policyName: "table_admin_update", command: "UPDATE", using: "public.current_user_is_admin()" }
+     - And: { tableName, policyName: "table_admin_delete", command: "DELETE", using: "public.current_user_is_admin()" }
+  3. Custom: { tableName, policyName, command: "ALL"|"SELECT"|"INSERT"|"UPDATE"|"DELETE", using: "SQL expression", withCheck?: "SQL expression" }`,
+                },
+            },
+            required: ['database_id', 'operation', 'params'],
+        },
+    },
+    {
+        name: 'list_staged_changes',
+        description: 'List all staged (pending) schema changes for a database',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                database_id: {
+                    type: 'string',
+                    description: 'The database ID or name',
+                },
+            },
+            required: ['database_id'],
+        },
+    },
+    {
+        name: 'preview_changes',
+        description: 'Preview the DDL statements that will be executed when applying staged changes',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                database_id: {
+                    type: 'string',
+                    description: 'The database ID or name',
+                },
+            },
+            required: ['database_id'],
+        },
+    },
+    {
+        name: 'apply_changes',
+        description: 'Apply all staged changes as a migration. This executes the DDL on the database.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                database_id: {
+                    type: 'string',
+                    description: 'The database ID or name',
+                },
+                description: {
+                    type: 'string',
+                    description: 'Optional description for the migration',
+                },
+            },
+            required: ['database_id'],
+        },
+    },
+    {
+        name: 'unstage_change',
+        description: 'Remove a staged change before it is applied',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                database_id: {
+                    type: 'string',
+                    description: 'The database ID or name',
+                },
+                change_id: {
+                    type: 'string',
+                    description: 'The ID of the staged change to remove',
+                },
+            },
+            required: ['database_id', 'change_id'],
+        },
+    },
+    {
+        name: 'get_migration_history',
+        description: 'List all applied migrations for a database',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                database_id: {
+                    type: 'string',
+                    description: 'The database ID or name',
+                },
+            },
+            required: ['database_id'],
+        },
+    },
+    {
+        name: 'rollback_migration',
+        description: 'Roll back a migration if it is reversible. Only the most recent migration can be rolled back.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                database_id: {
+                    type: 'string',
+                    description: 'The database ID or name',
+                },
+                migration_id: {
+                    type: 'string',
+                    description: 'The ID of the migration to roll back',
+                },
+            },
+            required: ['database_id', 'migration_id'],
+        },
+    },
+];
+export async function handleMigrationTool(name, args) {
+    try {
+        switch (name) {
+            case 'stage_change': {
+                const databaseId = args.database_id;
+                const operation = args.operation;
+                const params = args.params;
+                const { staged } = await api.changes.stage(databaseId, operation, params);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Staged ${staged.length} change(s):\n${JSON.stringify(staged, null, 2)}`,
+                        },
+                    ],
+                };
+            }
+            case 'list_staged_changes': {
+                const databaseId = args.database_id;
+                const { changes } = await api.changes.list(databaseId);
+                if (changes.length === 0) {
+                    return {
+                        content: [{ type: 'text', text: 'No staged changes' }],
+                    };
+                }
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify(changes, null, 2),
+                        },
+                    ],
+                };
+            }
+            case 'preview_changes': {
+                const databaseId = args.database_id;
+                const result = await api.changes.preview(databaseId);
+                if (!result.preview) {
+                    return {
+                        content: [{ type: 'text', text: result.message || 'No staged changes to preview' }],
+                    };
+                }
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Preview of ${result.preview.changeCount} changes:\n\nDDL to execute:\n${result.preview.ddlStatements.join(';\n\n')};\n\nHas irreversible changes: ${result.preview.hasIrreversibleChanges}`,
+                        },
+                    ],
+                };
+            }
+            case 'apply_changes': {
+                const databaseId = args.database_id;
+                const description = args.description;
+                const { migration } = await api.changes.apply(databaseId, description);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Migration v${migration.version} applied successfully!\n\n${JSON.stringify(migration, null, 2)}`,
+                        },
+                    ],
+                };
+            }
+            case 'unstage_change': {
+                const databaseId = args.database_id;
+                const changeId = args.change_id;
+                const { deleted } = await api.changes.unstage(databaseId, changeId);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Unstaged change: ${deleted.change_type} on ${deleted.table_name}`,
+                        },
+                    ],
+                };
+            }
+            case 'get_migration_history': {
+                const databaseId = args.database_id;
+                const { migrations } = await api.migrations.list(databaseId);
+                if (migrations.length === 0) {
+                    return {
+                        content: [{ type: 'text', text: 'No migrations applied yet' }],
+                    };
+                }
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify(migrations, null, 2),
+                        },
+                    ],
+                };
+            }
+            case 'rollback_migration': {
+                const databaseId = args.database_id;
+                const migrationId = args.migration_id;
+                const { rolledBack } = await api.migrations.rollback(databaseId, migrationId);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Rolled back migration v${rolledBack.version}, reverted ${rolledBack.changesReverted} changes`,
+                        },
+                    ],
+                };
+            }
+            default:
+                return {
+                    content: [{ type: 'text', text: `Unknown migration tool: ${name}` }],
+                    isError: true,
+                };
+        }
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Error: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+}

package/dist/tools/schema.d.ts

@@ -0,0 +1,83 @@
+export declare const schemaTools: ({
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            name: {
+                type: string;
+                description: string;
+            };
+            display_name: {
+                type: string;
+                description: string;
+            };
+            environment: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            database_id?: undefined;
+            table_name?: undefined;
+        };
+        required: string[];
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            name?: undefined;
+            display_name?: undefined;
+            environment?: undefined;
+            database_id?: undefined;
+            table_name?: undefined;
+        };
+        required: never[];
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            database_id: {
+                type: string;
+                description: string;
+            };
+            name?: undefined;
+            display_name?: undefined;
+            environment?: undefined;
+            table_name?: undefined;
+        };
+        required: string[];
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            database_id: {
+                type: string;
+                description: string;
+            };
+            table_name: {
+                type: string;
+                description: string;
+            };
+            name?: undefined;
+            display_name?: undefined;
+            environment?: undefined;
+        };
+        required: string[];
+    };
+})[];
+export declare function handleSchemaTool(name: string, args: Record<string, unknown>): Promise<{
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+    isError?: boolean;
+}>;

package/dist/tools/schema.js

@@ -0,0 +1,289 @@
+import { api } from '../api-client.js';
+import { config } from '../config.js';
+export const schemaTools = [
+    {
+        name: 'create_database',
+        description: 'Create a new app database in ShareDB. THIS IS THE FIRST STEP when building any app that needs a backend - from personal single-user apps to multi-user platforms. ShareDB provides PostgreSQL + Auth + REST API. After creating, use stage_change to add tables.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                name: {
+                    type: 'string',
+                    description: 'The database name (lowercase, underscores allowed, e.g., "my_app" or "todo_list")',
+                },
+                display_name: {
+                    type: 'string',
+                    description: 'A human-readable display name (e.g., "My App" or "Todo List")',
+                },
+                environment: {
+                    type: 'string',
+                    enum: ['development', 'staging', 'production'],
+                    description: 'The environment for this database (default: development)',
+                },
+            },
+            required: ['name', 'display_name'],
+        },
+    },
+    {
+        name: 'list_databases',
+        description: 'List all app databases in ShareDB',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+            required: [],
+        },
+    },
+    {
+        name: 'get_database_schema',
+        description: 'Get the full schema for a database, including all tables, columns, indexes, constraints, RLS policies, and functions',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                database_id: {
+                    type: 'string',
+                    description: 'The database ID or name',
+                },
+            },
+            required: ['database_id'],
+        },
+    },
+    {
+        name: 'get_table_details',
+        description: 'Get detailed information about a specific table, including columns, indexes, constraints, and RLS policies',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                database_id: {
+                    type: 'string',
+                    description: 'The database ID or name',
+                },
+                table_name: {
+                    type: 'string',
+                    description: 'The name of the table',
+                },
+            },
+            required: ['database_id', 'table_name'],
+        },
+    },
+    {
+        name: 'get_rls_policies',
+        description: 'List all RLS (Row Level Security) policies for a database',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                database_id: {
+                    type: 'string',
+                    description: 'The database ID or name',
+                },
+            },
+            required: ['database_id'],
+        },
+    },
+    {
+        name: 'start_postgrest',
+        description: 'Start the PostgREST API server for a database. This enables the REST API endpoints for data access. Required before using insert_rows, query_rows, etc.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                database_id: {
+                    type: 'string',
+                    description: 'The database ID or name',
+                },
+            },
+            required: ['database_id'],
+        },
+    },
+    {
+        name: 'restart_postgrest',
+        description: 'Restart the PostgREST API server for a database. Use this after schema changes to refresh the API, or if PostgREST is in a bad state.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                database_id: {
+                    type: 'string',
+                    description: 'The database ID or name',
+                },
+            },
+            required: ['database_id'],
+        },
+    },
+];
+export async function handleSchemaTool(name, args) {
+    try {
+        switch (name) {
+            case 'create_database': {
+                const dbName = args.name;
+                const displayName = args.display_name;
+                const environment = args.environment || 'development';
+                const { database } = await api.databases.create({
+                    name: dbName,
+                    displayName,
+                    environment,
+                });
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Database "${database.display_name}" created successfully!
+
+---
+**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}
+- Auth API: ${config.authApiUrl}
+
+Use the Database ID for all subsequent ShareDB operations (stage_change, apply_changes, insert_rows, etc.)
+---
+
+## API Endpoints for your app
+
+**Auth API** (${config.authApiUrl}):
+- 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
+- GET /<table> - List rows
+- GET /<table>?id=eq.<uuid> - Get single row
+- POST /<table> - Create row
+- PATCH /<table>?id=eq.<uuid> - Update row
+- DELETE /<table>?id=eq.<uuid> - Delete row
+- Include header: Authorization: Bearer <accessToken>
+
+## 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`,
+                        },
+                    ],
+                };
+            }
+            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');
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `## ShareDB Databases
+
+${databases.length === 0 ? '_No databases yet. Use create_database to create one._' : dbList}
+
+---
+**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.)
+---
+
+## API Endpoints
+
+**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.`,
+                        },
+                    ],
+                };
+            }
+            case 'get_database_schema': {
+                const databaseId = args.database_id;
+                const schema = await api.databases.schema(databaseId);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify(schema, null, 2),
+                        },
+                    ],
+                };
+            }
+            case 'get_table_details': {
+                const databaseId = args.database_id;
+                const tableName = args.table_name;
+                const details = await api.databases.tableDetails(databaseId, tableName);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify(details, null, 2),
+                        },
+                    ],
+                };
+            }
+            case 'get_rls_policies': {
+                const databaseId = args.database_id;
+                const { policies } = await api.databases.rlsPolicies(databaseId);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify(policies, null, 2),
+                        },
+                    ],
+                };
+            }
+            case 'start_postgrest': {
+                const databaseId = args.database_id;
+                const result = await api.databases.startPostgrest(databaseId);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `${result.message}
+
+---
+**Store this PostgREST URL for this database:**
+- PostgREST URL: ${result.postgrestUrl}
+- Port: ${result.port}
+- Status: ${result.status}
+
+This URL is used for direct REST API access to the database tables.
+---
+
+You can now use insert_rows, query_rows, update_rows, and delete_rows with this database.`,
+                        },
+                    ],
+                };
+            }
+            case 'restart_postgrest': {
+                const databaseId = args.database_id;
+                const result = await api.databases.restartPostgrest(databaseId);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `${result.message}
+
+PostgREST URL: ${result.postgrestUrl}
+Port: ${result.port}
+Status: ${result.status}
+
+The PostgREST API has been restarted and should now reflect any recent schema changes.`,
+                        },
+                    ],
+                };
+            }
+            default:
+                return {
+                    content: [{ type: 'text', text: `Unknown schema tool: ${name}` }],
+                    isError: true,
+                };
+        }
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Error: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@daylight-labs/sharedb-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for ShareDB schema management and development",
+  "type": "module",
+  "main": "./dist/index.js",
+  "bin": {
+    "sharedb-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "dev": "tsx watch src/index.ts",
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "sharedb",
+    "postgresql",
+    "database",
+    "schema"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.10",
+    "tsx": "^4.16.2",
+    "typescript": "^5.5.3"
+  }
+}