@ductape/mcp 0.1.48 → 0.1.49

package/dist/index.js

@@ -1192,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
 
@@ -3549,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.48",
+  "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

@@ -1242,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
 
@@ -3682,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,