@ductape/mcp 0.2.29 → 0.2.30

package/dist/index.js

@@ -197,14 +197,14 @@ 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 -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 create -f ductape/apps/<app-tag>.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")
+           ductape_cli("resources database create -f ductape/databases/<database-tag>.database.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 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
+       --action-file ductape/actions/<app-tag>/<action-tag>.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?,
@@ -290,6 +290,16 @@ There are THREE categories of operations. Use the right tool for each:
        → Applies to: actions, features, sessions, notifications, databases, storage, graphs, vectors,
          quotas, fallbacks, jobs, and any other operation that executes against a pre-configured schema.
 
+       SAVED ACTION REUSE IS MANDATORY:
+       → Before creating a database, graph, or vector action, list the existing actions on that exact
+         component and inspect plausible matches with get/fetch.
+       → Reuse an existing action when its operation, target, template/query, parameters, and output
+         semantics satisfy the requested behavior. Invoke it by tag; do not create a duplicate merely
+         because the requested name differs.
+       → Create a new action only when no existing action provides the required behavior. Update an
+         existing action only for a compatible correction; do not mutate a shared action into different
+         semantics. State the evidence used to decide reuse versus creation.
+
   Skipping ductape_generate_payload for applicable runtime operations will produce incorrect or empty input payloads.
   Exception: messaging produce/consume/dispatch — the producer defines the schema, so infer from context instead.
 
@@ -483,8 +493,8 @@ ALL params are passed as a JSON array in positional order matching the SDK signa
 
 ━━━ MODULE: actions (app actions) ━━━
   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 create --app <app_tag> --action-file ductape/actions/<app_tag>/<action_tag>.action.json")
+    ductape_cli("apps actions update --app <app_tag> --action <action_tag> --action-file ductape/actions/<app_tag>/<action_tag>.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>")
@@ -782,7 +792,7 @@ ALL params are passed as a JSON array in positional order matching the SDK signa
   databases.migration.status [migrations]
   databases.action.create [{ tag: "product:database:action", name, description, tableName, operation: "query"|"insert"|"update"|"delete"|"aggregate"|"count", template, filterTemplate? }]
     ← ADMINISTRATIVE (access key required). FORBIDDEN via ductape_execute (publishable key) —
-      use ductape_cli("db actions create --action-file action.json") instead. tag MUST be fully qualified
+      use ductape_cli("db actions create --action-file ductape/database/actions/<action-tag>.action.json") instead. tag MUST be fully qualified
       "product_tag:database_tag:action_tag" — a 2-part "database:action" shorthand only resolves
       inside a long-lived process that already has that product's builder cached, never in a
       fresh CLI/MCP call. This is pure metadata registration; it never connects to the live
@@ -2432,9 +2442,15 @@ ctx.database.execute inside a Feature step invokes a saved action through its \`
 Direct ctx.database.query/insert/update/delete calls retain their normal {table, where, data, ...}
 shape and do not resolve a saved action.
 
+REUSE BEFORE CREATE:
+  1. ductape_cli("db actions list --database product_tag:database_tag --json")
+  2. Inspect likely matches with ductape_cli("db actions get product_tag:database_tag:action_tag --json").
+  3. Reuse the matching tag with database.execute/ctx.database.execute when operation, table,
+     template, parameters, and result semantics match. Create only when no exact functional match exists.
+
 Create/update/delete are ADMINISTRATIVE (access key) — FORBIDDEN through ductape_execute
 (publishable key). Use ductape_cli, same as every other admin resource:
-  ductape_cli("db actions create --action-file action.json")
+  ductape_cli("db actions create --action-file ductape/database/actions/<action-tag>.action.json")
     File: { tag: "product:database:action", name, description, tableName,
              operation: "query"|"insert"|"update"|"delete"|"aggregate"|"count",
              template, filterTemplate? }
@@ -2478,6 +2494,10 @@ scheduled, dispatched with retries, and audited via logs.
     graphs: `
 DUCTAPE GRAPH DATABASES
 
+Before creating a graph action, list existing actions for the graph and inspect likely matches.
+Reuse an action whose query/operation, parameters, and result semantics already satisfy the task;
+create a new action only when no functional match exists.
+
 Supported engines: neo4j | neptune | cosmos-gremlin | spanner-graph | arangodb | memgraph
 
 Registration (admin — ductape_cli):
@@ -2841,7 +2861,7 @@ 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("apps create -f ductape/apps/<app-tag>.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:
@@ -2924,14 +2944,14 @@ Connecting an app to a product (after creation):
 
   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")
+  1. Create the app:     ductape_cli("apps create -f ductape/apps/<app-tag>.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.
+                         <app_tag> --proxy -f ductape/apps/<app-tag>.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")
+  4. Define actions:     ductape_cli("apps actions create --app <app_tag> --action-file ductape/actions/<app_tag>/<action-tag>.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" |
@@ -5075,8 +5095,11 @@ 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.
   Register reusable vector actions administratively, then read them back before compiling Features:
+    ductape vector actions list --vector <vector-tag> --json
     ductape vector actions create --action-file vector-action.json --json
     ductape vector actions get <action-tag> --vector <vector-tag> --json
+  Always list and inspect first. Reuse an existing action when operation, namespace/filter/template,
+  parameters, and output semantics match; do not create a duplicate action under a new name.
   Update/delete/list use the same \`ductape vector actions\` surface. At runtime the SDK namespace is
   \`ductape.vector.actions.*\` (plural), while Feature reuse is singular \`ctx.vector.execute(...)\`.
   Vertex AI Vector Search stores and searches supplied vectors. It does NOT generate embeddings.
@@ -5303,7 +5326,8 @@ const integrateEndpointHandler = async (args) => {
                 '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")',
+                'Persist it at ductape/apps/<app-tag>.app.json. Do not use a scratchpad, temporary file, or repository-root JSON.',
+                'Run: ductape_cli("apps create -f ductape/apps/<app-tag>.app.json --json")',
                 'The app tag is what you supplied, not something the response generates — use it as app_tag ' +
                     'in every later stage.',
             ],
@@ -5330,7 +5354,8 @@ const integrateEndpointHandler = async (args) => {
                 '"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> ' +
+            'Persist it at ductape/actions/<app_tag>/<action-tag>.action.json. This canonical file must remain in the project after creation.',
+            'Run: ductape_cli("apps actions create --app <app_tag> --action-file ductape/actions/<app_tag>/<action-tag>.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).',
         ],
@@ -5422,7 +5447,7 @@ const eventsProjectValidationHandler = async (args) => {
 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", ' +
+        '"apps list", "apps create -f ductape/apps/<app-tag>.app.json", "resources storage list", ' +
         '"events topics create -f topic.json", "events topics list --tag broker-tag", ' +
         '"cloud connections list", "link --product my-product --env dev".\n\n' +
         'Use this tool for administrative operations: creating or updating products, apps, ' +
@@ -5492,6 +5517,16 @@ function handleCliFlags() {
 // Surfaced to every connected agent at initialize time, before any tool is called.
 // Keep this short — it is ambient, unconditional overhead on every session.
 // The full doctrine with concrete API shapes lives in the "ductape-first-approach" prompt below.
+const DUCTAPE_ASSET_FILE_POLICY = 'Canonical asset-file policy: every JSON file used by the CLI to create, update, import, ' +
+    'provision, or apply a Ductape asset must be kept inside the target project\'s ductape/ folder, ' +
+    'under the matching asset-type directory (for example ductape/apps/, ductape/actions/, ' +
+    'ductape/databases/, ductape/quotas/, ductape/fallbacks/, or ductape/healthchecks/). Use a ' +
+    'stable tag-based filename such as <tag>.<asset-type>.json. Never create authoritative asset ' +
+    'JSON in /tmp, a scratchpad, the repository root, or another disposable location and then pass ' +
+    'that path to the CLI. Preserve established specialized layouts such as ' +
+    'ductape/database/schema.json, ductape/database/migrations/, ductape/graphs/<graph-tag>/actions/, ' +
+    'and ductape/events/<topic-tag>.topic.json. The ductape/ copy is the source-controlled source of ' +
+    'truth and must remain after the CLI command completes.';
 const DUCTAPE_FIRST_INSTRUCTIONS = 'Ductape-first: before writing custom code for a capability, check whether Ductape already ' +
     'provides it (databases, storage, notifications, events, sessions, caches, actions, quotas, ' +
     'fallback, health). Model any multi-step or externally-risky operation as a Feature ' +
@@ -5504,7 +5539,7 @@ const DUCTAPE_FIRST_INSTRUCTIONS = 'Ductape-first: before writing custom code fo
     'to be defined once and reused across products and environments — check what already exists ' +
     'before creating something new. Treat the ductape/ folder (features/, database/schema.json, ' +
     'notifications.json, events/) as the source of truth: define there first, sync/apply, then ' +
-    'write application code against it — never the reverse. Invoke the "ductape-first-approach" ' +
+    'write application code against it — never the reverse. ' + DUCTAPE_ASSET_FILE_POLICY + ' Invoke the "ductape-first-approach" ' +
     'prompt for the full doctrine with concrete API shapes before scaffolding a new backend.';
 // The detailed doctrine, invoked on demand via the "ductape-first-approach" prompt rather than
 // forced onto every session. Grounded in the actual module contracts this server exposes
@@ -5525,7 +5560,7 @@ const DUCTAPE_FIRST_DOCTRINE = 'Follow this checklist before defaulting to plain
     '"ductape features sync", ductape/database/schema.json + "ductape db schema generate/migrate", ' +
     'ductape/notifications.json + "ductape apply notifications", ductape/events/*.topic.json + ' +
     '"ductape apply events". Define the capability there first, then write application code that ' +
-    'calls into it — never duplicate the logic inline.\n\n' +
+    'calls into it — never duplicate the logic inline. ' + DUCTAPE_ASSET_FILE_POLICY + '\n\n' +
     '5. Secrets never live in code or plain config. Store every credential with secrets.create ' +
     '(scoped and env-aware), then reference it as $Secret{KEY} wherever a credential is needed — ' +
     'action auth headers, database/storage connection config, notification provider config. ' +
@@ -6144,6 +6179,7 @@ async function main() {
         server.registerTool('ductape_cli', {
             title: 'Ductape CLI',
             description: 'Run a Ductape CLI command for administrative operations.\n\n' +
+                DUCTAPE_ASSET_FILE_POLICY + '\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' +

package/docs/TOOLS.md

@@ -1,5 +1,25 @@
 # MCP Tools Reference
 
+## Canonical asset files
+
+Every JSON document used by the CLI to create, update, import, provision, or apply an asset is a
+project asset, not a temporary command payload. Store it beneath `<project-root>/ductape/` in the
+matching asset-type directory and keep it after the command completes. For example:
+
+```text
+ductape/apps/paystack.app.json
+ductape/actions/paystack/initialize-transaction.action.json
+ductape/databases/orders.database.json
+ductape/quotas/payment-gateway.quota.json
+ductape/fallbacks/payment-gateway.fallback.json
+ductape/healthchecks/paystack.healthcheck.json
+```
+
+Never place authoritative asset JSON in `/tmp`, a scratchpad, the repository root, or another
+disposable directory. Established specialized layouts remain authoritative, including
+`ductape/database/schema.json`, `ductape/database/migrations/`,
+`ductape/graphs/<graph-tag>/actions/`, and `ductape/events/<topic-tag>.topic.json`.
+
 The Ductape MCP server exposes proxy, CLI, discovery, documentation, migration, and portable-function setup tools.
 
 ## Tool: `ductape_integrate_endpoint`
@@ -12,11 +32,12 @@ It is read-only guidance — it runs no CLI command itself and returns the order
    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.
+   app needs; every active environment needs a `base_url` before its action can be called. Persist
+   the body at `ductape/apps/<app-tag>.app.json`.
 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
+   `ductape_cli("apps actions create --app <tag> --action-file ductape/actions/<app-tag>/<action-tag>.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).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ductape/mcp",
-  "version": "0.2.29",
+  "version": "0.2.30",
   "description": "MCP server that exposes Ductape SDK operations via the backend proxy",
   "type": "module",
   "main": "dist/index.js",
@@ -15,7 +15,7 @@
   ],
   "scripts": {
     "build": "tsc",
-    "test": "npm run build && node scripts/check-cli-command-security.mjs && node scripts/check-frontend-analytics-guidance.mjs && node scripts/check-events-discovery.mjs && node scripts/check-schema-fallback.mjs && node scripts/check-paystack-action-schema.mjs && node scripts/check-portable-functions.mjs && node scripts/check-project-link-guidance.mjs && node scripts/check-graph-vector-projection-guidance.mjs",
+    "test": "npm run build && node scripts/check-cli-command-security.mjs && node scripts/check-frontend-analytics-guidance.mjs && node scripts/check-events-discovery.mjs && node scripts/check-schema-fallback.mjs && node scripts/check-paystack-action-schema.mjs && node scripts/check-portable-functions.mjs && node scripts/check-project-link-guidance.mjs && node scripts/check-graph-vector-projection-guidance.mjs && node scripts/check-asset-file-guidance.mjs",
     "start": "node dist/index.js",
     "dev": "tsx src/index.ts"
   },