@ductape/mcp 0.1.30 → 0.1.32

package/dist/index.js

@@ -522,11 +522,20 @@ ALL params are passed as a JSON array in positional order matching the SDK signa
   databases.connect [{ product, env, database }]
   databases.testConnection [{ product, env, database }]
   databases.disconnect []
-  databases.query   [{ product, env, database, entity, where?: {field: {$eq|$gt|$lt|$in: value}}, select?: string[], orderBy?: [{field, order:"ASC"|"DESC"}], limit?, offset? }]
-  databases.insert  [{ product, env, database, entity, data: {key: value}|{key:value}[], returning? }]
-  databases.update  [{ product, env, database, entity, data: {key:value}, where: {key: {$eq: value}}, returning? }]
-  databases.delete  [{ product, env, database, entity, where: {key: {$eq: value}}, returning? }]
-  databases.upsert  [{ product, env, database, entity, data: {key:value}, conflictKeys: string[], returning? }]
+  databases.query   [{ product, env, database, table, where?: {field: value}, select?: string[], orderBy?: [{field, order:"ASC"|"DESC"}], limit?, offset?, session?, cache? }]  ← CALL ductape_generate_payload FIRST (operation_family="database", method="query", targets={database, table})
+  databases.insert  [{ product, env, database, table, data: {key: value}|{key:value}[], returning?, session?, cache? }]  ← CALL ductape_generate_payload FIRST (operation_family="database", method="insert", targets={database, table})
+  databases.update  [{ product, env, database, table, data: {key:value}, where: {field: value}, returning?, session?, cache? }]  ← CALL ductape_generate_payload FIRST (operation_family="database", method="update", targets={database, table})
+  databases.delete  [{ product, env, database, table, where: {field: value}, returning?, session?, cache? }]  ← CALL ductape_generate_payload FIRST (operation_family="database", method="delete", targets={database, table})
+  databases.upsert  [{ product, env, database, table, data: {key:value}, conflictKeys: string[], returning?, session?, cache? }]  ← CALL ductape_generate_payload FIRST (operation_family="database", method="upsert", targets={database, table})
+  NOTE: ductape_generate_payload for databases returns:
+    payload.input  — ready-to-use input with real field names in where/data, plus session and cache inside input
+    meta.schema_context.database.fields          — { fieldName: { type, required, description?, sample? } } for the table
+    meta.schema_context.database.available_tables — list of all tables that have configured actions
+    meta.schema_warnings — array of warning strings; if it contains "No table schema discovered..." it means no
+      migrations or schema have been synced to the server yet. To fix this, tell the user:
+        "Run: ductape db schema push --db <database_tag>
+        This reads the live table schema from the database and syncs it to the Ductape server,
+        enabling accurate field guidance for AI operations. Once complete, retry your request."
   databases.count   [{ product, env, database, entity, where? }]
   databases.sum     [{ product, env, database, entity, field, where? }]
   databases.avg     [{ product, env, database, entity, field, where? }]
@@ -558,8 +567,8 @@ ALL params are passed as a JSON array in positional order matching the SDK signa
   databases.action.fetch  [action_tag]
   databases.action.list   [database_tag]
   databases.action.delete [action_tag]
-  databases.action.dispatch [{ product, env, database, action, input, schedule? }]  ← CALL ductape_generate_payload FIRST (operation_family="database", method="dispatch", targets={database, action})
-  databases.dispatch [{ product, env, database, action, input, schedule? }]  ← CALL ductape_generate_payload FIRST (operation_family="database", method="dispatch")
+  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"})
+  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"})
   databases.beginTransaction [{ product, env, database, isolationLevel?: "READ_COMMITTED"|"REPEATABLE_READ"|"SERIALIZABLE" }]
     → returns a transaction object; pass it to insert/update/delete/upsert/query calls as the last argument.
     Commit with: transaction.commit()   Rollback with: transaction.rollback()
