@dypai-ai/mcp 1.2.3 → 1.3.0

package/src/index.js

@@ -25,7 +25,14 @@ import { checkForUpdates } from "./auto-update.js"
 // get_build_status, list_deployments, get_deployment_logs) into a single operation-dispatched
 // tool. The heavy deploy logic still lives in ./tools/deploy.js (exported as deployFromSource).
 import { manageFrontendTool } from "./tools/frontend.js"
-import { scaffoldTool } from "./tools/scaffold.js"
+// scaffoldTool (download_template) was removed from the catalog in favor of
+// `manage_frontend(operation: "sync")`, which pulls the project's actual
+// source from GitHub instead of dropping a generic Vite starter on disk.
+// The "create from scratch" use case is owned by the `@dypai-ai/install` CLI
+// (interactive, OAuth, IDE detection, MCP config), which is a better fit for
+// that flow than an MCP tool. The ./tools/scaffold.js file is preserved on
+// disk in case a future v2 wants to resurrect a leaner version.
+// import { scaffoldTool } from "./tools/scaffold.js"
 import { manageDomainTool } from "./tools/domains.js"
 import { bulkUpsertTool } from "./tools/bulk-upsert.js"
 // dypaiTestTool (YAML test-suite runner) is intentionally not imported — deferred to v2.
