@ductape/mcp 0.2.16 → 0.2.17

package/dist/index.js

@@ -445,7 +445,9 @@ ALL params are passed as a JSON array in positional order matching the SDK signa
     ductape_cli("products create --name <name> --tag <tag>")
     ductape_cli("products environments list <tag> --json")
     ductape_cli("products environments get <tag> <slug> --json")
-    ductape_cli("products apps list --product <id> --json")
+    ductape_cli("products apps list --product <id_or_tag> --json") ← compact linked apps only
+    ductape_cli("products apps actions list --product <id_or_tag> --app <app_tag> --json")
+    ductape_cli("products apps actions get --product <id_or_tag> --app <app_tag> --action <action_tag> --json")
 
   SDK method signatures (for reference, admin key only):
   product.create        [data: { name, description, tag?, envs?: [{slug, name}] }]
@@ -1086,6 +1088,25 @@ const snippetGenerateInputSchema = payloadGenerateInputSchema.extend({
 const schemaInputSchema = z.object({
     module: z.enum(['app', 'product']).optional().describe('Optional. Scope the result to one module. With no method, returns only the compact list of available methods.'),
     method: z.string().optional().describe('Optional method key such as "databases.create" or "notifications.update". Use with module to return only that method schema.'),
+    product_tag: z.string().optional().describe('For live app-action discovery, the product the app is linked to. Must be supplied with app_tag and action_tag.'),
+    app_tag: z.string().optional().describe('For live app-action discovery, the linked app tag. Must be supplied with product_tag and action_tag.'),
+    action_tag: z.string().optional().describe('For live app-action discovery, the exact action tag whose complete contract should be returned.'),
+});
+const marketplaceDiscoverInputSchema = z.object({
+    query: z.string().min(1).describe('Capability or provider search, for example "payments" or "paystack".'),
+    category: z.string().optional().describe('Optional marketplace category/domain filter.'),
+    limit: z.number().int().min(1).max(50).optional().default(10),
+});
+const marketplaceConnectInputSchema = z.object({
+    product_tag: z.string().min(1).describe('Product that should receive the marketplace app connection.'),
+    app_tag: z.string().min(1).describe('Exact public app tag returned by ductape_marketplace_discover.'),
+    environments: z.array(z.object({
+        app_env_slug: z.string().min(1),
+        product_env_slug: z.string().min(1),
+    })).min(1).describe('Explicit app-to-product environment mappings. Include every product environment that will use the app.'),
+});
+const marketplaceInspectInputSchema = z.object({
+    app_tag: z.string().min(1).describe('Exact public app tag returned by ductape_marketplace_discover.'),
 });
 function toPrettyJson(value) {
     return JSON.stringify(value ?? {}, null, 2);
@@ -2636,17 +2657,27 @@ An App must be fully set up in Ductape before any code can use it:
   5. The App must be connected to the product (product.apps.add) and its envs mapped
 
 DISCOVER BEFORE CREATING:
-  ductape_cli("marketplace search payments --json")
-  ductape_cli("marketplace search paystack --json")
+  ductape_marketplace_discover({ query: "payments" })
+  ductape_marketplace_discover({ query: "paystack" })
   ductape_cli("marketplace categories --json")
-  ductape_cli("marketplace get <app_tag> --json")
+  ductape_marketplace_inspect({ app_tag: "<exact-returned-tag>" })
 
 marketplace search matches capability terms against public app names, tags, descriptions,
-categories, actions, and webhooks. marketplace get returns the complete public app definition,
-including the exact current-version action tags and body/query/header/param schemas. Never infer
+categories, actions, and webhooks. Marketplace inspect returns a compact current-version definition,
+including the exact action tags and body/query/header/param schemas. Never infer
 Paystack action names such as "initialize" or "verify": inspect the marketplace record first.
 If no suitable app exists, create one or import Paystack's OpenAPI/Postman definition.
 
+CONNECT A DISCOVERED APP THROUGH MCP:
+  1. Run ductape_marketplace_discover and select an exact returned app tag.
+  2. Run ductape_marketplace_inspect to read its environments and compact action contracts.
+  3. Read product environments with ductape_cli("products environments list <product_tag> --json").
+  4. Match each product environment explicitly to one environment exposed by the app.
+  5. Call ductape_marketplace_connect({ product_tag, app_tag, environments }).
+  6. Verify with ductape_cli("products apps list --product <product_tag> --json").
+  Never guess environment mappings or action tags. Connecting mutates product configuration;
+  obtain user approval when the user has not already requested the connection.
+
 ONLY after all five steps can any code call:
   ctx.api.run({ app: '<app_tag>', event: '<action_tag>', input: { ... } })   ← in a feature handler
   actions.run([{ product, env, app: '<app_tag>', action: '<action_tag>', input }])   ← at runtime
@@ -2676,18 +2707,21 @@ Manage environments (base URLs per stage) in Workbench; this currently has no CL
 
 Discover apps in a product and their actions (ALWAYS do this before writing any ctx.api.run call):
   Step 1 — list apps connected to the product:
-    ductape_cli("products get --tag <product_tag> --json")    → full product document; check apps[]
-    ductape_cli("products apps list --product <product_id> --json")  → apps[] with access_tag, envs
-  Step 2 — list actions in an app:
-    ductape_execute("actions.list", [app_tag])                → returns all action tags + names
-  Step 3 — fetch the input schema for an action:
-    ductape_execute("actions.fetch", [app_tag, action_tag])
+    ductape_cli("products apps list --product <product_id_or_tag> --json")
+      → compact list containing ONLY apps linked to that product; accepts an id or tag
+  Step 2 — list compact action summaries for one linked app:
+    ductape_cli("products apps actions list --product <product_id_or_tag> --app <app_tag> --json")
+  Step 3 — fetch one complete action contract:
+    ductape_cli("products apps actions get --product <product_id_or_tag> --app <app_tag> --action <action_tag> --json")
+    OR ductape_schema({ product_tag: "<product_tag>", app_tag: "<app_tag>", action_tag: "<action_tag>" })
       → returns { body: {fieldName: {type, required}}, params: {}, query: {}, headers: {} }
     OR: call ductape_generate_payload (operation_family="action", method="run",
           targets={app: "app_tag", action: "action_tag"}) to get the exact resolved payload shape
   Step 4 — call ductape_schema({ module: "app" }) if you need the JSON schema for creating/updating
            app resources (not for runtime input — use actions.fetch or ductape_generate_payload for that)
   NEVER assume action input field names. Always fetch the action definition first.
+  NEVER fetch products get, apps get, marketplace get, or products apps list --full merely to inspect
+  one action. Those expanded catalogues can be very large and may exceed MCP/client token limits.
 
 Manage actions (individual API endpoints) in Workbench or import an OpenAPI/Postman file.
 Creation/update are administrative and must never use ductape_execute.
@@ -2746,11 +2780,11 @@ Connecting an app to a product (after creation):
   3. Configure auth:     Workbench
   4. Define actions:     Workbench
                          OR import: ductape_cli("apps import <file.json> -t postman|openapi")
-  5. Connect to product: Requires the product_id (from ductape_cli("products get --tag <tag> --json")).
+  5. Connect to product: Requires the product_id.
                          There is no CLI command for this step — the SDK product.apps.add method requires
                          an access key which only the backend can provide. Connect via Workbench.
-  6. Verify:             ductape_cli("products get --tag <product_tag> --json") → check apps[] contains the app
-                         ductape_execute("actions.list", [app_tag]) → verify actions are registered
+  6. Verify:             ductape_cli("products apps list --product <product_tag> --json")
+                         ductape_cli("products apps actions list --product <product_tag> --app <app_tag> --json")
 `.trim(),
     products: `
 DUCTAPE PRODUCTS
@@ -3524,7 +3558,8 @@ STEP 1 — UNDERSTAND the goal
   understand: what the feature does, what it returns, what can fail and how failures should behave.
 
 STEP 2 — INVENTORY existing Ductape components
-  Call ductape_cli("products get --tag <product_tag> --json") to read the full product document.
+  Call ductape_cli("products components list --product-tag <product_tag> --json") for the compact inventory.
+  Call ductape_cli("products apps list --product <product_tag> --json") for linked apps only.
   (product.* requires the access key — never use ductape_execute for product reads, it will return 403)
   Note what already exists:
     - databases[]      → available for ctx.database.insert/query/update/delete steps
@@ -3616,10 +3651,25 @@ STEP 8 — SET rollbacks for reversible steps
       async (result) => ctx.api.run({ app: 'stripe', event: 'refund', input: { chargeId: result.id } })
     );
 
-Code-first ctx step types currently record: function | action | database | graph | vector |
+Code-first ctx step types currently record: function | action | database | graph | vector | session |
   notification | storage | produce | quota | fallback | child_feature | sleep | wait_for_signal |
   checkpoint.
 
+CODE-FIRST SESSION LIFECYCLE:
+  ctx.session is the optional session token inherited by the Feature and all nested Ductape
+  operations. It is read-only execution context and is not a session service.
+  ctx.sessions records explicit product-session lifecycle steps:
+    ctx.sessions.start<T>({ session: "player-session", data, cache? })
+    ctx.sessions.verify<T>({ session: "player-session", token, cache? })
+    ctx.sessions.refresh<T>({ session: "player-session", refreshToken, cache? })
+    ctx.sessions.revoke({ session: "player-session", sessionId?, identifier? })
+    ctx.sessions.list<T>({ session: "player-session", identifier?, page?, limit?, cache? })
+  Put each call inside ctx.step(). The session field identifies the configured product session; the
+  executor supplies product and env. start creates a new token pair but does not replace ctx.session
+  for subsequent steps in the same Feature. Pass the returned token explicitly where application
+  logic needs the newly created session. Never serialize the inherited ctx.session into the Feature
+  definition, logs, metadata, or another step unless the target operation explicitly requires a token.
+
 Valid synchronous Feature candidates include generate-world, resolve-nation-turn,
 calculate-route-capacity, price-subscription, evaluate-entitlement, and build-replay.
 
@@ -5376,6 +5426,35 @@ async function main() {
     };
     const schemaHandler = async (args) => {
         try {
+            const liveActionScope = [args.product_tag, args.app_tag, args.action_tag];
+            if (liveActionScope.some(Boolean)) {
+                if (!liveActionScope.every(Boolean)) {
+                    throw new Error('product_tag, app_tag, and action_tag are all required to fetch a live app action contract');
+                }
+                const response = await cliHandler({
+                    command: `products apps actions get --product ${shellArgument(args.product_tag)} --app ${shellArgument(args.app_tag)} --action ${shellArgument(args.action_tag)} --json`,
+                });
+                if (response.isError)
+                    return response;
+                const raw = response.content[0]?.type === 'text' ? response.content[0].text : '';
+                let action = raw;
+                try {
+                    action = JSON.parse(raw);
+                }
+                catch { /* Preserve the CLI diagnostic verbatim. */ }
+                return {
+                    content: [{
+                            type: 'text',
+                            text: JSON.stringify({
+                                product_tag: args.product_tag,
+                                app_tag: args.app_tag,
+                                action_tag: args.action_tag,
+                                action,
+                                hint: 'This is the complete contract for one action linked to this product; use products apps actions list for compact discovery.',
+                            }, null, 2),
+                        }],
+                };
+            }
             if (args.method && !args.module) {
                 throw new Error('module is required when method is provided');
             }
@@ -5465,9 +5544,10 @@ async function main() {
         }, snippetGenerateHandler);
         server.registerTool('ductape_schema', {
             title: 'Ductape Asset Schema',
-            description: 'Returns a compact method index or one targeted asset schema derived from the SDK Joi validators. ' +
+            description: 'Returns a compact method index, one targeted asset schema, or one complete live app-action contract. ' +
                 'Call with module="app" or module="product" first to list method keys, then call again with ' +
                 'module and method (for example method="databases.create") for the complete field schema. ' +
+                'For one linked app action, call with product_tag, app_tag, and action_tag; do not fetch a full app catalogue. ' +
                 'Avoid calling without module unless you explicitly need the entire manifest.\n\n' +
                 'ALWAYS call this before constructing a file for "resources <type> create" or any cloud ' +
                 'import/provision operation — field shapes are not guessable from context.\n\n' +
@@ -5542,6 +5622,35 @@ async function main() {
                 'Supports in-place and new-codebase guidance destinations. Read-only unless write or ensure_product is explicitly enabled.',
             inputSchema: migrationInputSchema,
         }, migrationHandler);
+        server.registerTool('ductape_marketplace_discover', {
+            title: 'Discover Ductape Marketplace Apps',
+            description: 'Search public marketplace apps by capability and return compact app, environment, and action summaries. ' +
+                'Use the returned exact app tag; never infer provider or action tags from a brand name.',
+            inputSchema: marketplaceDiscoverInputSchema,
+        }, async (args) => cliHandler({
+            command: `marketplace search ${shellArgument(args.query)}${args.category ? ` --category ${shellArgument(args.category)}` : ''} --limit ${args.limit ?? 10} --json`,
+        }));
+        server.registerTool('ductape_marketplace_inspect', {
+            title: 'Inspect a Ductape Marketplace App',
+            description: 'Return the selected public app version, supported environment slugs, and compact action contracts. ' +
+                'Call this after discovery and before choosing environment mappings or writing action calls.',
+            inputSchema: marketplaceInspectInputSchema,
+        }, async (args) => cliHandler({
+            command: `marketplace get ${shellArgument(args.app_tag)} --json`,
+        }));
+        server.registerTool('ductape_marketplace_connect', {
+            title: 'Connect a Marketplace App to a Product',
+            description: 'Create/reuse secure app access, connect an exact discovered marketplace app to a product, and map its environments. ' +
+                'Discover first, inspect the returned environments/actions, obtain any required user configuration, and never guess mappings.',
+            inputSchema: marketplaceConnectInputSchema,
+        }, async (args) => {
+            const mappings = args.environments
+                .map((env) => ` --env-map ${shellArgument(`${env.app_env_slug}:${env.product_env_slug}`)}`)
+                .join('');
+            return cliHandler({
+                command: `products apps connect --product ${shellArgument(args.product_tag)} --app ${shellArgument(args.app_tag)}${mappings} --json`,
+            });
+        });
         server.registerTool('ductape_cli', {
             title: 'Ductape CLI',
             description: 'Run a Ductape CLI command for administrative operations.\n\n' +

package/package.json

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