@ductape/mcp 0.1.0 → 0.1.2

package/src/index.ts

@@ -5,13 +5,16 @@
  * 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,
+  getAssetSchemas,
   type SDKModule,
 } from './proxy-client.js';
 
@@ -29,6 +32,32 @@ const MODULES: SDKModule[] = [
 // ─────────────────────────────────────────────────────────────────────────────
 
 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 ━━━
@@ -57,8 +86,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 }]
@@ -82,7 +111,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? }]
@@ -96,13 +125,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
@@ -111,7 +145,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
@@ -123,28 +162,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,
@@ -156,12 +205,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]
@@ -179,12 +228,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 ━━━
@@ -197,9 +246,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? }]
@@ -225,7 +274,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}] }]
@@ -272,8 +321,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?}] }]
@@ -326,7 +375,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?}] }]
@@ -358,19 +407,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
@@ -378,20 +432,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,
@@ -406,7 +465,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, ... })
@@ -420,11 +479,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,
@@ -436,10 +495,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,
@@ -447,18 +506,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}] }]
@@ -507,10 +566,68 @@ 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 as [string, ...string[]]).describe(
     'SDK module to target. Options: ' + MODULES.join(', ') + '.'
   ),
@@ -522,31 +639,57 @@ const executeInputSchema = z.object({
 });
 
 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: unknown): string {
   return JSON.stringify(value ?? {}, null, 2);
 }
 
 const ALLOWED_SNIPPET_METHODS: Record<string, string[]> = {
   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'],
@@ -580,7 +723,7 @@ function resolveSdkCallPath(operationFamily: string, method: string): string {
   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') return m === 'dispatch' ? 'graph.dispatch' : `graph.${m}`;
   if (family === 'vector') return `vector.${m}`;
@@ -708,17 +851,46 @@ async function loadMcpSdk(): Promise<{
   process.exit(1);
 }
 
+function handleCliFlags(): boolean {
+  const arg = process.argv[2];
+  if (arg === '--version' || arg === '-v') {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const { version } = require('../package.json') as { version: string };
+    process.stdout.write(version + '\n');
+    return true;
+  }
+  if (arg === '--help' || arg === '-h') {
+    process.stdout.write(
+      'ductape-mcp — Ductape MCP server\n\n' +
+      'Usage: ductape-mcp\n\n' +
+      'The server communicates over stdio and is meant to be spawned by an MCP\n' +
+      'client (Cursor, Claude Desktop, Claude Code). Run it directly only to\n' +
+      'verify the binary is working.\n\n' +
+      'Options:\n' +
+      '  --version, -v   Print version and exit\n' +
+      '  --help,    -h   Print this message and exit\n\n' +
+      'Environment:\n' +
+      '  DUCTAPE_PUBLISHABLE_KEY   Your workspace publishable key. Set this in\n' +
+      '                            the MCP client env config to avoid passing\n' +
+      '                            publishable_key on every tool call.\n',
+    );
+    return true;
+  }
+  return false;
+}
+
 async function main() {
   const { McpServer, StdioServerTransport } = await loadMcpSdk();
   const server = new McpServer({ name: 'ductape-mcp', version: '0.1.0' });
   const transport = new StdioServerTransport();
 
-  const executeHandler = async (args: { publishable_key: string; module: SDKModule; method: string; params: unknown[] }) => {
+  const executeHandler = async (args: { publishable_key?: string; module: SDKModule; method: string; params: unknown[] }) => {
     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) {
       const message = err instanceof Error ? err.message : String(err);
@@ -730,7 +902,11 @@ async function main() {
     args: z.infer<typeof payloadGenerateInputSchema>,
   ) => {
     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) {
       const message = err instanceof Error ? err.message : String(err);
@@ -742,8 +918,12 @@ async function main() {
     args: z.infer<typeof snippetGenerateInputSchema>,
   ) => {
     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 as any)?.payload ?? {};
       const snippet = buildSnippet(args.language, payload, args.operation_family, args.method);
       return {
@@ -767,12 +947,28 @@ async function main() {
     }
   };
 
+  const schemaHandler = async (args: { module?: 'app' | 'product' }) => {
+    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,
@@ -781,7 +977,14 @@ async function main() {
       '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,
@@ -795,10 +998,24 @@ async function main() {
       },
       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()');
     process.exit(1);
@@ -807,7 +1024,9 @@ async function main() {
   await server.connect(transport);
 }
 
-main().catch((err) => {
-  console.error(err);
-  process.exit(1);
-});
+if (!handleCliFlags()) {
+  main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+  });
+}