@ductape/mcp 0.1.0 → 0.1.1

package/dist/index.d.ts

@@ -5,7 +5,9 @@
  * Exposes Ductape SDK operations as MCP tools by calling the backend proxy.
  *
  * Authentication:
- * Requires passing a `publishable_key` with every `ductape_execute` payload.
+ * Set DUCTAPE_PUBLISHABLE_KEY in the MCP server's env config to avoid passing
+ * publishable_key on every tool call. Per-call publishable_key still overrides
+ * the env var when provided.
  */
 export {};
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;;GAOG"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;;;;GASG"}

package/dist/index.js

@@ -5,10 +5,12 @@
  * Exposes Ductape SDK operations as MCP tools by calling the backend proxy.
  *
  * Authentication:
- * Requires passing a `publishable_key` with every `ductape_execute` payload.
+ * Set DUCTAPE_PUBLISHABLE_KEY in the MCP server's env config to avoid passing
+ * publishable_key on every tool call. Per-call publishable_key still overrides
+ * the env var when provided.
  */
 import { z } from 'zod';
-import { executeViaProxy, generateExecutablePayload, } from './proxy-client.js';
+import { executeViaProxy, generateExecutablePayload, getAssetSchemas, } from './proxy-client.js';
 const MODULES = [
     'product', 'app', 'databases', 'graph', 'webhooks', 'notifications',
     'messageBrokers', 'storage', 'vector', 'caches', 'sessions', 'quotas',
@@ -19,6 +21,32 @@ const MODULES = [
 // Each entry follows: [module].[method] → params array signature.
 // ─────────────────────────────────────────────────────────────────────────────
 const METHOD_DOCS = `
+━━━ TOOL SELECTION GUIDE ━━━
+
+There are two categories of SDK operations. Use the right tool for each:
+
+  1. ASSET CREATION / UPDATE  (create, update, add, register…)
+       Input shape is fixed by the SDK's Joi validators.
+       → Call ductape_schema first to discover required fields and enum values.
+       → Then call ductape_execute with the filled params.
+       EXCEPTION — features.create / quotas.create / fallback.create have TWO distinct input fields:
+         a) Top-level "input": a SCHEMA DECLARATION — defines what fields the asset accepts at runtime.
+            Construct this yourself based on what the caller will provide. Do NOT use ductape_generate_payload for this.
+         b) options[].input (quotas/fallbacks) or steps[].input (features): maps declared inputs → the underlying action's fields.
+            ← CALL ductape_generate_payload for the target action to discover what fields it accepts,
+              then wire them using "$Input{fieldName}" or "$Step{stepTag}{field}" references.
+
+  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.
+       → 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.
+
+  Skipping ductape_generate_payload for runtime operations will produce incorrect or empty input payloads.
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
 ALL params are passed as a JSON array in positional order matching the SDK signature.
 
 ━━━ MODULE: product ━━━
@@ -47,8 +75,8 @@ ALL params are passed as a JSON array in positional order matching the SDK signa
   actions.update  [app_tag, action_tag, data: { resource?: string, method?: "GET"|"POST"|"PUT"|"PATCH"|"DELETE", description?: string, request_type?: "json"|"xml"|"form", body?: object, query?: object, params?: object, headers?: object, response?: { name?: string, success: boolean, body: object, response_format: "json"|"xml"|"form", status_code: number } }]
   actions.fetch   [app_tag, action_tag]
   actions.list    [app_tag]
-  actions.run     [{ product, env, app, action, input: { "body:fieldName": value, "headers:Authorization": "Bearer token", "params:id": "123", "query:limit": 10 } }]
-  actions.dispatch [{ product, env, app, action, input, retries?, session?, cache?, schedule?: { start_at?, cron?, every?, limit?, tz? } }]
+  actions.run     [{ product, env, app, action, input: { "body:fieldName": value, ... } }]  ← CALL ductape_generate_payload FIRST (operation_family="action", method="run", targets={app, action})
+  actions.dispatch [{ product, env, app, action, input, retries?, session?, cache?, schedule?: { start_at?, cron?, every?, limit?, tz? } }]  ← CALL ductape_generate_payload FIRST (operation_family="action", method="dispatch")
 
 ━━━ MODULE: auths ━━━
   auths.create  [app_tag, data: { tag: string, name: string, setup_type: "header"|"bearer"|"basic"|"oauth2"|"apikey", expiry: number, period: "seconds"|"minutes"|"hours"|"days", description: string, action_tag?: string }]
@@ -72,7 +100,7 @@ ALL params are passed as a JSON array in positional order matching the SDK signa
   sessions.fetch         [product_tag, session_tag]
   sessions.list          [product_tag]
   sessions.delete        [product_tag, session_tag]
-  sessions.start         [{ product, env, tag, data: { key: value } }]
+  sessions.start         [{ product, env, tag, data: { key: value } }]  ← CALL ductape_generate_payload FIRST (operation_family="session", method="start", targets={tag}) to discover the data field shape
   sessions.verify        [{ product, env, tag, token }]
   sessions.refresh       [{ product, env, tag, refreshToken }]
   sessions.revoke        [{ product, env, tag, sessionId?, identifier? }]
@@ -86,13 +114,18 @@ ALL params are passed as a JSON array in positional order matching the SDK signa
     tag: string,                          // unique identifier
     name?: string,                        // display name
     description?: string,
-    input: {                              // declare the input fields this quota expects
+
+    // INPUT SCHEMA (top-level): declares what fields the quota accepts when called at runtime.
+    // These are the fields callers will pass to quotas.run / quotas.dispatch.
+    // Construct this yourself — it is a schema declaration, not a runtime value.
+    input: {
       fieldName: {
         type: "string"|"number"|"boolean"|"object"|"array",
         required?: boolean,
         description?: string
       }
     },
+
     options: [                            // list of providers tried in order
       {
         provider?: string,                // friendly name for this provider slot
@@ -101,7 +134,12 @@ ALL params are passed as a JSON array in positional order matching the SDK signa
         event: string,                    // action tag on that app
         quota: number,                    // max allowed uses for this provider
         uses?: number,                    // current use count (usually 0 at creation)
-        input: { "body:field": "$Input{fieldName}" },   // maps quota input → action input
+
+        // OPTIONS INPUT (per provider): maps the quota's declared input fields → the underlying action's fields.
+        // ← CALL ductape_generate_payload (operation_family="action", method="run", targets={app, event})
+        //   to discover what fields the action accepts, then wire them with "$Input{fieldName}" references.
+        input: { "body:field": "$Input{fieldName}" },
+
         output: {},                       // expected output shape (can be {})
         retries: number,
         healthcheck?: string,             // optional healthcheck tag to gate this provider
@@ -113,28 +151,38 @@ ALL params are passed as a JSON array in positional order matching the SDK signa
   quotas.fetch    [product_tag, quota_tag]
   quotas.list     [product_tag]
   quotas.delete   [product_tag, quota_tag]
-  quotas.run      [{ product: string, env: string, tag: string, input: { fieldName: value }, session?: string, cache?: string }]
-  quotas.dispatch [{ product: string, env: string, tag: string, input: object, session?: string, cache?: string, schedule?: { cron?: string, delay?: number, at?: string } }]
+  quotas.run      [{ product: string, env: string, tag: string, input: { fieldName: value }, session?: string, cache?: string }]  ← CALL ductape_generate_payload FIRST (operation_family="quota", method="run", targets={tag})
+  quotas.dispatch [{ product: string, env: string, tag: string, input: object, session?: string, cache?: string, schedule?: { cron?: string, delay?: number, at?: string } }]  ← CALL ductape_generate_payload FIRST (operation_family="quota", method="dispatch")
 
 ━━━ MODULE: fallback ━━━
   fallback.create   [product_tag, data: {
     tag: string,
     name?: string,
     description?: string,
-    input: {                              // input fields this fallback expects
+
+    // INPUT SCHEMA (top-level): declares what fields the fallback accepts when called at runtime.
+    // These are the fields callers will pass to fallback.run / fallback.dispatch.
+    // Construct this yourself — it is a schema declaration, not a runtime value.
+    input: {
       fieldName: {
         type: "string"|"number"|"boolean"|"object"|"array",
         required?: boolean,
         description?: string
       }
     },
+
     options: [                            // ordered list: primary first, then fallback(s)
       {
         provider?: string,                // friendly name e.g. "primary", "backup"
         app: string,                      // app tag
         type: "action",
         event: string,                    // action tag
+
+        // OPTIONS INPUT (per provider): maps the fallback's declared input fields → the underlying action's fields.
+        // ← CALL ductape_generate_payload (operation_family="action", method="run", targets={app, event})
+        //   to discover what fields the action accepts, then wire them with "$Input{fieldName}" references.
         input: { "body:field": "$Input{fieldName}" },
+
         output: {},
         retries: number,
         healthcheck?: string,
@@ -146,12 +194,12 @@ ALL params are passed as a JSON array in positional order matching the SDK signa
   fallback.fetch    [product_tag, fallback_tag]
   fallback.list     [product_tag]
   fallback.delete   [product_tag, fallback_tag]
-  fallback.run      [{ product: string, env: string, tag: string, input: { fieldName: value }, session?: string, cache?: string }]
-  fallback.dispatch [{ product: string, env: string, tag: string, input: object, session?: string, cache?: string, schedule?: { cron?: string, delay?: number, at?: string } }]
+  fallback.run      [{ product: string, env: string, tag: string, input: { fieldName: value }, session?: string, cache?: string }]  ← CALL ductape_generate_payload FIRST (operation_family="fallback", method="run", targets={tag})
+  fallback.dispatch [{ product: string, env: string, tag: string, input: object, session?: string, cache?: string, schedule?: { cron?: string, delay?: number, at?: string } }]  ← CALL ductape_generate_payload FIRST (operation_family="fallback", method="dispatch")
 
 ━━━ MODULE: health ━━━
-  health.create   [product_tag, data: { tag: string, name: string, description?: string, app?: string, event?: string, probe?: { type: "app"|"database"|"workflow"|"feature", app?: string, event?: string, input?: object }, interval: number, retries: number, envs: [{ slug: string, input?: object }], onFailure?: { notifications?: [{ notification: string, message: string, channels: { email?: { recipients: string[] }, push?: { recipients?: string[] }, sms?: { recipients: string[] } } }], webhooks?: [{ url: string, method?: "GET"|"POST", headers?: object, body?: object }] } }]
-  health.update   [product_tag, health_tag, data: { name?: string, description?: string, app?: string, event?: string, probe?: { type: "app"|"database"|"workflow"|"feature", app?: string, event?: string, input?: object }, interval?: number, retries?: number, envs?: [{ slug: string, input?: object }], onFailure?: object }]
+  health.create   [product_tag, data: { tag: string, name: string, description?: string, app?: string, event?: string, probe?: { type: "app"|"database"|"feature", app?: string, event?: string, input?: object }, interval: number, retries: number, envs: [{ slug: string, input?: object }], onFailure?: { notifications?: [{ notification: string, message: string, channels: { email?: { recipients: string[] }, push?: { recipients?: string[] }, sms?: { recipients: string[] } } }], webhooks?: [{ url: string, method?: "GET"|"POST", headers?: object, body?: object }] } }]
+  health.update   [product_tag, health_tag, data: { name?: string, description?: string, app?: string, event?: string, probe?: { type: "app"|"database"|"feature", app?: string, event?: string, input?: object }, interval?: number, retries?: number, envs?: [{ slug: string, input?: object }], onFailure?: object }]
   health.fetch    [product_tag, health_tag]
   health.list     [product_tag]
   health.delete   [product_tag, health_tag]
@@ -169,12 +217,12 @@ ALL params are passed as a JSON array in positional order matching the SDK signa
   notifications.messages.update  [product_tag, msg_tag, data: { subject?: { template: string, data: object }, body?: { template: string, data: object } }]
   notifications.messages.fetch   [product_tag, msg_tag]
   notifications.messages.list    [product_tag, notification_tag]
-  notifications.send     [{ product, env, event, input: { email?: { recipients, subject, template }, push_notification?: { device_tokens, title, body, data }, sms?: { recipients, body }, callback?: { query, params, body, headers } } }]
-  notifications.email.send  [{ product, env, notification, input: { recipients: string[], subject: object, template: object }, session?, cache? }]
-  notifications.push.send   [{ product, env, notification, input: { device_tokens: string[], title: object, body: object, data: object }, session?, cache? }]
-  notifications.sms.send    [{ product, env, notification, input: { recipients: string[], body: object }, session?, cache? }]
-  notifications.callback.send [{ product, env, notification, input: { query, params, body, headers }, session?, cache? }]
-  notifications.dispatch   [{ product, env, notification, event, input, retries?, session?, cache?, schedule?: { cron?, every?, start_at? } }]
+  notifications.send     [{ product, env, event, input: { ... } }]  ← CALL ductape_generate_payload FIRST (operation_family="notification", method="send", targets={notification})
+  notifications.email.send  [{ product, env, notification, input: { ... }, session?, cache? }]  ← CALL ductape_generate_payload FIRST (operation_family="notification", method="email.send")
+  notifications.push.send   [{ product, env, notification, input: { ... }, session?, cache? }]  ← CALL ductape_generate_payload FIRST (operation_family="notification", method="push.send")
+  notifications.sms.send    [{ product, env, notification, input: { ... }, session?, cache? }]  ← CALL ductape_generate_payload FIRST (operation_family="notification", method="sms.send")
+  notifications.callback.send [{ product, env, notification, input: { ... }, session?, cache? }]  ← CALL ductape_generate_payload FIRST (operation_family="notification", method="callback.send")
+  notifications.dispatch   [{ product, env, notification, event, input, retries?, session?, cache?, schedule?: { cron?, every?, start_at? } }]  ← CALL ductape_generate_payload FIRST (operation_family="notification", method="dispatch")
   notifications.getMessages [{ product_tag?, env?, notification_tag?, status?, type?, start_date?, end_date?, page?, limit? }]
 
 ━━━ MODULE: messageBrokers ━━━
@@ -187,9 +235,9 @@ ALL params are passed as a JSON array in positional order matching the SDK signa
   messageBrokers.topics.update [product_tag, topic_tag, data: { name?: string, type?: "producer"|"consumer"|"both" }]
   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? }]
+  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.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? } }]
+  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.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? }]
@@ -215,7 +263,7 @@ ALL params are passed as a JSON array in positional order matching the SDK signa
   storage.files.delete   [{ product, env, storage, fileName }]
   storage.files.list     [{ product, env, storage, prefix?, limit?, continuationToken? }]
   storage.files.getSignedUrl [{ product, env, storage, fileName, expiresIn?, action? }]
-  storage.dispatch [{ product, env, storage, operation, input, retries?, session?, cache?, schedule? }]
+  storage.dispatch [{ product, env, storage, operation, input, retries?, session?, cache?, schedule? }]  ← CALL ductape_generate_payload FIRST (operation_family="storage", method="dispatch", targets={storage})
 
 ━━━ MODULE: databases ━━━
   databases.create  [{ product, tag, name, description?, type: "mongodb"|"postgresql"|"mysql"|"sqlite", envs: [{slug, connection_url}] }]
@@ -262,8 +310,8 @@ ALL params are passed as a JSON array in positional order matching the SDK signa
   databases.action.fetch  [action_tag]
   databases.action.list   [database_tag]
   databases.action.delete [action_tag]
-  databases.action.dispatch [{ product, env, database, action, input, schedule? }]
-  databases.dispatch [{ product, env, database, action, input, schedule? }]
+  databases.action.dispatch [{ product, env, database, action, input, schedule? }]  ← CALL ductape_generate_payload FIRST (operation_family="database", method="dispatch", targets={database, action})
+  databases.dispatch [{ product, env, database, action, input, schedule? }]  ← CALL ductape_generate_payload FIRST (operation_family="database", method="dispatch")
 
 ━━━ MODULE: graph ━━━
   graph.create  [{ product, tag, name, description?, type: "neo4j"|"nebula"|"arangodb", envs: [{slug, connection_url, username?, password?}] }]
@@ -316,7 +364,7 @@ ALL params are passed as a JSON array in positional order matching the SDK signa
   graph.beginTransaction [options?]
   graph.commitTransaction [transaction]
   graph.rollbackTransaction [transaction]
-  graph.dispatch [data]
+  graph.dispatch [data]  ← CALL ductape_generate_payload FIRST (operation_family="graph", method="dispatch", targets={graph})
 
 ━━━ MODULE: vector ━━━
   vector.create  [{ product, tag, name, description?, provider: "pinecone"|"qdrant"|"weaviate", dimensions: number, metric?: "cosine"|"euclidean"|"dotproduct", envs: [{slug, api_key, environment?}] }]
@@ -348,19 +396,24 @@ ALL params are passed as a JSON array in positional order matching the SDK signa
   vector.listIndexes    [{ product, env, vector }]
   vector.count          [{ product, env, vector, namespace? }]
 
-━━━ MODULE: workflow ━━━
-  workflow.create  [product_tag, data: {
+━━━ MODULE: features ━━━
+  features.create  [product_tag, data: {
     tag: string,
     name: string,
     description?: string,
+
+    // INPUT SCHEMA (top-level): declares what fields this feature accepts when executed at runtime.
+    // These are the fields callers will pass to features.execute / features.dispatch.
+    // Construct this yourself — it is a schema declaration, not a runtime value.
     input?: { fieldName: { type: string, required?: boolean } },
+
     output?: object,
     envs?: [{ slug: string, active?: boolean }],
     steps: [
       {
         tag: string,              // unique step id
         name?: string,
-        type: "action"|"database"|"graph"|"notification"|"storage"|"publish"|"workflow"|"sleep"|"wait_signal",
+        type: "action"|"database"|"graph"|"notification"|"storage"|"publish"|"feature"|"sleep"|"wait_signal",
         app?: string,             // for type=action
         event?: string,           // action/event tag
         database?: string,        // for type=database
@@ -368,20 +421,25 @@ ALL params are passed as a JSON array in positional order matching the SDK signa
         notification?: string,    // for type=notification
         storage?: string,         // for type=storage
         broker?: string,          // for type=publish
-        workflow?: string,        // for type=workflow (child)
+        feature?: string,         // for type=feature (child feature)
+
+        // STEP INPUT: maps this feature's declared input fields (or prior step outputs) → the step's underlying action/event fields.
+        // ← CALL ductape_generate_payload (operation_family matching step type, method="run", targets={app/event/database/etc.})
+        //   to discover what fields the target accepts, then wire them with "$Input{fieldName}" or "$Step{stepTag}{field}" references.
         input?: { "body:field": "$Input{fieldName}" | "$Step{stepTag}{field}" | literal },
+
         condition?: string,       // e.g. "$Step{validate}{valid} == true"
         dependsOn?: string[],
         options?: { retries?: number, timeout?: number, allow_fail?: boolean, critical?: boolean }
       }
     ]
   }]
-  workflow.update  [product_tag, workflow_tag, data: { name?: string, description?: string, steps?: array, envs?: array }]
-  workflow.fetch   [product_tag, workflow_tag]
-  workflow.fetchAll [product_tag]
-  workflow.delete  [product_tag, workflow_tag]
+  features.update  [product_tag, feature_tag, data: { name?: string, description?: string, steps?: array, envs?: array }]
+  features.fetch   [product_tag, feature_tag]
+  features.fetchAll [product_tag]
+  features.delete  [product_tag, feature_tag]
 
-  workflow.define  [{
+  features.define  [{
     product?: string,
     tag: string,
     name: string,
@@ -396,7 +454,7 @@ ALL params are passed as a JSON array in positional order matching the SDK signa
     recordScenarios?: object[],   // multiple recording scenarios for branching
     branchOverrides?: object,     // force step results during recording to reach later branches
     handler: async (ctx) => {
-      // ctx.input                – typed workflow input
+      // ctx.input                – typed feature input
       // ctx.step(tag, fn, rollback?, opts?)  – define a durable step
       // ctx.action.run({ app, event, input }) – call an app action
       // ctx.database.query/insert/update/delete({ database, event, ... })
@@ -410,11 +468,11 @@ ALL params are passed as a JSON array in positional order matching the SDK signa
       // ctx.sleep(ms|"1h30m")
       // ctx.waitForSignal("signal-name", { timeout? })
       // ctx.setState(key, value) / ctx.getState(key)
-      // ctx.workflow(childId, childTag, childInput) – child workflow
+      // ctx.feature(childId, childTag, childInput) – child feature
     }
   }]
 
-  workflow.execute [{
+  features.execute [{   ← CALL ductape_generate_payload FIRST (operation_family="features", method="execute", targets={tag}) to discover the input field shape
     product: string,
     env: string,
     tag: string,
@@ -426,10 +484,10 @@ ALL params are passed as a JSON array in positional order matching the SDK signa
     timeout?: number
   }]
 
-  workflow.dispatch [{
+  features.dispatch [{   ← CALL ductape_generate_payload FIRST (operation_family="features", method="dispatch", targets={feature})
     product: string,
     env: string,
-    workflow: string,
+    feature: string,
     input: { fieldName: value },
     schedule?: { start_at?: number|string, cron?: string, every?: number, limit?: number, endDate?: number|string, tz?: string },
     session?: string,
@@ -437,18 +495,18 @@ ALL params are passed as a JSON array in positional order matching the SDK signa
     retries?: number
   }]
 
-  workflow.signal  [{ product, env, workflow_id, signal: string, payload?: object }]
-  workflow.query   [{ product, env, workflow_id, query: string, params?: object }]
-  workflow.status  [executionId: string]
-  workflow.cancel  [executionId: string, reason?: string]
-  workflow.replay  [executionId: string, options?: object]
-  workflow.restart [executionId: string]
-  workflow.resume  [executionId: string]
-  workflow.replayFromStep [executionId: string, stepTag: string]
-  workflow.history [executionId: string]
-  workflow.stepDetail [executionId: string, stepTag: string]
-  workflow.relatedExecutions [executionId: string]
-  workflow.compare [executionId1: string, executionId2: string]
+  features.signal  [{ product, env, feature_id, signal: string, payload?: object }]
+  features.query   [{ product, env, feature_id, query: string, params?: object }]
+  features.status  [executionId: string]
+  features.cancel  [executionId: string, reason?: string]
+  features.replay  [executionId: string, options?: object]
+  features.restart [executionId: string]
+  features.resume  [executionId: string]
+  features.replayFromStep [executionId: string, stepTag: string]
+  features.history [executionId: string]
+  features.stepDetail [executionId: string, stepTag: string]
+  features.relatedExecutions [executionId: string]
+  features.compare [executionId1: string, executionId2: string]
 
 ━━━ MODULE: caches ━━━
   caches.create  [{ product, tag, name, description?, type: "redis"|"memcached"|"in-memory", envs: [{slug, connection_url}] }]
@@ -497,37 +555,108 @@ ALL params are passed as a JSON array in positional order matching the SDK signa
 ━━━ MODULE: logs ━━━
   logs.init   [product_tag?, app_tag?]   (at least one required)
   logs.fetch  [{ product_id?, app_id?, env?, level?: "info"|"warn"|"error"|"debug", start_date?, end_date?, page?, limit? }]
+
+━━━ TOOL: ductape_schema ━━━
+  Use this tool to dynamically discover the full field manifest for Ductape asset creation and update operations,
+  derived live from the SDK's Joi validators. No arguments are required to get everything.
+
+  Arguments:
+    module?: "app" | "product"   (optional — omit to get both modules + all enums)
+
+  Returns:
+    When module is omitted:
+      {
+        modules: {
+          app:     { [method: string]: { fields: { [field]: FieldDef } } },
+          product: { [method: string]: { fields: { [field]: FieldDef } } }
+        },
+        enums: {
+          HttpMethods, AuthTypes, DataFormats, DataTypes, StatusCodes, TokenPeriods,
+          DatabaseTypes, AppComponents, ProductComponents, Categories, DefaultTypes,
+          EventTypes, InputsTypes, PublicStates
+        }
+      }
+
+    When module="app" or module="product":
+      { module: string, methods: { [method]: { fields: { [field]: FieldDef } } }, enums: { ... } }
+
+  FieldDef shape:
+    {
+      type: string,           // "string" | "number" | "boolean" | "object" | "array" | "alternatives" | "any"
+      required: boolean,
+      enum?: (string | number | boolean)[],   // present when field is restricted to specific values
+      fields?: { [key]: FieldDef },           // present for nested objects
+      items?: FieldDef,                       // present for arrays (describes each element)
+      oneOf?: FieldDef[],                     // present for alternatives (.try(...))
+      minLength?: number, maxLength?: number, // string length constraints
+      min?: number, max?: number,             // number range constraints
+      pattern?: string                        // string pattern regex
+    }
+
+  Example method keys for app module:
+    "create", "update", "environments.create", "environments.update",
+    "actions.create", "actions.update", "auths.create", "auths.update",
+    "variables.create", "variables.update", "constants.create", "constants.update",
+    "webhooks.create", "webhooks.update", "webhooks.events.create", "webhooks.events.update"
+
+  Example method keys for product module:
+    "create", "environments.create", "environments.update", "apps.add", "apps.update",
+    "databases.create", "databases.update", "notifications.create", "notifications.update",
+    "caches.create", "caches.update", "jobs.create", "jobs.update",
+    "messageBrokers.create", "messageBrokers.update", "fallbacks.create", "fallbacks.update",
+    "graphs.create", "graphs.update", "vectors.create", "vectors.update",
+    "sessions.create", "sessions.update", "healthchecks.create",
+    "quotas.create", "quotas.update", "functions.create", "functions.update",
+    "agents.create", "agents.update", "models.create", "models.update"
+
+  When to use this tool:
+  - Before calling ductape_execute to create or update any asset — use this to discover required fields
+  - To enumerate valid enum values (e.g. which DatabaseTypes or AuthTypes are accepted)
+  - To understand nested object shapes without reading SDK docs
 `;
 const executeInputSchema = z.object({
-    publishable_key: z.string().describe('The publishable key for your workspace. Required for authentication.'),
+    publishable_key: z.string().optional().describe('Your workspace publishable key. Omit if DUCTAPE_PUBLISHABLE_KEY is set in the MCP server env config.'),
     module: z.enum(MODULES).describe('SDK module to target. Options: ' + MODULES.join(', ') + '.'),
     method: z.string().describe('The SDK method to call. Use dot-notation for nested methods (e.g. "environments.create", "schema.addField", "messages.query").\n' +
         'Full reference: see the METHOD_DOCS embedded in the params description.'),
     params: z.array(z.any()).default([]).describe(METHOD_DOCS),
 });
 const payloadGenerateInputSchema = z.object({
-    workspace_id: z.string(),
-    user_id: z.string(),
-    public_key: z.string(),
-    product_tag: z.string(),
-    env_slug: z.string(),
-    operation_family: z.string(),
-    method: z.string(),
-    targets: z.record(z.any()).optional(),
-    include_session: z.boolean().optional().default(true),
-    include_cache: z.boolean().optional().default(true),
-    schema_mode: z.enum(['strict', 'best_effort']).optional().default('best_effort'),
-    input_hint: z.record(z.any()).optional(),
+    publishable_key: z.string().optional().describe('Your workspace publishable key. Omit if DUCTAPE_PUBLISHABLE_KEY is set in the MCP server env config.'),
+    product_tag: z.string().describe('The product tag (e.g. "my-product"). Identifies which product configuration to read.'),
+    env_slug: z.string().describe('The environment slug (e.g. "dev", "prod"). Determines which env-specific values are used.'),
+    operation_family: z.string().describe('The operation category. One of: "action", "features", "database", "graph", "vector", "storage", ' +
+        '"notification", "messaging", "quota", "fallback", "healthcheck", "session", "cache".'),
+    method: z.string().describe('The method within the operation family. E.g. "run", "dispatch", "execute", "start", "send", "produce", ' +
+        '"query", "insert", "update", "delete". Must match an allowed method for the given operation_family.'),
+    targets: z.record(z.any()).optional().describe('Identifies the specific operation to generate a payload for. ' +
+        'For actions: { app: "app_tag", action: "action_tag" }. ' +
+        'For features: { feature: "feature_tag" }. ' +
+        'For databases: { database: "db_tag", action?: "action_tag" }. ' +
+        'For sessions: { session: "session_tag" }. ' +
+        'For notifications: { notification: "notif_tag" }. ' +
+        'For quotas/fallbacks: { tag: "resource_tag" }. ' +
+        'For storage: { storage: "storage_tag" }. ' +
+        'For messaging: { broker: "broker_tag", topic?: "topic_tag" }.'),
+    include_session: z.boolean().optional().default(true).describe('Include session field in the generated payload template.'),
+    include_cache: z.boolean().optional().default(true).describe('Include cache field in the generated payload template.'),
+    schema_mode: z.enum(['strict', 'best_effort']).optional().default('best_effort').describe('"strict" — fail if any required field cannot be resolved. ' +
+        '"best_effort" — fill what is known, leave unknowns as null/placeholder. Use best_effort when exploring.'),
+    input_hint: z.record(z.any()).optional().describe('Optional. Partial input values you already know. These are merged into the generated payload template ' +
+        'so the result is pre-filled. Use this to get a payload with known values already substituted.'),
 });
 const snippetGenerateInputSchema = payloadGenerateInputSchema.extend({
     language: z.enum(['typescript', 'python']).default('typescript'),
 });
+const schemaInputSchema = z.object({
+    module: z.enum(['app', 'product']).optional().describe('Optional. Scope the result to a single module ("app" or "product"). Omit to get the full manifest including enums.'),
+});
 function toPrettyJson(value) {
     return JSON.stringify(value ?? {}, null, 2);
 }
 const ALLOWED_SNIPPET_METHODS = {
     action: ['run', 'dispatch', 'execute'],
-    workflow: ['run', 'dispatch', 'execute'],
+    features: ['run', 'dispatch', 'execute'],
     database: ['dispatch', 'find', 'insert', 'update', 'delete', 'query', 'upsert', 'count', 'aggregate'],
     graph: ['dispatch', 'find', 'insert', 'update', 'delete', 'query', 'execute'],
     vector: ['query', 'find', 'findSimilar', 'upsert', 'insert', 'delete', 'dispatch'],
@@ -557,8 +686,8 @@ function resolveSdkCallPath(operationFamily, method) {
     const m = String(method || '').toLowerCase();
     if (family === 'action')
         return `actions.${m}`;
-    if (family === 'workflow')
-        return `workflow.${m}`;
+    if (family === 'features' || family === 'feature')
+        return `features.${m}`;
     if (family === 'database')
         return m === 'dispatch' ? 'databases.dispatch' : `databases.${m}`;
     if (family === 'graph')
@@ -679,10 +808,11 @@ async function main() {
     const transport = new StdioServerTransport();
     const executeHandler = async (args) => {
         try {
-            if (!args.publishable_key) {
-                throw new Error('Not authenticated. Please provide the `publishable_key` in your tool invocation arguments.');
+            const key = args.publishable_key || process.env.DUCTAPE_PUBLISHABLE_KEY;
+            if (!key) {
+                throw new Error('Not authenticated. Set DUCTAPE_PUBLISHABLE_KEY in your MCP server env config, or pass publishable_key on every tool call.');
             }
-            const result = await executeViaProxy(args.publishable_key, args.module, args.method, args.params);
+            const result = await executeViaProxy(key, args.module, args.method, args.params);
             return { content: [{ type: 'text', text: JSON.stringify(result ?? null, null, 2) }] };
         }
         catch (err) {
@@ -692,7 +822,11 @@ async function main() {
     };
     const payloadGenerateHandler = async (args) => {
         try {
-            const result = await generateExecutablePayload(args);
+            const key = args.publishable_key || process.env.DUCTAPE_PUBLISHABLE_KEY;
+            if (!key) {
+                throw new Error('Not authenticated. Set DUCTAPE_PUBLISHABLE_KEY in your MCP server env config, or pass publishable_key on every tool call.');
+            }
+            const result = await generateExecutablePayload({ ...args, publishable_key: key });
             return { content: [{ type: 'text', text: JSON.stringify(result ?? null, null, 2) }] };
         }
         catch (err) {
@@ -702,8 +836,12 @@ async function main() {
     };
     const snippetGenerateHandler = async (args) => {
         try {
+            const key = args.publishable_key || process.env.DUCTAPE_PUBLISHABLE_KEY;
+            if (!key) {
+                throw new Error('Not authenticated. Set DUCTAPE_PUBLISHABLE_KEY in your MCP server env config, or pass publishable_key on every tool call.');
+            }
             ensureSupportedSnippetOperation(args.operation_family, args.method);
-            const generated = await generateExecutablePayload(args);
+            const generated = await generateExecutablePayload({ ...args, publishable_key: key });
             const payload = generated?.payload ?? {};
             const snippet = buildSnippet(args.language, payload, args.operation_family, args.method);
             return {
@@ -723,15 +861,36 @@ async function main() {
             return { content: [{ type: 'text', text: `Error: ${message}` }], isError: true };
         }
     };
+    const schemaHandler = async (args) => {
+        try {
+            const data = await getAssetSchemas(args.module);
+            return { content: [{ type: 'text', text: JSON.stringify(data ?? null, null, 2) }] };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return { content: [{ type: 'text', text: `Error: ${message}` }], isError: true };
+        }
+    };
     if (typeof server.registerTool === 'function') {
         server.registerTool('ductape_execute', {
             title: 'Ductape SDK Execute',
-            description: 'Execute a Ductape SDK operation via the backend proxy (databases, graph, storage, etc.)',
+            description: 'Execute a Ductape SDK operation via the backend proxy.\n\n' +
+                'IMPORTANT — two-step rule for runtime operations (run, dispatch, execute, start, send, produce, query, insert, update, delete):\n' +
+                '  1. Call ductape_generate_payload first to get the canonical payload template for the specific operation.\n' +
+                '     This reveals the exact "input" field keys and their types — they are product/env/operation-specific.\n' +
+                '  2. Fill in the values from the template, then call ductape_execute.\n\n' +
+                'For asset creation/update operations (create, update, add), use ductape_schema to discover required fields instead.',
             inputSchema: executeInputSchema,
         }, executeHandler);
         server.registerTool('ductape_generate_payload', {
             title: 'Ductape Payload Generator',
-            description: 'Generate canonical executable payload templates and schema metadata for SDK code snippet generation',
+            description: 'Generate the canonical input payload template for a runtime SDK operation.\n\n' +
+                'CALL THIS BEFORE ductape_execute when you need to run, dispatch, execute, start, send, produce, ' +
+                'or otherwise trigger any Ductape operation that takes an "input" field.\n\n' +
+                'The "input" field shape is defined by how each action/feature/session/quota/etc. was configured ' +
+                'in the product — it cannot be inferred from the SDK schema alone. This tool returns the exact ' +
+                'field names, types, and placeholder values for that specific operation in that specific environment.\n\n' +
+                'Returns: { payload: { product, env, input: { fieldName: placeholder, ... }, session?, cache? }, meta: { ... } }',
             inputSchema: payloadGenerateInputSchema,
         }, payloadGenerateHandler);
         server.registerTool('ductape_generate_snippet', {
@@ -739,11 +898,20 @@ async function main() {
             description: 'Generate canonical payload and ready TypeScript/Python snippet for engineers',
             inputSchema: snippetGenerateInputSchema,
         }, snippetGenerateHandler);
+        server.registerTool('ductape_schema', {
+            title: 'Ductape Asset Schema',
+            description: 'Returns the full field manifest for Ductape asset creation/update methods, ' +
+                'derived live from the SDK Joi validators. Includes field types, required flags, ' +
+                'enum values, nested structures, and all enum constants. ' +
+                'Pass module="app" or module="product" to scope the result.',
+            inputSchema: schemaInputSchema,
+        }, schemaHandler);
     }
     else if (typeof server.tool === 'function') {
         server.tool('ductape_execute', executeInputSchema.shape, executeHandler);
         server.tool('ductape_generate_payload', payloadGenerateInputSchema.shape, payloadGenerateHandler);
         server.tool('ductape_generate_snippet', snippetGenerateInputSchema.shape, snippetGenerateHandler);
+        server.tool('ductape_schema', schemaInputSchema.shape, schemaHandler);
     }
     else {
         console.error('MCP server does not expose .registerTool() or .tool()');

package/dist/proxy-client.d.ts

@@ -8,9 +8,7 @@ export type SDKModule = 'product' | 'app' | 'databases' | 'graph' | 'webhooks' |
  */
 export declare function executeViaProxy<T = unknown>(publishable_key: string, module: SDKModule, method: string, params?: unknown[]): Promise<T>;
 export interface IGenerateExecutablePayloadRequest {
-    workspace_id: string;
-    user_id: string;
-    public_key: string;
+    publishable_key: string;
     product_tag: string;
     env_slug: string;
     operation_family: string;
@@ -25,5 +23,6 @@ export interface IGenerateExecutablePayloadResponse {
     payload: Record<string, unknown>;
     meta: Record<string, unknown>;
 }
+export declare function getAssetSchemas(module?: string): Promise<unknown>;
 export declare function generateExecutablePayload<T = IGenerateExecutablePayloadResponse>(request: IGenerateExecutablePayloadRequest): Promise<T>;
 //# sourceMappingURL=proxy-client.d.ts.map

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,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,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,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,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;AAQD,wBAAsB,yBAAyB,CAAC,CAAC,GAAG,kCAAkC,EACpF,OAAO,EAAE,iCAAiC,GACzC,OAAO,CAAC,CAAC,CAAC,CAmBZ"}
+{"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,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,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;AAQD,wBAAsB,eAAe,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAYvE;AAED,wBAAsB,yBAAyB,CAAC,CAAC,GAAG,kCAAkC,EACpF,OAAO,EAAE,iCAAiC,GACzC,OAAO,CAAC,CAAC,CAAC,CAmBZ"}