@ductape/mcp 0.1.47 → 0.1.49

package/dist/index.js

@@ -576,6 +576,11 @@ ALL params are passed as a JSON array in positional order matching the SDK signa
   databases.update  [{ product, env, database, table, data: {key:value}, where: {field: value}, returning?, session?, cache? }]  ← CALL ductape_generate_payload FIRST (operation_family="database", method="update", targets={database, table})
   databases.delete  [{ product, env, database, table, where: {field: value}, returning?, session?, cache? }]  ← CALL ductape_generate_payload FIRST (operation_family="database", method="delete", targets={database, table})
   databases.upsert  [{ product, env, database, table, data: {key:value}, conflictKeys: string[], returning?, session?, cache? }]  ← CALL ductape_generate_payload FIRST (operation_family="database", method="upsert", targets={database, table})
+  NOTE on write operations (insert/update/delete/upsert): if the proxy returns "Authentication failed",
+  the publishable key does not have write access for that database. Write permissions are configured
+  in Workbench → Tokens → Publishable Key. An access key is required for write operations that are
+  not explicitly enabled for the publishable key. In that case the operation must be performed
+  server-side using a full Ductape SDK instance initialized with an access key.
   NOTE: ductape_generate_payload for databases returns:
     payload.input  — ready-to-use input with real field names in where/data, plus session and cache inside input
     meta.schema_context.database.fields          — { fieldName: { type, required, description?, sample? } } for the table
