@ductape/mcp 0.2.22 → 0.2.23

package/dist/index.js

@@ -90,12 +90,15 @@ There are THREE categories of operations. Use the right tool for each:
        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("products create -f product.json")   # body: { name, tag?, envs?: [...] } — no --name/--tag flags exist, only -f <file.json> or interactive TTY
            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: App actions are configured in the Workbench UI — there is no CLI command for them.
        Environments DO have CLI commands: ductape_cli("products environments list/get/create/update ...").
+       App actions (endpoints) also have CLI commands: ductape_cli("apps actions list/get/create/update/delete
+       --app <app_tag> ..."). When the user wants to integrate a new endpoint, call
+       ductape_integrate_endpoint first — it returns the full ordered flow (choose/create the app,
+       define the action, connect the app to the product) before any code should be written.
 
        RESOLVING "No linked project" ERRORS:
        Some commands (declarative sync below, db migrate/schema, products environments *) need a
@@ -194,13 +197,22 @@ There are THREE categories of operations. Use the right tool for each:
   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 create -f app.json")   # no --name/--description flags exist, only -f <file.json> or interactive TTY. body: { app_name, description, tag, envs?: [{ env_name, slug, description, base_url, active }] } — tag is REQUIRED.
            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 have their own CLI commands (see below);
-       App actions and auths are configured in the Workbench UI. Quotas, fallbacks, jobs, and
+       app actions have their own CLI commands too — ductape_cli("apps actions create --app <tag>
+       --action-file action.json") (NOT -f — that flag is claimed by the parent "apps" command, so
+       Commander resolves it against the ancestor and this subcommand never sees it; same fix as
+       "products environments create/update" uses --env-file for the identical reason). Body: {
+       tag, name, resource, method, request_type, description?, params?, query?, headers?, body?,
+       response? }, where resource is a path RELATIVE to each of the app's environment base_urls
+       (e.g. "/v1/users/{id}"), not a full URL, and request_type is REQUIRED — one of
+       "application/json" | "application/x-www-form-urlencoded" | "multipart/form-data" | "SOAP" |
+       "html" (not the short names "json"/"xml"/"form"). Auths are still configured
+       in the Workbench UI. Quotas, fallbacks, jobs, and
        healthchecks are administrative resources managed with ductape_cli("resources <type> ...").
        Features have no CLI create command because their definitions are code-first through
        features.define. They DO have a CLI persistence command — ductape_cli("features sync") —
@@ -470,8 +482,26 @@ ALL params are passed as a JSON array in positional order matching the SDK signa
   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 } }]