@@ -891,14 +900,26 @@ const payloadGenerateInputSchema = z.object({
     targets: z.record(z.any()).optional().describe('Identifies the specific operation to generate a payload for. ' +
         'For actions: { app: "app_tag", action: "action_tag" }. ' +
         'For features: { feature: "feature_tag" }. ' +
-        'For databases: { database: "db_tag", action?: "action_tag" }. ' +
+        'For databases: { database: "db_tag", table: "table_or_collection_name" }. ' +
+        '  Providing table is strongly recommended — the generator scans all actions configured for that table, ' +
+        '  aggregates field definitions (name, type, required, sample value), and returns them in ' +
+        '  meta.schema_context.database.fields. The where/data placeholders in the payload are also ' +
+        '  pre-filled with the real field names. meta.schema_context.database.available_tables lists ' +
+        '  every table the database has actions configured for, so you can discover table names first. ' +
+        'For graphs: { graph: "graph_tag", node_label?: "NodeLabel", edge_type?: "REL_TYPE" }. ' +
+        '  node_label and edge_type pre-fill the Cypher template; omit to get generic placeholders. ' +
+        '  meta.schema_context.graph.type tells you the engine (neo4j, neptune, etc.). ' +
+        'For vectors: { vector: "vector_tag", namespace?: "ns" }. ' +
+        '  meta.schema_context.vector surfaces dimensions, metric, and index so you know what size ' +
+        '  embedding to pass and which distance function is used. ' +
         'For sessions: { session: "session_tag" }. ' +
         'For notifications: { notification: "notif_tag" }. ' +
         'For quotas/fallbacks: { tag: "resource_tag" }. ' +
         'For storage: { storage: "storage_tag" }. ' +
         'For messaging: { broker: "broker_tag", topic?: "topic_tag" }.'),
-    include_session: z.boolean().optional().default(true).describe('Include session field in the generated payload template.'),
-    include_cache: z.boolean().optional().default(true).describe('Include cache field in the generated payload template.'),
+    include_session: z.boolean().optional().default(true).describe('Include a session placeholder inside the generated input object. ' +
+        'The placeholder is named "<session_tag_token>" to indicate it expects the runtime JWT, not the tag name.'),
+    include_cache: z.boolean().optional().default(true).describe('Include the cache tag inside the generated input object so the caller knows which cache to reference for this query.'),
     schema_mode: z.enum(['strict', 'best_effort']).optional().default('best_effort').describe('"strict" — fail if any required field cannot be resolved. ' +
         '"best_effort" — fill what is known, leave unknowns as null/placeholder. Use best_effort when exploring.'),
     input_hint: z.record(z.any()).optional().describe('Optional. Partial input values you already know. These are merged into the generated payload template ' +

package/package.json

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

package/src/index.ts

@@ -533,11 +533,20 @@ ALL params are passed as a JSON array in positional order matching the SDK signa
   databases.connect [{ product, env, database }]
   databases.testConnection [{ product, env, database }]
   databases.disconnect []
-  databases.query   [{ product, env, database, entity, where?: {field: {$eq|$gt|$lt|$in: value}}, select?: string[], orderBy?: [{field, order:"ASC"|"DESC"}], limit?, offset? }]
-  databases.insert  [{ product, env, database, entity, data: {key: value}|{key:value}[], returning? }]
-  databases.update  [{ product, env, database, entity, data: {key:value}, where: {key: {$eq: value}}, returning? }]
-  databases.delete  [{ product, env, database, entity, where: {key: {$eq: value}}, returning? }]
-  databases.upsert  [{ product, env, database, entity, data: {key:value}, conflictKeys: string[], returning? }]
+  databases.query   [{ product, env, database, table, where?: {field: value}, select?: string[], orderBy?: [{field, order:"ASC"|"DESC"}], limit?, offset?, session?, cache? }]  ← CALL ductape_generate_payload FIRST (operation_family="database", method="query", targets={database, table})
+  databases.insert  [{ product, env, database, table, data: {key: value}|{key:value}[], returning?, session?, cache? }]  ← CALL ductape_generate_payload FIRST (operation_family="database", method="insert", targets={database, table})
+  databases.update  [{ product, env, database, table, data: {key:value}, where: {field: value}, returning?, session?, cache? }]  ← CALL ductape_generate_payload FIRST (operation_family="database", method="update", targets={database, table})
+  databases.delete  [{ product, env, database, table, where: {field: value}, returning?, session?, cache? }]  ← CALL ductape_generate_payload FIRST (operation_family="database", method="delete", targets={database, table})
+  databases.upsert  [{ product, env, database, table, data: {key:value}, conflictKeys: string[], returning?, session?, cache? }]  ← CALL ductape_generate_payload FIRST (operation_family="database", method="upsert", targets={database, table})
+  NOTE: ductape_generate_payload for databases returns:
+    payload.input  — ready-to-use input with real field names in where/data, plus session and cache inside input
+    meta.schema_context.database.fields          — { fieldName: { type, required, description?, sample? } } for the table
+    meta.schema_context.database.available_tables — list of all tables that have configured actions
+    meta.schema_warnings — array of warning strings; if it contains "No table schema discovered..." it means no
+      migrations or schema have been synced to the server yet. To fix this, tell the user:
+        "Run: ductape db schema push --db <database_tag>
+        This reads the live table schema from the database and syncs it to the Ductape server,
+        enabling accurate field guidance for AI operations. Once complete, retry your request."
   databases.count   [{ product, env, database, entity, where? }]
   databases.sum     [{ product, env, database, entity, field, where? }]
   databases.avg     [{ product, env, database, entity, field, where? }]
@@ -569,8 +578,8 @@ ALL params are passed as a JSON array in positional order matching the SDK signa
   databases.action.fetch  [action_tag]
   databases.action.list   [database_tag]
   databases.action.delete [action_tag]
-  databases.action.dispatch [{ product, env, database, action, input, schedule? }]  ← CALL ductape_generate_payload FIRST (operation_family="database", method="dispatch", targets={database, action})
-  databases.dispatch [{ product, env, database, action, input, schedule? }]  ← CALL ductape_generate_payload FIRST (operation_family="database", method="dispatch")
+  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"})
+  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"})
   databases.beginTransaction [{ product, env, database, isolationLevel?: "READ_COMMITTED"|"REPEATABLE_READ"|"SERIALIZABLE" }]
     → returns a transaction object; pass it to insert/update/delete/upsert/query calls as the last argument.
     Commit with: transaction.commit()   Rollback with: transaction.rollback()
@@ -913,15 +922,31 @@ const payloadGenerateInputSchema = z.object({
     'Identifies the specific operation to generate a payload for. ' +
     'For actions: { app: "app_tag", action: "action_tag" }. ' +
     'For features: { feature: "feature_tag" }. ' +
-    'For databases: { database: "db_tag", action?: "action_tag" }. ' +
+    'For databases: { database: "db_tag", table: "table_or_collection_name" }. ' +
+    '  Providing table is strongly recommended — the generator scans all actions configured for that table, ' +
+    '  aggregates field definitions (name, type, required, sample value), and returns them in ' +
+    '  meta.schema_context.database.fields. The where/data placeholders in the payload are also ' +
+    '  pre-filled with the real field names. meta.schema_context.database.available_tables lists ' +
+    '  every table the database has actions configured for, so you can discover table names first. ' +
+    'For graphs: { graph: "graph_tag", node_label?: "NodeLabel", edge_type?: "REL_TYPE" }. ' +
+    '  node_label and edge_type pre-fill the Cypher template; omit to get generic placeholders. ' +
+    '  meta.schema_context.graph.type tells you the engine (neo4j, neptune, etc.). ' +
+    'For vectors: { vector: "vector_tag", namespace?: "ns" }. ' +
+    '  meta.schema_context.vector surfaces dimensions, metric, and index so you know what size ' +
+    '  embedding to pass and which distance function is used. ' +
     'For sessions: { session: "session_tag" }. ' +
     'For notifications: { notification: "notif_tag" }. ' +
     'For quotas/fallbacks: { tag: "resource_tag" }. ' +
     'For storage: { storage: "storage_tag" }. ' +
     'For messaging: { broker: "broker_tag", topic?: "topic_tag" }.'
   ),
-  include_session: z.boolean().optional().default(true).describe('Include session field in the generated payload template.'),
-  include_cache: z.boolean().optional().default(true).describe('Include cache field in the generated payload template.'),
+  include_session: z.boolean().optional().default(true).describe(
+    'Include a session placeholder inside the generated input object. ' +
+    'The placeholder is named "<session_tag_token>" to indicate it expects the runtime JWT, not the tag name.'
+  ),
+  include_cache: z.boolean().optional().default(true).describe(
+    'Include the cache tag inside the generated input object so the caller knows which cache to reference for this query.'
+  ),
   schema_mode: z.enum(['strict', 'best_effort']).optional().default('best_effort').describe(
     '"strict" — fail if any required field cannot be resolved. ' +
     '"best_effort" — fill what is known, leave unknowns as null/placeholder. Use best_effort when exploring.'