@@ -1187,9 +1192,58 @@ const docsInputSchema = z.object({
     topic: z.string().describe('Feature topic to look up. Supported: ' +
         'transactions, presave, triggers, aggregations, migrations, indexes, performance, actions, ' +
         'graphs, storage, cloud, vector, warehouse, secrets, apps, products, sessions, caches, ' +
-        'notifications, resilience, features, events, logs'),
+        'notifications, resilience, features, events, logs, frontend, client, react, vue'),
 });
 const DOCS = {
+    frontend: `
+DUCTAPE FRONTEND SDK GUIDE
+
+Choose one integration package:
+  React 17+  — npm install @ductape/react
+               Provider and hooks built on @ductape/client.
+               Continue with ductape_docs({ topic: "react" }).
+  Vue 3+     — npm install @ductape/vue
+               Plugin and composables built on @ductape/client.
+               Continue with ductape_docs({ topic: "vue" }).
+  Other UI   — npm install @ductape/client
+  frameworks   Use directly with Svelte, Angular, vanilla JavaScript, or a custom adapter.
+               Continue with ductape_docs({ topic: "client" }).
+
+Do not install @ductape/client separately when using @ductape/react or @ductape/vue unless the
+application also needs direct access to a client API not exposed by the framework package. Both
+framework packages wrap @ductape/client and expose the underlying client through useDuctape().
+
+SHARED APPLICATION LIFECYCLE
+  1. Create one client at the application root using a browser-safe publishableKey, proxy baseUrl,
+     default product tag, and environment slug.
+  2. Connect the real-time client only in the browser. In React use DuctapeProvider autoConnect or
+     connect() after mount; in Vue use createDuctape({ autoConnect: true }) or connect() in onMounted.
+  3. Authenticate the player with the sessions API and retain the returned session token according
+     to the application's security policy. Refresh it before expiry (the React/Vue packages provide
+     useSessionAutoRefresh) and revoke it on logout.
+  4. Pass the session value when connecting a broker that requires player-scoped authorization.
+  5. Subscribe through the framework hook/composable or the client service. Always unsubscribe on
+     component teardown; the framework integrations do this automatically for declarative hooks.
+  6. The underlying client reconnects its WebSocket and restores active subscriptions. Observe
+     connectionState to render disconnected/reconnecting UI; do not create duplicate subscriptions.
+  7. Disconnect resource sessions and the root client when the owning application scope is torn down.
+
+AUTHENTICATION AND SECURITY
+  - Use publishableKey in browser applications. Never ship workspace private keys or privileged
+    access keys in frontend bundles.
+  - A Ductape player session and the real-time transport connection are separate: authenticate or
+    refresh the session, then use that session when opening player-scoped broker resources.
+  - For SSR, create/connect the real-time client only on the browser side.
+
+MIGRATING A CUSTOM WRAPPER
+  - Keep @ductape/client when the wrapper implements application-specific projection or state logic.
+  - For React, move root connection ownership to DuctapeProvider, replace imperative subscriptions
+    with useBroker/useBrokerSubscription, and keep projection reduction in an application hook.
+  - For Vue, move root ownership to createDuctape(), replace imperative subscriptions with
+    useBroker/useBrokerSubscription, and keep projection reduction in an application composable.
+  - Verify session handoff, initial loading state, error state, reconnect UI, subscription cleanup,
+    and duplicate-event behavior with a live end-to-end run before removing the old wrapper.
+`.trim(),
     transactions: `
 DUCTAPE DATABASE TRANSACTIONS
 
@@ -3418,7 +3472,14 @@ async function main() {
             return { content: [{ type: 'text', text: JSON.stringify(result ?? null, null, 2) }] };
         }
         catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
+            let message = err instanceof Error ? err.message : String(err);
+            const isAuthFailed = /authentication failed/i.test(message);
+            const isDbWrite = args.module === 'databases' && /^(insert|update|delete|upsert)$/.test(args.method);
+            if (isAuthFailed && isDbWrite) {
+                message += '\n\nThe publishable key does not have write access for this database operation. ' +
+                    'Enable it in Workbench → Tokens → Publishable Key. ' +
+                    'If write access cannot be granted to the publishable key, perform this operation server-side using a full Ductape SDK instance initialized with an access key.';
+            }
             return { content: [{ type: 'text', text: `Error: ${message}` }], isError: true };
         }
     };
@@ -3537,7 +3598,7 @@ async function main() {
                 'index strategy, operation types) that should be confirmed with the user first.\n\n' +
                 'Available topics: transactions, presave, triggers, aggregations, migrations, indexes, performance, actions, ' +
                 'graphs, storage, cloud, vector, warehouse, secrets, apps, products, sessions, caches, ' +
-                'notifications, resilience, features, events, logs, client, react, vue',
+                'notifications, resilience, features, events, logs, frontend, client, react, vue',
             inputSchema: docsInputSchema,
         }, docsHandler);
         server.registerTool('ductape_cli', {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ductape/mcp",
-  "version": "0.1.47",
+  "version": "0.1.49",
   "description": "MCP server that exposes Ductape SDK operations via the backend proxy",
   "type": "module",
   "main": "dist/index.js",

package/src/index.ts

@@ -587,6 +587,11 @@ ALL params are passed as a JSON array in positional order matching the SDK signa
   databases.update  [{ product, env, database, table, data: {key:value}, where: {field: value}, returning?, session?, cache? }]  ← CALL ductape_generate_payload FIRST (operation_family="database", method="update", targets={database, table})
   databases.delete  [{ product, env, database, table, where: {field: value}, returning?, session?, cache? }]  ← CALL ductape_generate_payload FIRST (operation_family="database", method="delete", targets={database, table})
   databases.upsert  [{ product, env, database, table, data: {key:value}, conflictKeys: string[], returning?, session?, cache? }]  ← CALL ductape_generate_payload FIRST (operation_family="database", method="upsert", targets={database, table})
+  NOTE on write operations (insert/update/delete/upsert): if the proxy returns "Authentication failed",
+  the publishable key does not have write access for that database. Write permissions are configured
+  in Workbench → Tokens → Publishable Key. An access key is required for write operations that are
+  not explicitly enabled for the publishable key. In that case the operation must be performed
+  server-side using a full Ductape SDK instance initialized with an access key.
   NOTE: ductape_generate_payload for databases returns:
     payload.input  — ready-to-use input with real field names in where/data, plus session and cache inside input
     meta.schema_context.database.fields          — { fieldName: { type, required, description?, sample? } } for the table
@@ -1237,11 +1242,61 @@ const docsInputSchema = z.object({
     'Feature topic to look up. Supported: ' +
     'transactions, presave, triggers, aggregations, migrations, indexes, performance, actions, ' +
     'graphs, storage, cloud, vector, warehouse, secrets, apps, products, sessions, caches, ' +
-    'notifications, resilience, features, events, logs',
+    'notifications, resilience, features, events, logs, frontend, client, react, vue',
   ),
 });
 
 const DOCS: Record<string, string> = {
+  frontend: `
+DUCTAPE FRONTEND SDK GUIDE
+
+Choose one integration package:
+  React 17+  — npm install @ductape/react
+               Provider and hooks built on @ductape/client.
+               Continue with ductape_docs({ topic: "react" }).
+  Vue 3+     — npm install @ductape/vue
+               Plugin and composables built on @ductape/client.
+               Continue with ductape_docs({ topic: "vue" }).
+  Other UI   — npm install @ductape/client
+  frameworks   Use directly with Svelte, Angular, vanilla JavaScript, or a custom adapter.
+               Continue with ductape_docs({ topic: "client" }).
+
+Do not install @ductape/client separately when using @ductape/react or @ductape/vue unless the
+application also needs direct access to a client API not exposed by the framework package. Both
+framework packages wrap @ductape/client and expose the underlying client through useDuctape().
+
+SHARED APPLICATION LIFECYCLE
+  1. Create one client at the application root using a browser-safe publishableKey, proxy baseUrl,
+     default product tag, and environment slug.
+  2. Connect the real-time client only in the browser. In React use DuctapeProvider autoConnect or
+     connect() after mount; in Vue use createDuctape({ autoConnect: true }) or connect() in onMounted.
+  3. Authenticate the player with the sessions API and retain the returned session token according
+     to the application's security policy. Refresh it before expiry (the React/Vue packages provide
+     useSessionAutoRefresh) and revoke it on logout.
+  4. Pass the session value when connecting a broker that requires player-scoped authorization.
+  5. Subscribe through the framework hook/composable or the client service. Always unsubscribe on
+     component teardown; the framework integrations do this automatically for declarative hooks.
+  6. The underlying client reconnects its WebSocket and restores active subscriptions. Observe
+     connectionState to render disconnected/reconnecting UI; do not create duplicate subscriptions.
+  7. Disconnect resource sessions and the root client when the owning application scope is torn down.
+
+AUTHENTICATION AND SECURITY
+  - Use publishableKey in browser applications. Never ship workspace private keys or privileged
+    access keys in frontend bundles.
+  - A Ductape player session and the real-time transport connection are separate: authenticate or
+    refresh the session, then use that session when opening player-scoped broker resources.
+  - For SSR, create/connect the real-time client only on the browser side.
+
+MIGRATING A CUSTOM WRAPPER
+  - Keep @ductape/client when the wrapper implements application-specific projection or state logic.
+  - For React, move root connection ownership to DuctapeProvider, replace imperative subscriptions
+    with useBroker/useBrokerSubscription, and keep projection reduction in an application hook.
+  - For Vue, move root ownership to createDuctape(), replace imperative subscriptions with
+    useBroker/useBrokerSubscription, and keep projection reduction in an application composable.
+  - Verify session handoff, initial loading state, error state, reconnect UI, subscription cleanup,
+    and duplicate-event behavior with a live end-to-end run before removing the old wrapper.
+`.trim(),
+
   transactions: `
 DUCTAPE DATABASE TRANSACTIONS
 
