@ductape/mcp 0.1.2 → 0.1.4

package/dist/index.js

@@ -9,6 +9,8 @@
  * publishable_key on every tool call. Per-call publishable_key still overrides
  * 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 = [
@@ -23,18 +25,26 @@ 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("product create --name \\"My Product\\" --tag my-product")
+           ductape_cli("environments list my-product")
+           ductape_cli("cloud connections list")
+       If the CLI is not installed, ductape_cli will return install instructions automatically.
+
+  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("app create --name \\"Email Service\\" --description \\"Transactional email\\"")
+           ductape_cli("apps list")
+           ductape_cli("actions list my-app-tag")
+       This applies to: products, apps, actions, auths, environments, databases, storage,
+       graphs, vectors, brokers, sessions, notifications, jobs, features, quotas, fallbacks,
+       healthchecks, caches, secrets, and webhooks.
 
   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.
@@ -776,6 +786,68 @@ function buildSnippet(language, payload, operationFamily, method) {
         ? buildPythonSnippet(payload, operationFamily, method)
         : buildTypeScriptSnippet(payload, operationFamily, method);
 }
+// ─── CLI helpers ─────────────────────────────────────────────────────────────
+const ADMIN_SUBCOMMANDS = [
+    'products', 'product',
+    'apps', 'app',
+    'workspaces', 'workspace',
+    'environments', 'environment',
+    'cloud',
+    'secrets',
+    'databases',
+    'storage',
+    'graphs',
+    'vectors',
+    'brokers',
+    'notifications',
+    'sessions',
+    'caches',
+    'jobs',
+    'generate',
+    'resources',
+    'init',
+    'login',
+    'logout',
+    'whoami',
+];
+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", "product create --name \\"My Product\\" --tag my-product", ' +
+        '"environments list my-product", "cloud connections list".\n\n' +
+        'Use this tool for ALL administrative operations: creating or updating products, apps, ' +
+        'environments, resources, cloud connections, and workspace configuration.\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([
@@ -805,8 +877,7 @@ async function loadMcpSdk() {
 function handleCliFlags() {
     const arg = process.argv[2];
     if (arg === '--version' || arg === '-v') {
-        // eslint-disable-next-line @typescript-eslint/no-require-imports
-        const { version } = require('../package.json');
+        const { version } = createRequire(import.meta.url)('../package.json');
         process.stdout.write(version + '\n');
         return true;
     }
@@ -831,6 +902,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 +997,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 +1031,27 @@ 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, apps, environments\n' +
+                '  - Managing cloud connections and resources\n' +
+                '  - Listing workspaces, products, secrets\n' +
+                '  - Any operation that would require an access key via the SDK\n\n' +
+                'DO NOT use ductape_execute for these — 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.2",
+  "version": "0.1.4",
   "description": "MCP server that exposes Ductape SDK operations via the backend proxy",
   "type": "module",
   "main": "dist/index.js",

package/src/index.ts

@@ -10,6 +10,8 @@
  * the env var when provided.
  */
 
+import { createRequire } from 'module';
+import { execSync } from 'child_process';
 import { z } from 'zod';
 import {
   executeViaProxy,
@@ -34,18 +36,26 @@ 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("product create --name \\"My Product\\" --tag my-product")
+           ductape_cli("environments list my-product")
+           ductape_cli("cloud connections list")
+       If the CLI is not installed, ductape_cli will return install instructions automatically.
+
+  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("app create --name \\"Email Service\\" --description \\"Transactional email\\"")
+           ductape_cli("apps list")
+           ductape_cli("actions list my-app-tag")
+       This applies to: products, apps, actions, auths, environments, databases, storage,
+       graphs, vectors, brokers, sessions, notifications, jobs, features, quotas, fallbacks,
+       healthchecks, caches, secrets, and webhooks.
 
   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.
@@ -819,6 +829,73 @@ function buildSnippet(
 }
 
 
+// ─── CLI helpers ─────────────────────────────────────────────────────────────
+
+const ADMIN_SUBCOMMANDS = [
+  'products', 'product',
+  'apps', 'app',
+  'workspaces', 'workspace',
+  'environments', 'environment',
+  'cloud',
+  'secrets',
+  'databases',
+  'storage',
+  'graphs',
+  'vectors',
+  'brokers',
+  'notifications',
+  'sessions',
+  'caches',
+  'jobs',
+  'generate',
+  'resources',
+  'init',
+  'login',
+  'logout',
+  'whoami',
+];
+
+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", "product create --name \\"My Product\\" --tag my-product", ' +
+    '"environments list my-product", "cloud connections list".\n\n' +
+    'Use this tool for ALL administrative operations: creating or updating products, apps, ' +
+    'environments, resources, cloud connections, and workspace configuration.\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;
@@ -854,8 +931,7 @@ async function loadMcpSdk(): Promise<{
 function handleCliFlags(): boolean {
   const arg = process.argv[2];
   if (arg === '--version' || arg === '-v') {
-    // eslint-disable-next-line @typescript-eslint/no-require-imports
-    const { version } = require('../package.json') as { version: string };
+    const { version } = createRequire(import.meta.url)('../package.json') as { version: string };
     process.stdout.write(version + '\n');
     return true;
   }
@@ -884,6 +960,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 +1067,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 +1117,31 @@ 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, apps, environments\n' +
+          '  - Managing cloud connections and resources\n' +
+          '  - Listing workspaces, products, secrets\n' +
+          '  - Any operation that would require an access key via the SDK\n\n' +
+          'DO NOT use ductape_execute for these — 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);