@@ -61,8 +68,9 @@ await checkForUpdates().catch(() => {})
 
 const LOCAL_TOOLS = [
   // ── Frontend & Deploy ─────────────────────────────────────────────────────
+  // manage_frontend covers: deploy, sync (pull source from repo), status,
+  // build_status, list_deployments, logs.
   manageFrontendTool,
-  scaffoldTool,
   // ── Domains ───────────────────────────────────────────────────────────────
   manageDomainTool,
   // ── Data ──────────────────────────────────────────────────────────────────
@@ -94,7 +102,7 @@ const REMOTE_TOOLS = [
   // ── Project ───────────────────────────────────────────────────────────────
   { name: "list_projects", description: "Lists all projects you have access to across your organizations. Returns project id, name, description, organization, subscription plan, and status. Use this as the first step to discover which projects are available, then pass project_id to other tools.", inputSchema: { type: "object", properties: { organization_id: { type: "string", description: "Optional. Filter projects by organization UUID." } }, required: [] } },
   { name: "get_project", description: "Gets detailed information about a specific project. Returns project name, description, organization, plan, status, engine URL, frontend slug, and timestamps.", inputSchema: { type: "object", properties: { project_id: { type: "string" } }, required: ["project_id"] } },
-  { name: "create_project", description: "Create a new DYPAI project (free plan). Creates a full project with database, API engine, GitHub repo, and frontend hosting. Provisioning takes ~1 minute.", inputSchema: { type: "object", properties: { name: { type: "string", description: "Project name (e.g. 'My Veterinary App')" }, organization_id: { type: "string", description: "Optional. Uses default org if omitted." }, description: { type: "string" }, template_slug: { type: "string", description: "Optional. Start from a project template (e.g. 'clinic', 'gym', 'blank'). Use search_project_templates to browse." } }, required: ["name"] } },
+  { name: "create_project", description: "Create a new DYPAI project (free plan). Creates a full project with database, engine, and hosting. Provisioning takes ~1 minute.\n\nIMPORTANT: before calling this, check for a matching template with `search_project_templates`. Passing a `template_slug` drops in a ready-made schema + endpoints + UI that cover 70% of common app types (clinic, gym, waitlist, SaaS, e-commerce, landing, etc.). Only create a blank project if nothing matches — starting blank costs the user hours of boilerplate.", inputSchema: { type: "object", properties: { name: { type: "string", description: "Project name (e.g. 'My Veterinary App')" }, organization_id: { type: "string", description: "Optional. Uses default org if omitted." }, description: { type: "string" }, template_slug: { type: "string", description: "RECOMMENDED. Project template slug to start from (e.g. 'clinic', 'gym', 'waitlist', 'blank'). Always call search_project_templates first to find the best match for what the user asked. Only omit this / use 'blank' when nothing fits." } }, required: ["name"] } },
   { name: "get_app_credentials", description: "Lists available credentials in the current application. Returns API keys, anon key, service role key, and engine URL needed for SDK configuration.", inputSchema: { type: "object", properties: { project_id: { type: "string" } }, required: [] } },
 
   // ── Database ──────────────────────────────────────────────────────────────
@@ -127,17 +135,249 @@ const REMOTE_TOOLS = [
   // (dypai_pull handles this), review with git, then dypai_push. That keeps
   // the change reviewable in git instead of being an invisible DB rewrite.
   // { name: "rollback_endpoint", description: "EMERGENCY rollback ...", inputSchema: { ... } },
-  { name: "search_nodes", description: "Semantic (vector) search over the node catalog by intent/meaning. Use when you don't know the node_type name — e.g. 'send email', 'process payment', 'transform array'. For looking up a KNOWN node_type's parameters, read dypai/node-catalog.json locally instead (faster, offline, no token used).", inputSchema: { type: "object", properties: { query: { type: "string", description: "What you need (e.g. 'send email', 'stripe', 'database')" } }, required: ["query"] } },
+  // search_nodes is intentionally hidden — `dypai/node-catalog.json` is cached
+  // locally by `dypai_pull` and contains EVERY node with its full schema. The
+  // agent should `Read` that file directly: faster, offline, no token used,
+  // and the catalog easily fits in context. Exposing search_nodes alongside
+  // it confused agents into doing semantic search before bothering to read
+  // the file. Implementation still lives on the remote and can be re-enabled
+  // if a pure-vector fallback is ever needed.
+  // { name: "search_nodes", description: "Semantic (vector) search over the node catalog ...", inputSchema: { ... } },
 
   // ── Auth & Users ──────────────────────────────────────────────────────────
   // Note: `get_auth_users` is intentionally NOT exposed — manage_users covers
   // create/delete/ban/update_role/set_password; for listing/reading, use
   // execute_sql against auth.users (read-only) or manage_users with list op.
-  { name: "manage_users", description: "Manage authenticated users. Operations: create, list, delete, ban, unban, update_role, set_password.", inputSchema: { type: "object", properties: { project_id: { type: "string" }, operation: { type: "string", description: "create, list, delete, ban, unban, update_role, set_password" } }, required: ["operation"] } },
-  { name: "manage_roles", description: "Manage user roles. Operations: create, list, update, delete.", inputSchema: { type: "object", properties: { project_id: { type: "string" }, operation: { type: "string", description: "create, list, update, delete" } }, required: ["operation"] } },
+  // manage_users — discriminated by `operation`. The `allOf` block tells the
+  // agent which params each operation requires, so it doesn't have to call
+  // and fail to learn the contract. Mirrors the validation the remote does.
+  {
+    name: "manage_users",
+    description: `Manage authenticated users (better-auth backed).
+
+Operations:
+- list:         Paginated user listing. Optional: search, limit (1-100, default 20), offset, sort_by, sort_order.
+- get:          Fetch a single user by user_id.
+- create:       Create a user with email + password. Optional: name, role, email_verified, send_invite_email.
+- set_password: Admin-overrides a user's password (user_id + new password).
+- update_role:  Change a user's app role (user_id + role; role must exist in system.roles).
+- delete:       Permanently remove a user (user_id).
+- ban / unban:  Block / unblock login (user_id; ban supports ban_reason and ban_expires_in seconds).
+
+NOTE: user IDs are TEXT (better-auth nanoids like "G1LIBXsbMLxUrs99ebCaL9X4auxW26AC"), NOT UUIDs.`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        project_id:        { type: "string", description: "Project UUID. Required for user tokens; auto-detected for project tokens." },
+        operation:         { type: "string", enum: ["list", "get", "create", "set_password", "update_role", "delete", "ban", "unban"] },
+        // Fields used by various operations
+        user_id:           { type: "string", description: "User ID (TEXT, better-auth nanoid). Required for: get, set_password, update_role, delete, ban, unban." },
+        email:             { type: "string", description: "User email. Required for: create." },
+        password:          { type: "string", description: "User password (min 6 chars). Required for: create, set_password." },
+        name:              { type: "string", description: "Display name. Optional for: create." },
+        role:              { type: "string", description: "App role name (must exist in system.roles). Optional for create; required for update_role." },
+        email_verified:    { type: "boolean", description: "Mark email as verified on create (default false). Optional for: create." },
+        send_invite_email: { type: "boolean", description: "If creating without password, send a reset-password invite email (default true). Optional for: create." },
+        ban_reason:        { type: "string", description: "Reason text. Optional for: ban." },
+        ban_expires_in:    { type: "integer", description: "Ban duration in seconds. Omit for permanent ban. Optional for: ban." },
+        // List pagination/sort fields
+        search:            { type: "string", description: "Substring filter on email or name. Optional for: list." },
+        limit:             { type: "integer", description: "Max results 1-100 (default 20). Optional for: list." },
+        offset:            { type: "integer", description: "Pagination offset (default 0). Optional for: list." },
+        sort_by:           { type: "string", description: "Sort column (default 'created_at'). Optional for: list." },
+        sort_order:        { type: "string", enum: ["asc", "desc"], description: "Sort direction (default 'desc'). Optional for: list." },
+      },
+      required: ["operation"],
+      allOf: [
+        { if: { properties: { operation: { const: "get" } },          required: ["operation"] }, then: { required: ["user_id"] } },
+        { if: { properties: { operation: { const: "create" } },       required: ["operation"] }, then: { required: ["email", "password"] } },
+        { if: { properties: { operation: { const: "set_password" } }, required: ["operation"] }, then: { required: ["user_id", "password"] } },
+        { if: { properties: { operation: { const: "update_role" } },  required: ["operation"] }, then: { required: ["user_id", "role"] } },
+        { if: { properties: { operation: { const: "delete" } },       required: ["operation"] }, then: { required: ["user_id"] } },
+        { if: { properties: { operation: { const: "ban" } },          required: ["operation"] }, then: { required: ["user_id"] } },
+        { if: { properties: { operation: { const: "unban" } },        required: ["operation"] }, then: { required: ["user_id"] } },
+      ],
+    },
+  },
+
+  // manage_roles — discriminated by `operation`. Same pattern as manage_users.
+  {
+    name: "manage_roles",
+    description: `Manage app roles used for endpoint access control (allowed_roles in YAML) and user assignment.
+
+Operations:
+- list:   Returns all roles with permissions.
+- create: Create a role (name required). Built-in: 'authenticated', 'admin'.
+- update: Update name / description / permissions of a role (role_id required).
+- delete: Delete a role (role_id required). Endpoints referencing it lose that role.`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        project_id:  { type: "string", description: "Project UUID. Required for user tokens; auto-detected for project tokens." },
+        operation:   { type: "string", enum: ["list", "create", "update", "delete"] },
+        role_id:     { type: "string", description: "Role UUID. Required for: update, delete." },
+        name:        { type: "string", description: "Role name. Required for: create. Optional for: update." },
+        description: { type: "string", description: "Free-text role description. Optional for: create, update." },
+        permissions: { type: "object", description: "JSON of role flags. Keys: manage_users, manage_roles, manage_system. Optional for: create, update." },
+      },
+      required: ["operation"],
+      allOf: [
+        { if: { properties: { operation: { const: "create" } }, required: ["operation"] }, then: { required: ["name"] } },
+        { if: { properties: { operation: { const: "update" } }, required: ["operation"] }, then: { required: ["role_id"] } },
+        { if: { properties: { operation: { const: "delete" } }, required: ["operation"] }, then: { required: ["role_id"] } },
+      ],
+    },
+  },
 
   // ── Storage ───────────────────────────────────────────────────────────────
