@daylight-labs/sharedb-mcp 0.1.0 → 0.1.1

package/dist/api-client.d.ts

@@ -75,6 +75,23 @@ 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 declare const api: {
     databases: {
         list: () => Promise<{
@@ -172,4 +189,15 @@ 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;
+        }>;
+    };
 };

package/dist/api-client.js

@@ -62,4 +62,22 @@ 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}`),
+    },
 };

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/schema.js

@@ -149,17 +149,32 @@ Use the Database ID for all subsequent ShareDB operations (stage_change, apply_c
 - 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
+- POST /<table> - Create row (IMPORTANT: include user_id in body if table has user_id column!)
 - PATCH /<table>?id=eq.<uuid> - Update row
 - 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 /todos { "title": "Buy milk", "user_id": "<id-from-login>" }
+- RLS policies filter BY user_id but don't SET it
+
 ## 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 PostgREST API
+
+---
+**NOTE FOR ASSISTANT:** ShareDB users are often non-technical builders who need guidance through technical steps. When helping them:
+- 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`,
                         },
                     ],
                 };
@@ -185,7 +200,10 @@ 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.`,
                         },
                     ],
                 };
@@ -245,7 +263,13 @@ Use get_api_endpoints with database_id for full endpoint documentation.`,
 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.`,
+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`,
                         },
                     ],
                 };

package/package.json

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