@ductape/mcp 0.1.20 → 0.1.22

package/dist/index.js

@@ -99,11 +99,15 @@ There are THREE categories of operations. Use the right tool for each:
   2. RUNTIME OPERATIONS  (run, dispatch, execute, start, send, produce, query, insert, update, delete…)
        The "input" field shape is product- and operation-specific — it is NOT derivable from Joi validators.
        It is defined by how the product's action/feature/session/quota/etc. was configured in Ductape.
-       → ALWAYS call ductape_generate_payload first to get the canonical payload template.
+       → ALWAYS call ductape_generate_payload first to get the canonical payload template, EXCEPT for
+         messaging (produce/consume/dispatch) — see the Events section for why.
        → The template shows you exactly which input keys are expected and their types/defaults.
        → Then fill in the values and pass the completed payload to ductape_execute.
+       → Applies to: actions, features, sessions, notifications, databases, storage, graphs, vectors,
+         quotas, fallbacks, jobs, and any other operation that executes against a pre-configured schema.
 
-  Skipping ductape_generate_payload for runtime operations will produce incorrect or empty input payloads.
+  Skipping ductape_generate_payload for applicable runtime operations will produce incorrect or empty input payloads.
+  Exception: messaging produce/consume/dispatch — the producer defines the schema, so infer from context instead.
 
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
@@ -305,9 +309,9 @@ ALL params are passed as a JSON array in positional order matching the SDK signa
     sample?: object, idempotent?: boolean, queueUrls?: [{ env_slug: string, url: string }] }]
   messageBrokers.topics.fetch  [product_tag, topic_tag]
   messageBrokers.topics.list   [product_tag, broker_tag]
-  messageBrokers.produce  [{ product, env, event: "broker_tag:topic_tag", message: { key: value }, session?, cache? }]  ← CALL ductape_generate_payload FIRST (operation_family="messaging", method="produce", targets={broker, event})
+  messageBrokers.produce  [{ product, env, event: "broker_tag:topic_tag", message: { key: value }, session?, cache? }]
   messageBrokers.consume  [{ product, env, event: "broker_tag:topic_tag", callback: "function_ref" }]
-  messageBrokers.dispatch [{ product, env, broker, event, input: { message }, retries?, session?, cache?, schedule?: { cron?, every?, start_at? } }]  ← CALL ductape_generate_payload FIRST (operation_family="messaging", method="dispatch")
+  messageBrokers.dispatch [{ product, env, broker, event, input: { message }, retries?, session?, cache?, schedule?: { cron?, every?, start_at? } }]
   messageBrokers.messages.query [{ product, env, brokerTag, topicTag?, producerTag?, consumerTag?, status?, startDate?, endDate?, page?, limit? }]
   messageBrokers.messages.getProducers [{ product, env, brokerTag, topicTag?, page?, limit? }]
   messageBrokers.messages.getConsumers [{ product, env, brokerTag, topicTag?, page?, limit? }]
@@ -2063,25 +2067,45 @@ Import (register an EXISTING cloud resource):
   List topics on a broker:
     ductape_execute("messageBrokers.topics.list", [product_tag, "broker-tag"])
 
-━━━ RUNTIME: PRODUCE AND CONSUME ━━━
+━━━ STEP 3: PRODUCE AND CONSUME — WRITTEN IN APPLICATION CODE ━━━
 
-  Produce (publish a message):
-    → CALL ductape_generate_payload FIRST (operation_family="messaging", method="produce")
-    messageBrokers.produce [{ product, env, event: "broker_tag:topic_tag", message: { key: value } }]
-    Idempotent publish (deduplicates by key, default TTL 86400 s):
-      messageBrokers.publishIdempotent [{ product, env, event, message, idempotency_key, ttl? }]
+  There is NO admin command or file to declare producers/consumers.
+  There is NO "create producer" step before writing code.
+  Producers and consumers are registered automatically by the SDK the first time your code calls
+  produce/consume — you do not pre-declare them.
 