+  These are admin ops — go through ductape_cli, not ductape_execute:
+    ductape_cli("apps actions create --app <app_tag> --action-file action.json")
+    ductape_cli("apps actions update --app <app_tag> --action <action_tag> --action-file action.json")
+    ductape_cli("apps actions list --app <app_tag> --json")
+    ductape_cli("apps actions get --app <app_tag> --action <action_tag> --json")
+    ductape_cli("apps actions delete --app <app_tag> --action <action_tag>")
+  NOTE: the flag is --action-file, NOT -f/--file — that flag belongs to the parent "apps" command
+  (used by "apps create"/"apps update"), and Commander resolves a flag shared by an ancestor and a
+  descendant against the ancestor, so -f here would silently never reach this subcommand. Verified
+  live: passing -f prints "required option '-f, --file <path>' not specified" even though it was
+  supplied; --action-file is the fix (same pattern already used by "products environments
+  create/update" with --env-file for the identical collision).
+  resource is a path RELATIVE to each of the app's environment base_urls (e.g. "/v1/users/{id}"),
+  never a full URL — Ductape joins base_url + resource per environment at call time.
+  request_type is REQUIRED (verified live) — one of "application/json" |
+  "application/x-www-form-urlencoded" | "multipart/form-data" | "SOAP" | "html". response.status_code
+  is a STRING enum of standard HTTP status codes (e.g. "200", not the number 200) and
+  response.response_format uses the SAME enum as request_type above (not "json"/"xml"/"form").
+  actions.create  [app_tag, data: { tag: string, name: string, resource: string, method: "GET"|"POST"|"PUT"|"PATCH"|"DELETE", request_type: "application/json"|"application/x-www-form-urlencoded"|"multipart/form-data"|"SOAP"|"html", description?: string, body?: object, params?: object, query?: object, headers?: object, response?: { name?: string, status_code: string, success: boolean, body: object, response_format: "application/json"|"application/x-www-form-urlencoded"|"multipart/form-data"|"SOAP"|"html" } }]
+  actions.update  [app_tag, action_tag, data: { resource?: string, method?: "GET"|"POST"|"PUT"|"PATCH"|"DELETE", description?: string, request_type?: "application/json"|"application/x-www-form-urlencoded"|"multipart/form-data"|"SOAP"|"html", body?: object, query?: object, params?: object, headers?: object, response?: { name?: string, success: boolean, body: object, response_format: "application/json"|"application/x-www-form-urlencoded"|"multipart/form-data"|"SOAP"|"html", status_code: string } }]
   actions.fetch   [app_tag, action_tag]
   actions.list    [app_tag]
   actions.run     [{ product, env, app, action, input: { "body:fieldName": value, ... } }]  ← CALL ductape_generate_payload FIRST (operation_family="action", method="run", targets={app, action})
@@ -1112,6 +1142,11 @@ const marketplaceConnectInputSchema = z.object({
 const marketplaceInspectInputSchema = z.object({
     app_tag: z.string().min(1).describe('Exact public app tag returned by ductape_marketplace_discover.'),
 });
+const integrateEndpointInputSchema = z.object({
+    product_tag: z.string().min(1).optional().describe('Target product tag, if already known. Omit if the user has not said which product this is for yet.'),
+    app_tag: z.string().min(1).optional().describe('Existing app tag, if the user already said which app this endpoint belongs to. Omit when creating ' +
+        'a new app, or when the app has not been chosen yet — the returned flow starts by asking.'),
+});
 function toPrettyJson(value) {
     return JSON.stringify(value ?? {}, null, 2);
 }
@@ -2750,8 +2785,12 @@ If a feature step needs to call an external service and no App is registered for
 An app is a versioned API integration definition. It contains environments (base URLs), actions
 (individual endpoint specs), auth schemes, webhooks, variables, and constants.
 
-Create an app (admin — ductape_cli):
-  ductape_cli("apps create --name \\"Email Service\\" --description \\"Transactional email\\"")
+Call ductape_integrate_endpoint for the full ordered flow (choose/create the app, define the
+action, connect it to the product) before writing the ctx.api.run call below.
+
+Create an app (admin — ductape_cli; no --name/--description flags exist, only -f <file.json> or
+interactive TTY):
+  ductape_cli("apps create -f app.json")   # body: { app_name, description, tag, envs?: [...] } — tag is REQUIRED
   ductape_cli("app.init", ["app_tag"])       → loads app into builder state
 
 Import from a file:
@@ -2832,15 +2871,27 @@ Connecting an app to a product (after creation):
   NOTE: All product.* module methods require the access key and CANNOT use ductape_execute.
   Use ductape_cli for all product-level operations.
 
-  FULL FLOW to make an app callable from a product:
-  1. Create the app:     ductape_cli("apps create --name \\"Service Name\\" --description \\"...\\"")
-  2. Add environments:   Workbench
-  3. Configure auth:     Workbench
-  4. Define actions:     Workbench
+  FULL FLOW to make an app callable from a product — call ductape_integrate_endpoint for the
+  ordered version of this with exact ask-the-user points; summary (all verified live):
+  1. Create the app:     ductape_cli("apps create -f app.json")
+                         body: { app_name, description, tag, envs: [{ env_name, slug, description,
+                         base_url, active }, ...] } — tag is REQUIRED; every active env needs a base_url.
+                         No --name/--description flags exist, only -f <file.json> or interactive TTY.
+  2. Add environments:   Part of step 1's envs array, or later via ductape_cli("apps update --tag
+                         <app_tag> --proxy -f app.json") with an updated envs array.
+  3. Configure auth:     Workbench (no CLI command).
+  4. Define actions:     ductape_cli("apps actions create --app <app_tag> --action-file action.json")
+                         body: { tag, name, resource, method, request_type, description?, params?,
+                         query?, headers?, body?, response? } — request_type is REQUIRED, one of
+                         "application/json" | "application/x-www-form-urlencoded" |
+                         "multipart/form-data" | "SOAP" | "html" (not "json"/"xml"/"form"); resource
+                         is relative to each env's base_url, never a full URL.
                          OR import: ductape_cli("apps import <file.json> -t postman|openapi")
-  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.
+  5. Connect to product: ductape_cli("products apps connect --product <product_tag> --app <app_tag>
+                         --env-map <app_env>:<product_env> [repeat --env-map per environment] --json")
+                         Requires the app to be public in the marketplace OR owned by the same
+                         workspace as the product. Does the full connect + environment-mapping
+                         sequence in one call.
   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(),
@@ -5002,7 +5053,14 @@ EMBEDDING EXECUTION — CURRENT CODE-FIRST CONTRACT:
         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.
+  Register a real local handler at application bootstrap or configure gRPC-mTLS, Events, or signed HTTPS.
+  Remote resolution order is gRPC-mTLS, Events, then signed HTTPS. A gRPC transport is
+  { type:'grpc', endpoint:'host:443', service:'ductape.functions.v1.PortableFunctions',
+    method:'Invoke', authentication:'mtls', tls:{ ca_env, cert_env, key_env } }.
+  Never write PEM, certificates, private keys, tokens, or access keys into function JSON. Set
+  DUCTAPE_FUNCTION_GRPC_ENDPOINT and referenced TLS variables in the application runtime. The gRPC
+  adapter must pool channels. Only UNAVAILABLE/deadline failures may fall back; auth, correlation,
+  schema, and application failures must not execute again over another 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
@@ -5156,6 +5214,113 @@ const portableFunctionSetupHandler = async (args) => {
                     ],
                 }, null, 2) }] };
 };
