@ductape/mcp 0.1.0

package/dist/index.js

@@ -0,0 +1,757 @@
+#!/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, } from './proxy-client.js';
+const MODULES = [
+    '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).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) {
+    return JSON.stringify(value ?? {}, null, 2);
+}
+const ALLOWED_SNIPPET_METHODS = {
+    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, method) {
+    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, method) {
+    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) {
+    const input = payload?.input || {};
+    return {
+        product: payload?.product_tag,
+        env: payload?.env,
+        ...input,
+        ...(payload?.session ? { session: payload.session } : {}),
+        ...(payload?.cache ? { cache: payload.cache } : {}),
+    };
+}
+function buildTypeScriptSnippet(payload, operationFamily, method) {
+    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, operationFamily, method) {
+    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, payload, operationFamily, method) {
+    return language === 'python'
+        ? buildPythonSnippet(payload, operationFamily, method)
+        : buildTypeScriptSnippet(payload, operationFamily, method);
+}
+async function loadMcpSdk() {
+    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) => {
+        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) => {
+        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) => {
+        try {
+            ensureSupportedSnippetOperation(args.operation_family, args.method);
+            const generated = await generateExecutablePayload(args);
+            const payload = generated?.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);
+});