@ductape/mcp 0.2.26 → 0.2.28

package/dist/index.js

@@ -780,11 +780,21 @@ 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 --action-file 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> --action-file 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.execute [{ product, env, database, action, input, session? }]  ← synchronous saved-action execution
+    CLI: ductape db actions execute --action-file execute.json --json
   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" }]
@@ -845,6 +855,13 @@ ALL params are passed as a JSON array in positional order matching the SDK signa
   graph.getAction    [actionTag, graphTag?, productTag?]
   graph.updateAction [actionTag, updates, graphTag?, productTag?]
   graph.deleteAction [actionTag, graphTag?, productTag?]
+  graph.action.create [{ product, graph|graphTag, name, description?, operation, query, parameters? }]
+  graph.action.update [{ product, graph|graphTag, action|actionTag, name?, description?, query?, parameters? }]
+  graph.action.fetch  [{ product, graph|graphTag, action|actionTag }]
+  graph.action.fetchAll [{ product, graph|graphTag }]
+  graph.action.delete [{ product, graph|graphTag, action|actionTag }]
+  graph.action.execute [{ product, env, graph, action, input }]
+  graph.action.dispatch [{ product, env, graph, event, input, schedule? }]
   graph.beginTransaction [options?]
   graph.commitTransaction [transaction]
   graph.rollbackTransaction [transaction]
@@ -879,6 +896,12 @@ ALL params are passed as a JSON array in positional order matching the SDK signa
   vector.deleteIndex    [{ product, env, vector, name }]
   vector.listIndexes    [{ product, env, vector }]
   vector.count          [{ product, env, vector, namespace? }]
+  vector.actions.create [{ product, vector, actionTag, name, operation, template, description?, parameters? }]
+  vector.actions.update [{ product, vector, actionTag, name?, description?, template?, parameters? }]
+  vector.actions.fetch  [{ product, vector, actionTag }]
+  vector.actions.fetchAll [{ product, vector }]
+  vector.actions.delete [{ product, vector, actionTag }]
+  vector.actions.execute [{ product, env, vector, action, input }]
 
 ━━━ MODULE: features ━━━
   Feature definitions are code-first. Use features.define in application source; do not call
@@ -910,7 +933,8 @@ ALL params are passed as a JSON array in positional order matching the SDK signa
       // ctx.step(tag, fn, rollback?, opts?)  – define a durable step
       // ctx.api.run({ app, action, input }) – call an app action (NOT 'event' -- that field name
       //   only applies to ctx.database/ctx.notification/ctx.storage below, never ctx.api/ctx.action)
-      // ctx.database.query/insert/update/delete({ database, event, ... })
+      // ctx.database.execute({ database, action, input }) for a saved database action
+      // ctx.database.query/insert/update/delete({ database, table, ... }) for direct operations
       // ctx.graph.execute({ graph, action, input })
       // ctx.notification.send/email/push/sms({ notification, event, ... })
       // ctx.storage.upload/download({ storage, event, input })
@@ -2399,12 +2423,41 @@ 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.execute inside a Feature step invokes a saved action through its \`action\` field.
+Direct ctx.database.query/insert/update/delete calls retain their normal {table, where, data, ...}
+shape and do not resolve a saved action.
+
+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")
+    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> --action-file 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:
+  Synchronous execution:
+  ductape_execute("databases.execute", [{
+    product: "my-product", env: "prd", database: "core-db",
+    action: "get-active-users", input: { status: "active" }
+  }])
+  CLI equivalent:
+  ductape_cli("db actions execute --action-file execute.json --json")
+
+Deferred or scheduled execution:
   → CALL ductape_generate_payload FIRST to get the canonical input shape.
   ductape_execute("databases.action.dispatch", [{
     product: "my-product",
@@ -2414,13 +2467,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(),
@@ -2840,8 +2886,8 @@ Run an action at runtime:
 In a Ductape feature handler, call the registered action through:
   await ctx.api.run({ app: "<app_tag>", action: "<action_tag>", input: { ... } })
 ctx.api is the supported feature-context surface (also described as ctx.action in older code).
-NEVER use 'event' as the field name here -- that is only correct for ctx.database/ctx.notification/
-ctx.storage steps. ctx.api.run's real field is 'action'; passing 'event' instead silently produces
+NEVER use 'event' as the field name here -- that is only correct for ctx.notification/ctx.storage
+steps. ctx.api.run and ctx.database.execute both use 'action'; passing 'event' instead produces
 an unset step and fails feature compilation with "did not record a portable operation".
 There is no ctx.apps, ctx.integrations, or generic external-HTTP feature surface.
 
@@ -3882,9 +3928,9 @@ Synchronous multi-step Feature (no Event, schedule, sleep, signal, or external s
     },
     handler: async (ctx) => {
       const validated = await ctx.step('validate-orders', () =>
-        ctx.database.execute({ database: 'orders-db', event: 'validate-orders', input: ctx.input }));
+        ctx.database.execute({ database: 'orders-db', action: 'validate-orders', input: ctx.input }));
       return ctx.step('resolve-orders', () =>
-        ctx.database.execute({ database: 'orders-db', event: 'resolve-orders', input: validated }));
+        ctx.database.execute({ database: 'orders-db', action: 'resolve-orders', input: validated }));
     },
   });
 This is a valid Feature despite requiring no signal and producing no Event. Its qualification comes
@@ -3898,9 +3944,9 @@ Define a feature (write this into the project's source files — do NOT use feat
     name: "Onboard User",
     handler: async (ctx) => {
       const account = await ctx.step("create-account", async () =>
-        ctx.database.insert({ database: "core-db", event: "insert-user",
+        ctx.database.insert({ database: "core-db", table: "users",
           data: { userId: ctx.input.userId, email: ctx.input.email } }),
-        async (result) => ctx.database.delete({ database: "core-db", event: "delete-user",
+        async (result) => ctx.database.delete({ database: "core-db", table: "users",
           where: { id: result.id } })   // rollback
       );
 
@@ -4995,9 +5041,9 @@ SAVED GRAPH ACTION ASSET AND CLI CONTRACT:
   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
+    ductape graph actions create --action-file 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
+    ductape graph actions update --action-file <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.
@@ -5023,6 +5069,11 @@ EXACT CODE-FIRST VECTOR CONTEXT:
   Product/env and the Feature's inherited session are supplied by the executor. Do not serialize
   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 create --action-file vector-action.json --json
+    ductape vector actions get <action-tag> --vector <vector-tag> --json
+  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.
   Do not claim that a Vertex Vector Search index embeds text.
 

package/package.json

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