+// This tool only derives a step-by-step plan from its arguments and read-only lookups the calling
+// agent performs itself via other tools. It runs no CLI command and writes nothing.
+const integrateEndpointHandler = async (args) => {
+    const hasApp = Boolean(args.app_tag);
+    const hasProduct = Boolean(args.product_tag);
+    const stages = [];
+    if (!hasApp) {
+        stages.push({
+            stage: 0,
+            title: 'Choose the app',
+            ask_user: 'Should this endpoint be added to an existing app, or do you want to create a new app for it?',
+            if_existing_app: [
+                'Get the exact app tag. If unsure, call ductape_cli("apps list --json"), or ' +
+                    'ductape_marketplace_discover/ductape_marketplace_inspect if it might be a public marketplace app.',
+                'Re-call this tool with that app_tag once known — the returned flow will skip straight to stage 2.',
+            ],
+            if_new_app: 'Continue to stage 1.',
+        });
+    }
+    if (!hasApp) {
+        stages.push({
+            stage: 1,
+            title: 'Create the app (new app path only — skip if using an existing app)',
+            ask_user: [
+                'App name and a short description.',
+                'What environments does this app need (e.g. dev, staging, production), and what is the base ' +
+                    'URL for each? At least one environment is required. Every ACTIVE environment must have a ' +
+                    'base_url before the action in stage 2 can be called against it.',
+            ],
+            then: [
+                'Write a JSON body: { app_name, description, tag, envs: [{ env_name, slug, description, ' +
+                    'base_url, active: true }, ...] }. tag is REQUIRED — derive a slug from app_name if the ' +
+                    'user has not given one explicitly.',
+                'Run: ductape_cli("apps create -f <path-to-body.json> --json")',
+                'The app tag is what you supplied, not something the response generates — use it as app_tag ' +
+                    'in every later stage.',
+            ],
+        });
+    }
+    stages.push({
+        stage: 2,
+        title: 'Define the action (the endpoint itself)',
+        app_tag: args.app_tag ?? '<app tag from stage 1, or the existing app tag>',
+        ask_user: [
+            'The HTTP method (GET/POST/PUT/PATCH/DELETE).',
+            'The endpoint PATH relative to the app\'s base_url — e.g. "/v1/users/{id}", never a full URL. ' +
+                'Ductape joins base_url + resource per environment at call time, so the same action works ' +
+                'across every environment automatically.',
+            'Only what is relevant to this specific endpoint: query params, headers, request body shape ' +
+                '(for POST/PUT/PATCH), and the expected response shape (status_code, success flag, a body ' +
+                'sample). Do not invent fields the user has not described or that are not in the API docs.',
+        ],
+        then: [
+            'If the exact body shape is uncertain, call ductape_schema first.',
+            'Write a JSON body: { tag, name, resource, method, request_type, description?, params?, ' +
+                'query?, headers?, body?, response? }. request_type is REQUIRED — one of "application/json" ' +
+                '| "application/x-www-form-urlencoded" | "multipart/form-data" | "SOAP" | "html" (not ' +
+                '"json"/"xml"/"form"). If response is included, response.status_code and ' +
+                'response.response_format use that same set of values, and status_code is a STRING (e.g. ' +
+                '"200", not the number 200).',
+            'Run: ductape_cli("apps actions create --app <app_tag> --action-file <path-to-action.json> ' +
+                '--json") — the flag is --action-file, not -f (that flag belongs to the parent "apps" ' +
+                'command and Commander resolves it there, so -f would silently be ignored here).',
+        ],
+    });
+    stages.push({
+        stage: 3,
+        title: 'Connect the app to the product',
+        skip_if: 'The app is already connected to the target product — check with ' +
+            'ductape_cli("products apps list --product <product_tag> --json") before asking the user anything here.',
+        product_tag: args.product_tag ?? '<ask the user, if not already established from context>',
+        then: [
+            hasProduct
+                ? `Product already known: ${args.product_tag}.`
+                : 'Ask the user which product this belongs to, unless already obvious from context.',
+            'Get the product\'s environments: ductape_cli("products environments list <product_tag> --json")',
+            'Map each product environment to one of the app\'s environments (usually 1:1 by name) — ask the ' +
+                'user rather than guessing if it is not obvious.',
+            'Run: ductape_cli("products apps connect --product <product_tag> --app <app_tag> --env-map ' +
+                '<app_env>:<product_env> [repeat --env-map per environment] --json"). If the app is a public ' +
+                'marketplace app, ductape_marketplace_connect does the same thing in one call.',
+        ],
+    });
+    stages.push({
+        stage: 4,
+        title: 'Only now write integration code',
+        instructions: [
+            'Do not write any code that calls this endpoint before stages 0-3 are complete — the action and ' +
+                'the product connection must exist first, or the generated code will reference a tag that ' +
+                'does not exist yet.',
+            'Call ductape_generate_payload (operation_family="action", method="run" or "dispatch", ' +
+                'targets={app, action}) first, then ductape_generate_snippet or ductape_execute to call it.',
+        ],
+    });
+    return {
+        content: [{
+                type: 'text',
+                text: JSON.stringify({
+                    ok: true,
+                    flow: 'integrate_endpoint',
+                    note: 'Follow these stages in order. Each stage tells you what to ask the user and which ' +
+                        'ductape_cli command to run. Stages already satisfied by the arguments you passed are omitted.',
+                    stages,
+                }, null, 2),
+            }],
+    };
+};
 const eventsTopicSetupHandler = async (args) => {
     const tag = `${args.broker_tag}:${args.topic_tag}`;
     const relativePath = `ductape/events/${args.topic_tag}.topic.json`;
@@ -5840,6 +6005,15 @@ async function main() {
                 command: `products apps connect --product ${shellArgument(args.product_tag)} --app ${shellArgument(args.app_tag)}${mappings} --json`,
             });
         });
