@dypai-ai/mcp 1.5.22 → 1.5.23

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dypai-ai/mcp",
-  "version": "1.5.22",
+  "version": "1.5.23",
   "description": "DYPAI MCP Server — AI agent toolkit for building and deploying full-stack apps",
   "type": "module",
   "main": "src/index.js",

package/src/index.js

@@ -1057,7 +1057,7 @@ Endpoint naming is strict: the YAML \`name\` is the public API slug and must exa
 
 Mental translations: "edge function" → workflow with one code node; "cron" → \`trigger.schedule\` in the YAML; "webhook receiver" → \`trigger.webhook\`; "internal API" → \`trigger.http_api auth_mode:jwt\`.
 
-→ Full workflow patterns + YAML shape: \`search_docs("workflow patterns")\` and \`search_docs("trigger model")\`. Node catalog (full input/output schemas): read \`dypai/node-catalog.json\`.
+→ Full workflow patterns + YAML shape: \`search_docs("workflow patterns")\` and \`search_docs("trigger model")\`. Public HTTP response vs internal node output: \`search_docs("placeholder cheatsheet")\`. Node catalog (full input/output schemas): read \`dypai/node-catalog.json\`.
 
 ## What the engine handles for you (don't reinvent)
 
@@ -1078,9 +1078,10 @@ Mental translations: "edge function" → workflow with one code node; "cron" →
 3. **Treating \`dypai_push\` as a deploy** — it's "save as draft", not publish. Live traffic is untouched until \`manage_drafts(publish, confirm:true)\`. Push freely, only ask the user before publish.
 4. **\`public\` auth_mode with \`\${current_user_id}\`** — no JWT → placeholder empty → SQL fails or returns wrong data. Use \`jwt\` if you need the user.
 5. **Missing \`return: true\`** — endpoint returns \`null\`. Every path that should produce an HTTP response needs one node with \`return: true\`.
-6. **\`tool_ids\` in YAML instead of \`tools\`** — write \`tools: [name1, name2]\`. \`tool_ids\` bypasses the codec and fails silently in prod.
-7. **Putting workflow placeholders inside \`javascript_code.code\`** — code is raw JavaScript, so JS template literals like \`\${where.join(" AND ")}\` are safe and not rendered by DYPAI. Pass workflow values via \`input_data\`, \`ctx.nodes\`, \`ctx.user\`, or \`ctx.env\`; do not write \`\${input.email}\` inside code or set \`code\` from another node output.
-8. **Human endpoint names** — \`name: Listar videos\` in \`list-videos.yaml\` creates a draft the frontend cannot call as \`list-videos\`. \`dypai_validate\` and \`dypai_push\` reject this; fix the slug instead of testing around it.
+6. **SQL return + \`output.type: object\` without \`response_cardinality\` or \`set_fields\`** — runtime body is \`[{...}]\` but the frontend expects \`{...}\`. Add top-level \`response_cardinality: single\` for direct SQL returns, or compose the public object with \`set_fields\`. \`dypai_validate\` errors with \`response_cardinality_required\`. Do not unwrap arrays in frontend code.
+7. **\`tool_ids\` in YAML instead of \`tools\`** — write \`tools: [name1, name2]\`. \`tool_ids\` bypasses the codec and fails silently in prod.
+8. **Putting workflow placeholders inside \`javascript_code.code\`** — code is raw JavaScript, so JS template literals like \`\${where.join(" AND ")}\` are safe and not rendered by DYPAI. Pass workflow values via \`input_data\`, \`ctx.nodes\`, \`ctx.user\`, or \`ctx.env\`; do not write \`\${input.email}\` inside code or set \`code\` from another node output.
+9. **Human endpoint names** — \`name: Listar videos\` in \`list-videos.yaml\` creates a draft the frontend cannot call as \`list-videos\`. \`dypai_validate\` and \`dypai_push\` reject this; fix the slug instead of testing around it.
 
 → Longer list of common pitfalls + fixes: \`search_docs("troubleshooting")\`.
 
@@ -1101,7 +1102,7 @@ Mental translations: "edge function" → workflow with one code node; "cron" →
 
 SDK is pre-configured at \`src/lib/dypai.ts\` (or \`src/dypai.ts\`). Import \`dypai\` from there. Every method returns \`{ data, error }\` — never throws.
 
-- **API**: \`dypai.api.get(name)\`, \`.post(name, body)\`, \`.put()\`, \`.delete()\`, \`.upload(name, file)\`, \`.stream(name, body)\`.
+- **API**: \`dypai.api.get(name)\`, \`.post(name, body)\`, \`.put()\`, \`.delete()\`, \`.upload(name, file)\`, \`.stream(name, body)\`. \`response.data\` matches the endpoint \`output\` schema — if SQL returns row arrays, declare \`response_cardinality: single\` or use \`set_fields\`; never unwrap in the UI.
 - **Auth**: \`dypai.auth.signInWithPassword()\`, \`.signUp()\`, \`.signOut()\`, \`.getSession()\`. **Never** create login/signup workflows — auth is built-in.
 - **Hooks**: \`useAuth\`, \`useEndpoint\`, \`useAction\`, \`useUpload\`, \`useRealtime\`, \`<ProtectedRoute>\`.
 - **Rule**: NEVER \`fetch()\` directly — always through the SDK.
@@ -1142,7 +1143,7 @@ async function handleRequest(msg) {
     return makeResponse(id, {
       protocolVersion: "2024-11-05",
       capabilities: { tools: {} },
-      serverInfo: { name: "dypai", version: "1.5.14" },
+      serverInfo: { name: "dypai", version: "1.5.23" },
       instructions: SERVER_INSTRUCTIONS,
     })
   }

package/src/tools/sync/codec.js

@@ -205,6 +205,7 @@ export function serializeEndpoint(row, mapsCtx) {
   }
   if (row.input) doc.input = row.input
   if (row.output) doc.output = row.output
+  if (row.response_cardinality) doc.response_cardinality = row.response_cardinality
   doc.trigger = triggersToYaml(wf.execution_config?.triggers)
 
   const workflow = { nodes }
@@ -354,6 +355,7 @@ export function deserializeEndpoint(doc, mapsCtx) {
     workflow_code,
     input: doc.input || null,
     output: doc.output || null,
+    response_cardinality: doc.response_cardinality || null,
     allowed_roles: doc.allowed_roles || [],
     // Accept both `tool: true` (canonical) and `is_tool: true` (engine-style).
     // Without this, an agent that wrote `is_tool` in YAML would silently get

package/src/tools/sync/pull.js

@@ -194,6 +194,7 @@ input:
 
 # ─── Output schema (optional but recommended) ───────────────────────────────
 # Describes the response shape. Helps the validator + frontend type-checkers.
+# This is the PUBLIC HTTP body (what dypai.api.*().data receives).
 output:
   type: object
   properties:
@@ -201,6 +202,15 @@ output:
     total:    { type: number }
     status:   { type: string }
 
+# ─── Public response cardinality (optional) ───────────────────────────────────
+# Only needed when the return node is dypai_database (SQL row arrays) and
+# output.type is object. The engine unwraps [{...}] -> {...} at the HTTP boundary.
+#   response_cardinality: single      # one row / INSERT RETURNING *
+#   response_cardinality: many        # public body is an array (output.type: array)
+#   response_cardinality: zero_or_one # lookup; [] -> null
+# Prefer set_fields (see build_response below) when composing { items, total, ... }.
+# Node-level output_cardinality is internal-only for \${nodes.<id>.field} placeholders.
+
 # ─── Workflow ───────────────────────────────────────────────────────────────
 # Nodes are the steps. Placeholders wire data flow between them:
 #
@@ -600,7 +610,7 @@ export const dypaiPullTool = {
     const [endpoints, credentials, groups, schemaSql, nodeCatalogResult, realtimePolicies, draftsResult] = await Promise.all([
       execSql(project_id, `
         SELECT id, name, method, description, workflow_code, input, output,
