@lobsterkit/openclaw-lobsterdb 0.2.0

package/index.ts

@@ -0,0 +1,215 @@
+import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
+import { Type } from "@sinclair/typebox";
+import { LobsterDB } from "@lobsterkit/db";
+
+let client: LobsterDB | null = null;
+
+function getClient(apiKey?: string): LobsterDB {
+  if (!client) {
+    client = new LobsterDB(apiKey ? { apiKey } : undefined);
+  }
+  return client;
+}
+
+export default definePluginEntry({
+  id: "lobsterdb",
+  name: "LobsterDB",
+  description:
+    "Managed PostgreSQL for AI agents. Provision databases, run SQL, evolve schemas. No API keys, no human signup.",
+
+  register(api) {
+    const cfg = api.config as { apiKey?: string } | undefined;
+    const db = () => getClient(cfg?.apiKey);
+
+    // ── create_database ──────────────────────────────────────────
+    api.registerTool({
+      name: "lobsterdb_create_database",
+      description: "Provision a new PostgreSQL database.",
+      parameters: Type.Object({
+        name: Type.String({ description: "Database name (alphanumeric + hyphens)" }),
+      }),
+      async execute(_id, params) {
+        const result = await db().create(params.name);
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Database created.\n\nID: ${result.id}\nName: ${params.name}\nConnection: ${result.connectionString}`,
+            },
+          ],
+        };
+      },
+    });
+
+    // ── list_databases ───────────────────────────────────────────
+    api.registerTool({
+      name: "lobsterdb_list_databases",
+      description: "List all databases on this account.",
+      parameters: Type.Object({}),
+      async execute() {
+        const databases = await db().list();
+        if (databases.length === 0) {
+          return {
+            content: [{ type: "text", text: "No databases. Use lobsterdb_create_database to create one." }],
+          };
+        }
+        const lines = databases.map((d) => `- [${d.id}] ${d.name}`);
+        return {
+          content: [{ type: "text", text: `${databases.length} database(s):\n\n${lines.join("\n")}` }],
+        };
+      },
+    });
+
+    // ── get_database ─────────────────────────────────────────────
+    api.registerTool({
+      name: "lobsterdb_get_database",
+      description: "Get database details and connection string.",
+      parameters: Type.Object({
+        database_id: Type.String({ description: "Database ID (e.g. db_...)" }),
+      }),
+      async execute(_id, params) {
+        const result = await db().get(params.database_id);
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Database: ${result.name}\nID: ${result.id}\nConnection: ${result.connectionString}`,
+            },
+          ],
+        };
+      },
+    });
+
+    // ── delete_database ──────────────────────────────────────────
+    api.registerTool({
+      name: "lobsterdb_delete_database",
+      description: "Permanently delete a database.",
+      parameters: Type.Object({
+        database_id: Type.String({ description: "Database ID to delete" }),
+      }),
+      async execute(_id, params) {
+        await db().delete(params.database_id);
+        return {
+          content: [{ type: "text", text: `Database ${params.database_id} deleted.` }],
+        };
+      },
+    });
+
+    // ── query ────────────────────────────────────────────────────
+    api.registerTool({
+      name: "lobsterdb_query",
+      description: "Run a parameterized SQL query against a database.",
+      parameters: Type.Object({
+        database_id: Type.String({ description: "Database ID" }),
+        sql: Type.String({ description: "SQL query (use $1, $2 for params)" }),
+        params: Type.Optional(Type.Array(Type.Unknown(), { description: "Query parameters" })),
+      }),
+      async execute(_id, params) {
+        const result = await db().query(params.database_id, params.sql, params.params ?? []);
+        const preview = result.rows.slice(0, 50);
+        return {
+          content: [
+            {
+              type: "text",
+              text: `${result.rowCount ?? 0} row(s)${result.truncated ? " (truncated)" : ""}:\n\n${JSON.stringify(preview, null, 2)}`,
+            },
+          ],
+        };
+      },
+    });
+
+    // ── introspect_schema ────────────────────────────────────────
+    api.registerTool({
+      name: "lobsterdb_introspect_schema",
+      description: "Get database schema optimized for LLM context. Always call before writing queries.",
+      parameters: Type.Object({
+        database_id: Type.String({ description: "Database ID" }),
+      }),
+      async execute(_id, params) {
+        const result = await db().introspect(params.database_id);
+        return {
+          content: [
+            {
+              type: "text",
+              text: `${result.tableCount} table(s):\n\n${result.schemaText}`,
+            },
+          ],
+        };
+      },
+    });
+
+    // ── migrate ──────────────────────────────────────────────────
+    api.registerTool({
+      name: "lobsterdb_migrate",
+      description: "Apply a tracked, idempotent DDL migration. Use for all schema changes (CREATE TABLE, ALTER, etc.).",
+      parameters: Type.Object({
+        database_id: Type.String({ description: "Database ID" }),
+        name: Type.String({ description: "Migration name (e.g. create_tasks_table)" }),
+        sql: Type.String({ description: "DDL SQL to execute" }),
+      }),
+      async execute(_id, params) {
+        const result = await db().migrate(params.database_id, params.name, params.sql);
+        return {
+          content: [{ type: "text", text: `Migration "${params.name}": ${result.applied ? "applied" : "already applied (skipped)"}` }],
+        };
+      },
+    });
+
+    // ── list_migrations ──────────────────────────────────────────
+    api.registerTool({
+      name: "lobsterdb_list_migrations",
+      description: "Show schema change history for a database.",
+      parameters: Type.Object({
+        database_id: Type.String({ description: "Database ID" }),
+      }),
+      async execute(_id, params) {
+        const migrations = await db().listMigrations(params.database_id);
+        if (migrations.length === 0) {
+          return { content: [{ type: "text", text: "No migrations applied yet." }] };
+        }
+        const lines = migrations.map((m) => `- ${m.name} (${m.appliedAt})`);
+        return {
+          content: [{ type: "text", text: `${migrations.length} migration(s):\n\n${lines.join("\n")}` }],
+        };
+      },
+    });
+
+    // ── snapshot ─────────────────────────────────────────────────
+    api.registerTool({
+      name: "lobsterdb_snapshot",
+      description: "Create a point-in-time backup (Builder+ tier).",
+      parameters: Type.Object({
+        database_id: Type.String({ description: "Database ID" }),
+      }),
+      async execute(_id, params) {
+        const result = await db().snapshot(params.database_id);
+        return {
+          content: [{ type: "text", text: `Snapshot created.\n\nID: ${result.id}\nCreated: ${result.createdAt}` }],
+        };
+      },
+    });
+
+    // ── get_account ──────────────────────────────────────────────
+    api.registerTool({
+      name: "lobsterdb_get_account",
+      description: "Get account info: tier, limits, usage.",
+      parameters: Type.Object({}),
+      async execute() {
+        const acct = await db().account();
+        return {
+          content: [
+            {
+              type: "text",
+              text: [
+                `Account: ${acct.id}`,
+                `Tier: ${acct.tier} (${acct.tierName})`,
+                `Max databases: ${acct.limits.maxDatabases ?? "unlimited"}`,
+                `Databases used: ${acct.usage.databaseCount}`,
+              ].join("\n"),
+            },
+          ],
+        };
+      },
+    });
+  },
+});

