@ductape/mcp 0.1.3 → 0.1.5

package/dist/index.js

@@ -10,6 +10,7 @@
  * the env var when provided.
  */
 import { createRequire } from 'module';
+import { execSync } from 'child_process';
 import { z } from 'zod';
 import { executeViaProxy, generateExecutablePayload, getAssetSchemas, } from './proxy-client.js';
 const MODULES = [
@@ -24,18 +25,45 @@ const MODULES = [
 const METHOD_DOCS = `
 ━━━ TOOL SELECTION GUIDE ━━━
 
-There are two categories of SDK operations. Use the right tool for each:
+There are THREE categories of 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.
+  0. ADMINISTRATIVE OPERATIONS  (create/update products, apps, environments, cloud connections…)
+       These require an access key and CANNOT be done via ductape_execute (publishable key only).
+       → Use ductape_cli instead. Examples:
+           ductape_cli("products list")
+           ductape_cli("products create --name \\"My Product\\" --tag my-product")
+           ductape_cli("cloud connections list")
+           ductape_cli("link --product my-product --env dev")
+       If the CLI is not installed, ductape_cli will return install instructions automatically.
+       NOTE: Environments and app actions are configured in the Workbench UI — there are no CLI commands for them.
+
+       DECLARATIVE SYNC  (apply sessions, notifications, events from code; run DB migrations)
+       → Also use ductape_cli. The project must be linked first (ductape init --link).
+           ductape_cli("apply")                        # sync all: sessions + notifications + events
+           ductape_cli("apply sessions")               # sessions only
+           ductape_cli("apply notifications")          # notifications only
+           ductape_cli("apply events")                 # event brokers only
+           ductape_cli("apply --dry-run")              # preview without changes
+           ductape_cli("db schema generate")           # diff schema.json → write migration files
+           ductape_cli("db schema generate --destructive")  # also generate drop operations
+           ductape_cli("db migrate")                   # apply pending migration files
+           ductape_cli("db migrate --dry-run")         # preview without applying
+           ductape_cli("db migrate --env prd")         # apply to a specific environment
+           ductape_cli("db migrate status")            # show applied vs pending migrations
+           ductape_cli("db migrate status --json")     # machine-readable status
+           ductape_cli("db migrate rollback")          # roll back last migration
+           ductape_cli("db migrate rollback -n 3")     # roll back last 3 migrations
+
+  1. ASSET CREATION / UPDATE  (create, update, add, register… for ANY asset type)
+       ALL creation and update operations require an access key and CANNOT go through ductape_execute.
+       → Use ductape_cli for every create/update operation. Examples:
+           ductape_cli("apps create --name \\"Email Service\\" --description \\"Transactional email\\"")
+           ductape_cli("apps list")
+           ductape_cli("resources storage list")
+           ductape_cli("resources database create -f db-config.json")
+       This applies to: products, apps, and resources (databases, storage, caches, etc.),
+       cloud connections, and secrets. Environments, app actions, auths, features, quotas,
+       fallbacks, jobs, and healthchecks are configured in the Workbench UI.
 
   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.
@@ -777,6 +805,63 @@ function buildSnippet(language, payload, operationFamily, method) {
         ? buildPythonSnippet(payload, operationFamily, method)
         : buildTypeScriptSnippet(payload, operationFamily, method);
 }
+// ─── CLI helpers ─────────────────────────────────────────────────────────────
+const ADMIN_SUBCOMMANDS = [
+    'login', 'logout', 'whoami',
+    'profiles',
+    'workspaces',
+    'link', 'unlink', 'init',
+    'products', 'apps',
+    'resources',
+    'cloud',
+    'secrets',
+    'generate',
+    'apply',
+    'db',
+    'graph',
+];
+function checkCli() {
+    try {
+        const out = execSync('ductape --version', { encoding: 'utf8', timeout: 5000, stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+        return { available: true, version: out || 'unknown' };
+    }
+    catch {
+        return { available: false };
+    }
+}
+function runCli(command) {
+    const first = command.trim().split(/\s+/)[0];
+    if (!ADMIN_SUBCOMMANDS.includes(first)) {
+        return {
+            success: false,
+            output: `Subcommand "${first}" is not in the allowed admin subcommand list. Allowed: ${ADMIN_SUBCOMMANDS.join(', ')}.`,
+        };
+    }
+    try {
+        const output = execSync(`ductape ${command}`, {
+            encoding: 'utf8',
+            timeout: 30000,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        return { success: true, output: output.trim() };
+    }
+    catch (err) {
+        const msg = (err.stderr || err.stdout || err.message || String(err)).trim();
+        return { success: false, output: msg };
+    }
+}
+const cliInputSchema = z.object({
+    command: z.string().describe('The ductape CLI command to run, without the leading "ductape" word. ' +
+        'Examples: "products list", "products create --name \\"My Product\\" --tag my-product", ' +
+        '"apps list", "apps create -f app.json", "resources storage list", ' +
+        '"cloud connections list", "link --product my-product --env dev".\n\n' +
+        'Use this tool for administrative operations: creating or updating products, apps, ' +
+        'resources (databases, storage, caches…), cloud connections, secrets, ' +
+        'and for apply/migrate workflows.\n\n' +
+        'Note: environments, app actions, features, quotas, fallbacks, and jobs are configured ' +
+        'in the Workbench UI — there are no CLI commands for them.\n\n' +
+        'The CLI uses the user\'s local logged-in session (ductape login) — no key is required.'),
+});
 async function loadMcpSdk() {
     try {
         const [{ McpServer }, { StdioServerTransport }] = await Promise.all([
@@ -831,6 +916,33 @@ async function main() {
     const { McpServer, StdioServerTransport } = await loadMcpSdk();
     const server = new McpServer({ name: 'ductape-mcp', version: '0.1.0' });
     const transport = new StdioServerTransport();
+    const cliHandler = async (args) => {
+        const cli = checkCli();
+        if (!cli.available) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: [
+                            'The Ductape CLI is not installed or not in PATH.',
+                            '',
+                            'Install it with:',
+                            '  npm install --global @ductape/cli',
+                            '',
+                            'Then log in:',
+                            '  ductape login',
+                            '',
+                            'After logging in, retry this operation.',
+                        ].join('\n'),
+                    }],
+                isError: true,
+            };
+        }
+        const result = runCli(args.command);
+        return {
+            content: [{ type: 'text', text: result.output || '(no output)' }],
+            ...(result.success ? {} : { isError: true }),
+        };
+    };
     const executeHandler = async (args) => {
         try {
             const key = args.publishable_key || process.env.DUCTAPE_PUBLISHABLE_KEY;
@@ -899,12 +1011,14 @@ async function main() {
     if (typeof server.registerTool === 'function') {
         server.registerTool('ductape_execute', {
             title: 'Ductape SDK Execute',
-            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.',
+            description: 'Execute a Ductape SDK RUNTIME operation via the backend proxy (publishable key).\n\n' +
+                'ONLY use this tool for runtime operations: run, dispatch, execute, start, send, produce, query, insert, update, delete.\n' +
+                'Do NOT use this for creating or updating any asset (product, app, action, environment, database, storage, etc.) — ' +
+                'those require an access key. Use ductape_cli for all creation and update operations.\n\n' +
+                'Two-step rule for runtime operations:\n' +
+                '  1. Call ductape_generate_payload first to get the canonical payload template.\n' +
+                '     This reveals the exact "input" field keys — they are product/env/operation-specific.\n' +
+                '  2. Fill in the values from the template, then call ductape_execute.',
             inputSchema: executeInputSchema,
         }, executeHandler);
         server.registerTool('ductape_generate_payload', {
@@ -931,12 +1045,33 @@ async function main() {
                 'Pass module="app" or module="product" to scope the result.',
             inputSchema: schemaInputSchema,
         }, schemaHandler);
+        server.registerTool('ductape_cli', {
+            title: 'Ductape CLI',
+            description: 'Run a Ductape CLI command for administrative operations.\n\n' +
+                'USE THIS TOOL for any operation that creates or modifies platform configuration:\n' +
+                '  - Creating or updating products (products create/update) and apps (apps create/update)\n' +
+                '  - Importing an app from a Postman v2.1 or OpenAPI 3.0 file: "apps import <file> -t postman|openapi"\n' +
+                '  - Managing resources via "resources <type> <verb>" (databases, storage, caches…)\n' +
+                '  - Managing cloud connections and cloud-linked resources\n' +
+                '  - Listing workspaces, products, secrets\n' +
+                '  - Linking a project folder: "link --product <tag> --env <slug>"\n' +
+                '  - Syncing sessions/notifications/events: "apply" or "apply sessions" etc.\n' +
+                '  - Running database migrations: "db migrate", "db schema generate"\n\n' +
+                'NOTE: Environments, app actions, auths, features, quotas, fallbacks, and jobs are ' +
+                'configured in the Workbench UI — the CLI does not have commands for them.\n\n' +
+                'DO NOT use ductape_execute for admin operations — it uses a publishable key which only ' +
+                'covers runtime operations. Administrative operations will fail with "Authentication failed".\n\n' +
+                'The CLI uses the user\'s local logged-in session (ductape login). ' +
+                'If the CLI is not installed, this tool will return install instructions automatically.',
+            inputSchema: cliInputSchema,
+        }, cliHandler);
     }
     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);
+        server.tool('ductape_cli', cliInputSchema.shape, cliHandler);
     }
     else {
         console.error('MCP server does not expose .registerTool() or .tool()');

package/package.json

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

package/src/index.ts

@@ -11,6 +11,7 @@
  */
 
 import { createRequire } from 'module';
+import { execSync } from 'child_process';
 import { z } from 'zod';
 import {
   executeViaProxy,
@@ -35,18 +36,45 @@ 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.
+There are THREE categories of operations. Use the right tool for each:
+
+  0. ADMINISTRATIVE OPERATIONS  (create/update products, apps, environments, cloud connections…)
+       These require an access key and CANNOT be done via ductape_execute (publishable key only).
+       → Use ductape_cli instead. Examples:
+           ductape_cli("products list")
+           ductape_cli("products create --name \\"My Product\\" --tag my-product")
+           ductape_cli("cloud connections list")
+           ductape_cli("link --product my-product --env dev")
+       If the CLI is not installed, ductape_cli will return install instructions automatically.
+       NOTE: Environments and app actions are configured in the Workbench UI — there are no CLI commands for them.
+
+       DECLARATIVE SYNC  (apply sessions, notifications, events from code; run DB migrations)
+       → Also use ductape_cli. The project must be linked first (ductape init --link).
+           ductape_cli("apply")                        # sync all: sessions + notifications + events
+           ductape_cli("apply sessions")               # sessions only
+           ductape_cli("apply notifications")          # notifications only
+           ductape_cli("apply events")                 # event brokers only
+           ductape_cli("apply --dry-run")              # preview without changes
+           ductape_cli("db schema generate")           # diff schema.json → write migration files
+           ductape_cli("db schema generate --destructive")  # also generate drop operations
+           ductape_cli("db migrate")                   # apply pending migration files
+           ductape_cli("db migrate --dry-run")         # preview without applying
+           ductape_cli("db migrate --env prd")         # apply to a specific environment
+           ductape_cli("db migrate status")            # show applied vs pending migrations
+           ductape_cli("db migrate status --json")     # machine-readable status
+           ductape_cli("db migrate rollback")          # roll back last migration
+           ductape_cli("db migrate rollback -n 3")     # roll back last 3 migrations
+
+  1. ASSET CREATION / UPDATE  (create, update, add, register… for ANY asset type)
+       ALL creation and update operations require an access key and CANNOT go through ductape_execute.
+       → Use ductape_cli for every create/update operation. Examples:
+           ductape_cli("apps create --name \\"Email Service\\" --description \\"Transactional email\\"")
+           ductape_cli("apps list")
+           ductape_cli("resources storage list")
+           ductape_cli("resources database create -f db-config.json")
+       This applies to: products, apps, and resources (databases, storage, caches, etc.),
+       cloud connections, and secrets. Environments, app actions, auths, features, quotas,
+       fallbacks, jobs, and healthchecks are configured in the Workbench UI.
 
   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.
@@ -820,6 +848,68 @@ function buildSnippet(
 }
 
 
+// ─── CLI helpers ─────────────────────────────────────────────────────────────
+
+const ADMIN_SUBCOMMANDS = [
+  'login', 'logout', 'whoami',
+  'profiles',
+  'workspaces',
+  'link', 'unlink', 'init',
+  'products', 'apps',
+  'resources',
+  'cloud',
+  'secrets',
+  'generate',
+  'apply',
+  'db',
+  'graph',
+];
+
+function checkCli(): { available: boolean; version?: string } {
+  try {
+    const out = execSync('ductape --version', { encoding: 'utf8', timeout: 5000, stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+    return { available: true, version: out || 'unknown' };
+  } catch {
+    return { available: false };
+  }
+}
+
+function runCli(command: string): { success: boolean; output: string } {
+  const first = command.trim().split(/\s+/)[0];
+  if (!ADMIN_SUBCOMMANDS.includes(first)) {
+    return {
+      success: false,
+      output: `Subcommand "${first}" is not in the allowed admin subcommand list. Allowed: ${ADMIN_SUBCOMMANDS.join(', ')}.`,
+    };
+  }
+  try {
+    const output = execSync(`ductape ${command}`, {
+      encoding: 'utf8',
+      timeout: 30000,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    return { success: true, output: output.trim() };
+  } catch (err: any) {
+    const msg = (err.stderr || err.stdout || err.message || String(err)).trim();
+    return { success: false, output: msg };
+  }
+}
+
+const cliInputSchema = z.object({
+  command: z.string().describe(
+    'The ductape CLI command to run, without the leading "ductape" word. ' +
+    'Examples: "products list", "products create --name \\"My Product\\" --tag my-product", ' +
+    '"apps list", "apps create -f app.json", "resources storage list", ' +
+    '"cloud connections list", "link --product my-product --env dev".\n\n' +
+    'Use this tool for administrative operations: creating or updating products, apps, ' +
+    'resources (databases, storage, caches…), cloud connections, secrets, ' +
+    'and for apply/migrate workflows.\n\n' +
+    'Note: environments, app actions, features, quotas, fallbacks, and jobs are configured ' +
+    'in the Workbench UI — there are no CLI commands for them.\n\n' +
+    'The CLI uses the user\'s local logged-in session (ductape login) — no key is required.',
+  ),
+});
+
 async function loadMcpSdk(): Promise<{
   McpServer: new (info: { name: string; version: string }) => any;
   StdioServerTransport: new () => any;
@@ -884,6 +974,34 @@ async function main() {
   const server = new McpServer({ name: 'ductape-mcp', version: '0.1.0' });
   const transport = new StdioServerTransport();
 
+  const cliHandler = async (args: { command: string }) => {
+    const cli = checkCli();
+    if (!cli.available) {
+      return {
+        content: [{
+          type: 'text',
+          text: [
+            'The Ductape CLI is not installed or not in PATH.',
+            '',
+            'Install it with:',
+            '  npm install --global @ductape/cli',
+            '',
+            'Then log in:',
+            '  ductape login',
+            '',
+            'After logging in, retry this operation.',
+          ].join('\n'),
+        }],
+        isError: true,
+      };
+    }
+    const result = runCli(args.command);
+    return {
+      content: [{ type: 'text', text: result.output || '(no output)' }],
+      ...(result.success ? {} : { isError: true }),
+    };
+  };
+
   const executeHandler = async (args: { publishable_key?: string; module: SDKModule; method: string; params: unknown[] }) => {
     try {
       const key = args.publishable_key || process.env.DUCTAPE_PUBLISHABLE_KEY;
@@ -963,12 +1081,14 @@ async function main() {
       {
         title: 'Ductape SDK Execute',
         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.',
+          'Execute a Ductape SDK RUNTIME operation via the backend proxy (publishable key).\n\n' +
+          'ONLY use this tool for runtime operations: run, dispatch, execute, start, send, produce, query, insert, update, delete.\n' +
+          'Do NOT use this for creating or updating any asset (product, app, action, environment, database, storage, etc.) — ' +
+          'those require an access key. Use ductape_cli for all creation and update operations.\n\n' +
+          'Two-step rule for runtime operations:\n' +
+          '  1. Call ductape_generate_payload first to get the canonical payload template.\n' +
+          '     This reveals the exact "input" field keys — they are product/env/operation-specific.\n' +
+          '  2. Fill in the values from the template, then call ductape_execute.',
         inputSchema: executeInputSchema,
       },
       executeHandler,
@@ -1011,11 +1131,37 @@ async function main() {
       },
       schemaHandler,
     );
+    server.registerTool(
+      'ductape_cli',
+      {
+        title: 'Ductape CLI',
+        description:
+          'Run a Ductape CLI command for administrative operations.\n\n' +
+          'USE THIS TOOL for any operation that creates or modifies platform configuration:\n' +
+          '  - Creating or updating products (products create/update) and apps (apps create/update)\n' +
+          '  - Importing an app from a Postman v2.1 or OpenAPI 3.0 file: "apps import <file> -t postman|openapi"\n' +
+          '  - Managing resources via "resources <type> <verb>" (databases, storage, caches…)\n' +
+          '  - Managing cloud connections and cloud-linked resources\n' +
+          '  - Listing workspaces, products, secrets\n' +
+          '  - Linking a project folder: "link --product <tag> --env <slug>"\n' +
+          '  - Syncing sessions/notifications/events: "apply" or "apply sessions" etc.\n' +
+          '  - Running database migrations: "db migrate", "db schema generate"\n\n' +
+          'NOTE: Environments, app actions, auths, features, quotas, fallbacks, and jobs are ' +
+          'configured in the Workbench UI — the CLI does not have commands for them.\n\n' +
+          'DO NOT use ductape_execute for admin operations — it uses a publishable key which only ' +
+          'covers runtime operations. Administrative operations will fail with "Authentication failed".\n\n' +
+          'The CLI uses the user\'s local logged-in session (ductape login). ' +
+          'If the CLI is not installed, this tool will return install instructions automatically.',
+        inputSchema: cliInputSchema,
+      },
+      cliHandler,
+    );
   } 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);
+    server.tool('ductape_cli', cliInputSchema.shape, cliHandler);
   } else {
     console.error('MCP server does not expose .registerTool() or .tool()');
     process.exit(1);