@ductape/mcp 0.2.25 → 0.2.27

package/dist/index.js

@@ -780,11 +780,19 @@ ALL params are passed as a JSON array in positional order matching the SDK signa
   databases.migration.rollback [migrations, count?]
   databases.migration.history []
   databases.migration.status [migrations]
-  databases.action.create [{ product, database, data: { tag, name, description?, type:"sql"|"nosql", query } }]
-  databases.action.update [{ product: string, tag: string, data: { name?: string, description?: string, query?: string } }]
-  databases.action.fetch  [action_tag]
-  databases.action.list   [database_tag]
-  databases.action.delete [action_tag]
+  databases.action.create [{ tag: "product:database:action", name, tableName, operation: "query"|"insert"|"update"|"delete"|"upsert"|"aggregate"|"rawSql", template: { where?, select?, limit?, offset?, orderBy?, records?, query?, params?, ... }, description?, filterTemplate? }]
+    ← ADMINISTRATIVE (access key required). FORBIDDEN via ductape_execute (publishable key) —
+      use ductape_cli("db actions create -f 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
+      database, so it does NOT require the database to be reachable at call time.
+  databases.action.update [{ tag, name?, description?, template?, filterTemplate? }]
+    ← ADMINISTRATIVE. Use ductape_cli("db actions update --tag <tag> -f patch.json").
+  databases.action.fetch  [action_tag]  ← read-only, safe via ductape_execute
+  databases.action.fetchAll [database_tag]  ← read-only, safe via ductape_execute.
+    NOTE: the method is fetchAll — "action.list" is not a callable method on this sub-object.
+  databases.action.delete [action_tag]  ← ADMINISTRATIVE. Use ductape_cli("db actions delete <tag>").
   databases.action.dispatch [{ product, env, database, action, input, schedule? }]  ← CALL ductape_generate_payload FIRST (operation_family="database", method="dispatch", targets={database: "db_tag", table: "table_name"}) — requires redisUrl in ductape initialization
   databases.dispatch [{ product, env, database, action, input, schedule? }]  ← CALL ductape_generate_payload FIRST (operation_family="database", method="dispatch", targets={database: "db_tag", table: "table_name"}) — requires redisUrl in ductape initialization
   databases.beginTransaction [{ product, env, database, isolationLevel?: "READ_COMMITTED"|"REPEATABLE_READ"|"SERIALIZABLE" }]
@@ -2399,10 +2407,30 @@ DUCTAPE DATABASE PERFORMANCE GUIDANCE
     actions: `
 DUCTAPE DATABASE ACTIONS
 
-A database action is a saved query or mutation (SQL string or NoSQL command) stored
-on the Ductape product and executed by tag at runtime.
-
-Create/update actions in Workbench (administrative access), never through ductape_execute.
+A database action is a saved, parameterized query or mutation template (with {{placeholder}}
+fields) stored on a database component and executed by tag at runtime. This is what
+ctx.database.query/insert/update/delete inside a Feature step actually calls via its
+\`event\` field — Features do NOT accept the top-level {table, where} shape that
+sdk.databases.query/insert/update use outside of a Feature.
+
+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 -f action.json")
+    File: { tag: "product:database:action", name, tableName,
+             operation: "query"|"insert"|"update"|"delete"|"upsert"|"aggregate"|"rawSql",
+             template: { where?, select?, limit?, offset?, orderBy?, records?, query?, params? },
+             description?, filterTemplate? }
+    tag MUST be fully qualified "product_tag:database_tag:action_tag" — the SDK's 2-part
+    "database:action" shorthand only works inside one already-warm process, never a fresh CLI call.
+    This is pure metadata registration — it does not connect to the live database, so the
+    database does not need to be reachable at creation time.
+  ductape_cli("db actions update --tag <tag> -f patch.json")
+  ductape_cli("db actions delete <tag>")
+
+List/fetch are read-only and safe via ductape_execute:
+  ductape_execute("databases.action.fetchAll", ["product_tag:database_tag"])
+    NOTE: the method is fetchAll — "action.list" is not a callable method on this sub-object.
+  ductape_execute("databases.action.fetch",  ["product_tag:database_tag:action_tag"])
 
 Dispatch an action at runtime:
   → CALL ductape_generate_payload FIRST to get the canonical input shape.
@@ -2414,13 +2442,6 @@ Dispatch an action at runtime:
     input: { status: "active" },
   }])
 
-List actions for a database:
-  ductape_execute("databases.action.list", ["database_tag"])
-
-Fetch:
-  ductape_execute("databases.action.fetch",  ["action_tag"])
-Update/delete are administrative and must be performed in Workbench.
-
 Actions are the preferred way to encapsulate complex or reused queries — they can be
 scheduled, dispatched with retries, and audited via logs.
 `.trim(),
@@ -6146,24 +6167,33 @@ async function main() {
                 '  - Atlas (MongoDB Atlas) import flow — service identifier is "atlas-cluster" (required, not optional):\n' +
                 '    IMPORTANT: dbName is mandatory for every MongoDB env — see "MONGODB CLOUD CONNECTION RULE" in the\n' +
                 '    databases module above. The SDK enforces this at create time; omitting it throws a validation error.\n' +
+                '    An existing Atlas cluster is NEVER a blocker. Atlas has no concept of provisioning a new cluster\n' +
+                '    per database — a MongoDB "database" is just a named namespace inside a cluster, created on first\n' +
+                '    write. Any number of database components may point at the SAME cluster (same cloud connection,\n' +
+                '    same resource/cluster name) as long as each uses a DIFFERENT dbName. Needing a new database on a\n' +
+                '    cluster that already has one imported is the normal path, not a conflict — do not stop or ask\n' +
+                '    the user to provision a new cluster; just import again with a different dbName.\n' +
                 '    Step 1 — discover the cluster name:\n' +
                 '      ductape_cli("cloud resources list -f /tmp/atlas-list.json --json")\n' +
                 '      File: {"cloud": "<atlas-connection-tag>", "service": "atlas-cluster"}\n' +
                 '      Returns a list of clusters; note the "name" field (this is your resource identifier).\n' +
-                '    Step 2 — check if the database component already exists:\n' +
+                '    Step 2 — decide new database vs. repoint an existing one:\n' +
                 '      ductape_cli("resources databases list <product_tag> --json")\n' +
-                '      If a component already uses the same Atlas cluster, do NOT re-import — instead update it:\n' +
-                '        use ductape_cli resource update when supported; otherwise update it in Workbench\n' +
-                '      Add or change the dbName in the env\'s connection_url to switch databases on the same cluster.\n' +
-                '    Step 3 — import (only if no existing component uses this cluster):\n' +
+                '      Only skip importing when you want an EXISTING component (same product, env, and dbName) to\n' +
+                '      keep pointing at the same database — that is a repoint, not a new database, and should go\n' +
+                '      through ductape_cli resource update (or Workbench) instead of a fresh import.\n' +
+                '      Otherwise — including "same cluster, different database" — proceed to Step 3 with a new\n' +
+                '      component tag and a dbName distinct from every other component already on that cluster.\n' +
+                '    Step 3 — import (one entry per new database; reusing a cluster across components is expected):\n' +
                 '      Use import-persist-all with one entry per product env. Required fields per entry:\n' +
                 '        cloud (connection tag), service: "atlas-cluster", type: "databases",\n' +
                 '        product, component (new tag), env, resource (cluster name from Step 1),\n' +
-                '        dbName (the MongoDB database name to connect to — required for Atlas).\n' +
-                '      Example: [{"cloud":"atlas-tag","service":"atlas-cluster","type":"databases",\n' +
-                '        "product":"my-product","component":"core-db","env":"snd","resource":"Cluster0","dbName":"myapp_snd"},\n' +
+                '        dbName (the MongoDB database name to connect to — must be unique per cluster, not per workspace).\n' +
+                '      Example — a second database ("billing-db") added to the same cluster as an existing "core-db":\n' +
+                '      [{"cloud":"atlas-tag","service":"atlas-cluster","type":"databases",\n' +
+                '        "product":"my-product","component":"billing-db","env":"snd","resource":"Cluster0","dbName":"billing_snd"},\n' +
                 '        {"cloud":"atlas-tag","service":"atlas-cluster","type":"databases",\n' +
-                '        "product":"my-product","component":"core-db","env":"prd","resource":"Cluster0","dbName":"myapp_prd"}]\n' +
+                '        "product":"my-product","component":"billing-db","env":"prd","resource":"Cluster0","dbName":"billing_prd"}]\n' +
                 '  - Message broker / event broker import:\n' +
                 '    CLI accepts these aliases for the messageBrokers module: events, event, broker, brokers, message-brokers.\n' +
                 '    List existing brokers: ductape_cli("resources events list --json")\n' +

package/package.json

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