-  Consume (subscribe):
-    messageBrokers.consume [{ product, env, event: "broker_tag:topic_tag",
-      callback: async (message) => { ... } }]
+  The entire producer/consumer contract is the code you write in your controllers or services:
+
+  Produce (publish a message) — write in your service/controller:
+    Do NOT call ductape_generate_payload for messaging. Events have no pre-existing backend schema
+    to discover — the producer defines the schema. Instead, infer the message shape from context
+    (event name, existing data models, user input), present it to the user for approval, then implement.
+    await ductape.events.produce({
+      product: "my-product",
+      env: "prd",
+      event: "broker_tag:topic_tag",   // "broker_tag:topic_tag" — always colon-separated
+      message: { key: value },         // shape inferred from context, approved by user
+    });
+    Idempotent publish (deduplicates by key):
+      await ductape.events.publishIdempotent({ product, env, event, message, idempotencyKey, idempotencyTtl? })
+
+  Consume (subscribe) — write in your service/controller:
+    await ductape.events.consume({
+      product: "my-product",
+      env: "prd",
+      event: "broker_tag:topic_tag",
+      callback: async (message) => { /* handle message */ },
+    });
     Callback errors are re-thrown so the broker can nack/retry.
 
-  Background dispatch with scheduling:
-    messageBrokers.dispatch [{ product, env, broker, event, input: { message },
-      schedule?: { start_at?, cron?, every?, limit?, endDate?, tz? } }]
-    → CALL ductape_generate_payload FIRST (operation_family="messaging", method="dispatch")
+  Background dispatch with scheduling — write in your service/controller:
+    await ductape.events.dispatch({ product, env, broker, event, input: { message },
+      schedule?: { start_at?, cron?, every?, limit?, endDate?, tz? } })
+
+  For the four standard producer declarations (match-state, match-report, projection-updated,
+  notification), write these produce calls in the relevant application service methods — there is
+  no separate configuration file or CLI step. The SDK creates the producer metadata on first call.
 
-Event format string: "broker_tag:topic_tag" — always colon-separated.
 Message payload is AES-encrypted before the tracking API call — tracking never sees plaintext.
 
 ━━━ OBSERVABILITY ━━━

package/package.json

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

package/src/index.ts

@@ -110,11 +110,15 @@ There are THREE categories of operations. Use the right tool for each:
   2. RUNTIME OPERATIONS  (run, dispatch, execute, start, send, produce, query, insert, update, delete…)
        The "input" field shape is product- and operation-specific — it is NOT derivable from Joi validators.
        It is defined by how the product's action/feature/session/quota/etc. was configured in Ductape.
-       → ALWAYS call ductape_generate_payload first to get the canonical payload template.
+       → ALWAYS call ductape_generate_payload first to get the canonical payload template, EXCEPT for
+         messaging (produce/consume/dispatch) — see the Events section for why.
        → The template shows you exactly which input keys are expected and their types/defaults.
        → Then fill in the values and pass the completed payload to ductape_execute.
+       → Applies to: actions, features, sessions, notifications, databases, storage, graphs, vectors,
+         quotas, fallbacks, jobs, and any other operation that executes against a pre-configured schema.
 
-  Skipping ductape_generate_payload for runtime operations will produce incorrect or empty input payloads.
+  Skipping ductape_generate_payload for applicable runtime operations will produce incorrect or empty input payloads.
+  Exception: messaging produce/consume/dispatch — the producer defines the schema, so infer from context instead.
 
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
@@ -316,9 +320,9 @@ ALL params are passed as a JSON array in positional order matching the SDK signa
     sample?: object, idempotent?: boolean, queueUrls?: [{ env_slug: string, url: string }] }]
   messageBrokers.topics.fetch  [product_tag, topic_tag]
   messageBrokers.topics.list   [product_tag, broker_tag]
-  messageBrokers.produce  [{ product, env, event: "broker_tag:topic_tag", message: { key: value }, session?, cache? }]  ← CALL ductape_generate_payload FIRST (operation_family="messaging", method="produce", targets={broker, event})
+  messageBrokers.produce  [{ product, env, event: "broker_tag:topic_tag", message: { key: value }, session?, cache? }]
   messageBrokers.consume  [{ product, env, event: "broker_tag:topic_tag", callback: "function_ref" }]