-  { name: "list_buckets", description: "Manage storage buckets for the project. List buckets with their configuration (public/private, file size limits, allowed MIME types).", inputSchema: { type: "object", properties: { project_id: { type: "string" } }, required: [] } },
+  // manage_storage covers BOTH bucket-level and object-level operations.
+  // The remote also accepts the legacy name `list_buckets` (alias) so older
+  // local MCP versions still work during rollout. We expose only the new name.
+  {
+    name: "manage_storage",
+    description: `Manage storage: buckets AND the objects inside them.
+
+Bucket operations:
+- list:                    Returns all buckets (default operation; no args needed).
+- create:                  Create a bucket. Args: name (lowercase, hyphens, 3-63 chars), public (default false).
+- delete:                  Delete a bucket and ALL its objects. Args: name. WARNING: irreversible.
+
+Object operations (within a specific bucket):
+- list_objects:            List files in a bucket. Args: bucket; optional prefix, limit, offset.
+- delete_object:           Delete one file. Args: bucket, name.
+- get_signed_download_url: Generate a temporary URL to view/download a file.
+                           Args: bucket, name; optional expires_minutes (1-1440, default 15),
+                           download (true = force attachment).
+
+Notes:
+- UPLOADS are NOT exposed here. Multipart doesn't fit cleanly over MCP stdio.
+  Upload via: SDK frontend (\`dypai.api.upload\`) or the \`dypai_storage\` node in a workflow.
+- Bucket names: lowercase, 3-63 chars, [a-z0-9-]. Use hyphens, not underscores.
+- Protected system buckets (e.g. avatars, public, dypai-storage) cannot be deleted.`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        project_id: { type: "string", description: "Project UUID. Required for user tokens; auto-detected for project tokens." },
+        operation: {
+          type: "string",
+          enum: ["list", "create", "delete", "list_objects", "delete_object", "get_signed_download_url"],
+          default: "list",
+        },
+        // Bucket-level
+        name:    { type: "string", description: "For create/delete (bucket name) OR for delete_object/get_signed_download_url (object's logical name inside the bucket, e.g. 'avatars/u_123.png')." },
+        public:  { type: "boolean", description: "If true, bucket files are publicly accessible. Used by: create. Default: false." },
+        // Object-level
+        bucket:           { type: "string", description: "Bucket name. Required by: list_objects, delete_object, get_signed_download_url." },
+        prefix:           { type: "string", description: "Filter objects whose name starts with this prefix (e.g. 'avatars/'). Optional for: list_objects." },
+        expires_minutes:  { type: "integer", minimum: 1, maximum: 1440, description: "Signed URL TTL in minutes. Optional for: get_signed_download_url. Default: 15." },
+        download:         { type: "boolean", description: "If true, signed URL forces download (Content-Disposition: attachment). Optional for: get_signed_download_url. Default: false." },
+        // Pagination (used by list and list_objects)
+        limit:   { type: "integer", description: "Max results. list: default 50, max 200. list_objects: default 20, max 100." },
+        offset:  { type: "integer", description: "Pagination offset. Default 0." },
+      },
+      required: [],
+      allOf: [
+        { if: { properties: { operation: { const: "create" } },                  required: ["operation"] }, then: { required: ["name"] } },
+        { if: { properties: { operation: { const: "delete" } },                  required: ["operation"] }, then: { required: ["name"] } },
+        { if: { properties: { operation: { const: "list_objects" } },            required: ["operation"] }, then: { required: ["bucket"] } },
+        { if: { properties: { operation: { const: "delete_object" } },           required: ["operation"] }, then: { required: ["bucket", "name"] } },
+        { if: { properties: { operation: { const: "get_signed_download_url" } }, required: ["operation"] }, then: { required: ["bucket", "name"] } },
+      ],
+    },
+  },
+
+  // ── Triggers (Schedules + Webhooks) ──────────────────────────────────────
+  // These tools OBSERVE + CONTROL trigger runtime state. The DEFINITION lives
+  // in the endpoint YAML (`trigger.schedule` / `trigger.webhook`) — to change
+  // a cron expression or webhook path, edit the YAML and `dypai_push`.
+  {
+    name: "manage_schedules",
+    description: `Observe + control cron schedules at runtime, by endpoint name.
+
+Schedules are DECLARED in dypai/endpoints/<name>.yaml under \`trigger.schedule\`.
+This tool exists for runtime observability and toggling is_active WITHOUT
+round-tripping the YAML.
+
+All per-schedule operations target an endpoint by its \`endpoint_name\` — the
+same name you wrote in the YAML. Internal UUIDs are resolved automatically.
+
+Operations:
+- list:    All schedules in the project. Optional filter: is_active.
+- get:     Full detail of one schedule (cron, timezone, last_run, status).
+- pause:   Set is_active=false. Engine immediately stops firing the cron.
+- resume:  Set is_active=true. Engine re-arms the BullMQ repeatable job.
+- history: List recent executions from system.schedule_runs.
+
+To CHANGE the cron expression, timezone, or payload: edit the endpoint YAML
+and \`dypai_push\`. This tool does NOT modify the schedule definition.`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        project_id:    { type: "string", description: "Project UUID. Required for user tokens; auto-detected for project tokens." },
+        operation:     { type: "string", enum: ["list", "get", "pause", "resume", "history"] },
+        endpoint_name: { type: "string", description: "Endpoint name as declared in dypai/endpoints/<name>.yaml. Required for: get, pause, resume, history." },
+        is_active:     { type: "boolean", description: "Filter by active state. Optional for: list." },
+        limit:         { type: "integer", description: "Max results. list: 1-200 (default 50). history: 1-100 (default 20)." },
+        offset:        { type: "integer", description: "Pagination offset. Optional for: list, history. Default 0." },
+      },
+      required: ["operation"],
+      allOf: [
+        { if: { properties: { operation: { const: "get" } },     required: ["operation"] }, then: { required: ["endpoint_name"] } },
+        { if: { properties: { operation: { const: "pause" } },   required: ["operation"] }, then: { required: ["endpoint_name"] } },
+        { if: { properties: { operation: { const: "resume" } },  required: ["operation"] }, then: { required: ["endpoint_name"] } },
+        { if: { properties: { operation: { const: "history" } }, required: ["operation"] }, then: { required: ["endpoint_name"] } },
+      ],
+    },
+  },
+
+  {
+    name: "manage_webhooks",
+    description: `Observe + control HTTP-trigger webhooks at runtime, by endpoint name.
+
+Webhooks are DECLARED in dypai/endpoints/<name>.yaml under \`trigger.webhook\`.
+This tool exists for runtime observability and control WITHOUT round-tripping
+the YAML.
+
+All per-webhook operations target an endpoint by its \`endpoint_name\` — the
+same name you wrote in the YAML. Internal UUIDs are resolved automatically.
+
+Operations:
+- list:           All webhooks. Each item includes the FULL URL (ready to paste
+                  into Stripe / Telegram / Polar / etc. provider config).
+- get:            Full detail of one webhook (URL, last_called_at, total_calls).
+- pause:          Set is_active=false (incoming calls are rejected).
+- resume:         Set is_active=true.
+- history:        Recent incoming calls (status, payload preview, errors).
+- test:           Fire a synthetic payload at the webhook to validate the trigger.
+                  Optional: test_payload (object), test_headers (object).
+- rotate_secret:  Generate a new HMAC secret. Use after a leak; you'll need
+                  to update the secret in the upstream provider too.
+
+To CHANGE the path, auth mode, allowed methods, or filtering: edit the
+endpoint YAML and \`dypai_push\`. This tool does NOT modify the definition.`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        project_id:    { type: "string", description: "Project UUID. Required for user tokens; auto-detected for project tokens." },
+        operation:     { type: "string", enum: ["list", "get", "pause", "resume", "history", "test", "rotate_secret"] },
+        endpoint_name: { type: "string", description: "Endpoint name as declared in dypai/endpoints/<name>.yaml. Required for: get, pause, resume, history, test, rotate_secret." },
+        is_active:     { type: "boolean", description: "Filter by active state. Optional for: list." },
+        limit:         { type: "integer", description: "Max results. list: 1-200 (default 50). history: 1-100 (default 20)." },
+        offset:        { type: "integer", description: "Pagination offset. Optional for: list, history. Default 0." },
+        test_payload:  { type: "object", description: "Synthetic JSON body to send. Optional for: test (default: empty object)." },
+        test_headers:  { type: "object", description: "Extra headers to attach to the synthetic call. Optional for: test." },
+      },
+      required: ["operation"],
+      allOf: [
+        { if: { properties: { operation: { const: "get" } },           required: ["operation"] }, then: { required: ["endpoint_name"] } },
+        { if: { properties: { operation: { const: "pause" } },         required: ["operation"] }, then: { required: ["endpoint_name"] } },
+        { if: { properties: { operation: { const: "resume" } },        required: ["operation"] }, then: { required: ["endpoint_name"] } },
+        { if: { properties: { operation: { const: "history" } },       required: ["operation"] }, then: { required: ["endpoint_name"] } },
+        { if: { properties: { operation: { const: "test" } },          required: ["operation"] }, then: { required: ["endpoint_name"] } },
+        { if: { properties: { operation: { const: "rotate_secret" } }, required: ["operation"] }, then: { required: ["endpoint_name"] } },
+      ],
+    },
+  },
 
   // ── Knowledge ─────────────────────────────────────────────────────────────
   { name: "search_docs", description: "Search DYPAI documentation. Use this when unsure about SDK usage, auth patterns, workflow nodes, or platform features. Returns relevant documentation chunks.", inputSchema: { type: "object", properties: { query: { type: "string", description: "What you want to learn about" } }, required: ["query"] } },
