@ductape/mcp 0.1.57 → 0.1.59

package/dist/index.js

@@ -123,8 +123,9 @@ There are THREE categories of operations. Use the right tool for each:
            ductape_cli("resources storage list")
            ductape_cli("resources database create -f db-config.json")
        This applies to: products, apps, and resources (databases, storage, caches, etc.),
-       cloud connections, and secrets. Environments, app actions, auths, features, quotas,
-       fallbacks, jobs, and healthchecks are configured in the Workbench UI.
+       cloud connections, and secrets. Environments, app actions, auths, quotas, fallbacks,
+       jobs, and healthchecks are configured in the Workbench UI. Features have no CLI create
+       command because their definitions are code-first through features.define.
 
        ⚠ MULTI-ENV REQUIREMENT — applies to ALL product assets (storage, database, cache,
        messageBroker, graph, vector, and any other resource with an envs array):
@@ -323,6 +324,9 @@ ALL params are passed as a JSON array in positional order matching the SDK signa
   IMPORTANT: ALL product.* methods require the access key and will return 403 with a publishable key.
   Use ductape_cli for ALL product operations — never ductape_execute:
     ductape_cli("products get --tag <tag> --json")           ← fetch product + full inventory
+    ductape_cli("products components list --tag <tag> --json") ← compact non-secret inventory
+    ductape_cli("products components get --tag <tag> --type notifications --json")
+    ductape_cli("products components get --tag <tag> --type events --json")
     ductape_cli("products create --name <name> --tag <tag>")
     ductape_cli("products environments list <tag> --json")
     ductape_cli("products environments get <tag> <slug> --json")
@@ -490,8 +494,8 @@ ALL params are passed as a JSON array in positional order matching the SDK signa
   notifications.fetch    [product_tag, notif_tag]
   notifications.list     [product_tag]
   notifications.delete   [product_tag, notif_tag]
-  notifications.messages.create  [product_tag, data: { tag: string, notification: string, subject?: { template: string, data: object }, body?: { template: string, data: object } }]
-  notifications.messages.update  [product_tag, msg_tag, data: { subject?: { template: string, data: object }, body?: { template: string, data: object } }]
+  notifications.messages.create  [product_tag, data: { tag: string, name: string, description?: string, push_notification?: { title: string, body: string, data?: object }, email?: { subject: string, template: string }, callback?: object, sms?: string }]
+  notifications.messages.update  [product_tag, msg_tag, data: { name?: string, description?: string, push_notification?: { title: string, body: string, data?: object }, email?: { subject: string, template: string }, callback?: object, sms?: string }]
   notifications.messages.fetch   [product_tag, msg_tag]
   notifications.messages.list    [product_tag, notification_tag]
   notifications.send     [{ product, env, event, input: { ... } }]  ← CALL ductape_generate_payload FIRST (operation_family="notification", method="send", targets={notification})
@@ -783,7 +787,7 @@ ALL params are passed as a JSON array in positional order matching the SDK signa
       // ctx.graph.execute({ graph, action, input })
       // ctx.notification.send/email/push/sms({ notification, event, ... })
       // ctx.storage.upload/download({ storage, event, input })
-      // ctx.messaging.produce({ event: "broker:topic", message: {} })
+      // ctx.events.produce({ event: "broker:topic", message: {} })
       // ctx.quota.execute({ quota, input })
       // ctx.fallback.execute({ fallback, input })
       // ctx.healthcheck.getStatus(tag)
