@ductape/mcp 0.2.15 → 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}] }]
@@ -805,7 +807,7 @@ ALL params are passed as a JSON array in positional order matching the SDK signa
   graph.dropConstraint [name: string]
   graph.listLabels []
   graph.listRelationshipTypes []
-  graph.createAction [{ graphTag, tag, name, query, params? }, productTag?]
+  graph.createAction [{ graphTag, name, description?, operation, query: { operation, options }, parameters: [{ name, path, defaultValue, type, description?, required? }] }, productTag?]
   graph.listActions  [graphTag?, productTag?]
   graph.getAction    [actionTag, graphTag?, productTag?]
   graph.updateAction [actionTag, updates, graphTag?, productTag?]
@@ -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.
 
@@ -4716,9 +4766,51 @@ EXACT CODE-FIRST GRAPH CONTEXT:
   ctx.graph.deleteRelationship({ graph, id })
   ctx.graph.query<T>({ graph, action, params? })
   ctx.graph.execute<T>({ graph, action, input })
-  Every call must be inside ctx.step(). createNode/createRelationship are not projection upserts.
-  For replay-safe Neo4j projections, register a saved graph action whose Cypher uses MERGE and call
-  that action through ctx.graph.execute. Do not describe CREATE as idempotent.
+  Every call must be inside ctx.step(). Prefer the direct ctx.graph primitive that expresses the
+  operation. Saved actions are not generally preferred over createNode/updateNode/deleteNode,
+  relationship operations, or query; use a saved action only for a reusable parameterized operation
+  that the typed primitives cannot express. createNode/createRelationship are not projection upserts.
+
+SAVED GRAPH ACTION ASSET AND CLI CONTRACT:
+  Canonical project path:
+    ductape/graphs/<graph-tag>/actions/<action-tag>.action.json
+  action-tag is generated by lowercasing name, replacing non-alphanumerics with hyphens, and trimming
+  hyphens. Exactly one action object belongs in each file. Allowed top-level fields are graphTag,
+  name, description, operation, query, and parameters. Required fields are graphTag, name, operation,
+  query, and parameters. There is no persisted version field.
+
+  Example ductape/graphs/discovery-graph/actions/upsert-product-v1.action.json:
+  {
+    "graphTag": "discovery-graph",
+    "name": "Upsert Product V1",
+    "description": "Idempotently project one product by stable domain ID",
+    "operation": "executeRaw",
+    "query": {
+      "operation": "executeRaw",
+      "options": {
+        "query": "MERGE (p:Product {id: $productId}) SET p.name = $name, p.sourceVersion = $sourceVersion RETURN p",
+        "params": { "productId": null, "name": null, "sourceVersion": null }
+      }
+    },
+    "parameters": [
+      { "name": "productId", "path": "options.params.productId", "defaultValue": null, "type": "string", "required": true },
+      { "name": "name", "path": "options.params.name", "defaultValue": null, "type": "string", "required": true },
+      { "name": "sourceVersion", "path": "options.params.sourceVersion", "defaultValue": 0, "type": "number", "required": true }
+    ]
+  }
+  Validate without mutation:
+    ductape graph validateAction -f ductape/graphs/discovery-graph/actions/upsert-product-v1.action.json --json
+  Create and persist against the linked product:
+    ductape graph createAction -f ductape/graphs/discovery-graph/actions/upsert-product-v1.action.json --json
+  Read back with graph.getAction/listActions before relying on it. In-place updates use:
+    ductape graph updateAction -f <patch.json> --json
+  where patch.json is { "actionTag":"upsert-product-v1", "graphTag":"discovery-graph", "updates":{...} }.
+  Updating name does not change the stored tag. For breaking query/input/result changes, create a new
+  name/tag such as V2 and migrate callers; use updateAction for compatible corrections only.
+  ctx.graph.execute returns IExecuteGraphActionResult<T>: { success, executionTime, data: T[], count,
+  error? }. It resolves parameter values by each parameter.path. The SDK currently returns
+  success:false for action execution errors, so Feature code must inspect success and throw to fail
+  the step; do not treat a resolved unsuccessful result as success.
 
 EXACT CODE-FIRST VECTOR CONTEXT:
   ctx.vector.upsert<T>({
@@ -4738,9 +4830,40 @@ EXACT CODE-FIRST VECTOR CONTEXT:
   them into the Feature definition. Note the deliberate naming: ctx.vector.query uses values for
   the embedding, while the lower-level ductape.vector.query runtime facade uses vector.
   Vertex AI Vector Search stores and searches supplied vectors. It does NOT generate embeddings.
-  Generate embeddings through a separately registered/called model or App/function contract and
-  verify that the returned number[] dimension exactly matches the vector component. Do not claim
-  that a Vertex Vector Search index embeds text.
+  Do not claim that a Vertex Vector Search index embeds text.
+
+EMBEDDING EXECUTION — CURRENT CODE-FIRST CONTRACT:
+  Registered product models are configuration CRUD only in the current SDK. There is no ctx.model,
+  ctx.models, ctx.ai, or registered-model execute method, so never generate those calls. To execute
+  discovery-embeddings portably inside a Feature, define it as a portable function contract (preferred
+  for application-owned embedding code) or call an already registered App action via ctx.api.run.
+
+  import { defineFunctions } from '@ductape/sdk';
+  type EmbedInput = { texts: string[] };
+  type EmbedOutput = { embeddings: number[][]; dimensions: number; model: string };
+  export const DiscoveryEmbeddings = defineFunctions({
+    namespace: 'discovery-embeddings', version: '1', operations: { embed: {
+      input: { type:'object', required:['texts'], additionalProperties:false,
+        properties:{ texts:{ type:'array', items:{ type:'string', minLength:1 } } } },
+      output: { type:'object', required:['embeddings','dimensions','model'], additionalProperties:false,
+        properties:{ embeddings:{ type:'array', items:{ type:'array', items:{ type:'number' } } },
+          dimensions:{ type:'integer', minimum:1 }, model:{ type:'string', minLength:1 } } },
+      timeout_ms: 15000, idempotent: true, transports:[{ type:'local' }]
+    } } });
+
+  In the Feature handler:
+    const embeddings = ctx.functions.use(DiscoveryEmbeddings);
+    const generated = await ctx.step('embed-products', () =>
+      embeddings.embed({ texts: ctx.input.texts }));
+    if (generated.embeddings.length !== ctx.input.texts.length ||
+        generated.embeddings.some(v => v.length !== EXPECTED_VECTOR_DIMENSIONS)) {
+      throw new Error('EMBEDDING_DIMENSION_MISMATCH');
+    }
+  Register a real local handler at application bootstrap or configure a signed HTTPS/events transport.
+  Input and output JSON schemas are validated at runtime. Missing implementation fails with
+  FUNCTION_UNAVAILABLE; schema mismatch fails with FUNCTION_SCHEMA_VALIDATION_FAILED; timeout fails
+  with FUNCTION_TIMEOUT. Never substitute sample/random/recording-time embeddings. The Feature's
+  session is inherited in the portable function context, outside its business input.
 
 NESTJS CONSUMER ROUTING AND FEATURE INPUT:
   @Events.Consumer receives the published message object. Ductape may add
@@ -5303,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');
             }
@@ -5392,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' +
@@ -5469,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.15",
+  "version": "0.2.17",
   "description": "MCP server that exposes Ductape SDK operations via the backend proxy",
   "type": "module",
   "main": "dist/index.js",