@ductape/mcp 0.1.0

package/src/index.ts

@@ -0,0 +1,813 @@
+#!/usr/bin/env node
+/**
+ * Ductape MCP Server
+ *
+ * Exposes Ductape SDK operations as MCP tools by calling the backend proxy.
+ *
+ * Authentication:
+ * Requires passing a `publishable_key` with every `ductape_execute` payload.
+ */
+
+import { z } from 'zod';
+import {
+  executeViaProxy,
+  generateExecutablePayload,
+  type SDKModule,
+} from './proxy-client.js';
+
+const MODULES: SDKModule[] = [
+  'product', 'app', 'databases', 'graph', 'webhooks', 'notifications',
+  'messageBrokers', 'storage', 'vector', 'caches', 'sessions', 'quotas',
+  'actions', 'features', 'jobs', 'logs', 'resilience', 'health', 'fallback', 'secrets',
+];
+
+
+
+// ─── Exhaustive SDK Method & Params Reference ────────────────────────────────
+// Built from a complete read of sdk/ts/src/index.ts (Ductape class public API).
+// Each entry follows: [module].[method] → params array signature.
+// ─────────────────────────────────────────────────────────────────────────────
+
+const METHOD_DOCS = `
+ALL params are passed as a JSON array in positional order matching the SDK signature.
+
+━━━ MODULE: product ━━━
+  product.create        [data: { name, description, tag?, envs?: [{slug, name}] }]
+  product.fetch         [product_tag: string]
+  product.update        [product_tag: string, data: { name?: string, description?: string }]
+  product.init          [product_tag: string]
+  product.environments.create   [product_tag, data: { slug: string, env_name: string, description: string, active?: boolean }]
+  product.environments.update   [product_tag, slug: string, data: { env_name?: string, description?: string, active?: boolean }]
+  product.environments.list     [product_tag]
+  product.environments.fetch    [product_tag, slug]
+  product.apps.connect  [product_tag, app_tag]
+  product.apps.add      [product_tag, app: { access_tag: string, envs: [{ app_env_slug: string, product_env_slug: string, variables?: [{key: string, value: string}], auth?: { auth_tag: string, data: string|object, expiry?: number } }] }]
+  product.apps.list     [product_tag]
+  product.apps.fetch    [product_tag, access_tag]
+  product.apps.update   [product_tag, access_tag: string, data: { version?: string, envs?: [{ app_env_slug: string, product_env_slug: string, variables?: [{key: string, value: string}], auth?: { auth_tag: string, data: string|object, expiry?: number } }] }]
+
+━━━ MODULE: app ━━━
+  app.create    [data: { app_name: string, description: string, unique?: boolean }]
+  app.fetch     [app_tag]
+  app.update    [app_tag, data: { app_name?: string, description?: string, logo?: string, colors?: { primary?: string, secondary?: string, accent?: string, background?: string }, require_whitelist?: boolean, aboutText?: string, aboutHTML?: string, request_type?: string }]
+  app.init      [app_tag]
+
+━━━ MODULE: actions (app actions) ━━━
+  actions.create  [app_tag, data: { tag: string, name: string, resource: string, method: "GET"|"POST"|"PUT"|"PATCH"|"DELETE", description?: string, body?: object, params?: object, query?: object, headers?: object, response?: { name?: string, status_code: number, success: boolean, body: object, response_format: "json"|"xml"|"form" } }]
+  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? } }]
+
+━━━ 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 }]
+  auths.update  [app_tag, auth_tag, data: { name?: string, setup_type?: "header"|"bearer"|"basic"|"oauth2"|"apikey", expiry?: number, period?: "seconds"|"minutes"|"hours"|"days", description?: string, action_tag?: string }]
+  auths.fetch   [app_tag, auth_tag]
+  auths.list    [app_tag]
+
+━━━ MODULE: webhooks ━━━
+  webhooks.create   [app_tag, data: { tag: string, name: string, description: string, envs?: [{ slug: string, registration_url?: string, method?: "GET"|"POST"|"PUT"|"PATCH", sample?: object }] }]
+  webhooks.update   [app_tag, webhook_tag, data: { name?: string, description?: string, envs?: [{ slug: string, registration_url?: string, method?: "GET"|"POST"|"PUT"|"PATCH", sample?: object }] }]
+  webhooks.fetch    [app_tag, webhook_tag]
+  webhooks.list     [app_tag]
+  webhooks.events.create [app_tag, data: { tag: string, name: string, selector: string, description: string, sample: object }]
+  webhooks.events.update [app_tag, event_tag, data: { name?: string, selector?: string, selectorValue?: string, description?: string, sample?: object }]
+  webhooks.events.fetch  [app_tag, event_tag]
+  webhooks.events.list   [app_tag, webhook_tag]
+
+━━━ MODULE: sessions ━━━
+  sessions.create        [product_tag, data: { tag: string, name: string, description?: string, expiry: number, period: "seconds"|"minutes"|"hours"|"days", selector: string, schema: { fieldName: "string"|"number"|"boolean" } }]
+  sessions.update        [product_tag, session_tag, data: { name?: string, description?: string, expiry?: number, period?: "seconds"|"minutes"|"hours"|"days", selector?: string, schema?: object }]
+  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.verify        [{ product, env, tag, token }]
+  sessions.refresh       [{ product, env, tag, refreshToken }]
+  sessions.revoke        [{ product, env, tag, sessionId?, identifier? }]
+  sessions.listActive    [{ product, env, tag, identifier?, page?, limit? }]
+  sessions.fetchUsers    [{ product, session, env?, page?, limit? }]
+  sessions.fetchUserDetails  [{ product, session, identifier, env? }]
+  sessions.fetchDashboard    [{ product, session, env? }]
+
+━━━ MODULE: quotas ━━━
+  quotas.create   [product_tag, data: {
+    tag: string,                          // unique identifier
+    name?: string,                        // display name
+    description?: string,
+    input: {                              // declare the input fields this quota expects
+      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
+        app: string,                      // app tag whose action to call
+        type: "action",
+        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
+        output: {},                       // expected output shape (can be {})
+        retries: number,
+        healthcheck?: string,             // optional healthcheck tag to gate this provider
+        check_interval?: number           // ms between health polls
+      }
+    ]
+  }]
+  quotas.update   [product_tag, quota_tag, data: { name?: string, description?: string, options?: array }]
+  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 } }]
+
+━━━ MODULE: fallback ━━━
+  fallback.create   [product_tag, data: {
+    tag: string,
+    name?: string,
+    description?: string,
+    input: {                              // input fields this fallback expects
+      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
+        input: { "body:field": "$Input{fieldName}" },
+        output: {},
+        retries: number,
+        healthcheck?: string,
+        check_interval?: number
+      }
+    ]
+  }]
+  fallback.update   [product_tag, fallback_tag, data: { name?: string, description?: string, options?: array }]
+  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 } }]
+
+━━━ 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.fetch    [product_tag, health_tag]
+  health.list     [product_tag]
+  health.delete   [product_tag, health_tag]
+  health.status   [{ product, env, tag }]
+  health.run      [{ product, env, tag }]
+  health.check    [{ product, env, tag }]
+
+━━━ MODULE: notifications ━━━
+  notifications.create   [product_tag, data: { tag: string, name: string, type?: "email"|"push"|"sms"|"callback" }]
+  notifications.update   [product_tag, notif_tag, data: { name?: string, type?: "email"|"push"|"sms"|"callback" }]
+  notifications.fetch    [product_tag, notif_tag]
+  notifications.list     [product_tag]
+  notifications.delete   [product_tag, notif_tag]
+  notifications.messages.create  [product_tag, data: { tag: string, notification: string, subject?: { template: string, data: object }, body?: { template: string, data: object } }]
+  notifications.messages.update  [product_tag, msg_tag, data: { subject?: { template: string, data: object }, body?: { template: string, data: object } }]
+  notifications.messages.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.getMessages [{ product_tag?, env?, notification_tag?, status?, type?, start_date?, end_date?, page?, limit? }]
+
+━━━ MODULE: messageBrokers ━━━
+  messageBrokers.create   [{ product: string, tag: string, name: string, description?: string, type: "kafka"|"rabbitmq"|"redis"|"sqs", envs: [{ slug: string, connection_url: string }] }]
+  messageBrokers.update   [product_tag, broker_tag, data: { name?: string, description?: string, type?: "kafka"|"rabbitmq"|"redis"|"sqs", envs?: [{ slug: string, connection_url: string }] }]
+  messageBrokers.fetch    [product_tag, broker_tag]
+  messageBrokers.list     [product_tag]
+  messageBrokers.delete   [product_tag, broker_tag]
+  messageBrokers.topics.create [product_tag, data: { tag: string, name: string, broker: string, type: "producer"|"consumer"|"both" }]
+  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.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.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? }]
+  messageBrokers.messages.getDeadLetters [{ product, env, brokerTag, topicTag?, consumerTag?, startDate?, endDate?, page?, limit? }]
+  messageBrokers.messages.getStats      [{ product, env, brokerTag }]
+  messageBrokers.messages.getDashboard  [{ product, env, brokerTag }]
+
+━━━ MODULE: storage ━━━
+  storage.create   [{ product: string, tag: string, name: string, description?: string, envs: [{ slug: string, type: "aws"|"azure"|"gcp", config: { bucket?: string, region?: string, accessKeyId?: string, secretAccessKey?: string, containerName?: string, connectionString?: string, projectId?: string, keyFilename?: string } }] }]
+  storage.update   [product_tag, storage_tag, data: { name?: string, description?: string, envs?: [{ slug: string, type: "aws"|"azure"|"gcp", config: { bucket?: string, region?: string, accessKeyId?: string, secretAccessKey?: string } }] }]
+  storage.fetch    [product_tag, storage_tag]
+  storage.list     [product_tag]
+  storage.delete   [product_tag, storage_tag]
+  storage.upload   [{ product, env, storage, fileName, buffer: string|Buffer, mimeType? }]
+  storage.download [{ product, env, storage, fileName }]
+  storage.remove   [{ product, env, storage, fileName }]
+  storage.listFiles [{ product, env, storage, prefix?, limit?, continuationToken? }]
+  storage.getSignedUrl [{ product, env, storage, fileName, expiresIn?: number, action?: "read"|"write" }]
+  storage.stats    [{ product, env, storage, prefix?, session?, cache? }]
+  storage.testConnection [{ product, env, storage }]
+  storage.files.upload   [{ product, env, storage, fileName, buffer, mimeType? }]
+  storage.files.download [{ product, env, storage, fileName }]
+  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? }]
+
+━━━ MODULE: databases ━━━
+  databases.create  [{ product, tag, name, description?, type: "mongodb"|"postgresql"|"mysql"|"sqlite", envs: [{slug, connection_url}] }]
+  databases.register [product_tag, data: IProductDatabase]
+  databases.list    [product_tag]
+  databases.fetch   [product_tag, database_tag]
+  databases.updateDatabase [product_tag, database_tag, data: { name?: string, description?: string, type?: "postgresql"|"mongodb"|"mysql", envs?: [{ slug: string, connection_url: string, description?: string }] }]
+  databases.connect [{ product, env, database }]
+  databases.testConnection [{ product, env, database }]
+  databases.disconnect []
+  databases.query   [{ product, env, database, entity, where?: {field: {$eq|$gt|$lt|$in: value}}, select?: string[], orderBy?: [{field, order:"ASC"|"DESC"}], limit?, offset? }]
+  databases.insert  [{ product, env, database, entity, data: {key: value}|{key:value}[], returning? }]
+  databases.update  [{ product, env, database, entity, data: {key:value}, where: {key: {$eq: value}}, returning? }]
+  databases.delete  [{ product, env, database, entity, where: {key: {$eq: value}}, returning? }]
+  databases.upsert  [{ product, env, database, entity, data: {key:value}, conflictKeys: string[], returning? }]
+  databases.count   [{ product, env, database, entity, where? }]
+  databases.sum     [{ product, env, database, entity, field, where? }]
+  databases.avg     [{ product, env, database, entity, field, where? }]
+  databases.min     [{ product, env, database, entity, field, where? }]
+  databases.max     [{ product, env, database, entity, field, where? }]
+  databases.aggregate [{ product, env, database, entity, aggregations: [{type:"count"|"sum"|"avg"|"min"|"max", field?, alias}], where?, groupBy? }]
+  databases.schema.create [collection_name, definition: { fieldName: "string"|"number"|"boolean"|"date"|{type, required?, unique?, default?} }, options?]
+  databases.schema.drop   [collection_name, options?]
+  databases.schema.addField [collection, fieldName, definition]
+  databases.schema.dropField [collection, fieldName]
+  databases.schema.renameField [collection, oldName, newName]
+  databases.schema.modifyField [collection, fieldName, changes: Partial<{type, required, unique, default}>]
+  databases.schema.createIndex [collection, fields: string[]|[{field, order}], options?: {unique?, name?}]
+  databases.schema.dropIndex   [collection, indexName]
+  databases.schema.list   [schemaName?]
+  databases.schema.describe [collection_name]
+  databases.schema.indexes  [collection_name]
+  databases.migration.create [{ product, database, data: { name, tag, description?, value: { up: string[], down: string[] } } }]
+  databases.migration.update [{ product, tag, data: { name?, description?, value? } }]
+  databases.migration.fetch  [{ product, tag }]
+  databases.migration.list   [{ product, database }]
+  databases.migration.delete [{ product, tag }]
+  databases.migration.run    [migrations, options?]
+  databases.migration.rollback [migrations, count?]
+  databases.migration.history []
+  databases.migration.status [migrations]
+  databases.action.create [{ product, database, data: { tag, name, description?, type:"sql"|"nosql", query } }]
+  databases.action.update [{ product: string, tag: string, data: { name?: string, description?: string, query?: string } }]
+  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? }]
+
+━━━ MODULE: graph ━━━
+  graph.create  [{ product, tag, name, description?, type: "neo4j"|"nebula"|"arangodb", envs: [{slug, connection_url, username?, password?}] }]
+  graph.fetch   [product_tag, graph_tag]
+  graph.list    [product_tag?]
+  graph.update  [product_tag, graph_tag, data: { name?: string, description?: string, type?: "neo4j"|"neptune"|"arangodb"|"memgraph", envs?: [{ slug: string, connection_url: string, username?: string, password?: string, database?: string, graphName?: string, region?: string }] }]
+  graph.delete  [graph_tag, product_tag?]
+  graph.connect [{ product, env, graph }]
+  graph.testConnection [config]
+  graph.createNode    [{ labels: string[], properties: { key: value } }, transaction?]
+  graph.findNodes     [{ labels?: string[], where?: { key: value }, limit?, skip? }, transaction?]
+  graph.findNodeById  [id: string|number, transaction?]
+  graph.updateNode    [{ id, properties: { key: value } }, transaction?]
+  graph.deleteNode    [{ id, detach?: boolean }, transaction?]
+  graph.mergeNode     [{ labels: string[], matchProps: { key: value }, setProps?: { key: value } }, transaction?]
+  graph.addLabels     [{ id, labels: string[] }, transaction?]
+  graph.removeLabels  [{ id, labels: string[] }, transaction?]
+  graph.setLabels     [{ id, labels: string[] }, transaction?]
+  graph.createRelationship [{ fromId, toId, type: string, properties?: { key: value } }, transaction?]
+  graph.findRelationships  [{ type?: string, where?, limit? }, transaction?]
+  graph.findRelationshipById [id, transaction?]
+  graph.updateRelationship   [{ id, properties: { key: value } }, transaction?]
+  graph.deleteRelationship   [{ id }, transaction?]
+  graph.mergeRelationship    [{ fromId, toId, type, matchProps?, setProps? }, transaction?]
+  graph.traverse      [{ startId, direction?: "in"|"out"|"both", relationshipTypes?: string[], maxDepth?, where? }, transaction?]
+  graph.shortestPath  [{ fromId, toId, relationshipType?, maxDepth? }, transaction?]
+  graph.allPaths      [{ fromId, toId, relationshipType?, maxDepth? }, transaction?]
+  graph.getNeighborhood [{ id, depth?, relationshipTypes? }, transaction?]
+  graph.findConnectedComponents [{ labels? }, transaction?]
+  graph.query    [cypher_query: string, params?: { key: value }, transaction?]
+  graph.getStatistics [transaction?]
+  graph.countNodes [labels?: string[], where?, transaction?]
+  graph.countRelationships [types?: string[], where?, transaction?]
+  graph.fullTextSearch [{ index, query, limit? }, transaction?]
+  graph.vectorSearch   [{ index, vector: number[], topK? }, transaction?]
+  graph.createNodeIndex [{ label, field, type?: "btree"|"fulltext"|"vector" }]
+  graph.createNodeConstraint [{ label, field, type: "unique"|"exists" }]
+  graph.createRelationshipIndex [{ type, field }]
+  graph.listIndexes []
+  graph.listConstraints []
+  graph.dropIndex [name: string]
+  graph.dropConstraint [name: string]
+  graph.listLabels []
+  graph.listRelationshipTypes []
+  graph.createAction [{ graphTag, tag, name, query, params? }, productTag?]
+  graph.listActions  [graphTag?, productTag?]
+  graph.getAction    [actionTag, graphTag?, productTag?]
+  graph.updateAction [actionTag, updates, graphTag?, productTag?]
+  graph.deleteAction [actionTag, graphTag?, productTag?]
+  graph.beginTransaction [options?]
+  graph.commitTransaction [transaction]
+  graph.rollbackTransaction [transaction]
+  graph.dispatch [data]
+
+━━━ MODULE: vector ━━━
+  vector.create  [{ product, tag, name, description?, provider: "pinecone"|"qdrant"|"weaviate", dimensions: number, metric?: "cosine"|"euclidean"|"dotproduct", envs: [{slug, api_key, environment?}] }]
+  vector.update  [{ product: string, tag: string, data: { name?: string, description?: string, type?: "pinecone"|"qdrant"|"weaviate"|"chroma"|"milvus"|"pgvector"|"memory", dimensions?: number, metric?: "cosine"|"euclidean"|"dotproduct", envs?: [{ slug: string, endpoint?: string, apiKey?: string, region?: string, index?: string, namespace?: string }] } }]
+  vector.fetch   [{ product, tag }]
+  vector.list    [{ product }]
+  vector.delete  [{ product, tag }]
+  vector.connect [{ product, env, vector }]
+  vector.disconnect [{ product, env, vector }]
+  vector.query   [{ product, env, tag, vector: number[], topK?: number, filter?, namespace?, includeValues?, includeMetadata? }]
+  vector.upsert  [{ product, env, tag, vectors: [{id, values: number[], metadata?}], namespace? }]
+  vector.fetchVectors  [{ product, env, vector, ids: string[], namespace? }]
+  vector.deleteVectors [{ product, env, tag, ids: string[], namespace?, deleteAll? }]
+  vector.findSimilar   [{ product, env, vector, values: number[], topK?, filter?, namespace?, includeValues?, includeMetadata? }]
+  vector.upsertOne     [{ product, env, tag, id, values: number[], metadata?, namespace?, session? }]
+  vector.fetchOne      [{ product, env, vector, id, namespace? }]
+  vector.updateVector  [{ product, env, vector, id, values?, setMetadata?, mergeMetadata?, namespace? }]
+  vector.updateMetadata [{ product, env, vector, id, metadata: { key: value }, merge?, namespace? }]
+  vector.deleteByIds   [{ product, env, vector, ids: string[], namespace? }]
+  vector.deleteAll     [{ product, env, vector, namespace? }]
+  vector.listVectors   [{ product, env, vector, namespace?, prefix?, limit?, cursor? }]
+  vector.listAllVectors [{ product, env, vector, namespace?, prefix? }]
+  vector.listNamespaces [{ product, env, vector }]
+  vector.deleteNamespace [{ product, env, vector, namespace }]
+  vector.describeIndex  [{ product, env, vector }]
+  vector.getStats       [{ product, env, vector }]
+  vector.createIndex    [{ product, env, vector, name, dimensions, metric?, replicas?, shards? }]
+  vector.deleteIndex    [{ product, env, vector, name }]
+  vector.listIndexes    [{ product, env, vector }]
+  vector.count          [{ product, env, vector, namespace? }]
+
+━━━ MODULE: workflow ━━━
+  workflow.create  [product_tag, data: {
+    tag: string,
+    name: string,
+    description?: string,
+    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",
+        app?: string,             // for type=action
+        event?: string,           // action/event tag
+        database?: string,        // for type=database
+        graph?: string,           // for type=graph
+        notification?: string,    // for type=notification
+        storage?: string,         // for type=storage
+        broker?: string,          // for type=publish
+        workflow?: string,        // for type=workflow (child)
+        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]
+
+  workflow.define  [{
+    product?: string,
+    tag: string,
+    name: string,
+    description?: string,
+    input?: { fieldName: { type: string, required?: boolean } },
+    output?: object,
+    signals?: { signalName: { input?: object } },
+    queries?: { queryName: { handler?: function } },
+    options?: { timeout?: number, retries?: number },
+    envs?: [{ slug: string, active?: boolean }],
+    recordInput?: object,         // sample input for step-recording (run once during define)
+    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.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, ... })
+      // ctx.graph.execute({ graph, action, input })
+      // ctx.notification.send/email/push/sms({ notification, event, ... })
+      // ctx.storage.upload/download({ storage, event, input })
+      // ctx.messaging.produce({ event: "broker:topic", message: {} })
+      // ctx.quota.execute({ quota, input })
+      // ctx.fallback.execute({ fallback, input })
+      // ctx.healthcheck.getStatus(tag)
+      // ctx.sleep(ms|"1h30m")
+      // ctx.waitForSignal("signal-name", { timeout? })
+      // ctx.setState(key, value) / ctx.getState(key)
+      // ctx.workflow(childId, childTag, childInput) – child workflow
+    }
+  }]
+
+  workflow.execute [{
+    product: string,
+    env: string,
+    tag: string,
+    input: { fieldName: value },
+    session?: string,             // "session_tag:jwt_token"
+    idempotency_key?: string,
+    cache?: string,
+    retries?: number,
+    timeout?: number
+  }]
+
+  workflow.dispatch [{
+    product: string,
+    env: string,
+    workflow: string,
+    input: { fieldName: value },
+    schedule?: { start_at?: number|string, cron?: string, every?: number, limit?: number, endDate?: number|string, tz?: string },
+    session?: string,
+    cache?: string,
+    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]
+
+━━━ MODULE: caches ━━━
+  caches.create  [{ product, tag, name, description?, type: "redis"|"memcached"|"in-memory", envs: [{slug, connection_url}] }]
+  caches.update  [product_tag, cache_tag, data: { name?: string, description?: string, expiry?: number }]
+  caches.fetch   [product_tag, cache_tag]
+  caches.list    [product_tag]
+  caches.delete  [product_tag, cache_tag]
+  caches.get     [{ key: string }]
+  caches.set     [{ product, cache, key, value: string, componentTag?, componentType?, expiry?: Date }]
+  caches.clear   [{ key: string }]
+  caches.clearAll [{ product, cache, env? }]
+  caches.fetchValues [{ product, cache, env?, page?, limit?, expiryFilter?: "all"|"expiring"|"permanent"|"expired" }]
+  caches.fetchDashboard [{ product, cache, env? }]
+
+━━━ MODULE: jobs ━━━
+  jobs.create  [product_tag, data: { tag, name, description?, type: "action"|"notification"|"storage"|"database"|"publish", app?, event?, executions?, intervals?, start_at? }]
+  jobs.update  [product_tag, job_tag, data: { name?: string, description?: string, type?: "action"|"notification"|"storage"|"database"|"publish", app?: string, event?: string, executions?: number, intervals?: number, start_at?: number }]
+  jobs.fetch   [product_tag, job_tag]
+  jobs.list    [product_tag]
+  jobs.delete  [product_tag, job_tag]
+  jobs.get     [jobId: string]
+  jobs.listJobs [{ product?, status?, limit?, page? }]
+  jobs.cancel  [jobId, { reason? }?]
+  jobs.cancelMany [{ product?, status? }]
+  jobs.pause   [jobId]
+  jobs.pauseMany [{ product?, recurring? }]
+  jobs.resume  [jobId]
+  jobs.resumeMany [{ product?, status? }]
+  jobs.retry   [jobId, { delay? }?]
+  jobs.retryMany [{ status?, from? }]
+  jobs.reschedule [jobId, { start_at?, cron?, every? }]
+  jobs.getHistory [jobId, { limit? }?]
+  jobs.getStats   [{ product?, env?, from?, to? }?]
+
+━━━ MODULE: secrets ━━━
+  secrets.create  [{ key, value, description?, token_type?: "api"|"password"|"certificate", scope?: string[], envs?: string[], expires_at?: number }]
+  secrets.update  [key, { value?, description?, scope?, envs?, expires_at? }]
+  secrets.fetch   [key]
+  secrets.list    []
+  secrets.delete  [key]
+  secrets.revoke  [key]
+  secrets.exists  [key]
+  secrets.resolve [value, { env?, app? }?]
+  secrets.validate [value]
+
+━━━ 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? }]
+`;
+
+const executeInputSchema = z.object({
+  publishable_key: z.string().describe('The publishable key for your workspace. Required for authentication.'),
+  module: z.enum(MODULES as [string, ...string[]]).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(),
+});
+
+const snippetGenerateInputSchema = payloadGenerateInputSchema.extend({
+  language: z.enum(['typescript', 'python']).default('typescript'),
+});
+
+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'],
+  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'],
+  storage: ['dispatch', 'upload', 'download', 'remove', 'listFiles', 'getSignedUrl', 'stats'],
+  notification: ['dispatch', 'send', 'email.send', 'push.send', 'sms.send', 'callback.send'],
+  messaging: ['dispatch', 'send', 'publish', 'produce', 'consume'],
+  broker: ['dispatch', 'send', 'publish', 'produce', 'consume'],
+  quota: ['run', 'dispatch', 'check', 'consume'],
+  fallback: ['run', 'dispatch'],
+  healthcheck: ['run', 'check', 'status'],
+  health: ['run', 'check', 'status'],
+  session: ['start', 'verify', 'refresh', 'revoke', 'listActive'],
+  cache: ['get', 'set', 'clear', 'clearAll', 'dispatch', 'fetchValues'],
+};
+
+function ensureSupportedSnippetOperation(operationFamily: string, method: string): void {
+  const family = String(operationFamily || '').toLowerCase();
+  const m = String(method || '');
+  const allowed = ALLOWED_SNIPPET_METHODS[family] || [];
+  if (!allowed.includes(m)) {
+    const supportedFamilies = Object.keys(ALLOWED_SNIPPET_METHODS).sort().join(', ');
+    throw new Error(
+      `Unsupported snippet operation "${family}.${m}". Allowed methods for "${family}": ${allowed.join(', ') || '(none)'}.\n` +
+      `Supported families: ${supportedFamilies}`,
+    );
+  }
+}
+
+function resolveSdkCallPath(operationFamily: string, method: string): string {
+  const family = String(operationFamily || '').toLowerCase();
+  const m = String(method || '').toLowerCase();
+
+  if (family === 'action') return `actions.${m}`;
+  if (family === 'workflow') return `workflow.${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}`;
+  if (family === 'storage') return m === 'dispatch' ? 'storage.dispatch' : `storage.${m}`;
+  if (family === 'notification') return m === 'dispatch' ? 'notifications.dispatch' : `notifications.${m}`;
+  if (family === 'messaging' || family === 'broker') {
+    if (m === 'dispatch') return 'messageBrokers.dispatch';
+    if (m === 'send' || m === 'publish' || m === 'produce') return 'messageBrokers.produce';
+    return `messageBrokers.${m}`;
+  }
+  if (family === 'quota') return `quotas.${m}`;
+  if (family === 'fallback') return `fallback.${m}`;
+  if (family === 'healthcheck' || family === 'health') return `health.${m}`;
+  if (family === 'session') return `sessions.${m}`;
+  if (family === 'cache') return m === 'dispatch' ? 'caches.dispatch' : `caches.${m}`;
+  return `${family}.${m}`;
+}
+
+function buildSdkInvocationArgs(payload: Record<string, unknown>): Record<string, unknown> {
+  const input = (payload?.input as Record<string, unknown>) || {};
+  return {
+    product: payload?.product_tag,
+    env: payload?.env,
+    ...input,
+    ...(payload?.session ? { session: payload.session } : {}),
+    ...(payload?.cache ? { cache: payload.cache } : {}),
+  };
+}
+
+function buildTypeScriptSnippet(
+  payload: Record<string, unknown>,
+  operationFamily: string,
+  method: string,
+): string {
+  const callPath = resolveSdkCallPath(operationFamily, method);
+  const invocationArgs = buildSdkInvocationArgs(payload);
+  return `import Ductape from "@ductape/sdk";
+
+const ductape = new Ductape({
+  workspace_id: process.env.DUCTAPE_WORKSPACE_ID!,
+  user_id: process.env.DUCTAPE_USER_ID!,
+  public_key: process.env.DUCTAPE_PUBLIC_KEY!,
+});
+
+async function run() {
+  const payload = ${toPrettyJson(payload)};
+  const args = ${toPrettyJson(invocationArgs)};
+  const result = await ductape.${callPath}(args);
+  return { payload, result };
+}
+
+run().catch(console.error);
+`;
+}
+
+function buildPythonSnippet(
+  payload: Record<string, unknown>,
+  operationFamily: string,
+  method: string,
+): string {
+  const callPath = resolveSdkCallPath(operationFamily, method);
+  const invocationArgs = buildSdkInvocationArgs(payload);
+  return `from ductape import Ductape
+import os
+import json
+
+ductape = Ductape(
+    workspace_id=os.environ.get("DUCTAPE_WORKSPACE_ID"),
+    user_id=os.environ.get("DUCTAPE_USER_ID"),
+    public_key=os.environ.get("DUCTAPE_PUBLIC_KEY"),
+)
+
+def run():
+    payload = ${toPrettyJson(payload)}
+    args = ${toPrettyJson(invocationArgs)}
+    result = ductape.${callPath}(args)
+    return {"payload": payload, "result": result}
+
+if __name__ == "__main__":
+    print(json.dumps(run(), indent=2))
+`;
+}
+
+function buildSnippet(
+  language: 'typescript' | 'python',
+  payload: Record<string, unknown>,
+  operationFamily: string,
+  method: string,
+): string {
+  return language === 'python'
+    ? buildPythonSnippet(payload, operationFamily, method)
+    : buildTypeScriptSnippet(payload, operationFamily, method);
+}
+
+
+async function loadMcpSdk(): Promise<{
+  McpServer: new (info: { name: string; version: string }) => any;
+  StdioServerTransport: new () => any;
+}> {
+  try {
+    const [{ McpServer }, { StdioServerTransport }] = await Promise.all([
+      import('@modelcontextprotocol/sdk/server/mcp.js'),
+      import('@modelcontextprotocol/sdk/server/stdio.js'),
+    ]);
+    if (McpServer && StdioServerTransport) {
+      return { McpServer, StdioServerTransport };
+    }
+  } catch {
+    // fall through to v2 alpha package
+  }
+
+  try {
+    const sdk = await import('@modelcontextprotocol/server');
+    if (sdk.McpServer && sdk.StdioServerTransport) {
+      return { McpServer: sdk.McpServer, StdioServerTransport: sdk.StdioServerTransport };
+    }
+  } catch {
+    // fall through
+  }
+
+  console.error(
+    'Failed to load MCP SDK. Install: npm install @modelcontextprotocol/sdk zod\n' +
+      'Or v2 alpha: npm install @modelcontextprotocol/server zod @cfworker/json-schema',
+  );
+  process.exit(1);
+}
+
+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[] }) => {
+    try {
+      if (!args.publishable_key) {
+        throw new Error('Not authenticated. Please provide the `publishable_key` in your tool invocation arguments.');
+      }
+      const result = await executeViaProxy(args.publishable_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);
+      return { content: [{ type: 'text', text: `Error: ${message}` }], isError: true };
+    }
+  };
+
+  const payloadGenerateHandler = async (
+    args: z.infer<typeof payloadGenerateInputSchema>,
+  ) => {
+    try {
+      const result = await generateExecutablePayload(args);
+      return { content: [{ type: 'text', text: JSON.stringify(result ?? null, null, 2) }] };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      return { content: [{ type: 'text', text: `Error: ${message}` }], isError: true };
+    }
+  };
+
+  const snippetGenerateHandler = async (
+    args: z.infer<typeof snippetGenerateInputSchema>,
+  ) => {
+    try {
+      ensureSupportedSnippetOperation(args.operation_family, args.method);
+      const generated = await generateExecutablePayload(args);
+      const payload = (generated as any)?.payload ?? {};
+      const snippet = buildSnippet(args.language, payload, args.operation_family, args.method);
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify(
+              {
+                payload: generated,
+                snippet,
+              },
+              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.)',
+        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',
+        inputSchema: payloadGenerateInputSchema,
+      },
+      payloadGenerateHandler,
+    );
+    server.registerTool(
+      'ductape_generate_snippet',
+      {
+        title: 'Ductape Snippet Generator',
+        description: 'Generate canonical payload and ready TypeScript/Python snippet for engineers',
+        inputSchema: snippetGenerateInputSchema,
+      },
+      snippetGenerateHandler,
+    );
+  } 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);
+  } else {
+    console.error('MCP server does not expose .registerTool() or .tool()');
+    process.exit(1);
+  }
+
+  await server.connect(transport);
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});