@daylight-labs/sharedb-mcp 0.1.0

package/dist/resources/index.js

@@ -0,0 +1,638 @@
+export const resources = [
+    {
+        uri: 'sharedb://getting-started',
+        name: 'ShareDB: Getting Started',
+        description: 'Overview of ShareDB - a managed PostgreSQL backend for apps. READ THIS FIRST when building an app that needs a database.',
+        mimeType: 'text/markdown',
+    },
+    {
+        uri: 'sharedb://rls-templates/row-ownership',
+        name: 'RLS Pattern: Row Ownership',
+        description: 'RLS policy pattern for user-owned rows',
+        mimeType: 'text/markdown',
+    },
+    {
+        uri: 'sharedb://rls-templates/public-read',
+        name: 'RLS Pattern: Public Read, Owner Write',
+        description: 'RLS policy pattern for public read access with owner-only write',
+        mimeType: 'text/markdown',
+    },
+    {
+        uri: 'sharedb://rls-templates/team-based',
+        name: 'RLS Pattern: Team-Based Access',
+        description: 'RLS policy pattern for team/organization-based access',
+        mimeType: 'text/markdown',
+    },
+    {
+        uri: 'sharedb://guides/auth-integration',
+        name: 'Auth Integration Guide',
+        description: 'How to integrate ShareDB authentication into your app',
+        mimeType: 'text/markdown',
+    },
+    {
+        uri: 'sharedb://guides/postgrest-usage',
+        name: 'PostgREST Usage Guide',
+        description: 'How to query data via PostgREST API',
+        mimeType: 'text/markdown',
+    },
+];
+const resourceContent = {
+    'sharedb://getting-started': `# ShareDB: Your App's Backend
+
+ShareDB is a managed PostgreSQL backend that provides everything you need to build data-driven applications.
+
+## What ShareDB Provides
+
+- **PostgreSQL Database**: A dedicated database for your app with full SQL support
+- **Authentication Service**: User registration, login, JWT tokens, and session management
+- **PostgREST API**: Automatic REST API generated from your database schema
+- **Row Level Security**: Built-in patterns for securing data with two role types:
+  - **Regular users**: App users who own their own data
+  - **Admins**: App builders who manage reference/shared data
+- **Schema Migrations**: Version-controlled database changes with rollback support
+
+## When to Use ShareDB
+
+Use ShareDB when building ANY app that needs:
+- Persistent data storage
+- A REST API for your frontend
+- User accounts and authentication (optional - works great for single-user personal apps too!)
+
+**Works for all app sizes**:
+- **Personal apps**: Budget trackers, habit trackers, personal wikis, journals - even single-user apps benefit from a real database
+- **Multi-user apps**: Todo apps, note-taking apps, project management tools, social apps, dashboards, CRMs
+
+## Quick Start
+
+### 1. Create a Database
+
+\`\`\`
+Use the create_database tool:
+- name: "my_app" (lowercase, underscores ok)
+- display_name: "My App"
+- environment: "development"
+\`\`\`
+
+### 2. Design Your Schema
+
+\`\`\`
+Use the stage_change tool to add tables:
+
+stage_change({
+  database_id: "my_app",
+  operation: "CREATE_TABLE",
+  params: {
+    tableName: "todos",
+    columns: [
+      { name: "id", type: "UUID", primaryKey: true, defaultValue: "uuid_generate_v4()" },
+      { name: "user_id", type: "UUID", nullable: false, defaultValue: "current_user_id()" },
+      { name: "title", type: "TEXT", nullable: false },
+      { name: "completed", type: "BOOLEAN", defaultValue: "false" },
+      { name: "created_at", type: "TIMESTAMPTZ", defaultValue: "NOW()" }
+    ]
+  }
+})
+\`\`\`
+
+### 3. Preview and Apply
+
+\`\`\`
+preview_changes({ database_id: "my_app" })
+apply_changes({ database_id: "my_app", description: "Add todos table" })
+\`\`\`
+
+### 4. Connect Your App
+
+Your app can now:
+- Authenticate users via \`/auth/login\`, \`/auth/register\`
+- Query data via PostgREST: \`GET /api/todos\`, \`POST /api/todos\`, etc.
+- Include the JWT in the Authorization header
+
+## Available Tools
+
+| Tool | Purpose |
+|------|---------|
+| \`create_database\` | Create a new app database |
+| \`list_databases\` | List all your databases |
+| \`get_database_schema\` | View tables, columns, indexes |
+| \`stage_change\` | Stage schema changes (CREATE_TABLE, ADD_COLUMN, etc.) |
+| \`preview_changes\` | See DDL before applying |
+| \`apply_changes\` | Apply staged changes as a migration |
+| \`rollback_migration\` | Undo the last migration |
+
+## Resources
+
+- \`sharedb://guides/auth-integration\` - How to add auth to your app
+- \`sharedb://guides/postgrest-usage\` - How to query data via REST
+- \`sharedb://rls-templates/*\` - Security patterns for multi-user apps
+`,
+    'sharedb://rls-templates/row-ownership': `# Row Ownership RLS Pattern
+
+This pattern restricts row access to the user who owns the row.
+
+## SQL Implementation
+
+\`\`\`sql
+-- Enable RLS on the table
+ALTER TABLE your_table ENABLE ROW LEVEL SECURITY;
+
+-- Create policy for user-owned rows
+CREATE POLICY user_owns_row ON your_table
+  FOR ALL
+  USING (user_id = current_user_id());
+\`\`\`
+
+## Usage
+
+1. Ensure your table has a \`user_id\` column of type UUID
+2. The \`current_user_id()\` function extracts the user ID from the JWT claims
+3. Users can only see/modify rows where \`user_id\` matches their ID
+
+## Example Table
+
+\`\`\`sql
+CREATE TABLE todos (
+  id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
+  user_id UUID NOT NULL DEFAULT current_user_id(),
+  title TEXT NOT NULL,
+  completed BOOLEAN DEFAULT FALSE,
+  created_at TIMESTAMPTZ DEFAULT NOW()
+);
+
+ALTER TABLE todos ENABLE ROW LEVEL SECURITY;
+
+CREATE POLICY todos_user_isolation ON todos
+  FOR ALL
+  USING (user_id = current_user_id());
+\`\`\`
+`,
+    'sharedb://rls-templates/public-read': `# Public Read, Owner Write RLS Pattern
+
+This pattern allows anyone to read rows but only the owner can modify them.
+
+## SQL Implementation
+
+\`\`\`sql
+ALTER TABLE your_table ENABLE ROW LEVEL SECURITY;
+
+-- Anyone can read
+CREATE POLICY public_read ON your_table
+  FOR SELECT
+  USING (true);
+
+-- Only owner can insert
+CREATE POLICY owner_insert ON your_table
+  FOR INSERT
+  WITH CHECK (user_id = current_user_id());
+
+-- Only owner can update
+CREATE POLICY owner_update ON your_table
+  FOR UPDATE
+  USING (user_id = current_user_id())
+  WITH CHECK (user_id = current_user_id());
+
+-- Only owner can delete
+CREATE POLICY owner_delete ON your_table
+  FOR DELETE
+  USING (user_id = current_user_id());
+\`\`\`
+
+## Example: Blog Posts
+
+\`\`\`sql
+CREATE TABLE posts (
+  id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
+  user_id UUID NOT NULL DEFAULT current_user_id(),
+  title TEXT NOT NULL,
+  content TEXT NOT NULL,
+  published BOOLEAN DEFAULT FALSE,
+  created_at TIMESTAMPTZ DEFAULT NOW()
+);
+
+ALTER TABLE posts ENABLE ROW LEVEL SECURITY;
+
+-- Public can read published posts
+CREATE POLICY posts_public_read ON posts
+  FOR SELECT
+  USING (published = true OR user_id = current_user_id());
+
+-- Author can insert
+CREATE POLICY posts_author_insert ON posts
+  FOR INSERT
+  WITH CHECK (user_id = current_user_id());
+
+-- Author can update own posts
+CREATE POLICY posts_author_update ON posts
+  FOR UPDATE
+  USING (user_id = current_user_id());
+
+-- Author can delete own posts
+CREATE POLICY posts_author_delete ON posts
+  FOR DELETE
+  USING (user_id = current_user_id());
+\`\`\`
+`,
+    'sharedb://rls-templates/team-based': `# Team-Based Access RLS Pattern
+
+This pattern restricts access based on team/organization membership.
+
+## Required Tables
+
+\`\`\`sql
+-- Teams table
+CREATE TABLE teams (
+  id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
+  name TEXT NOT NULL,
+  created_at TIMESTAMPTZ DEFAULT NOW()
+);
+
+-- Team memberships
+CREATE TABLE team_members (
+  id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
+  team_id UUID NOT NULL REFERENCES teams(id) ON DELETE CASCADE,
+  user_id UUID NOT NULL,
+  role TEXT NOT NULL DEFAULT 'member',
+  created_at TIMESTAMPTZ DEFAULT NOW(),
+  UNIQUE(team_id, user_id)
+);
+\`\`\`
+
+## Helper Function
+
+\`\`\`sql
+CREATE OR REPLACE FUNCTION user_team_ids()
+RETURNS UUID[] AS $$
+  SELECT COALESCE(
+    ARRAY_AGG(team_id),
+    ARRAY[]::UUID[]
+  )
+  FROM team_members
+  WHERE user_id = current_user_id();
+$$ LANGUAGE sql STABLE;
+\`\`\`
+
+## Team Resource Policy
+
+\`\`\`sql
+CREATE TABLE projects (
+  id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
+  team_id UUID NOT NULL REFERENCES teams(id),
+  name TEXT NOT NULL,
+  created_at TIMESTAMPTZ DEFAULT NOW()
+);
+
+ALTER TABLE projects ENABLE ROW LEVEL SECURITY;
+
+-- Team members can access their team's projects
+CREATE POLICY projects_team_access ON projects
+  FOR ALL
+  USING (team_id = ANY(user_team_ids()));
+\`\`\`
+`,
+    'sharedb://guides/auth-integration': `# ShareDB Auth Integration Guide
+
+This guide explains how to integrate ShareDB authentication into your app.
+
+## Overview
+
+ShareDB provides a centralized authentication service that issues JWTs. Your app:
+1. Collects user credentials (email/password or OAuth)
+2. Calls ShareDB auth endpoints
+3. Stores the returned tokens
+4. Includes the access token in PostgREST requests
+
+## Authentication Flow
+
+\`\`\`
+┌──────────────────┐         ┌──────────────────┐
+│   Your App       │         │  ShareDB Auth    │
+└────────┬─────────┘         └────────┬─────────┘
+         │                            │
+         │ 1. POST /auth/login        │
+         │ { email, password }        │
+         │───────────────────────────>│
+         │                            │
+         │ 2. { accessToken,          │
+         │      refreshToken }        │
+         │<───────────────────────────│
+         │                            │
+         │ Store tokens locally       │
+         │                            │
+         │ 3. GET /api/todos          │
+         │ Authorization: Bearer ...  │
+         │───────────────────────────>│ PostgREST
+         │                            │
+         │ 4. [ user's todos ]        │
+         │<───────────────────────────│
+         │                            │
+\`\`\`
+
+## Auth Endpoints
+
+### Register
+\`\`\`
+POST /auth/register
+Content-Type: application/json
+
+{
+  "email": "user@example.com",
+  "password": "secure-password",
+  "name": "John Doe"
+}
+
+Response: { accessToken, refreshToken, user }
+\`\`\`
+
+### Login
+\`\`\`
+POST /auth/login
+Content-Type: application/json
+
+{
+  "email": "user@example.com",
+  "password": "secure-password"
+}
+
+Response: { accessToken, refreshToken, user }
+\`\`\`
+
+### Refresh Token
+\`\`\`
+POST /auth/refresh
+Content-Type: application/json
+
+{
+  "refreshToken": "..."
+}
+
+Response: { accessToken, refreshToken }
+\`\`\`
+
+### Get Current User
+\`\`\`
+GET /auth/me
+Authorization: Bearer <accessToken>
+
+Response: { id, email, name, ... }
+\`\`\`
+
+## React Example
+
+\`\`\`tsx
+import { useState, createContext, useContext } from 'react';
+
+interface AuthContext {
+  user: User | null;
+  login: (email: string, password: string) => Promise<void>;
+  logout: () => void;
+  getToken: () => string | null;
+}
+
+const AuthContext = createContext<AuthContext | null>(null);
+
+export function AuthProvider({ children }) {
+  const [user, setUser] = useState<User | null>(null);
+  const [accessToken, setAccessToken] = useState<string | null>(
+    localStorage.getItem('accessToken')
+  );
+
+  async function login(email: string, password: string) {
+    const res = await fetch('/auth/login', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ email, password }),
+    });
+
+    if (!res.ok) throw new Error('Login failed');
+
+    const { accessToken, refreshToken, user } = await res.json();
+    localStorage.setItem('accessToken', accessToken);
+    localStorage.setItem('refreshToken', refreshToken);
+    setAccessToken(accessToken);
+    setUser(user);
+  }
+
+  function logout() {
+    localStorage.removeItem('accessToken');
+    localStorage.removeItem('refreshToken');
+    setAccessToken(null);
+    setUser(null);
+  }
+
+  function getToken() {
+    return accessToken;
+  }
+
+  return (
+    <AuthContext.Provider value={{ user, login, logout, getToken }}>
+      {children}
+    </AuthContext.Provider>
+  );
+}
+
+export function useAuth() {
+  const ctx = useContext(AuthContext);
+  if (!ctx) throw new Error('useAuth must be used within AuthProvider');
+  return ctx;
+}
+\`\`\`
+
+## Making Authenticated API Requests
+
+\`\`\`tsx
+function useFetch() {
+  const { getToken } = useAuth();
+
+  return async function fetchWithAuth(url: string, options?: RequestInit) {
+    const token = getToken();
+    return fetch(url, {
+      ...options,
+      headers: {
+        ...options?.headers,
+        Authorization: \`Bearer \${token}\`,
+      },
+    });
+  };
+}
+\`\`\`
+`,
+    'sharedb://guides/postgrest-usage': `# PostgREST Usage Guide
+
+PostgREST automatically generates a REST API from your PostgreSQL schema.
+
+## Base URL
+
+Your app's PostgREST endpoint is:
+\`\`\`
+https://your-app.sharedb.example.com/api
+\`\`\`
+
+## Authentication
+
+Include the JWT in the Authorization header:
+\`\`\`
+Authorization: Bearer <your-jwt-token>
+\`\`\`
+
+## Basic CRUD Operations
+
+### Read All Rows
+\`\`\`
+GET /api/todos
+
+Response: [{ id, title, completed, ... }, ...]
+\`\`\`
+
+### Read Single Row
+\`\`\`
+GET /api/todos?id=eq.uuid-here
+
+Response: [{ id, title, completed, ... }]
+\`\`\`
+
+### Create Row
+\`\`\`
+POST /api/todos
+Content-Type: application/json
+
+{ "title": "New todo", "completed": false }
+
+Response: { id, title, completed, ... }
+\`\`\`
+
+### Update Row
+\`\`\`
+PATCH /api/todos?id=eq.uuid-here
+Content-Type: application/json
+
+{ "completed": true }
+
+Response: { id, title, completed, ... }
+\`\`\`
+
+### Delete Row
+\`\`\`
+DELETE /api/todos?id=eq.uuid-here
+\`\`\`
+
+## Filtering
+
+PostgREST supports powerful filtering:
+
+| Operator | Meaning | Example |
+|----------|---------|---------|
+| eq | equals | \`?status=eq.active\` |
+| neq | not equals | \`?status=neq.deleted\` |
+| gt | greater than | \`?price=gt.100\` |
+| gte | greater or equal | \`?price=gte.100\` |
+| lt | less than | \`?price=lt.50\` |
+| lte | less or equal | \`?price=lte.50\` |
+| like | pattern match | \`?title=like.*foo*\` |
+| ilike | case-insensitive | \`?title=ilike.*foo*\` |
+| in | in list | \`?status=in.(active,pending)\` |
+| is | is null/true/false | \`?deleted=is.null\` |
+
+## Ordering
+
+\`\`\`
+GET /api/todos?order=created_at.desc
+GET /api/todos?order=priority.asc,created_at.desc
+\`\`\`
+
+## Pagination
+
+\`\`\`
+GET /api/todos?limit=10&offset=0
+\`\`\`
+
+## Selecting Columns
+
+\`\`\`
+GET /api/todos?select=id,title,completed
+\`\`\`
+
+## Embedding Related Data
+
+If you have foreign key relationships:
+
+\`\`\`
+GET /api/todos?select=*,user:users(name,email)
+\`\`\`
+
+## JavaScript Client Example
+
+\`\`\`javascript
+class PostgRESTClient {
+  constructor(baseUrl, getToken) {
+    this.baseUrl = baseUrl;
+    this.getToken = getToken;
+  }
+
+  async request(path, options = {}) {
+    const response = await fetch(\`\${this.baseUrl}\${path}\`, {
+      ...options,
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: \`Bearer \${this.getToken()}\`,
+        ...options.headers,
+      },
+    });
+
+    if (!response.ok) {
+      throw new Error(\`API error: \${response.status}\`);
+    }
+
+    return response.json();
+  }
+
+  async list(table, params = {}) {
+    const query = new URLSearchParams(params).toString();
+    return this.request(\`/\${table}?\${query}\`);
+  }
+
+  async get(table, id) {
+    const [row] = await this.request(\`/\${table}?id=eq.\${id}\`);
+    return row;
+  }
+
+  async create(table, data) {
+    return this.request(\`/\${table}\`, {
+      method: 'POST',
+      body: JSON.stringify(data),
+      headers: { Prefer: 'return=representation' },
+    });
+  }
+
+  async update(table, id, data) {
+    return this.request(\`/\${table}?id=eq.\${id}\`, {
+      method: 'PATCH',
+      body: JSON.stringify(data),
+      headers: { Prefer: 'return=representation' },
+    });
+  }
+
+  async delete(table, id) {
+    return this.request(\`/\${table}?id=eq.\${id}\`, {
+      method: 'DELETE',
+    });
+  }
+}
+\`\`\`
+`,
+};
+export function readResource(uri) {
+    const content = resourceContent[uri];
+    if (!content) {
+        throw new Error(`Resource not found: ${uri}`);
+    }
+    const resource = resources.find((r) => r.uri === uri);
+    return {
+        contents: [
+            {
+                uri,
+                mimeType: resource?.mimeType || 'text/plain',
+                text: content,
+            },
+        ],
+    };
+}

package/dist/tools/auth.d.ts

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