@@ -149,11 +389,25 @@ const REMOTE_TOOLS = [
 
 const SERVER_INSTRUCTIONS = `You are building full-stack applications on the DYPAI platform. You handle backend (endpoints, database, auth, realtime) AND frontend (SDK integration, UI code).
 
+## Creating a new project — template-first
+
+When the user asks to CREATE a new project (not work on an existing one), you MUST check for a matching project template before falling back to a blank one:
+
+1. **Infer the intent.** If the user's request describes a recognizable app type — clinic / gym / waitlist / SaaS dashboard / e-commerce / landing / CRM / marketplace / chat app / booking / etc. — there's probably a pre-built starter for it.
+2. **Call \`search_project_templates(query: "...")\`** with a natural description of what they want. Use a few keywords, not a full sentence. Returns templates with a \`slug\`, name, description, and category.
+3. **If a template looks like a reasonable fit**, confirm briefly with the user ("I found a 'clinic' starter that includes patients, appointments and billing — start from that?") and then call \`create_project(name, template_slug: "<slug>")\`.
+4. **Only if nothing fits**, call \`create_project(name)\` without \`template_slug\` (or with \`template_slug: "blank"\`). Starting blank means writing every endpoint, table, and UI from scratch — skipping a template that covers 70% of the work costs the user an hour of rebuilding boilerplate.
+
+Trigger phrases that should make you reach for \`search_project_templates\` first: "create an app for X", "build me a Y", "I want to launch a Z", "start a new project for…", "montar una app de…", "I need a dashboard that…".
+
+Do NOT silently default to a blank project. If the match is uncertain, ASK the user before creating.
+
 ## Getting Started
 1. Call list_projects() to find your project_id (skip if you already know it).
-2. **ALWAYS CALL dypai_pull FIRST** on any project you haven't worked on in this session. It materializes ./dypai/ (endpoints, SQL, prompts, code, schema.sql, node-catalog.json, realtime.yaml) and returns an \`overview\` block with endpoint groups, credentials, and tool-enabled endpoints — everything you need to orient yourself in one call.
-3. BEFORE implementing an unfamiliar feature, call search_docs with the topic (e.g. "auth", "upload files", "realtime", "stripe").
-4. Build backend first, then frontend.
+2. **ALWAYS CALL dypai_pull FIRST** on any project you haven't worked on in this session. It materializes ./dypai/ (endpoints, SQL, prompts, code, schema.sql, node-catalog.json, realtime.yaml) and returns an \`overview\` block with endpoint groups, credentials, and tool-enabled endpoints — everything you need to orient yourself in one call. This ONLY brings BACKEND state.
+3. If you're going to read or edit FRONTEND code (React / Vite / Next / etc.) and the source isn't already on this machine, **also call \`manage_frontend(operation: "sync", targetDirectory: <absolute path>)\`** to download it. \`dypai_pull\` and \`manage_frontend(sync)\` are independent: run both when starting fresh on a full-stack project.
+4. BEFORE implementing an unfamiliar feature, call search_docs with the topic (e.g. "auth", "upload files", "realtime", "stripe").
+5. Build backend first, then frontend.
 
 ## Build Backend (git-first workflow)
 Everything about endpoints lives in files under ./dypai/ — you NEVER call endpoint CRUD tools directly. There is no create_endpoint / update_endpoint / add_node in this MCP anymore.
@@ -170,7 +424,7 @@ Everything about endpoints lives in files under ./dypai/ — you NEVER call endp
 
 ## Node reference — read the local catalog BEFORE picking
 
-\`dypai/node-catalog.json\` is the single source of truth for every node_type this engine exposes, with its full input/output schema. It's cached locally by \`dypai_pull\` and auto-refreshed. **Read it directly with your Read tool** — don't call search_nodes, don't guess parameter names, don't invent node_types. If a type isn't in node-catalog.json, it doesn't exist.
+\`dypai/node-catalog.json\` is the single source of truth for every node_type this engine exposes, with its full input/output schema. It's cached locally by \`dypai_pull\` and auto-refreshed. **Read it directly with your Read tool** — don't guess parameter names, don't invent node_types. If a type isn't in node-catalog.json, it doesn't exist.
 
 Typical flow when adding a step to a workflow:
 1. Decide the CONCEPT (DB insert? HTTP call? shape fields? branching?).
@@ -178,8 +432,6 @@ Typical flow when adding a step to a workflow:
 3. If you find one: read its input_schema from the same file and configure the node.
 4. If nothing native fits naturally: consider \`javascript_code\` / \`python_code\` (see below).
 
-\`search_nodes(query="...")\` is a semantic/vector fallback for when the intent is vague AND you can't locate it by name in node-catalog.json. It's rarely needed once you have the file open.
-
 ## Node selection — think before choosing
 
 javascript_code is a fine tool. The problem is picking it reflexively without considering native alternatives. Native nodes are validated by dypai_validate, observable per-node in traces, and readable in PR diffs — so when one fits, it's the better default. JS wins when the logic is genuinely custom and bundling multiple concerns is clearer than chaining 4+ native nodes.
@@ -219,6 +471,78 @@ When you hit a red flag, replace the JS node. When the JS legitimately does more
 - Client-side: \`dypai.realtime.subscribe(table, { filter, event }, callback)\`.
 - See search_docs "realtime" for patterns.
 
+## Agent tools (endpoints as tools for an \`agent\` node)
+
+Any endpoint can be flagged as a **tool** so that \`agent\` nodes elsewhere in the project can invoke it. This is how you give an LLM the ability to query your DB, call external APIs, send emails, etc. — you expose the action as a normal endpoint and mark it \`tool: true\`.
+
+### Step 1 — mark the endpoint as a tool (in its YAML)
+
+\`\`\`yaml
+name: search-products
+method: GET
+tool: true                                    # ← exposes it to agent nodes
+tool_description: |                           # ← what the agent should know about this tool
+  Search the product catalog by name or category.
+  Use when the user asks about availability, prices, or features.
+input:                                        # ← define a tight schema; the LLM reads it
+  type: object
+  required: [query]
+  properties:
+    query:   { type: string, description: "Free-text search term" }
+    limit:   { type: integer, default: 10 }
+trigger:
+  http_api:
+    auth_mode: api_key                        # agent calls are server-to-server
+workflow:
+  nodes:
+    - id: run
+      type: dypai_database
+      operation: query
+      return: true
+      query: SELECT id, name, price, stock FROM products WHERE name ILIKE '%' || \${input.query} || '%' LIMIT \${input.limit}
+\`\`\`
+
+Rules:
+- A tool endpoint is still a regular endpoint (same trigger, same workflow, same deploy). \`tool: true\` is additive.
+- **\`tool_description\` is critical** — this is the prompt the LLM sees when deciding whether to call your tool. Be specific about *when* to use it and *what it returns*. Vague descriptions cause the agent to skip useful tools or misuse them.
+- Define a **tight \`input\` JSON Schema** with \`description\` on each field. The LLM uses the schema to fabricate arguments; sloppy schemas = sloppy calls.
+- Auth mode: usually \`api_key\` (the agent node calls server-side) or \`jwt\` if you need \${current_user_id} in the tool. **Never \`public\`** for tools that write data.
+
+### Step 2 — wire the tool into an \`agent\` node (in another endpoint's YAML)
+
+In the YAML you reference tools **by name**, not by UUID. The codec converts names ↔ UUIDs automatically on push/pull.
+
+\`\`\`yaml
+workflow:
+  nodes:
+    - id: chat
+      type: agent
+      provider: openai                        # or anthropic | google
+      model: gpt-4o
+      credential: openai-prod                 # must exist — use get_app_credentials
+      system_prompt: |
+        You are a shop assistant. Use the search-products tool when the user
+        asks about availability, prices, or categories.
+      input: \${input.message}
+      tools: [search-products, send-email]    # ← by name. Codec resolves to UUIDs on push.
+      max_iterations: 5
+      return: true
+\`\`\`
+
+**COMMON TRAP**: the raw engine parameter is called \`tool_ids\` (takes UUIDs). If you read \`dypai/node-catalog.json\` you'll see that name. In YAML you MUST write \`tools: [names]\` — if you write \`tool_ids: ["my-endpoint"]\` the codec does NOT transform it, the engine receives "my-endpoint" as a literal UUID, and you fail silently in production. Always \`tools: [names]\` in YAML.
+
+### Step 3 — discover existing tools
+
+\`dypai_pull\` returns an \`overview.endpoints.tool_endpoints\` array listing every endpoint marked \`tool: true\` with its \`tool_description\`. Check that list before writing a new tool — you might already have it.
+
+### Validation
+
+\`dypai_validate\` has rule \`agent_tool_not_found\`: if an \`agent\` node references \`tools: ["foo"]\` and either no endpoint named "foo" exists, or it's not marked \`tool: true\`, validate fails with a fix_hint listing the available tool endpoints. Catches typos before you push.
+
+### Recursion safety
+
+The engine enforces a depth limit (currently 3) on agent→tool→agent chains, plus per-workflow stack tracking. A tool can itself be an agent endpoint, but runaway loops are cut off automatically.
+
 ## Testing & Debugging
 
 - **"Let me run this endpoint and see"** → \`dypai_test_endpoint\`
@@ -255,6 +579,22 @@ When you hit a red flag, replace the JS node. When the JS legitimately does more
 - Do NOT call the API directly with fetch() — always use the SDK
 - Do NOT create auth endpoints — auth is built-in via SDK (dypai.auth.*)
 
+### \`.env\` file — required for the SDK to reach the engine
+The frontend SDK reads the engine URL from an environment variable. \`.env\` is gitignored, so \`manage_frontend(sync)\` does NOT bring it down. **If the project has no \`.env\` after sync (the response sets \`env_file_missing: true\`), you MUST create it** before running or deploying the frontend:
+
+\`\`\`bash
+# Vite / React / Svelte / Vue / etc.
+VITE_DYPAI_URL=https://<project_id>.dypai.app
+VITE_PROJECT_ID=<project_id>
+
+# Next.js (prefix matters — must be NEXT_PUBLIC_ to be readable in the browser)
+NEXT_PUBLIC_DYPAI_URL=https://<project_id>.dypai.app
+\`\`\`
+
+- \`<project_id>\` is the UUID from \`list_projects\` / \`dypai.config.yaml\`.
+- Override the base domain with the \`DYPAI_ENGINE_BASE\` env var (default \`dypai.app\`) only for self-hosted setups.
+- Without \`.env\`, every SDK call fails with a network error / 404 because \`createClient(undefined)\` resolves nowhere. Don't try to debug the code — it's the missing env var.
+
 ## Deploy Frontend
 - \`manage_frontend(operation: deploy, sourceDirectory, project_id)\` — uploads source, returns immediately with build_status=queued.
 - Poll \`manage_frontend(operation: build_status)\` every ~5s until status is "success" or "failure" (typical build: 20-60s).
@@ -276,6 +616,97 @@ When you hit a red flag, replace the JS node. When the JS legitimately does more
 - Placeholders: \${input.<field>}, \${nodes.<node_id>.<field>}, \${current_user_id}, \${current_user_role}.
 - \${current_user_id} / \${current_user_role} only work with jwt auth mode.
 
+## dypai_database — choose between query and mutation
+
+The dypai_database node has TWO operations. Pick the right one and you'll never
+need the others:
+
+### \`operation: query\` — SQL (the power tool, no limits)
+Use for ANY non-trivial read or any complex write. Joins, CTEs, subqueries,
+window functions, FILTER clauses, aggregations, multi-table — all fair game.
+
+\`\`\`yaml
+- id: dashboard
+  type: dypai_database
+  operation: query
+  return: true
+  query: |
+    WITH revenue AS (
+      SELECT SUM(amount) AS total FROM invoices
+      WHERE user_id = \${current_user_id} AND paid_at >= date_trunc('month', NOW())
+    )
+    SELECT
+      (SELECT total FROM revenue) AS revenue,
+      (SELECT COUNT(*) FROM tasks WHERE user_id = \${current_user_id} AND status = 'pending') AS pending_tasks
+\`\`\`
+
+### \`operation: mutation\` — declarative CRUD (no SQL needed)
+Use for trivial single-table writes. The shape decides the operation:
+
+\`\`\`yaml
+# INSERT
+- id: create
+  type: dypai_database
+  operation: mutation
+  return: true
+  table: clients
+  insert: { name: \${input.name}, user_id: \${current_user_id} }
+
+# UPSERT (insert + on_conflict)
+- id: upsert
+  type: dypai_database
+  operation: mutation
+  return: true
+  table: clients
+  insert: { id: \${input.id}, name: \${input.name} }
+  on_conflict: { columns: [id], action: update }
+
+# UPDATE
+- id: update
+  type: dypai_database
+  operation: mutation
+  return: true
+  table: clients
+  update: { name: \${input.name} }
+  where: { id: \${input.id}, user_id: \${current_user_id} }
+
+# DELETE
+- id: delete
+  type: dypai_database
+  operation: mutation
+  table: clients
+  delete: true
+  where: { id: \${input.id}, user_id: \${current_user_id} }
+\`\`\`
+
+### Decision tree (use this — it's all you need)
+- Reading anything → \`operation: query\` (yes, even simple SELECTs — query is fine)
+- Writing one table, no fancy SQL → \`operation: mutation\`
+- Anything else (joins, subqueries, CTEs, multi-table writes) → \`operation: query\`
+
+### Legacy operations (deprecated but still work)
+\`select\`, \`insert\`, \`update\`, \`delete\`, \`upsert\`, \`aggregate\`, \`copy_to\`, \`custom_query\` — old endpoints in production keep running. Don't write new ones with these. \`dypai_validate\` warns if you do.
+
+## SQL Placeholders & Auto-Cast (IMPORTANT)
+Inside SQL queries (operation: query, or mutation values) the engine binds
+placeholders as real Postgres parameters (\$1, \$2…) — NOT string interpolation.
+This is injection-safe and type-safe by construction.
+
+The engine auto-casts based on the value SHAPE:
+  UUID-shaped string  → bound as \$1::uuid       (e.g. \${current_user_id})
+  plain object/array  → bound as \$1::jsonb      (e.g. \${input.metadata})
+  Date instance       → bound as \$1::timestamptz
+  text / int / bool   → bound without cast (Postgres infers from column)
+
+**Write SQL naturally — DO NOT add manual casts**:
+  ✅  WHERE user_id = \${current_user_id}
+  ❌  WHERE user_id = '\${current_user_id}'::uuid       (redundant, validator warns)
+
+  ✅  INSERT INTO events(payload) VALUES (\${input.meta})
+  ❌  INSERT INTO events(payload) VALUES ('\${input.meta}'::jsonb)  (redundant)
+
+The validator (dypai_validate) flags manual casts with rule \`sql_redundant_uuid_cast\`.
+
 ## Common Mistakes
 - Do NOT default to javascript_code — use native nodes (see decision tree above).
 - Do NOT create auth endpoints — auth is built-in via SDK (dypai.auth.*).
@@ -285,6 +716,86 @@ When you hit a red flag, replace the JS node. When the JS legitimately does more
 - Do NOT push without dypai_diff — always preview first.
 - Do NOT look up tables / endpoints remotely when a local dypai/ exists. Use Read/Glob/Grep on the files.
 - Do NOT push just to test a change — use dypai_test_endpoint to run the LOCAL edited version against the engine. Only push when you're satisfied.
+
+## Canonical YAML format (READ CAREFULLY — typical confusion points)
+
+Endpoint YAMLs follow ONE canonical shape. The codec tolerates some legacy aliases for forward-compat, but the canonical form is what you should write. These are the patterns where agents most commonly slip:
+
+### Trigger is TOP-LEVEL, never a node
+\`\`\`yaml
+# ✅ CORRECT
+trigger:
+  http_api:
+    auth_mode: jwt
+workflow:
+  nodes:
+    - id: list
+      type: dypai_database
+      ...
+\`\`\`
+\`\`\`yaml
+# ❌ WRONG — start_trigger is NOT a node anymore
+workflow:
+  nodes:
+    - id: start
+      type: start_trigger     # the codec auto-strips this and warns
+      ...
+\`\`\`
+Trigger options: \`http_api\` / \`webhook\` / \`schedule\` / \`telegram\`. \`auth_mode\` is one of \`jwt\` / \`api_key\` / \`public\`.
+
+### Nodes use \`type\`, not \`node_type\`
+\`\`\`yaml
+- id: insert
+  type: dypai_database          # ✅ canonical
+  return: true                  # ✅ not is_return
+\`\`\`
+The codec accepts \`node_type\` and \`is_return\` for safety, but write the canonical form.
+
+### Edges use \`from/to\`, not \`source/target\`
+\`\`\`yaml
+edges:
+  - { from: a, to: b }                          # ✅ canonical
+  - { from: cond, to: y, source_handle: "true" } # ✅ for branching
+\`\`\`
+
+### Parameters are FLAT inline on the node, not nested
+\`\`\`yaml
+# ✅ CORRECT — params flat on the node
+- id: insert
+  type: dypai_database
+  operation: insert
+  table: orders
+  data: { user_id: \${current_user_id}, qty: \${input.qty} }
+\`\`\`
+\`\`\`yaml
+# ❌ AVOID — only use nested parameters: when a param NAME collides with id/type/return/variable
+- id: insert
+  type: dypai_database
+  parameters:
+    operation: insert
+    table: orders
+\`\`\`
+
+### Multiple return paths are fine
+Mark \`return: true\` on every node that produces a final HTTP response. Workflow execution only reaches one of them per run.
+
+### Agent tools use \`tool:\` + \`tools: [names]\`
+\`\`\`yaml
+# Endpoint exposes itself as a tool:
+name: search-products
+tool: true
+tool_description: "Search the product catalog. Use for availability/prices."
+\`\`\`
+\`\`\`yaml
+# Agent node references tools by NAME (codec resolves to UUIDs on push):
+- id: chat
+  type: agent
+  tools: [search-products, send-email]   # ✅ names
+\`\`\`
+⚠️ The engine param is \`tool_ids\` (UUIDs) but in YAML you write \`tools: [names]\`. Writing \`tool_ids: ["name"]\` in YAML bypasses the codec transform and fails in production. See the "Agent tools" section above for the full pattern.
+
+### When in doubt
+Read \`dypai/endpoints/_example.yaml.disabled\` (auto-shipped on empty projects) — it's a complete tour of every pattern.
 `
 
 // ── MCP Protocol (JSON-RPC over stdio) ──────────────────────────────────────
@@ -306,7 +817,7 @@ async function handleRequest(msg) {
     return makeResponse(id, {
       protocolVersion: "2024-11-05",
       capabilities: { tools: {} },
-      serverInfo: { name: "dypai", version: "1.0.0" },
+      serverInfo: { name: "dypai", version: "1.3.0" },
       instructions: SERVER_INSTRUCTIONS,
     })
   }
@@ -390,8 +901,17 @@ async function handleRequest(msg) {
         content: [{ type: "text", text: typeof result === "string" ? result : JSON.stringify(result, null, 2) }],
       })
     } catch (e) {
+      // Return a structured error so the agent can parse `success`/`error`
+      // consistently with our other "soft failure" responses (validate,
+      // test_endpoint, etc.). Still flag isError=true at the MCP level.
+      const payload = {
+        success: false,
+        error: e.message || String(e),
+        // First few stack frames help debug which file blew up.
+        stack: (e.stack || "").split("\n").slice(0, 4).join("\n"),
+      }
       return makeResponse(id, {
-        content: [{ type: "text", text: `Error: ${e.message}` }],
+        content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
         isError: true,
       })
     }