@dypai-ai/mcp 1.2.3 → 1.3.0

package/src/tools/bulk-upsert.js

@@ -11,6 +11,59 @@ import { readFileSync, existsSync } from "fs"
 import { basename } from "path"
 import { proxyToolCall } from "./proxy.js"
 
+/**
+ * Minimal RFC 4180-compliant CSV parser.
+ * Handles: quoted fields, embedded commas, escaped quotes (""), CRLF, embedded newlines in quoted fields.
+ * Returns an array of rows, each row an array of string fields.
+ *
+ * The previous implementation did `line.split(",")` which silently corrupted
+ * any CSV with quoted commas (e.g. `"Smith, Jr.",100`).
+ */
+function parseCsv(text) {
+  const rows = []
+  let row = []
+  let field = ""
+  let i = 0
+  let inQuotes = false
+  while (i < text.length) {
+    const c = text[i]
+    if (inQuotes) {
+      if (c === '"') {
+        if (text[i + 1] === '"') { field += '"'; i += 2; continue }
+        inQuotes = false
+        i++
+        continue
+      }
+      field += c
+      i++
+      continue
+    }
+    if (c === '"') { inQuotes = true; i++; continue }
+    if (c === ",") { row.push(field); field = ""; i++; continue }
+    if (c === "\r") {
+      // Treat CRLF as one line break
+      if (text[i + 1] === "\n") i++
+      row.push(field); rows.push(row); row = []; field = ""
+      i++
+      continue
+    }
+    if (c === "\n") {
+      row.push(field); rows.push(row); row = []; field = ""
+      i++
+      continue
+    }
+    field += c
+    i++
+  }
+  // Tail row (no trailing newline)
+  if (field.length > 0 || row.length > 0) {
+    row.push(field); rows.push(row)
+  }
+  // Drop trailing empty rows (common when the file ends with \n)
+  while (rows.length && rows[rows.length - 1].length === 1 && rows[rows.length - 1][0] === "") rows.pop()
+  return rows
+}
+
 export const bulkUpsertTool = {
   name: "bulk_upsert",
   description: `Import data from a local CSV or JSON file into a database table.
@@ -63,21 +116,20 @@ Great for seeding initial data: products, categories, config, etc.`,
     // Read and parse data
     let rows
     try {
-      const raw = readFileSync(file_path, "utf-8")
+      // Strip UTF-8 BOM if present — otherwise the first header column ends up
+      // as "\uFEFFname" instead of "name" and silently misaligns everything.
+      const raw = readFileSync(file_path, "utf-8").replace(/^\uFEFF/, "")
 
       if (ext === "json") {
         const parsed = JSON.parse(raw)
         rows = Array.isArray(parsed) ? parsed : [parsed]
       } else {
-        // Parse CSV
-        const lines = raw.trim().split("\n")
-        if (lines.length < 2) return { error: "CSV must have a header row and at least one data row" }
-
-        const headers = lines[0].split(",").map(h => h.trim().replace(/^"|"$/g, ""))
-        rows = lines.slice(1).map(line => {
-          const values = line.split(",").map(v => v.trim().replace(/^"|"$/g, ""))
+        const records = parseCsv(raw)
+        if (records.length < 2) return { error: "CSV must have a header row and at least one data row" }
+        const headers = records[0].map(h => h.trim())
+        rows = records.slice(1).map(values => {
           const obj = {}
-          headers.forEach((h, i) => { obj[h] = values[i] || null })
+          headers.forEach((h, i) => { obj[h] = (values[i] === undefined || values[i] === "") ? null : values[i] })
           return obj
         })
       }
@@ -110,11 +162,16 @@ Great for seeding initial data: products, categories, config, etc.`,
     let inserted = 0
     let errors = []
 
+    // Quote a Postgres identifier safely. Doubles any embedded quotes.
+    const qIdent = (s) => `"${String(s).replace(/"/g, '""')}"`
+    const qTable = qIdent(table)
+
     // Batch in chunks of 50 rows
     const BATCH_SIZE = 50
     for (let i = 0; i < rows.length; i += BATCH_SIZE) {
       const batch = rows.slice(i, i + BATCH_SIZE)
       const batchCols = Object.keys(batch[0])
+      const quotedCols = batchCols.map(qIdent).join(", ")
       const batchValues = batch.map(row =>
         `(${batchCols.map(col => {
           const v = row[col]
@@ -126,10 +183,10 @@ Great for seeding initial data: products, categories, config, etc.`,
 
       let batchSql
       if (upsert_key && batchCols.includes(upsert_key)) {
-        const updateCols = batchCols.filter(c => c !== upsert_key).map(c => `${c} = EXCLUDED.${c}`).join(", ")
-        batchSql = `INSERT INTO ${table} (${batchCols.join(", ")}) VALUES\n${batchValues}\nON CONFLICT (${upsert_key}) DO UPDATE SET ${updateCols}`
+        const updateCols = batchCols.filter(c => c !== upsert_key).map(c => `${qIdent(c)} = EXCLUDED.${qIdent(c)}`).join(", ")
+        batchSql = `INSERT INTO ${qTable} (${quotedCols}) VALUES\n${batchValues}\nON CONFLICT (${qIdent(upsert_key)}) DO UPDATE SET ${updateCols}`
       } else {
-        batchSql = `INSERT INTO ${table} (${batchCols.join(", ")}) VALUES\n${batchValues}`
+        batchSql = `INSERT INTO ${qTable} (${quotedCols}) VALUES\n${batchValues}`
       }
 
       try {

package/src/tools/frontend.js

@@ -13,33 +13,53 @@
 
 import { api } from "../api.js"
 import { deployFromSource } from "./deploy.js"
+import { syncFromRemote } from "./sync.js"
 
 export const manageFrontendTool = {
   name: "manage_frontend",
   description:
-    "Manage the project's frontend deploy lifecycle. Operations:\n" +
-    "  - deploy: upload source files from a local directory and queue a build. Returns immediately with build_status=\"queued\" — poll with build_status until \"success\" or \"failure\".\n" +
-    "  - status: current live deploy info (URL, last deploy time, size).\n" +
-    "  - build_status: progress of the current/latest build (queued/building/success/failure + stage + %).\n" +
-    "  - list_deployments: recent deploy history (status, commit, duration, URL).\n" +
-    "  - logs: build logs for a specific deployment (needs deployment_id from list_deployments).",
+    "Manage the project's frontend: download the source code to disk AND the deploy lifecycle.\n\n" +
+    "Use `sync` FIRST whenever you start working on a project whose frontend code isn't already on this machine — " +
+    "without it you have no React/Vite source to read or edit. Call `deploy` to ship your changes.\n\n" +
+    "Operations:\n" +
+    "  - sync: Download the project's frontend source code (React/Vite/etc.) into a local directory. " +
+    "Use when: starting a session on an existing project, onboarding on a new machine, or refreshing after edits made from elsewhere. " +
+    "Also known as: clone, download source, get source, initial setup. " +
+    "Writes only; does NOT delete local files that were removed upstream — you may have stale files after sync (call them out to the user). " +
+    "By default refuses to overwrite a directory that already has a package.json — pass overwrite:true to allow it (local-only files like .env, node_modules, .vscode are always preserved). " +
+    "AFTER SYNC: .env is gitignored so it's NOT included in the download. If the target directory has no .env, the response sets `env_file_missing: true` and adds a `next_steps` line with the exact VITE_DYPAI_URL / NEXT_PUBLIC_DYPAI_URL value to write. Follow it — without .env the SDK can't reach the engine.\n" +
+    "  - deploy: Upload source files from a local directory and queue a build. Returns immediately with build_status=\"queued\" — poll with `build_status` until \"success\" or \"failure\".\n" +
+    "  - status: Current live deploy info (URL, last deploy time, size).\n" +
+    "  - build_status: Progress of the current/latest build (queued/building/success/failure + stage + %).\n" +
+    "  - list_deployments: Recent deploy history (status, commit, duration, URL).\n" +
+    "  - logs: Build logs for a specific deployment (needs deployment_id from list_deployments).\n\n" +
+    "Related: `dypai_pull` brings BACKEND state (YAML endpoints, SQL, prompts). The two are independent — run both when starting fresh on a full-stack project.",
 
   inputSchema: {
     type: "object",
     properties: {
       operation: {
         type: "string",
-        enum: ["deploy", "status", "build_status", "list_deployments", "logs"],
+        enum: ["deploy", "sync", "status", "build_status", "list_deployments", "logs"],
         description: "Which action to run.",
       },
       project_id: {
         type: "string",
-        description: "Project UUID. Auto-injected from dypai.config.yaml when omitted (except `deploy`, which needs it explicit).",
+        description: "Project UUID. Auto-injected from dypai.config.yaml when omitted (except `deploy` and `sync`, which need it explicit).",
       },
       sourceDirectory: {
         type: "string",
         description: "deploy only. Absolute path to the project source directory (must contain package.json).",
       },
+      targetDirectory: {
+        type: "string",
+        description: "sync only. Absolute path where the project source will be written. If it already contains a package.json, pass overwrite: true to allow replacing files.",
+      },
+      overwrite: {
+        type: "boolean",
+        description: "sync only. When true, allows writing into a directory that already has a project. Local-only files (.env, node_modules, etc.) are NOT touched. Default: false.",
+        default: false,
+      },
       deployment_id: {
         type: "string",
         description: "logs only. Deployment UUID obtained from list_deployments.",
@@ -52,9 +72,9 @@ export const manageFrontendTool = {
     required: ["operation"],
   },
 
-  async execute({ operation, project_id, sourceDirectory, deployment_id, limit } = {}) {
+  async execute({ operation, project_id, sourceDirectory, targetDirectory, overwrite, deployment_id, limit } = {}) {
     if (!operation) {
-      return { success: false, error: "operation is required (deploy | status | build_status | list_deployments | logs)." }
+      return { success: false, error: "operation is required (deploy | sync | status | build_status | list_deployments | logs)." }
     }
     if (!project_id) {
       return { success: false, error: "project_id is required. Set it in dypai.config.yaml or pass it explicitly." }
@@ -68,6 +88,12 @@ export const manageFrontendTool = {
           }
           return await deployFromSource({ sourceDirectory, project_id })
 
+        case "sync":
+          if (!targetDirectory) {
+            return { success: false, error: "operation 'sync' requires 'targetDirectory' (absolute path where the source will be written)." }
+          }
+          return await syncFromRemote({ project_id, targetDirectory, overwrite: !!overwrite })
+
         case "status":
           return await api.get(`/api/engine/${project_id}/frontend`)
 
@@ -84,7 +110,7 @@ export const manageFrontendTool = {
           return await api.get(`/api/engine/${project_id}/frontend/deployments/${deployment_id}/logs`)
 
         default:
-          return { success: false, error: `Unknown operation '${operation}'. Use deploy | status | build_status | list_deployments | logs.` }
+          return { success: false, error: `Unknown operation '${operation}'. Use deploy | sync | status | build_status | list_deployments | logs.` }
       }
     } catch (e) {
       return { success: false, error: e.message, operation }

package/src/tools/proxy.js

@@ -76,28 +76,41 @@ function mcpRequest(body) {
   })
 }
 
+// Single in-flight init promise so concurrent first-calls (e.g. push with
+// concurrency=5) don't all race to initialize and clobber each other's
+// session id mid-handshake.
+let initPromise = null
+
 async function ensureInitialized() {
   if (sessionId) return
-  try {
-    await mcpRequest({
-      jsonrpc: "2.0",
-      id: "init-proxy",
-      method: "initialize",
-      params: {
-        protocolVersion: "2024-11-05",
-        capabilities: {},
-        clientInfo: { name: "dypai-mcp-local", version: "1.0.0" },
-      },
-    })
-    // Send initialized notification
-    await mcpRequest({
-      jsonrpc: "2.0",
-      method: "notifications/initialized",
-    })
-  } catch (e) {
-    // Non-fatal — some servers don't require init
-    process.stderr.write(`MCP proxy init warning: ${e.message}\n`)
-  }
+  if (initPromise) return initPromise
+  initPromise = (async () => {
+    try {
+      await mcpRequest({
+        jsonrpc: "2.0",
+        id: "init-proxy",
+        method: "initialize",
+        params: {
+          protocolVersion: "2024-11-05",
+          capabilities: {},
+          clientInfo: { name: "dypai-mcp-local", version: "1.0.0" },
+        },
+      })
+      // Send initialized notification
+      await mcpRequest({
+        jsonrpc: "2.0",
+        method: "notifications/initialized",
+      })
+    } catch (e) {
+      // Don't swallow silently — calls right after will appear to "work"
+      // returning empty results and we'd never know init failed.
+      process.stderr.write(`MCP proxy init failed: ${e.message}\n`)
+      // Reset so a future call gets a chance to retry.
+      initPromise = null
+      throw e
+    }
+  })()
+  return initPromise
 }
 
 export async function proxyToolCall(toolName, args) {

package/src/tools/scaffold.js

@@ -47,9 +47,10 @@ Or use "blank" for an empty starter project.`,
       return { error: `Directory already has a package.json. Pick an empty directory or a new name.` }
     }
 
-    const token = process.env.DYPAI_TOKEN || ""
-    const mcpUrl = process.env.DYPAI_MCP_URL || "https://mcp.dypai.dev/mcp"
-    const engineUrl = `https://${project_id}.dypai.dev`
+    // Production engine URL: https://<project-id>.dypai.app (NOT .dypai.dev — that's the dev tier).
+    // Override with DYPAI_ENGINE_BASE for self-hosted / staging setups.
+    const engineBase = process.env.DYPAI_ENGINE_BASE || "dypai.app"
+    const engineUrl = `https://${project_id}.${engineBase}`
 
     // Try to download template from API
     let files = []
@@ -79,6 +80,35 @@ Or use "blank" for an empty starter project.`,
     // .env with engine URL
     files.push({ path: ".env", content: `VITE_DYPAI_URL=${engineUrl}\nVITE_PROJECT_ID=${project_id}\n` })
 
+    // .gitignore — keep node_modules / .dypai cache / build outputs / secrets out of git.
+    files.push({ path: ".gitignore", content: [
+      "# Dependencies",
+      "node_modules/",
+      "",
+      "# Build outputs",
+      "dist/",
+      "build/",
+      ".vite/",
+      ".turbo/",
+      "",
+      "# Logs",
+      "*.log",
+      "",
+      "# Secrets (never commit)",
+      ".env",
+      ".env.local",
+      ".env.*.local",
+      "",
+      "# DYPAI local cache (committed: dypai/, gitignored: dypai/.dypai/)",
+      "dypai/.dypai/",
+      "",
+      "# OS / editor",
+      ".DS_Store",
+      ".vscode/",
+      ".idea/",
+      "",
+    ].join("\n") })
+
     // SDK client helper (lib/dypai.ts)
     files.push({ path: "src/lib/dypai.ts", content: `import { createClient } from "@dypai-ai/client-sdk";\n\nexport const dypai = createClient(import.meta.env.VITE_DYPAI_URL);\n` })
 

package/src/tools/sync/codec.js

@@ -18,11 +18,14 @@ import { pullNodeParams, pushNodeParams } from "./transforms.js"
 
 function triggersToYaml(triggers = {}) {
   const out = {}
+  // Telegram takes precedence over webhook because the engine enables both
+  // (telegram piggybacks on webhook plumbing) but conceptually it's one trigger.
+  const telegramEnabled = triggers.telegram?.enabled
   for (const [kind, cfg] of Object.entries(triggers)) {
     if (!cfg) continue
     if (kind === "http_api" && cfg.enabled !== false) {
       out.http_api = { auth_mode: cfg.auth_mode || "jwt" }
-    } else if (kind === "webhook" && cfg.enabled) {
+    } else if (kind === "webhook" && cfg.enabled && !telegramEnabled) {
       out.webhook = { path: cfg.path || "" }
     } else if (kind === "schedule" && cfg.enabled) {
       const s = { cron: cfg.cron }
@@ -30,6 +33,9 @@ function triggersToYaml(triggers = {}) {
       out.schedule = s
     } else if (kind === "manual" && cfg.enabled) {
       out.manual = true
+    } else if (kind === "telegram" && cfg.enabled) {
+      const { enabled, ...rest } = cfg
+      out.telegram = Object.keys(rest).length ? rest : {}
     }
   }
   if (!Object.keys(out).length) out.http_api = { auth_mode: "jwt" }
@@ -43,14 +49,20 @@ function triggersToDb(trigger = {}) {
     http_api: { enabled: true, auth_mode: "jwt" },
     schedule: { enabled: false },
   }
-  if (trigger.http_api) {
-    out.http_api = { enabled: true, auth_mode: trigger.http_api.auth_mode || "jwt" }
-  } else if (trigger.webhook || trigger.schedule || trigger.manual) {
+  // Accept `http_api: true` (shorthand) by treating it as `http_api: {}`.
+  // Accept `auth_mode` or `mode` for forward/backward compat with older docs.
+  const httpApi = trigger.http_api === true ? {} : trigger.http_api
+  const hasNonHttpTrigger = trigger.webhook || trigger.schedule || trigger.manual || trigger.telegram
+  if (httpApi) {
+    const authMode = httpApi.auth_mode || httpApi.mode || "jwt"
+    out.http_api = { enabled: true, auth_mode: authMode }
+  } else if (hasNonHttpTrigger) {
     // Non-HTTP trigger: disable http_api
     out.http_api = { enabled: false, auth_mode: "jwt" }
   }
   if (trigger.webhook) {
-    out.webhook = { path: trigger.webhook.path || "", enabled: true }
+    const wh = trigger.webhook === true ? {} : trigger.webhook
+    out.webhook = { path: wh.path || "", enabled: true }
   }
   if (trigger.schedule) {
     out.schedule = { ...trigger.schedule, enabled: true }
@@ -58,6 +70,14 @@ function triggersToDb(trigger = {}) {
   if (trigger.manual) {
     out.manual = { enabled: true }
   }
+  if (trigger.telegram) {
+    // Telegram triggers piggyback on the webhook plumbing (the engine sets up
+    // the telegram webhook URL automatically). We mark webhook as enabled so
+    // the engine routes the inbound HTTP correctly.
+    const tg = trigger.telegram === true ? {} : trigger.telegram
+    out.telegram = { enabled: true, ...tg }
+    out.webhook = { path: "", enabled: true }
+  }
   return out
 }
 
@@ -74,13 +94,30 @@ function edgesToYaml(edges = []) {
 }
 
 function edgesToDb(edges = []) {
-  return edges.map(e => {
-    const out = { source: e.from, target: e.to }
+  return (edges || []).map(e => {
+    if (!e || typeof e !== "object") return null
+    // Tolerate both YAML-canonical (`from`/`to`) and engine-style (`source`/`target`).
+    // Without this, an agent that wrote `source/target` in YAML would silently
+    // produce edges with `source: undefined`, breaking workflow execution.
+    const source = e.from ?? e.source
+    const target = e.to ?? e.target
+    if (!source || !target) {
+      throw new Error(
+        `Edge is missing source/target: ${JSON.stringify(e).slice(0, 120)}. ` +
+        `Edges must have either 'from'/'to' (canonical) or 'source'/'target' (engine-style).`
+      )
+    }
+    const out = { source, target }
     if (e.condition) out.condition = e.condition
-    if (e.source_handle) out.source_handle = e.source_handle
+    // Accept `source_handle` (canonical) plus a `handle` shorthand. The `handle`
+    // shorthand mirrors how branching looks in a UI ("which branch did this come
+    // out of?") and shows up in agent-written YAML often. Engine only knows
+    // source_handle, so we always emit that key.
+    const sh = e.source_handle ?? e.handle
+    if (sh != null && sh !== "") out.source_handle = String(sh)
     if (e.target_handle) out.target_handle = e.target_handle
     return out
-  })
+  }).filter(Boolean)
 }
 
 // ─── Public codec ───────────────────────────────────────────────────────────
@@ -143,11 +180,114 @@ export function serializeEndpoint(row, mapsCtx) {
   return { doc, extractedFiles }
 }
 
+/**
+ * Detect legacy `start_trigger` nodes and extract their config to a top-level
+ * trigger if one isn't already declared. Returns:
+ *   - cleanedNodes: workflow.nodes minus any start_trigger entries
+ *   - cleanedEdges: workflow.edges minus any edge that referenced a removed node
+ *   - inferredTrigger: the trigger object to use if doc.trigger is missing
+ *
+ * This makes the codec tolerant of an agent that copied an old-format example
+ * (where the trigger was a node) into a YAML workflow. Without this they'd
+ * get "unknown_node_type: start_trigger" because the canonical form has no
+ * such node — trigger lives at the top level.
+ */
+function liftStartTriggerNodes(workflow) {
+  const allNodes = workflow?.nodes || []
+  const allEdges = workflow?.edges || []
+  const startNodes = allNodes.filter(n => {
+    const t = n?.type ?? n?.node_type
+    return t === "start_trigger"
+  })
+  if (!startNodes.length) {
+    return { cleanedNodes: allNodes, cleanedEdges: allEdges, inferredTrigger: null, lifted: false }
+  }
+
+  const startIds = new Set(startNodes.map(n => n.id))
+  const cleanedNodes = allNodes.filter(n => !startIds.has(n?.id))
+  const cleanedEdges = allEdges.filter(e =>
+    !startIds.has(e?.from ?? e?.source) && !startIds.has(e?.to ?? e?.target)
+  )
+
+  // Build a trigger from the FIRST start_trigger node's parameters. If multiple
+  // are present (rare), the first wins — we don't try to merge.
+  const first = startNodes[0]
+  const params = first.parameters || first
+  const triggerType = params.trigger_type || params.triggerType || "http_api"
+  let inferredTrigger
+  switch (triggerType) {
+    case "http_api":
+      inferredTrigger = { http_api: { auth_mode: params.auth_mode || params.mode || "jwt" } }
+      break
+    case "webhook":
+      inferredTrigger = { webhook: params.path ? { path: params.path } : {} }
+      break
+    case "schedule": {
+      const s = {}
+      if (params.cron) s.cron = params.cron
+      if (params.timezone) s.timezone = params.timezone
+      inferredTrigger = { schedule: s }
+      break
+    }
+    case "telegram":
+      inferredTrigger = { telegram: {} }
+      break
+    default:
+      inferredTrigger = { http_api: { auth_mode: "jwt" } }
+  }
+
+  return { cleanedNodes, cleanedEdges, inferredTrigger, lifted: true }
+}
+
 export function deserializeEndpoint(doc, mapsCtx) {
   const readFile = mapsCtx.readFile || (() => "")
 
-  const nodes = (doc.workflow?.nodes || []).map(clean => {
-    const { id, type, variable, return: isReturn, ...params } = clean
+  // Lift legacy `start_trigger` nodes into the canonical top-level trigger.
+  // If the doc already has a `trigger:` block, we trust that one and just
+  // strip the redundant nodes (no merge — top-level is canonical).
+  const { cleanedNodes, cleanedEdges, inferredTrigger } = liftStartTriggerNodes(doc.workflow)
+  const effectiveTrigger = doc.trigger || inferredTrigger
+  const effectiveWorkflow = { ...doc.workflow, nodes: cleanedNodes, edges: cleanedEdges }
+
+  const nodes = (effectiveWorkflow.nodes || []).map(clean => {
+    // Tolerate both YAML-canonical `type` and engine-style `node_type`. The
+    // canonical form is `type`, but agents writing YAML by hand sometimes use
+    // `node_type` because that's what the engine returns. We accept either,
+    // but FAIL LOUD if neither is present — silently sending undefined to the
+    // engine causes accepted-but-not-created ghost endpoints (the bug from 1.2.2).
+    if (!clean || typeof clean !== "object") {
+      throw new Error(`workflow.nodes contains a non-object entry in endpoint '${doc.name}'.`)
+    }
+    // Tolerate both YAML-canonical (`type`, `return`) and engine-style
+    // (`node_type`, `is_return`) for the keys that have a "renamed" form.
+    // Anything still in `rest` after this is treated as a node parameter
+    // (inline form). This is the layer that prevents silent data loss when
+    // an agent mixes the two conventions.
+    const {
+      id,
+      type: typeA, node_type: typeB,
+      variable,
+      return: isReturnA, is_return: isReturnB,
+      parameters: explicitParams,
+      ...rest
+    } = clean
+    const type = typeA || typeB
+    const isReturn = isReturnA || isReturnB
+    if (!id) {
+      throw new Error(
+        `A node in endpoint '${doc.name}' is missing 'id'. Every node needs a unique id within the workflow.`
+      )
+    }
+    if (!type) {
+      throw new Error(
+        `Node '${id}' in endpoint '${doc.name}' is missing 'type'. ` +
+        `Each node in workflow.nodes must declare a node type, e.g. \`type: dypai_database\`. ` +
+        `(Both 'type' and 'node_type' are accepted.)`
+      )
+    }
+    // Params: prefer an explicit `parameters:` object, otherwise fall back to
+    // the inline shape (everything that isn't id/type/variable/return is a param).
+    const params = explicitParams && typeof explicitParams === "object" ? explicitParams : rest
     const nodeCtx = {
       ...mapsCtx,
       endpointName: doc.name,
@@ -164,21 +304,25 @@ export function deserializeEndpoint(doc, mapsCtx) {
 
   const workflow_code = {
     nodes,
-    edges: edgesToDb(doc.workflow?.edges),
-    execution_config: { triggers: triggersToDb(doc.trigger) },
+    edges: edgesToDb(effectiveWorkflow.edges),
+    execution_config: { triggers: triggersToDb(effectiveTrigger) },
     schema_version: "2.0",
   }
-  if (doc.workflow?.on_error) workflow_code.on_error = doc.workflow.on_error
+  if (effectiveWorkflow.on_error) workflow_code.on_error = effectiveWorkflow.on_error
 
   return {
     name: doc.name,
-    method: doc.method || "GET",
+    // Engine expects uppercase HTTP methods. Normalize so YAML can use any case.
+    method: String(doc.method || "GET").toUpperCase(),
     description: doc.description || null,
     workflow_code,
     input: doc.input || null,
     output: doc.output || null,
     allowed_roles: doc.allowed_roles || [],
-    is_tool: !!doc.tool,
+    // Accept both `tool: true` (canonical) and `is_tool: true` (engine-style).
+    // Without this, an agent that wrote `is_tool` in YAML would silently get
+    // a non-tool endpoint and `allowed_roles` would not be enforced as expected.
+    is_tool: !!(doc.tool || doc.is_tool),
     tool_description: doc.tool_description || null,
     group_id: doc.group && mapsCtx.groupNameToId ? (mapsCtx.groupNameToId[doc.group] || null) : null,
   }

package/src/tools/sync/diff.js

@@ -52,6 +52,14 @@ export const dypaiDiffTool = {
       }
     }
 
+    if (!remote || !remote.mapsCtx) {
+      return {
+        success: false,
+        phase: "fetch_remote",
+        error: "Remote state could not be fetched (mapsCtx missing). Check your DYPAI_TOKEN and project_id.",
+      }
+    }
+
     const plan = computePlan(local, remote, remote.mapsCtx, {
       deleteOrphans: delete_orphans,
       stateSnapshot,

package/src/tools/sync/planner.js

@@ -178,9 +178,15 @@ async function findEndpointYamls(endpointsDir) {
         const sub = relFromRoot ? `${relFromRoot}/${e.name}` : e.name
         await walk(join(dir, e.name), sub, group || e.name)
       } else if (e.isFile() && (e.name.endsWith(".yaml") || e.name.endsWith(".yml"))) {
+        // Skip files ending in .disabled (e.g. _example.yaml.disabled — the
+        // reference template that ships with empty projects). Anything ending
+        // in .disabled BEFORE the .yaml suffix is also treated as disabled.
+        if (e.name.endsWith(".disabled.yaml") || e.name.endsWith(".disabled.yml")) continue
         const rel = relFromRoot ? `${relFromRoot}/${e.name}` : e.name
         out.push({ rel, group })
       }
+      // Note: files ending in .disabled (with no .yaml/.yml after) are also
+      // skipped naturally because the isFile branch only matches .yaml/.yml.
     }
   }
   await walk(endpointsDir, "", null)
@@ -232,8 +238,17 @@ export async function readLocalState(rootDir) {
  * This is what we'd send to update_endpoint.
  */
 export function localToCanonical(entry, mapsCtx) {
+  if (!entry || !entry.doc) {
+    throw new Error("localToCanonical: entry must have a `doc` field (parsed YAML).")
+  }
+  if (!mapsCtx || typeof mapsCtx !== "object") {
+    throw new Error(
+      "localToCanonical: mapsCtx required to resolve credential/group/tool references. " +
+      "If you see this, fetchRemoteState probably returned an empty/failed response."
+    )
+  }
   const { doc, fileMap } = entry
-  const ctx = { ...mapsCtx, readFile: (p) => fileMap[p] ?? "" }
+  const ctx = { ...mapsCtx, readFile: (p) => (fileMap || {})[p] ?? "" }
   return deserializeEndpoint(doc, ctx)
 }