@@ -3517,7 +3572,14 @@ async function main() {
       const result = await executeViaProxy(key, proxyModule, args.method, params);
       return { content: [{ type: 'text', text: JSON.stringify(result ?? null, null, 2) }] };
     } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
+      let message = err instanceof Error ? err.message : String(err);
+      const isAuthFailed = /authentication failed/i.test(message);
+      const isDbWrite = args.module === 'databases' && /^(insert|update|delete|upsert)$/.test(args.method);
+      if (isAuthFailed && isDbWrite) {
+        message += '\n\nThe publishable key does not have write access for this database operation. ' +
+          'Enable it in Workbench → Tokens → Publishable Key. ' +
+          'If write access cannot be granted to the publishable key, perform this operation server-side using a full Ductape SDK instance initialized with an access key.';
+      }
       return { content: [{ type: 'text', text: `Error: ${message}` }], isError: true };
     }
   };
@@ -3670,7 +3732,7 @@ async function main() {
           'index strategy, operation types) that should be confirmed with the user first.\n\n' +
           'Available topics: transactions, presave, triggers, aggregations, migrations, indexes, performance, actions, ' +
           'graphs, storage, cloud, vector, warehouse, secrets, apps, products, sessions, caches, ' +
-          'notifications, resilience, features, events, logs, client, react, vue',
+          'notifications, resilience, features, events, logs, frontend, client, react, vue',
         inputSchema: docsInputSchema,
       },
       docsHandler,