-  messageBrokers.dispatch [{ product, env, broker, event, input: { message }, retries?, session?, cache?, schedule?: { cron?, every?, start_at? } }]  ← CALL ductape_generate_payload FIRST (operation_family="messaging", method="dispatch")
+  messageBrokers.dispatch [{ product, env, broker, event, input: { message }, retries?, session?, cache?, schedule?: { cron?, every?, start_at? } }]
   messageBrokers.messages.query [{ product, env, brokerTag, topicTag?, producerTag?, consumerTag?, status?, startDate?, endDate?, page?, limit? }]
   messageBrokers.messages.getProducers [{ product, env, brokerTag, topicTag?, page?, limit? }]
   messageBrokers.messages.getConsumers [{ product, env, brokerTag, topicTag?, page?, limit? }]
@@ -2132,25 +2136,45 @@ Import (register an EXISTING cloud resource):
   List topics on a broker:
     ductape_execute("messageBrokers.topics.list", [product_tag, "broker-tag"])
 
-━━━ RUNTIME: PRODUCE AND CONSUME ━━━
+━━━ STEP 3: PRODUCE AND CONSUME — WRITTEN IN APPLICATION CODE ━━━
 
-  Produce (publish a message):
-    → CALL ductape_generate_payload FIRST (operation_family="messaging", method="produce")
-    messageBrokers.produce [{ product, env, event: "broker_tag:topic_tag", message: { key: value } }]
-    Idempotent publish (deduplicates by key, default TTL 86400 s):
-      messageBrokers.publishIdempotent [{ product, env, event, message, idempotency_key, ttl? }]
+  There is NO admin command or file to declare producers/consumers.
+  There is NO "create producer" step before writing code.
+  Producers and consumers are registered automatically by the SDK the first time your code calls
+  produce/consume — you do not pre-declare them.
 
-  Consume (subscribe):
-    messageBrokers.consume [{ product, env, event: "broker_tag:topic_tag",
-      callback: async (message) => { ... } }]
+  The entire producer/consumer contract is the code you write in your controllers or services:
+
+  Produce (publish a message) — write in your service/controller:
+    Do NOT call ductape_generate_payload for messaging. Events have no pre-existing backend schema
+    to discover — the producer defines the schema. Instead, infer the message shape from context
+    (event name, existing data models, user input), present it to the user for approval, then implement.
+    await ductape.events.produce({
+      product: "my-product",
+      env: "prd",
+      event: "broker_tag:topic_tag",   // "broker_tag:topic_tag" — always colon-separated
+      message: { key: value },         // shape inferred from context, approved by user
+    });
+    Idempotent publish (deduplicates by key):
+      await ductape.events.publishIdempotent({ product, env, event, message, idempotencyKey, idempotencyTtl? })
+
+  Consume (subscribe) — write in your service/controller:
+    await ductape.events.consume({
+      product: "my-product",
+      env: "prd",
+      event: "broker_tag:topic_tag",
+      callback: async (message) => { /* handle message */ },
+    });
     Callback errors are re-thrown so the broker can nack/retry.
 
-  Background dispatch with scheduling:
-    messageBrokers.dispatch [{ product, env, broker, event, input: { message },
-      schedule?: { start_at?, cron?, every?, limit?, endDate?, tz? } }]
-    → CALL ductape_generate_payload FIRST (operation_family="messaging", method="dispatch")
+  Background dispatch with scheduling — write in your service/controller:
+    await ductape.events.dispatch({ product, env, broker, event, input: { message },
+      schedule?: { start_at?, cron?, every?, limit?, endDate?, tz? } })
+
+  For the four standard producer declarations (match-state, match-report, projection-updated,
+  notification), write these produce calls in the relevant application service methods — there is
+  no separate configuration file or CLI step. The SDK creates the producer metadata on first call.
 
-Event format string: "broker_tag:topic_tag" — always colon-separated.
 Message payload is AES-encrypted before the tracking API call — tracking never sees plaintext.
 
 ━━━ OBSERVABILITY ━━━