+        server.registerTool('ductape_integrate_endpoint', {
+            title: 'Integrate a New Endpoint',
+            description: 'Call this FIRST whenever the user wants to integrate a new API endpoint — before writing any ' +
+                'code. Returns the ordered flow: choose an existing app or create a new one, define the ' +
+                'action (endpoint) on it, connect the app to the target product, and only then write code. ' +
+                'Read-only — it runs no CLI command itself and performs the steps only when you follow up with ' +
+                'the ductape_cli calls it names.',
+            inputSchema: integrateEndpointInputSchema,
+        }, integrateEndpointHandler);
         server.registerTool('ductape_cli', {
             title: 'Ductape CLI',
             description: 'Run a Ductape CLI command for administrative operations.\n\n' +
@@ -5958,6 +6132,7 @@ async function main() {
         server.tool('ductape_function_setup', portableFunctionSetupInputSchema.shape, portableFunctionSetupAnnotations, portableFunctionSetupHandler);
         server.tool('ductape_redis_setup', redisSetupInputSchema.shape, redisSetupHandler);
         server.tool('ductape_migration_plan', migrationInputSchema.shape, migrationHandler);
+        server.tool('ductape_integrate_endpoint', integrateEndpointInputSchema.shape, integrateEndpointHandler);
         server.tool('ductape_cli', cliInputSchema.shape, cliHandler);
     }
     else {

package/docs/TOOLS.md

@@ -2,6 +2,42 @@
 
 The Ductape MCP server exposes proxy, CLI, discovery, documentation, migration, and portable-function setup tools.
 
+## Tool: `ductape_integrate_endpoint`
+
+Call this first whenever the user wants to integrate a new API endpoint, before writing any code.
+It is read-only guidance — it runs no CLI command itself and returns the ordered flow to follow:
+
+1. **Choose the app** — ask first: existing app, or create a new one? Do not assume "new" just
+   because the API seems unfamiliar — check `ductape_cli("apps list --json")` and let the user
+   decide. If new: `ductape_cli("apps create -f app.json")`, body `{ app_name, description, tag,
+   envs: [...] }` (`tag` is REQUIRED — no `--name`/`--description` flags exist, only `-f
+   <file.json>` or interactive TTY), collecting an environment + base URL for each environment the
+   app needs; every active environment needs a `base_url` before its action can be called.
+2. **Define the action** — the HTTP method and the endpoint's path *relative to the app's base_url*
+   (e.g. `/v1/users/{id}`, never a full URL — Ductape joins `base_url + resource` per environment at
+   call time), plus only the params/headers/body/response fields relevant to that endpoint. Then
+   `ductape_cli("apps actions create --app <tag> --action-file action.json")` — the flag is
+   `--action-file`, **not** `-f`/`--file` (that flag belongs to the parent `apps` command; Commander
+   resolves a flag shared by an ancestor and a descendant against the ancestor, so `-f` here is
+   silently ignored — same fix `products environments create/update` uses `--env-file` for).
+   `request_type` is REQUIRED on the body — one of `"application/json"` |
+   `"application/x-www-form-urlencoded"` | `"multipart/form-data"` | `"SOAP"` | `"html"` (not the
+   short names `"json"`/`"xml"`/`"form"`); if `response` is included, `response.status_code` is a
+   **string** (e.g. `"200"`) and `response.response_format` uses that same value set.
+3. **Connect the app to the product** — skip if already connected. Otherwise map each product
+   environment to an app environment and run
+   `ductape_cli("products apps connect --product <tag> --app <tag> --env-map <app_env>:<product_env> ...")`.
+4. **Only then write integration code** — `ductape_generate_payload` → `ductape_generate_snippet` /
+   `ductape_execute`, calling `actions.run` or `actions.dispatch`.
+
+Optional arguments `product_tag` and `app_tag` let the tool skip stages already answered (e.g. pass
+`app_tag` once the user has said which existing app this belongs to, and the returned flow starts at
+stage 2 instead of asking again) — but never infer `app_tag` on the tool's behalf without the user
+having actually said so; when in doubt, omit it and let stage 1 ask.
+
+All of the above was verified against a live workspace: created a `jsonplaceholder` app with `prd`/
+`snd` environments, added a `GET /todos/1` action, and connected it to a real product end to end.
+
 ## Tools: `ductape_events_topic_setup` and `ductape_events_validate_project`
 
 `ductape_events_topic_setup` is a read-only generator for one canonical topic asset. It returns the

package/package.json

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