@@ -1163,6 +1167,7 @@ const ADMIN_SUBCOMMANDS = [
     'link', 'unlink', 'init',
     'products', 'apps',
     'resources',
+    'notifications',
     'events',
     'cloud',
     'secrets',
@@ -1227,7 +1232,9 @@ function runCli(command) {
     try {
         const output = execSync(`ductape ${finalCommand}`, {
             encoding: 'utf8',
-            timeout: 30000,
+            // Must exceed the proxy's operation timeout so stderr can preserve the structured timeout
+            // instead of this wrapper killing the CLI first and reducing it to "(no data)".
+            timeout: 90000,
             stdio: ['pipe', 'pipe', 'pipe'],
         });
         return { success: true, output: output.trim() };
@@ -2181,22 +2188,54 @@ ADMINISTRATION — CLI (never ductape_execute)
   ductape_cli("notifications messages get --tag <notification:message> --json")
   ductape_cli("notifications messages update --tag <notification:message> -f patch.json")
   Declarative alternative: ductape/notifications.json then ductape_cli("apply notifications").
+  The file MUST be a top-level JSON array. Each item is a notification definition and may contain
+  a nested "messages" array. {"notifications":[],"messages":[]} is not a valid envelope.
 
 Notification definition:
   {
-    tag: "welcome-email",
+    tag: "welcome-email", // component tags cannot contain ":"
     name: "Welcome Email",
-    type: "email",   // optional hint; actual channels configured per env
+    description: "Transactional welcome messages",
+    envs: [{
+      slug: "prd",
+      emails: {
+        provider: "smtp",
+        smtp: {
+          host: "smtp.example.com",
+          port: "$Secret{smtp-port}",
+          sender_email: "hello@example.com",
+          auth: { user: "$Secret{smtp-user}", pass: "$Secret{smtp-password}" },
+          secure: true
+        }
+      }
+    }],
+    messages: []
   }
 
 Create a message template through declarative apply or Workbench:
   {
-    tag: "welcome-email:default",       // format: "notification_tag:message_tag"
-    notification: "welcome-email",
-    subject: { template: "Welcome, {{name}}!", data: { name: "" } },
-    body:    { template: "Hi {{name}}, thanks for signing up.", data: { name: "" } },
+    tag: "welcome-email:default", // message tags use component-tag:message-tag
+    name: "Default welcome",
+    description: "Sent after account creation",
+    push_notification: {
+      title: "Welcome, {{name}}!",
+      body: "Thanks for signing up.",
+      data: {}
+    },
+    email: {
+      subject: "Welcome, {{name}}!",
+      template: "Hi {{name}}, thanks for signing up."
+    }
   }
 
+TAG AND SMTP RULES
+  Component tag: "game-alerts-critical" (no colon).
+  Message tag: "game-alerts-critical:match-launch" (one colon separator).
+  Do not add "notification", "subject", or "body" at message root.
+  SMTP requires emails.smtp.sender_email.
+  emails.smtp.secure is a boolean and cannot be a $Secret{...} string.
+  Credential strings such as auth.user and auth.pass may use $Secret{...}.
+
 Send at runtime (one channel at a time):
   → CALL ductape_generate_payload FIRST (operation_family="notification", method="email.send")
   notifications.email.send    [{ product, env, notification, input: { recipients, subject?, template? } }]
@@ -2244,6 +2283,10 @@ FIREBASE THROUGH A GCP CLOUD CONNECTION
     }
   The SDK requests current GCP credentials from the cloud connection at send time. Never put the
   service-account private key in the notification file. Expo does not use a GCP cloud connection.
+  The recommended cloud connection scope is "notifications". It expresses Ductape capability/UI
+  intent; creating a notification does not prove Google-side FCM permission. Runtime delivery
+  requires fcm.googleapis.com and roles/firebasecloudmessaging.admin, so validate the connection
+  and perform a delivery test.
 Notification tag and message tag are ALWAYS passed together as "notification_tag:message_tag".
 `.trim(),
     resilience: `
@@ -2610,9 +2653,11 @@ STEP 4 — PRESENT the plan and get approval BEFORE writing any code or creating
 STEP 5 — CREATE missing components (only with user approval)
   Administrative assets must never be created through ductape_execute. Use ductape_cli for products,
   apps, supported resources, broker topics, cloud connections, secrets, and declarative apply flows.
-  App actions, auths, Features, quotas, fallbacks, health checks, and other assets for which the CLI
-  has no command must be configured in Workbench. Do not generate an impossible publishable-key
-  create/update call. For a missing database action, configure it in Workbench, then verify it exists.
+  App actions, auths, quotas, fallbacks, health checks, and other administrative assets for which
+  the CLI has no command must be configured in Workbench. Feature definitions are the exception:
+  they are code-first via features.define, are registered by application boot/runtime initialization,
+  and cannot be created with the CLI. Do not generate a Workbench-only or publishable-key
+  create/update call for a Feature. For a missing database action, configure it in Workbench, then verify it exists.
   For a missing child feature, recursively apply this same workflow.
   Tell the user what you are about to create before each tool call.
 
@@ -2721,7 +2766,9 @@ When you call features.define({ handler }), the handler runs TWICE:
   Features do NOT execute arbitrary NestJS or server code directly. A feature handler can only
   call Ductape component primitives (ctx.api, ctx.database, ctx.notification, etc.) as steps.
   To invoke internal application business logic, produce a broker event from a feature step
-  (ctx.messaging.produce) and consume it in your NestJS service — that is the correct pattern.
+  (ctx.events.produce in the currently published SDK) and consume it in your NestJS service.
+  ctx.publish is deprecated; do not use it. Do not assume a ctx.messaging alias exists unless the
+  installed SDK types explicitly expose it.
 
 ━━━ ORCHESTRATION DECISION RULE ━━━
 
@@ -2735,7 +2782,7 @@ When you call features.define({ handler }), the handler runs TWICE:
     → define a Feature, then features.dispatch to schedule it
 
   Invoke internal application business logic (your own NestJS/backend service code):
-    → produce a broker event (ctx.messaging.produce or ductape.events.produce)
+    → produce a broker event (ctx.events.produce inside a Feature, or ductape.events.produce outside it)
     → follow ductape_docs({ topic: "events" }) and use the canonical NestJS decorator:
       @Events.Consumer({ event: "broker-tag:topic-tag" })
       async handle(message: MessageShape) { /* injected-service business logic; throw to nack */ }
@@ -3670,8 +3717,9 @@ const cliInputSchema = z.object({
         'Use this tool for administrative operations: creating or updating products, apps, ' +
         'resources (databases, storage, caches…), event broker topics, cloud connections, secrets, ' +
         'and for apply/migrate workflows.\n\n' +
-        'Note: environments, app actions, features, quotas, fallbacks, and jobs are configured ' +
-        'in the Workbench UI — there are no CLI commands for them.\n\n' +
+        'Note: environments, app actions, quotas, fallbacks, and jobs are configured in the ' +
+        'Workbench UI. Features also have no CLI creation command: define them in application code ' +
+        'with features.define so application boot/runtime registration makes them available.\n\n' +
         'The CLI uses the user\'s local logged-in session (ductape login) — no key is required.'),
 });
 async function loadMcpSdk() {
@@ -3753,8 +3801,10 @@ async function main() {
         const firstWord = args.command.trim().split(/\s+/)[0];
         const isAuthCommand = firstWord === 'login' || firstWord === 'logout';
         if (!isAuthCommand) {
-            // Check login status once per process (cached after first call)
-            if (authState === 'unknown') {
+            // Cache successful authentication, but re-check a missing/expired session on every call.
+            // The user may complete `ductape login` in another terminal while this MCP process remains
+            // alive; caching "none" would otherwise make the MCP blind to the newly written session.
+            if (authState === 'unknown' || authState === 'none') {
                 checkLoginState();
             }
             if (authState === 'none') {
@@ -4062,12 +4112,16 @@ async function main() {
                 '    Message brokers are import-only (no provision-persist). Import flow is the same as storage.\n' +
                 '    type field = "messageBrokers" (not "messagebrokers" or "events").\n' +
                 '    After importing, create topics first with ductape_cli("events topics create -f topic.json") — SQS requires explicit topic creation with queueUrls. For other providers, topics auto-register on first produce but should still be created explicitly before any consumer subscribes.\n' +
-                '  - Listing workspaces, products, secrets\n' +
+                '  - Listing workspaces, products, focused product components, secrets\n' +
+                '    Prefer "products components list --tag <tag> --json" for compact inventory; use\n' +
+                '    "products components get --tag <tag> --type notifications|events --json" for focused detail.\n' +
+                '  - Managing notification components and message templates through "resources notifications" and "notifications messages"\n' +
                 '  - Linking a project folder: "link --product <tag> --env <slug>"\n' +
                 '  - Syncing sessions/notifications/events: "apply" or "apply sessions" etc.\n' +
                 '  - Running database migrations: "db migrate", "db schema generate"\n\n' +
-                'NOTE: Environments, app actions, auths, features, quotas, fallbacks, and jobs are ' +
-                'configured in the Workbench UI — the CLI does not have commands for them.\n\n' +
+                'NOTE: Environments, app actions, auths, quotas, fallbacks, and jobs are configured ' +
+                'in the Workbench UI. Features have no CLI creation command because definitions are ' +
+                'code-first through features.define and registered by the application runtime.\n\n' +
                 'DO NOT use ductape_execute for admin operations — it uses a publishable key which only ' +
                 'covers runtime operations. Administrative operations will fail with "Authentication failed".\n\n' +
                 'The CLI uses the user\'s local logged-in session (ductape login). ' +

package/dist/proxy-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"proxy-client.d.ts","sourceRoot":"","sources":["../src/proxy-client.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,eAAO,MAAM,YAAY,4BAA4B,CAAC;AAEtD,MAAM,MAAM,SAAS,GACjB,SAAS,GACT,KAAK,GACL,WAAW,GACX,OAAO,GACP,UAAU,GACV,eAAe,GACf,gBAAgB,GAChB,QAAQ,GACR,SAAS,GACT,QAAQ,GACR,QAAQ,GACR,UAAU,GACV,QAAQ,GACR,SAAS,GACT,UAAU,GACV,MAAM,GACN,MAAM,GACN,YAAY,GACZ,QAAQ,GACR,UAAU,GACV,SAAS,CAAC;AAUd;;GAEG;AACH,wBAAsB,eAAe,CAAC,CAAC,GAAG,OAAO,EAC/C,eAAe,EAAE,MAAM,EACvB,MAAM,EAAE,SAAS,EACjB,MAAM,EAAE,MAAM,EACd,MAAM,GAAE,OAAO,EAAO,GACrB,OAAO,CAAC,CAAC,CAAC,CAuBZ;AAED,MAAM,WAAW,iCAAiC;IAChD,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,gBAAgB,EAAE,MAAM,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,iBAAiB,CAAC,EAAE,MAAM,GAAG,WAAW,GAAG,QAAQ,CAAC;IACpD,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,WAAW,CAAC,EAAE,QAAQ,GAAG,aAAa,CAAC;IACvC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAED,MAAM,WAAW,kCAAkC;IACjD,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AASD,wBAAsB,eAAe,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAYvE;AA4BD,wBAAsB,yBAAyB,CAAC,CAAC,GAAG,kCAAkC,EACpF,OAAO,EAAE,iCAAiC,GACzC,OAAO,CAAC,CAAC,CAAC,CAwBZ"}
+{"version":3,"file":"proxy-client.d.ts","sourceRoot":"","sources":["../src/proxy-client.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,eAAO,MAAM,YAAY,4BAA4B,CAAC;AAEtD,MAAM,MAAM,SAAS,GACjB,SAAS,GACT,KAAK,GACL,WAAW,GACX,OAAO,GACP,UAAU,GACV,eAAe,GACf,gBAAgB,GAChB,QAAQ,GACR,SAAS,GACT,QAAQ,GACR,QAAQ,GACR,UAAU,GACV,QAAQ,GACR,SAAS,GACT,UAAU,GACV,MAAM,GACN,MAAM,GACN,YAAY,GACZ,QAAQ,GACR,UAAU,GACV,SAAS,CAAC;AAUd;;GAEG;AACH,wBAAsB,eAAe,CAAC,CAAC,GAAG,OAAO,EAC/C,eAAe,EAAE,MAAM,EACvB,MAAM,EAAE,SAAS,EACjB,MAAM,EAAE,MAAM,EACd,MAAM,GAAE,OAAO,EAAO,GACrB,OAAO,CAAC,CAAC,CAAC,CAuBZ;AAED,MAAM,WAAW,iCAAiC;IAChD,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,gBAAgB,EAAE,MAAM,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,iBAAiB,CAAC,EAAE,MAAM,GAAG,WAAW,GAAG,QAAQ,CAAC;IACpD,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,WAAW,CAAC,EAAE,QAAQ,GAAG,aAAa,CAAC;IACvC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAED,MAAM,WAAW,kCAAkC;IACjD,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AASD,wBAAsB,eAAe,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAYvE;AA4BD,wBAAsB,yBAAyB,CAAC,CAAC,GAAG,kCAAkC,EACpF,OAAO,EAAE,iCAAiC,GACzC,OAAO,CAAC,CAAC,CAAC,CA8BZ"}

package/dist/proxy-client.js

@@ -67,9 +67,15 @@ function normalizeTargets(targets) {
     return result;
 }
 export async function generateExecutablePayload(request) {
+    // execution_context is MCP guidance metadata, not part of the integrations
+    // payload-generator API contract. Keep it for local session-awareness output
+    // but never forward it to the backend validator.
+    const { execution_context: _executionContext, ...backendRequest } = request;
     const normalizedRequest = {
-        ...request,
-        targets: request.targets ? normalizeTargets(request.targets) : request.targets,
+        ...backendRequest,
+        targets: backendRequest.targets
+            ? normalizeTargets(backendRequest.targets)
+            : backendRequest.targets,
     };
     const url = `${API_BASE_URL.replace(/\/$/, '')}/integrations/v1/payloads/generate`;
     const res = await fetch(url, {

package/package.json

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

package/scripts/check-frontend-analytics-guidance.mjs

@@ -51,6 +51,13 @@ const safetyChecks = [
   ['CLI distinguishes endpoint 401 from expired login', /session and active workspace are authenticated[\s\S]*Do not ask the user to log in again/],
   ['CLI auth guidance does not request secrets', /Never ask the user to paste their password/],
   ['notification CLI administration documented', /resources notifications create[\s\S]*notifications messages create/],
+  ['notification command allowed by MCP', /ADMIN_SUBCOMMANDS[\s\S]*'notifications'/],
+  ['notification template uses SDK shape', /push_notification\?: \{ title: string, body: string[\s\S]*email\?: \{ subject: string, template: string/],
+  ['notification declarations require array shape', /file MUST be a top-level JSON array/],
+  ['external CLI login is re-read', /authState === 'unknown' \|\| authState === 'none'/],
+  ['compact product inventory documented', /products components list --tag <tag> --json/],
+  ['features use installed events context', /ctx\.events\.produce inside a Feature/],
+  ['features are code-first rather than Workbench-created', /Features have no CLI (?:create|creation)\s+command because (?:their )?definitions are code-first/],
   ['Firebase GCP cloud connection documented', /FIREBASE THROUGH A GCP CLOUD CONNECTION[\s\S]*authMode.*cloud_connection/],
   ['Slack and Discord sends documented', /notifications\.slack\.send[\s\S]*notifications\.discord\.send/],
 ];
@@ -72,4 +79,10 @@ assert.doesNotMatch(
   'Browser Events guidance must not import the server SDK',
 );
 
+assert.doesNotMatch(
+  source,
+  /ctx\.messaging\.produce/,
+  'Feature guidance must use the installed ctx.events API, not a nonexistent ctx.messaging alias',
+);
+
 console.log(`MCP guidance: ${checks.length + 1 + safetyChecks.length} acceptance checks passed`);

package/src/index.ts

@@ -134,8 +134,9 @@ There are THREE categories of operations. Use the right tool for each:
            ductape_cli("resources storage list")
            ductape_cli("resources database create -f db-config.json")
        This applies to: products, apps, and resources (databases, storage, caches, etc.),
-       cloud connections, and secrets. Environments, app actions, auths, features, quotas,
-       fallbacks, jobs, and healthchecks are configured in the Workbench UI.
+       cloud connections, and secrets. Environments, app actions, auths, quotas, fallbacks,
+       jobs, and healthchecks are configured in the Workbench UI. Features have no CLI create
+       command because their definitions are code-first through features.define.
 
        ⚠ MULTI-ENV REQUIREMENT — applies to ALL product assets (storage, database, cache,
        messageBroker, graph, vector, and any other resource with an envs array):
@@ -334,6 +335,9 @@ ALL params are passed as a JSON array in positional order matching the SDK signa
   IMPORTANT: ALL product.* methods require the access key and will return 403 with a publishable key.
   Use ductape_cli for ALL product operations — never ductape_execute:
     ductape_cli("products get --tag <tag> --json")           ← fetch product + full inventory
+    ductape_cli("products components list --tag <tag> --json") ← compact non-secret inventory
+    ductape_cli("products components get --tag <tag> --type notifications --json")
+    ductape_cli("products components get --tag <tag> --type events --json")
     ductape_cli("products create --name <name> --tag <tag>")
     ductape_cli("products environments list <tag> --json")
     ductape_cli("products environments get <tag> <slug> --json")
@@ -501,8 +505,8 @@ ALL params are passed as a JSON array in positional order matching the SDK signa
   notifications.fetch    [product_tag, notif_tag]
   notifications.list     [product_tag]
   notifications.delete   [product_tag, notif_tag]
-  notifications.messages.create  [product_tag, data: { tag: string, notification: string, subject?: { template: string, data: object }, body?: { template: string, data: object } }]
-  notifications.messages.update  [product_tag, msg_tag, data: { subject?: { template: string, data: object }, body?: { template: string, data: object } }]
+  notifications.messages.create  [product_tag, data: { tag: string, name: string, description?: string, push_notification?: { title: string, body: string, data?: object }, email?: { subject: string, template: string }, callback?: object, sms?: string }]
+  notifications.messages.update  [product_tag, msg_tag, data: { name?: string, description?: string, push_notification?: { title: string, body: string, data?: object }, email?: { subject: string, template: string }, callback?: object, sms?: string }]
   notifications.messages.fetch   [product_tag, msg_tag]
   notifications.messages.list    [product_tag, notification_tag]
   notifications.send     [{ product, env, event, input: { ... } }]  ← CALL ductape_generate_payload FIRST (operation_family="notification", method="send", targets={notification})
@@ -794,7 +798,7 @@ ALL params are passed as a JSON array in positional order matching the SDK signa
       // ctx.graph.execute({ graph, action, input })
       // ctx.notification.send/email/push/sms({ notification, event, ... })
       // ctx.storage.upload/download({ storage, event, input })
-      // ctx.messaging.produce({ event: "broker:topic", message: {} })
+      // ctx.events.produce({ event: "broker:topic", message: {} })
       // ctx.quota.execute({ quota, input })
       // ctx.fallback.execute({ fallback, input })
       // ctx.healthcheck.getStatus(tag)
@@ -1224,6 +1228,7 @@ const ADMIN_SUBCOMMANDS = [
   'link', 'unlink', 'init',
   'products', 'apps',
   'resources',
+  'notifications',
   'events',
   'cloud',
   'secrets',
@@ -1288,7 +1293,9 @@ function runCli(command: string): { success: boolean; output: string } {
   try {
     const output = execSync(`ductape ${finalCommand}`, {
       encoding: 'utf8',
-      timeout: 30000,
+      // Must exceed the proxy's operation timeout so stderr can preserve the structured timeout
+      // instead of this wrapper killing the CLI first and reducing it to "(no data)".
+      timeout: 90000,
       stdio: ['pipe', 'pipe', 'pipe'],
     });
     return { success: true, output: output.trim() };
@@ -2264,22 +2271,54 @@ ADMINISTRATION — CLI (never ductape_execute)
   ductape_cli("notifications messages get --tag <notification:message> --json")
   ductape_cli("notifications messages update --tag <notification:message> -f patch.json")
   Declarative alternative: ductape/notifications.json then ductape_cli("apply notifications").
+  The file MUST be a top-level JSON array. Each item is a notification definition and may contain
+  a nested "messages" array. {"notifications":[],"messages":[]} is not a valid envelope.
 
 Notification definition:
   {
-    tag: "welcome-email",
+    tag: "welcome-email", // component tags cannot contain ":"
     name: "Welcome Email",
-    type: "email",   // optional hint; actual channels configured per env
+    description: "Transactional welcome messages",
+    envs: [{
+      slug: "prd",
+      emails: {
+        provider: "smtp",
+        smtp: {
+          host: "smtp.example.com",
+          port: "$Secret{smtp-port}",
+          sender_email: "hello@example.com",
+          auth: { user: "$Secret{smtp-user}", pass: "$Secret{smtp-password}" },
+          secure: true
+        }
+      }
+    }],
+    messages: []
   }
 
 Create a message template through declarative apply or Workbench:
   {
-    tag: "welcome-email:default",       // format: "notification_tag:message_tag"
-    notification: "welcome-email",
-    subject: { template: "Welcome, {{name}}!", data: { name: "" } },
-    body:    { template: "Hi {{name}}, thanks for signing up.", data: { name: "" } },
+    tag: "welcome-email:default", // message tags use component-tag:message-tag
+    name: "Default welcome",
+    description: "Sent after account creation",
+    push_notification: {
+      title: "Welcome, {{name}}!",
+      body: "Thanks for signing up.",
+      data: {}
+    },
+    email: {
+      subject: "Welcome, {{name}}!",
+      template: "Hi {{name}}, thanks for signing up."
+    }
   }
 
+TAG AND SMTP RULES
+  Component tag: "game-alerts-critical" (no colon).
+  Message tag: "game-alerts-critical:match-launch" (one colon separator).
+  Do not add "notification", "subject", or "body" at message root.
+  SMTP requires emails.smtp.sender_email.
+  emails.smtp.secure is a boolean and cannot be a $Secret{...} string.
+  Credential strings such as auth.user and auth.pass may use $Secret{...}.
+
 Send at runtime (one channel at a time):
   → CALL ductape_generate_payload FIRST (operation_family="notification", method="email.send")
   notifications.email.send    [{ product, env, notification, input: { recipients, subject?, template? } }]
@@ -2327,6 +2366,10 @@ FIREBASE THROUGH A GCP CLOUD CONNECTION
     }
   The SDK requests current GCP credentials from the cloud connection at send time. Never put the
   service-account private key in the notification file. Expo does not use a GCP cloud connection.
+  The recommended cloud connection scope is "notifications". It expresses Ductape capability/UI
+  intent; creating a notification does not prove Google-side FCM permission. Runtime delivery
+  requires fcm.googleapis.com and roles/firebasecloudmessaging.admin, so validate the connection
+  and perform a delivery test.
 Notification tag and message tag are ALWAYS passed together as "notification_tag:message_tag".
 `.trim(),
 
@@ -2696,9 +2739,11 @@ STEP 4 — PRESENT the plan and get approval BEFORE writing any code or creating
 STEP 5 — CREATE missing components (only with user approval)
   Administrative assets must never be created through ductape_execute. Use ductape_cli for products,
   apps, supported resources, broker topics, cloud connections, secrets, and declarative apply flows.
-  App actions, auths, Features, quotas, fallbacks, health checks, and other assets for which the CLI
-  has no command must be configured in Workbench. Do not generate an impossible publishable-key
-  create/update call. For a missing database action, configure it in Workbench, then verify it exists.
+  App actions, auths, quotas, fallbacks, health checks, and other administrative assets for which
+  the CLI has no command must be configured in Workbench. Feature definitions are the exception:
+  they are code-first via features.define, are registered by application boot/runtime initialization,
+  and cannot be created with the CLI. Do not generate a Workbench-only or publishable-key
+  create/update call for a Feature. For a missing database action, configure it in Workbench, then verify it exists.
   For a missing child feature, recursively apply this same workflow.
   Tell the user what you are about to create before each tool call.
 
@@ -2807,7 +2852,9 @@ When you call features.define({ handler }), the handler runs TWICE:
   Features do NOT execute arbitrary NestJS or server code directly. A feature handler can only
   call Ductape component primitives (ctx.api, ctx.database, ctx.notification, etc.) as steps.
   To invoke internal application business logic, produce a broker event from a feature step
-  (ctx.messaging.produce) and consume it in your NestJS service — that is the correct pattern.
+  (ctx.events.produce in the currently published SDK) and consume it in your NestJS service.
+  ctx.publish is deprecated; do not use it. Do not assume a ctx.messaging alias exists unless the
+  installed SDK types explicitly expose it.
 
 ━━━ ORCHESTRATION DECISION RULE ━━━
 
@@ -2821,7 +2868,7 @@ When you call features.define({ handler }), the handler runs TWICE:
     → define a Feature, then features.dispatch to schedule it
 
   Invoke internal application business logic (your own NestJS/backend service code):
-    → produce a broker event (ctx.messaging.produce or ductape.events.produce)
+    → produce a broker event (ctx.events.produce inside a Feature, or ductape.events.produce outside it)
     → follow ductape_docs({ topic: "events" }) and use the canonical NestJS decorator:
       @Events.Consumer({ event: "broker-tag:topic-tag" })
       async handle(message: MessageShape) { /* injected-service business logic; throw to nack */ }
@@ -3764,8 +3811,9 @@ const cliInputSchema = z.object({
     'Use this tool for administrative operations: creating or updating products, apps, ' +
     'resources (databases, storage, caches…), event broker topics, cloud connections, secrets, ' +
     'and for apply/migrate workflows.\n\n' +
-    'Note: environments, app actions, features, quotas, fallbacks, and jobs are configured ' +
-    'in the Workbench UI — there are no CLI commands for them.\n\n' +
+    'Note: environments, app actions, quotas, fallbacks, and jobs are configured in the ' +
+    'Workbench UI. Features also have no CLI creation command: define them in application code ' +
+    'with features.define so application boot/runtime registration makes them available.\n\n' +
     'The CLI uses the user\'s local logged-in session (ductape login) — no key is required.',
   ),
 });
@@ -3861,8 +3909,10 @@ async function main() {
     const isAuthCommand = firstWord === 'login' || firstWord === 'logout';
 
     if (!isAuthCommand) {
-      // Check login status once per process (cached after first call)
-      if (authState === 'unknown') {
+      // Cache successful authentication, but re-check a missing/expired session on every call.
+      // The user may complete `ductape login` in another terminal while this MCP process remains
+      // alive; caching "none" would otherwise make the MCP blind to the newly written session.
+      if (authState === 'unknown' || authState === 'none') {
         checkLoginState();
       }
       if (authState === 'none') {
@@ -4223,12 +4273,16 @@ async function main() {
           '    Message brokers are import-only (no provision-persist). Import flow is the same as storage.\n' +
           '    type field = "messageBrokers" (not "messagebrokers" or "events").\n' +
           '    After importing, create topics first with ductape_cli("events topics create -f topic.json") — SQS requires explicit topic creation with queueUrls. For other providers, topics auto-register on first produce but should still be created explicitly before any consumer subscribes.\n' +
-          '  - Listing workspaces, products, secrets\n' +
+          '  - Listing workspaces, products, focused product components, secrets\n' +
+          '    Prefer "products components list --tag <tag> --json" for compact inventory; use\n' +
+          '    "products components get --tag <tag> --type notifications|events --json" for focused detail.\n' +
+          '  - Managing notification components and message templates through "resources notifications" and "notifications messages"\n' +
           '  - Linking a project folder: "link --product <tag> --env <slug>"\n' +
           '  - Syncing sessions/notifications/events: "apply" or "apply sessions" etc.\n' +
           '  - Running database migrations: "db migrate", "db schema generate"\n\n' +
-          'NOTE: Environments, app actions, auths, features, quotas, fallbacks, and jobs are ' +
-          'configured in the Workbench UI — the CLI does not have commands for them.\n\n' +
+          'NOTE: Environments, app actions, auths, quotas, fallbacks, and jobs are configured ' +
+          'in the Workbench UI. Features have no CLI creation command because definitions are ' +
+          'code-first through features.define and registered by the application runtime.\n\n' +
           'DO NOT use ductape_execute for admin operations — it uses a publishable key which only ' +
           'covers runtime operations. Administrative operations will fail with "Authentication failed".\n\n' +
           'The CLI uses the user\'s local logged-in session (ductape login). ' +

package/src/proxy-client.ts

@@ -137,9 +137,15 @@ function normalizeTargets(targets: Record<string, unknown>): Record<string, unkn
 export async function generateExecutablePayload<T = IGenerateExecutablePayloadResponse>(
   request: IGenerateExecutablePayloadRequest,
 ): Promise<T> {
+  // execution_context is MCP guidance metadata, not part of the integrations
+  // payload-generator API contract. Keep it for local session-awareness output
+  // but never forward it to the backend validator.
+  const { execution_context: _executionContext, ...backendRequest } = request;
   const normalizedRequest = {
-    ...request,
-    targets: request.targets ? normalizeTargets(request.targets as Record<string, unknown>) : request.targets,
+    ...backendRequest,
+    targets: backendRequest.targets
+      ? normalizeTargets(backendRequest.targets as Record<string, unknown>)
+      : backendRequest.targets,
   };
   const url = `${API_BASE_URL.replace(/\/$/, '')}/integrations/v1/payloads/generate`;
   const res = await fetch(url, {