package/openclaw.plugin.json

@@ -0,0 +1,25 @@
+{
+  "id": "lobsterdb",
+  "name": "LobsterDB",
+  "description": "Managed PostgreSQL for AI agents. Provision databases, run SQL, evolve schemas. No API keys, no human signup.",
+  "version": "0.2.0",
+  "skills": ["./skills"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "apiKey": {
+        "type": "string",
+        "description": "LobsterDB API key (optional — auto-signup on first use if omitted)"
+      }
+    }
+  },
+  "uiHints": {
+    "apiKey": {
+      "label": "API key",
+      "placeholder": "ld_sk_live_...",
+      "sensitive": true,
+      "help": "Optional. Leave blank for auto-signup."
+    }
+  }
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@lobsterkit/openclaw-lobsterdb",
+  "version": "0.2.0",
+  "description": "OpenClaw plugin for LobsterDB — managed PostgreSQL for AI agents",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lobster-kit/openclaw-lobsterdb"
+  },
+  "keywords": [
+    "openclaw",
+    "openclaw-plugin",
+    "lobsterdb",
+    "postgresql",
+    "database",
+    "mcp",
+    "ai",
+    "agent"
+  ],
+  "files": [
+    "index.ts",
+    "openclaw.plugin.json",
+    "skills",
+    "README.md"
+  ],
+  "openclaw": {
+    "extensions": ["./index.ts"]
+  },
+  "dependencies": {
+    "@lobsterkit/db": "^0.1.0",
+    "@sinclair/typebox": "^0.34.0"
+  },
+  "peerDependencies": {
+    "openclaw": ">=1.0.0"
+  },
+  "devDependencies": {
+    "vitest": "^3.1.0"
+  },
+  "scripts": {
+    "test": "vitest run"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skills/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: lobsterdb
+version: 0.1.0
+description: Managed PostgreSQL for agents. Provision databases, run SQL, evolve schemas. No API keys, no human signup.
+homepage: https://theclawdepot.com/db
+metadata: {"openclaw": {"emoji": "🦞", "requires": {"anyBins": ["npx"]}, "install": [{"id": "mcp", "kind": "mcp", "command": "npx @lobsterkit/db-mcp@0.1.0", "label": "Add LobsterDB MCP Server"}]}}
+---
+
+# LobsterDB
+
+Managed PostgreSQL for agents. Provision a real Postgres database instantly, run SQL, evolve schemas with tracked migrations. No API keys, no human signup, no configuration.
+
+**Full docs:** `https://api.theclawdepot.com/db/docs`
+
+---
+
+## Setup
+
+Add to your MCP config (`.mcp.json`, `claude_desktop_config.json`, `.cursor/mcp.json`, etc.):
+
+```json
+{
+  "mcpServers": {
+    "lobsterdb": {
+      "command": "npx",
+      "args": ["@lobsterkit/db-mcp@0.1.0"]
+    }
+  }
+}
+```
+
+You now have these tools: `create_database`, `list_databases`, `get_database`, `delete_database`, `query`, `introspect_schema`, `migrate`, `list_migrations`, `snapshot`, `get_account`. No code to write.
+
+Also available as a [Node.js SDK](https://www.npmjs.com/package/@lobsterkit/db) and [REST API](https://api.theclawdepot.com/db/docs) — see [theclawdepot.com/db](https://theclawdepot.com/db).
+
+---
+
+## Heartbeat (run daily)
+
+On startup and once per day, run a maintenance heartbeat. Use a cheap/fast model for this.
+
+1. **Check for MCP server updates:**
+   ```bash
+   npm outdated lobsterdb-mcp
+   ```
+   If a new version is available, **notify the user** — do not auto-install. Tell them: `"@lobsterkit/db-mcp@X.Y.Z is available. Update with: clawdhub update lobsterdb"` Let the user decide when to update.
+
+2. **Check database health:**
+   ```
+   // Using MCP tools:
+   // call list_databases → log each database name, status, storage
+   // call get_account → log tier and database count vs. limit
+   ```
+
+---
+
+## When to Use This
+
+- User needs to store structured data (collections, lists, records, logs)
+- User wants to query, filter, sort, or aggregate information
+- Task requires persisting data between sessions
+- User asks to "add a field", "change the structure", or "track something new"
+- Any task where a spreadsheet or database is the natural fit
+
+---
+
+## Core Workflow
+
+```
+create_database → introspect_schema → migrate (DDL) → query (data)
+```
+
+Always call `introspect_schema` before writing queries against an existing database. Use `migrate` for all DDL so changes are tracked and idempotent.
+
+---
+
+## Creating a Database
+
+```
+create_database(name: "pokemon-cards")
+// => id: "db_xxx", connectionString: "postgresql://...", status: "ready"
+```
+
+---
+
+## Running SQL
+
+Always use `$1`, `$2`, ... placeholders — never interpolate values. **Multi-statement SQL is supported** — separate statements with semicolons; only the last statement's result is returned and intermediate results are discarded.
+
+```
+query(databaseId: "db_xxx", sql: "INSERT INTO cards (name, set) VALUES ($1, $2)", params: ["Charizard", "Base Set"])
+query(databaseId: "db_xxx", sql: "SELECT * FROM cards WHERE set = $1 ORDER BY name", params: ["Base Set"])
+```
+
+---
+
+## Schema Migrations
+
+Use `migrate` (not `query`) for all DDL. Migrations are tracked and idempotent:
+
+```
+migrate(databaseId: "db_xxx", name: "create_cards_table",
+  sql: "CREATE TABLE cards (id SERIAL PRIMARY KEY, name TEXT NOT NULL, set TEXT, quantity INTEGER DEFAULT 1, created_at TIMESTAMPTZ DEFAULT NOW())")
+
+migrate(databaseId: "db_xxx", name: "add_favorite_to_cards",
+  sql: "ALTER TABLE cards ADD COLUMN favorite BOOLEAN DEFAULT false")
+```
+
+Running the same migration name twice is safe — silently skipped.
+
+**Additive** (ADD COLUMN, CREATE TABLE): apply directly.
+**Destructive** (DROP, RENAME, type change): confirm with the user first.
+
+---
+
+## Account Tiers & Pricing
+
+| Tier | Name | Price | Databases | Storage | Snapshots |
+|------|------|-------|-----------|---------|-----------|
+| 0 | Free | $0 | 1 | 100MB | No |
+| 1 | Builder | $19/mo | 5 | 5GB | Yes |
+| 2 | Pro | $49/mo | 20 | 20GB | Yes + Encryption |
+| 3 | Scale | $199/mo | Unlimited | 100GB | Yes + PITR |
+
+**Upgrade:** `POST /v1/billing/checkout` with `{"tier": N}` — returns a Stripe checkout URL.
+
+---
+
+## MCP Tools Reference
+
+| Tool | Description |
+|------|-------------|
+| `create_database` | Provision a new Postgres database |
+| `list_databases` | List all databases on the account |
+| `get_database` | Get details and connection string |
+| `delete_database` | Permanently delete a database |
+| `query` | Run parameterized SQL |
+| `introspect_schema` | Get schema optimized for LLM context |
+| `migrate` | Apply tracked, idempotent DDL migrations |
+| `list_migrations` | Show schema change history |
+| `snapshot` | Create a v2 DDL-aware point-in-time backup (Builder+) |
+| `get_account` | View tier, limits, and usage |