-               allowed_roles, is_tool, tool_description, group_id, is_active, updated_at
+               response_cardinality, allowed_roles, is_tool, tool_description, group_id, is_active, updated_at
         FROM system.endpoints
         ORDER BY name
       `),

package/src/tools/sync/push.js

@@ -57,6 +57,7 @@ function endpointPayload(row) {
   if (row.group_id) p.group_id = row.group_id
   if (row.input) p.input = row.input
   if (row.output) p.output = row.output
+  if (row.response_cardinality) p.response_cardinality = row.response_cardinality
   return p
 }
 

package/src/tools/sync/validate.js

@@ -29,6 +29,19 @@ import {
  * Within the freshness window, we trust it without re-checking the remote.
  * Outside the window, sql_table_not_found triggers a remote verification. */
 const SCHEMA_FRESHNESS_MS = 5 * 60 * 1000  // 5 minutes
+const VALID_RESPONSE_CARDINALITIES = new Set(["single", "many", "zero_or_one"])
+const DATABASE_ROW_ARRAY_OPS = new Set([
+  "query",
+  "custom_query",
+  "select",
+  "update",
+  "delete",
+  "insert",
+  "mutation",
+  "aggregate",
+  "upsert",
+  "copy_to",
+])
 
 /**
  * Validate dypai/realtime.yaml against known schemas/tables. Rules:
@@ -425,6 +438,17 @@ function nodeParams(node) {
     : null
 }
 
+function nodeReturnsRowArray(node) {
+  const nodeType = node?.type ?? node?.node_type
+  if (nodeType === "set_fields" || nodeType === "javascript-code" || nodeType === "agent" || nodeType === "managed_ai") {
+    return false
+  }
+  if (nodeType !== "dypai_database") return false
+  const params = nodeParams(node)
+  const op = nodeField(node, params, "operation")
+  return DATABASE_ROW_ARRAY_OPS.has(op)
+}
+
 function nodeField(node, params, key) {
   return node?.[key] ?? params?.[key]
 }
@@ -1001,9 +1025,50 @@ function validateEndpoint(entry, ctx) {
   const nodeIds = new Set(workflowNodes.map(n => n.id))
   const nodeTypes = buildNodeTypeMap(workflowNodes)
   const outputContracts = buildNodeOutputContracts(workflowNodes, fileMap, ctx)
+  const outputType = typeof doc.output?.type === "string" ? doc.output.type : undefined
+  const responseCardinality =
+    typeof doc.response_cardinality === "string" ? doc.response_cardinality.trim() : ""
 
   const jwt = ruleUsesJwt(doc.trigger)
 
+  if (responseCardinality === "one") {
+    diagnostics.push({
+      severity: "error",
+      rule: "response_cardinality_legacy_one",
+      endpoint: name, file, loc: "response_cardinality",
+      message: "Endpoint uses response_cardinality: one, which is not supported.",
+      fix_hint: "Use response_cardinality: single.",
+    })
+  } else if (responseCardinality && !VALID_RESPONSE_CARDINALITIES.has(responseCardinality)) {
+    diagnostics.push({
+      severity: "error",
+      rule: "response_cardinality_invalid",
+      endpoint: name, file, loc: "response_cardinality",
+      message: `Invalid response_cardinality '${responseCardinality}'.`,
+      fix_hint: "Use single, many, or zero_or_one.",
+    })
+  }
+
+  if (responseCardinality === "single" && outputType === "array") {
+    diagnostics.push({
+      severity: "error",
+      rule: "response_cardinality_output_mismatch",
+      endpoint: name, file, loc: "response_cardinality",
+      message: "response_cardinality: single conflicts with output.type: array.",
+      fix_hint: "Use response_cardinality: many or change output.type to object.",
+    })
+  }
+
+  if (responseCardinality === "many" && outputType === "object") {
+    diagnostics.push({
+      severity: "error",
+      rule: "response_cardinality_output_mismatch",
+      endpoint: name, file, loc: "response_cardinality",
+      message: "response_cardinality: many conflicts with output.type: object.",
+      fix_hint: "Use response_cardinality: single/zero_or_one or change output.type to array.",
+    })
+  }
+
   // Collect all template-rendered strings, including query_file and prompts.
   // Raw code is intentionally skipped: javascript_code.code/code_file may
   // contain normal JS template literals such as `${where.join(" AND ")}`.
@@ -1391,6 +1456,15 @@ function validateEndpoint(entry, ctx) {
 
     const declaredCardinality =
       nodeField(node, nodeParams(node), "output_cardinality") || node.output_cardinality
+    if (declaredCardinality === "one") {
+      diagnostics.push({
+        severity: "error",
+        rule: "output_cardinality_legacy_one",
+        endpoint: name, file, loc: `workflow.nodes[${node.id}].output_cardinality`,
+        message: `Node '${node.id}' uses output_cardinality: one, which is not supported.`,
+        fix_hint: "Use output_cardinality: single.",
+      })
+    }
     if (
       nodeType === "dypai_database" &&
       (nodeField(node, nodeParams(node), "operation") === "query" ||
@@ -1721,6 +1795,19 @@ function validateEndpoint(entry, ctx) {
   const NEEDS_RESPONSE = new Set(["http_api", "webhook"])
   const needsResponse = triggerKeys.some(k => NEEDS_RESPONSE.has(k))
   const hasReturn = allNodes.some(n => n?.return === true || n?.is_return === true)
+  const returnNodes = allNodes.filter(n => n?.return === true || n?.is_return === true)
+  const returnNode = returnNodes.length === 1 ? returnNodes[0] : null
+
+  if (outputType === "object" && !responseCardinality && returnNode && nodeReturnsRowArray(returnNode)) {
+    diagnostics.push({
+      severity: "error",
+      rule: "response_cardinality_required",
+      endpoint: name, file, loc: "response_cardinality",
+      message:
+        `Endpoint '${name}' declares output.type: object but return node '${returnNode.id}' returns SQL row arrays.`,
+      fix_hint: "Add response_cardinality: single, return an object with set_fields, or change output.type to array.",
+    })
+  }
 
   if (needsResponse && allNodes.length > 0 && !hasReturn) {
     diagnostics.push({
@@ -2105,7 +2192,9 @@ export const __testing = {
   extractRuntimePaths,
   inferSelectOutputColumns,
   inferSqlCardinality,
+  nodeReturnsRowArray,
   unsupportedRuntimePlaceholder,
+  validateEndpoint,
   validateNodeOutputRef,
   validateStripeNodePlaceholder,
 }