@dypai-ai/mcp 1.0.9 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dypai-ai/mcp",
-  "version": "1.0.9",
+  "version": "1.1.0",
   "description": "DYPAI MCP Server — AI agent toolkit for building and deploying full-stack apps",
   "type": "module",
   "main": "src/index.js",
@@ -24,5 +24,8 @@
     "type": "git",
     "url": "https://github.com/DYPAI-SOLUTIONS/dypai-mcp"
   },
-  "homepage": "https://dypai.ai"
+  "homepage": "https://dypai.ai",
+  "dependencies": {
+    "yaml": "^2.6.0"
+  }
 }

package/src/index.js

@@ -21,12 +21,34 @@
 
 import { createInterface } from "readline"
 import { checkForUpdates } from "./auto-update.js"
-import { deployTool } from "./tools/deploy.js"
+// manage_frontend consolidates what used to be 5 tools (deploy_frontend, get_frontend_status,
+// 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"
-import { addDomainTool, listDomainsTool, removeDomainTool } from "./tools/domains.js"
-import { frontendStatusTool, buildStatusTool, listDeploymentsTool, getDeploymentLogsTool } from "./tools/status.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.
+// The format works but needs fixtures/auto-rollback/scaffolder + proper docs before being surfaced.
+// File still lives at ./tools/sync/test.js and is re-exported from ./tools/sync/index.js
+// so the implementation is preserved; just not wired into the catalog.
+// dypaiDescribeTool removed from the catalog — its output is now inlined as
+// the `overview` block returned by dypai_pull. One fewer tool, one fewer decision
+// for the agent. The implementation still lives at ./tools/sync/describe.js
+// in case we want to resurrect it as a read-only peek for multi-project flows.
+import { dypaiPullTool, dypaiDiffTool, dypaiPushTool, dypaiValidateTool, dypaiTestEndpointTool } from "./tools/sync/index.js"
+// dypaiCodegenTool is intentionally NOT imported here — codegen runs
+// automatically on dypai_pull / dypai_push / schema-affecting execute_sql.
+// The standalone tool would duplicate that path and could confuse the agent
+// into calling it needlessly. The helper `regenerateTypes` in ./tools/codegen.js
+// is still used internally by those triggers.
+// import { dypaiCodegenTool } from "./tools/codegen.js"
 import { proxyToolCall } from "./tools/proxy.js"
+import { enrichSuccess, enrichError } from "./tools/enrich.js"
+import { maybeRefreshSchemaAfterExecuteSql } from "./tools/sql-side-effects.js"
+import { withProjectContext, invalidateProjectContext } from "./tools/project-context.js"
+// summarizeDypaiTraceResponse (from ./tools/trace-summarize.js) is kept on
+// disk for when dypai_trace is re-enabled, but not imported here.
 
 // ── Self-update ─────────────────────────────────────────────────────────────
 // Throttled (6h) check against the npm registry. If a newer version is
@@ -39,17 +61,21 @@ await checkForUpdates().catch(() => {})
 
 const LOCAL_TOOLS = [
   // ── Frontend & Deploy ─────────────────────────────────────────────────────
-  deployTool,
+  manageFrontendTool,
   scaffoldTool,
-  buildStatusTool,
-  listDeploymentsTool,
-  getDeploymentLogsTool,
   // ── Domains ───────────────────────────────────────────────────────────────
-  addDomainTool,
-  listDomainsTool,
-  removeDomainTool,
+  manageDomainTool,
   // ── Data ──────────────────────────────────────────────────────────────────
   bulkUpsertTool,
+  // ── Git-first source of truth ─────────────────────────────────────────────
+  // dypai_describe was merged into dypai_pull (now returns an `overview` block).
+  dypaiPullTool,
+  dypaiValidateTool,
+  dypaiDiffTool,
+  dypaiPushTool,
+  dypaiTestEndpointTool,
+  // dypaiTestTool (YAML test-suite runner) — hidden until v2. See import comment above.
+  // dypaiCodegenTool hidden — runs automatically on pull/push/DDL.
 ]
 
 const localToolMap = new Map(LOCAL_TOOLS.map(t => [t.name, t]))
@@ -62,15 +88,11 @@ const FALLBACK_REMOTE_TOOLS = [
   { name: "get_project", description: "Get project details.", inputSchema: { type: "object", properties: { project_id: { type: "string" } }, required: ["project_id"] } },
   { name: "create_project", description: "Create a new project (free plan).", inputSchema: { type: "object", properties: { name: { type: "string" } }, required: ["name"] } },
   { name: "execute_sql", description: "Run SQL on the project's database.", inputSchema: { type: "object", properties: { project_id: { type: "string" }, sql: { type: "string" } }, required: ["sql"] } },
-  { name: "get_app_tables", description: "List database tables.", inputSchema: { type: "object", properties: { project_id: { type: "string" } }, required: [] } },
   { name: "create_endpoint", description: "Create an API endpoint.", inputSchema: { type: "object", properties: { project_id: { type: "string" }, name: { type: "string" }, method: { type: "string" }, workflow_code: { type: "object" } }, required: ["name", "method", "workflow_code"] } },
   { name: "update_endpoint", description: "Update an endpoint.", inputSchema: { type: "object", properties: { project_id: { type: "string" }, name: { type: "string" } }, required: ["name"] } },
   { name: "delete_endpoint", description: "Delete an endpoint.", inputSchema: { type: "object", properties: { project_id: { type: "string" }, name: { type: "string" } }, required: ["name"] } },
-  { name: "search_endpoints", description: "Search endpoints.", inputSchema: { type: "object", properties: { project_id: { type: "string" } }, required: [] } },
-  { name: "test_workflow", description: "Test an endpoint.", inputSchema: { type: "object", properties: { project_id: { type: "string" }, endpoint_name: { type: "string" } }, required: ["endpoint_name"] } },
   { name: "manage_users", description: "Manage auth users.", inputSchema: { type: "object", properties: { project_id: { type: "string" }, operation: { type: "string" } }, required: ["operation"] } },
   { name: "manage_roles", description: "Manage roles.", inputSchema: { type: "object", properties: { project_id: { type: "string" }, operation: { type: "string" } }, required: ["operation"] } },
-  { name: "get_auth_users", description: "List users.", inputSchema: { type: "object", properties: { project_id: { type: "string" } }, required: [] } },
   { name: "list_buckets", description: "List storage buckets.", inputSchema: { type: "object", properties: { project_id: { type: "string" } }, required: [] } },
   { name: "search_docs", description: "Search documentation.", inputSchema: { type: "object", properties: { query: { type: "string" } }, required: ["query"] } },
   { name: "search_workflow_templates", description: "Search workflow templates.", inputSchema: { type: "object", properties: { query: { type: "string" } }, required: ["query"] } },
@@ -87,27 +109,43 @@ const REMOTE_TOOLS = [
   { 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 ──────────────────────────────────────────────────────────────
-  { name: "execute_sql", description: "Executes any SQL query on the project database (PostgreSQL). Supports SELECT, INSERT, UPDATE, DELETE, CREATE TABLE, ALTER TABLE, DROP TABLE. Platform schemas (system, auth, storage) are read-only for security.", inputSchema: { type: "object", properties: { project_id: { type: "string" }, sql: { type: "string", description: "SQL query to execute" } }, required: ["sql"] } },
-  { name: "get_app_tables", description: "Query the project's database tables. Returns all tables with their columns, types, constraints, and indexes.", inputSchema: { type: "object", properties: { project_id: { type: "string" } }, required: [] } },
+  // Note: `get_app_tables` is intentionally NOT exposed — dypai/schema.sql already
+  // caches table info locally (auto-refreshed on DDL). For ad-hoc introspection,
+  // use execute_sql against information_schema.
+  { name: "execute_sql", description: "Executes any SQL query on the project database (PostgreSQL). Supports SELECT, INSERT, UPDATE, DELETE, CREATE TABLE, ALTER TABLE, DROP TABLE. Platform schemas (system, auth, storage) are read-only for security. DDL on public.* auto-refreshes dypai/schema.sql.", inputSchema: { type: "object", properties: { project_id: { type: "string" }, sql: { type: "string", description: "SQL query to execute" } }, required: ["sql"] } },
 
   // ── API Endpoints ─────────────────────────────────────────────────────────
-  { name: "create_endpoint", description: "Creates an endpoint as a workflow (nodes + edges). The workflow defines what the endpoint does: database queries, HTTP calls, AI agents, logic, transformations, etc.", inputSchema: { type: "object", properties: { project_id: { type: "string" }, name: { type: "string", description: "URL-friendly name (e.g. 'get-products')" }, method: { type: "string", description: "GET, POST, PUT, DELETE, PATCH" }, description: { type: "string" }, workflow_code: { type: "object", description: "Workflow definition with nodes and edges" } }, required: ["name", "method", "workflow_code"] } },
-  { name: "update_endpoint", description: "Updates fields of an existing endpoint. Only fields in 'updates' are modified — everything else stays the same.", inputSchema: { type: "object", properties: { project_id: { type: "string" }, name: { type: "string" }, workflow_code: { type: "object" }, description: { type: "string" }, method: { type: "string" } }, required: ["name"] } },
-  { name: "delete_endpoint", description: "Permanently deletes an endpoint. Irreversible operation.", inputSchema: { type: "object", properties: { project_id: { type: "string" }, name: { type: "string" } }, required: ["name"] } },
-  { name: "search_endpoints", description: "Search endpoints or retrieve the full detail of one by ID. Returns name, method, description, group, workflow code.", inputSchema: { type: "object", properties: { project_id: { type: "string" }, query: { type: "string" }, endpoint_id: { type: "string" } }, required: [] } },
-  { name: "test_workflow", description: "Test an endpoint's workflow with sample input data. Returns the execution result including node outputs and errors. Great for debugging.", inputSchema: { type: "object", properties: { project_id: { type: "string" }, endpoint_name: { type: "string" }, input: { type: "object", description: "Test input data" }, method: { type: "string" } }, required: ["endpoint_name"] } },
-  { name: "edit_workflow", description: "Edit a workflow using find-and-replace on the JSON text. Best for quick fixes — SQL queries, parameters, strings. Works like a code editor. USE THIS FOR MOST EDITS instead of rewriting the entire workflow.", inputSchema: { type: "object", properties: { project_id: { type: "string" }, endpoint_id: { type: "string" }, old_string: { type: "string", description: "Text to find in the workflow JSON" }, new_string: { type: "string", description: "Replacement text" } }, required: ["endpoint_id", "old_string", "new_string"] } },
-  { name: "add_node", description: "Add a new node to an existing workflow and connect it. Specify the node type, parameters, and where to insert it.", inputSchema: { type: "object", properties: { project_id: { type: "string" }, endpoint_id: { type: "string" }, node_type: { type: "string" }, parameters: { type: "object" }, after_node: { type: "string", description: "ID of the node to insert after" } }, required: ["endpoint_id", "node_type"] } },
-  { name: "remove_node", description: "Remove a node from a workflow. By default, reconnects surrounding nodes to maintain the flow.", inputSchema: { type: "object", properties: { project_id: { type: "string" }, endpoint_id: { type: "string" }, node_id: { type: "string" } }, required: ["endpoint_id", "node_id"] } },
-  { name: "get_endpoint_versions", description: "List version history for an endpoint. Shows previous workflow snapshots that can be restored with rollback_endpoint.", inputSchema: { type: "object", properties: { project_id: { type: "string" }, endpoint_name: { type: "string" } }, required: ["endpoint_name"] } },
-  { name: "rollback_endpoint", description: "Rollback an endpoint's workflow to a previous version. Use get_endpoint_versions first to see available versions.", inputSchema: { type: "object", properties: { project_id: { type: "string" }, endpoint_name: { type: "string" }, version_id: { type: "string" } }, required: ["endpoint_name", "version_id"] } },
-  { name: "search_nodes", description: "Discover and query available nodes for building workflows. Shows what building blocks exist: HTTP requests, database, email, Stripe, Telegram, AI agent, etc.", inputSchema: { type: "object", properties: { query: { type: "string", description: "What you need (e.g. 'send email', 'stripe', 'database')" } }, required: ["query"] } },
-  { name: "manage_endpoint_groups", description: "Organize endpoints into groups (folders). Operations: create, list, update, delete.", inputSchema: { type: "object", properties: { project_id: { type: "string" }, operation: { type: "string", description: "create, list, update, delete" } }, required: ["operation"] } },
+  // Full CRUD + exploration goes through the git-first flow:
+  //   dypai_pull (materialize + overview) → edit files → dypai_diff → dypai_push
+  // search_endpoints removed on purpose: having both files and a remote search confuses the agent.
+  // Only kept: test_workflow (runtime debug), versions/rollback (emergency).
+  // Note: test_workflow is NOT exposed — use dypai_test_endpoint (local tool).
+  // It reads the local YAML, inlines *_file refs, and tests the EDITED version
+  // against the engine. test_workflow still exists on the remote and is called
+  // internally by dypai_test_endpoint — just not user-facing.
+  //
+  // dypai_trace is temporarily hidden until the engine implements debug-on-error
+  // (buffer events in memory, flush to Redis only when an execution fails).
+  // Without that, production executions have no per-node trace — only the
+  // listing + top-level error_message would be available, which is confusing
+  // given the tool promises full traces. Re-enable once the engine captures
+  // traces for real prod runs, not just test_workflow debug calls.
+  // { name: "dypai_trace", description: "READ HISTORICAL executions — does NOT run anything. Use ONLY when a user reports a bug that already happened and you need to inspect the real failure. Two modes: execution_id → fetch specific past trace; endpoint_id + only_failed:true → list recent real failures.", inputSchema: { type: "object", properties: { project_id: { type: "string" }, execution_id: { type: "string" }, endpoint_id: { type: "string" }, only_failed: { type: "boolean", default: false }, limit: { type: "integer", default: 5 }, full: { type: "boolean", default: false } }, required: [] } },
+  { name: "get_endpoint_versions", description: "Dual-mode remote version history for an endpoint. Captures EVERY write to the remote (dashboard, push, API), so it sees changes your local git doesn't.\n\n- Without `version_number`: lists versions (metadata only — version, description, created_at).\n- With `version_number`: returns that version's FULL workflow_code. You can then restore it manually by writing it back via git (preferred) or by calling the remote directly.\n\nTypical recovery flow when a teammate edited in the dashboard and broke something:\n  1) get_endpoint_versions(endpoint_name: 'x') → pick the last good version\n  2) get_endpoint_versions(endpoint_name: 'x', version_number: N) → inspect the workflow_code\n  3) dypai_pull → write back to local YAML, review with git, dypai_push\n\nFor 'what did I change locally' use `git log dypai/endpoints/<name>.yaml` instead.", inputSchema: { type: "object", properties: { project_id: { type: "string" }, endpoint_name: { type: "string", description: "Endpoint name as declared in its YAML (e.g. 'create-order')." }, version_number: { type: "integer", description: "Optional. When provided, returns that version's full workflow_code instead of the list." }, limit: { type: "integer", description: "List mode only. Max versions (default 10, max 50).", default: 10 }, since: { type: "string", description: "List mode only. ISO date." }, before: { type: "string", description: "List mode only. ISO date." } }, required: ["endpoint_name"] } },
+  // rollback_endpoint is intentionally hidden — git-first makes it redundant.
+  // For reverting an endpoint: use get_endpoint_versions(version_number: N) to
+  // fetch the old workflow_code, write it back to dypai/endpoints/<name>.yaml
+  // (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"] } },
 
   // ── Auth & Users ──────────────────────────────────────────────────────────
-  { name: "manage_users", description: "Manage authenticated users. Operations: create, delete, ban, unban, update_role, set_password.", inputSchema: { type: "object", properties: { project_id: { type: "string" }, operation: { type: "string", description: "create, delete, ban, unban, update_role, set_password" } }, required: ["operation"] } },
+  // 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"] } },
-  { name: "get_auth_users", description: "List authenticated users with their email, role, status, and last login.", inputSchema: { type: "object", properties: { project_id: { type: "string" } }, required: [] } },
 
   // ── 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: [] } },
@@ -120,64 +158,144 @@ const REMOTE_TOOLS = [
 
 // ── Server Instructions ──────────────────────────────────────────────────────
 
-const SERVER_INSTRUCTIONS = `You are building full-stack applications on the DYPAI platform. You handle backend (endpoints, database, auth) AND frontend (SDK integration, UI code).
+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).
 
 ## Getting Started
-1. Call list_projects() to find your project_id
-2. Use get_app_tables and search_endpoints to understand existing state
-3. BEFORE implementing any feature, call search_docs with the topic (e.g. "auth", "upload files", "real-time") to get the correct SDK patterns
-4. Build backend first (tables + endpoints), then frontend
-
-## Build Backend
-1. Create tables with execute_sql (check get_app_tables first to avoid duplicates)
-2. Create endpoints with create_endpoint using workflow_code
-3. Test with test_workflow immediately after creating/updating
-4. Use search_workflow_templates to find ready-made workflow patterns
-5. Use search_project_templates when the user wants a starter app or template-based project
-6. Use search_nodes to discover available node types
-7. Use search_docs when unsure about patterns
+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), regenerates TS types under src/dypai/, 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.
+
+## 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.
+
+1. Tables: execute_sql for DDL (CREATE TABLE, ALTER TABLE). schema.sql refreshes automatically.
+2. Endpoints:
+   a. dypai_pull (once, to initialize ./dypai/)
+   b. Create or edit YAML files in dypai/endpoints/<group>/<name>.yaml with Edit/Write
+   c. Long SQL / prompts / code go in dypai/sql/ dypai/prompts/ dypai/code/ and are referenced from the YAML via query_file, system_prompt_file, code_file
+   d. dypai_validate to catch placeholder / schema / credential / node-param errors BEFORE pushing
+   e. dypai_diff to preview what will change (read-only)
+   f. dypai_push to apply
+3. Test each change with dypai_test_endpoint (runs the LOCAL YAML — tests the edit before pushing).
+
+## 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.
+
+Typical flow when adding a step to a workflow:
+1. Decide the CONCEPT (DB insert? HTTP call? shape fields? branching?).
+2. Scan \`dypai/node-catalog.json\` for a native node that covers that concept.
+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.
+
+**Before adding a javascript_code node, pause and check:** is there a native node in \`dypai/node-catalog.json\` that already expresses this concept?
+
+| If the step is... | Default to this native node | Only JS if... |
+|---|---|---|
+| SELECT / INSERT / UPDATE / DELETE on a table | \`dypai_database\` | You need tight branching between multiple queries in a single atomic block |
+| Reshaping / renaming / merging fields | \`set_fields\` | The transformation is arbitrary business logic (scoring, ranking, pricing rules) |
+| if / else / early return | \`logic\` | Branching is mixed with other custom logic that would fragment oddly |
+| Iterate an array | \`foreach\` (or \`filter\`, \`merge\`) | You need stateful accumulation or complex reduce across items |
+| Call an external HTTP API | \`http_request\` | You're orchestrating multiple API calls with interdependent logic |
+| LLM prompt / tool use | \`agent\` | Always use agent — it handles memory, tools, streaming, retries |
+| Stripe / Telegram / Slack / Resend / WhatsApp / Google Sheets / etc. | The dedicated integration node | Provider not covered and you fall back to \`http_request\` |
+| Upload / download / delete files | \`dypai_storage\` | Never — use the node |
+| Dates / crypto / delays | \`datetime\`, \`crypto\`, \`wait_delay\` | Never — use the node |
+
+**When javascript_code is the right choice (legitimate cases):**
+- Domain-specific scoring, pricing or validation with many branches that \`logic\` alone would fragment
+- Stateful aggregation over an array that \`foreach\` can't express cleanly
+- One-off glue between 2-3 sources that would otherwise need 5+ native nodes just to express intermediate shapes
+- Any business logic where writing a clear \`async function main(data, ctx)\` is genuinely simpler than chaining nodes
+
+**Red flags that you're picking JS by reflex (not by fit):**
+- The JS body is basically one \`await db.query(...)\` → use \`dypai_database\`
+- The JS body is \`return { a: data.x, b: nodes.prev.y }\` → use \`set_fields\`
+- The JS body is one \`await http.post(...)\` → use \`http_request\`
+- The JS body is \`if (x > 100) return {...} else return {...}\` → use \`logic\`
+
+When you hit a red flag, replace the JS node. When the JS legitimately does more than one concern glued together, keep it — that's what it's for.
+
+## Realtime (WebSocket subscriptions)
+- Declarative policies live in dypai/realtime.yaml. Tables NOT declared there → deny-by-default for subscribers.
+- To enable live updates on a table: add an entry with a subscribe_filter expression (same \${current_user_id} placeholders you use in endpoints).
+- Row mutations auto-fire notifications to subscribers that match the filter.
+- Client-side: \`dypai.realtime.subscribe(table, { filter, event }, callback)\`.
+- See search_docs "realtime" for patterns.
+
+## Testing & Debugging
+
+- **"Let me run this endpoint and see"** → \`dypai_test_endpoint\`
+  The only test tool surfaced today. Pass endpoint name + input. Reads the LOCAL YAML (even unpushed edits), inlines *_file refs, runs against the engine with fabricated input. For jwt endpoints pass as_user UUID to impersonate. Iterate tightly: edit → test → fix → test → push.
+
+- A YAML-based regression-test suite runner is planned but not yet surfaced — when writing a new endpoint, verify it with dypai_test_endpoint after each edit and document edge cases in the commit message / PR for now.
+
+- Historical production traces are not inspectable via MCP yet — direct the user to the dashboard if they need to debug a specific past execution.
+
+## Where things live
+- dypai/endpoints/foo.yaml — endpoint definition (top-level, no group)
+- dypai/endpoints/Admin/foo.yaml — endpoint in group "Admin" (subfolder = group)
+- dypai/sql/foo.sql — SQL extracted when > 500 chars
+- dypai/prompts/foo.md — agent system prompts extracted when > 800 chars
+- dypai/code/foo.js — JavaScript/Python extracted when > 500 chars (escape hatch only)
+- dypai/schema.sql — DDL of public.* tables (read BEFORE writing SQL; auto-refreshed on DDL)
+- dypai/node-catalog.json — every node_type with its input/output schemas
+- dypai/realtime.yaml — realtime subscription policies (optional)
+- dypai/tests/*.test.yaml — reserved for the v2 suite runner; leave empty for now
+- dypai/dypai.config.yaml — project identity (don't hand-edit)
+- dypai/.dypai/ — local cache (gitignored)
+- src/dypai/ — auto-generated TS types (Database + typed api wrapper). Auto-refreshed on pull/push/DDL.
+- All *_file paths inside YAML are relative to dypai/ root (not to the YAML file).
 
 ## Build Frontend
 - SDK client is already configured at src/lib/dypai.ts — just import it:
   import { dypai } from './lib/dypai'
+- Types: \`import { api } from '@/dypai'\` for typed endpoint calls with autocomplete.
 - API calls: dypai.api.get(name), dypai.api.post(name, body), dypai.api.put(), dypai.api.delete()
 - Auth: dypai.auth.signInWithPassword(), signUp(), signOut(), getSession()
+- Realtime: dypai.realtime.subscribe(table, opts, callback)
 - Files: dypai.api.upload(name, file) — always upload from browser
 - Every method returns { data, error } — never throws
 - 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.*)
 
 ## Deploy Frontend
-- Use deploy_frontend tool with the project's source directory
-- The tool pushes source, then waits for the build to finish (~1-2 min)
-- If the build succeeds, the response includes the live URL
-- If the build FAILS, the response includes the error logs — read them carefully, fix the code, and redeploy
-- Common build failures: missing dependencies (add to package.json), TypeScript errors, import path issues
-- Supports: Vite, React, Next.js, Astro, SvelteKit, Nuxt, Remix, Angular, Vinext, CRA, and more
-- Framework is auto-detected from package.json — correct build config is set automatically
-- If build times out (>2 min), use get_build_status / get_deployment_logs to check manually
+- \`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).
+- On failure: \`manage_frontend(operation: list_deployments)\` → pick the failed deployment_id → \`manage_frontend(operation: logs, deployment_id)\`.
+- Supports: Vite, React, Next.js, Astro, SvelteKit, Nuxt, Remix, Angular, CRA, and more (auto-detected).
 
 ## Import Data
 - Use bulk_upsert to import CSV or JSON files into database tables
 - Great for seeding initial data (products, categories, config)
 
 ## Custom Domains
-- Use add_domain to connect a user's own domain
-- The user configures a CNAME record at their registrar
-- SSL is automatic via Cloudflare
+- manage_domain(operation: list | add | remove | verify) — single tool for all domain ops.
+  - add returns the CNAME the user must configure at their registrar. SSL provisions automatically once DNS propagates.
+  - verify forces an on-demand DNS/SSL re-check (normally the platform polls in the background).
 
 ## Endpoint Rules
-- Auth modes: jwt (default, for users), api_key (server-to-server), public (read-only public data)
-- NEVER use public for endpoints that write data
-- Placeholders: \${input.<field>}, \${nodes.<node_id>.<field>}, \${current_user_id}
-- \${current_user_id} only works with jwt auth mode
-- Always test endpoints after creating them
+- Auth modes: jwt (default — for user-authenticated requests), api_key (server-to-server), public (read-only, anonymous).
+- NEVER use public for endpoints that write data.
+- 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.
 
 ## Common Mistakes
-- Do NOT create auth endpoints — auth is built-in via SDK (dypai.auth.*)
-- Do NOT use fetch() directly — use the SDK (dypai.api.*)
-- Do NOT assume endpoints exist — check with search_endpoints first
-- Do NOT skip testing — always test_workflow after create/update
+- 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.*).
+- Do NOT use fetch() in frontend — use the SDK (dypai.api.*).
+- Do NOT edit endpoints without running dypai_pull first (you'd overwrite unknown state).
+- Do NOT skip dypai_validate — it catches schema/placeholder/credential errors before push.
+- 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.
 `
 
 // ── MCP Protocol (JSON-RPC over stdio) ──────────────────────────────────────
@@ -223,10 +341,57 @@ async function handleRequest(msg) {
       // Local tool — execute directly
       if (localToolMap.has(name)) {
         result = await localToolMap.get(name).execute(args || {})
+        // dypai_pull may have (re)written dypai.config.yaml — refresh the
+        // cached project_id so subsequent remote calls use the new value.
+        if (name === "dypai_pull") invalidateProjectContext()
       }
-      // Remote tool — proxy to MCP server
+      // Remote tool — proxy to MCP server (with thin enrichment layer)
       else if (REMOTE_TOOLS.some(t => t.name === name)) {
-        result = await proxyToolCall(name, args || {})
+        try {
+          // Auto-inject project_id from dypai.config.yaml if the tool
+          // declares it and the caller didn't pass one. Keeps the agent
+          // from having to repeat itself and keeps metrics properly tagged.
+          const toolDef = REMOTE_TOOLS.find(t => t.name === name)
+          let finalArgs = withProjectContext(toolDef, args || {})
+
+          // Resolve endpoint_name → endpoint_id for tools that accept only the UUID.
+          // Keeps the agent-facing API name-based while the remote keeps its
+          // UUID-based contract. Best-effort: if the lookup fails we still pass
+          // through whatever the caller provided so they see the remote's error.
+          if (name === "get_endpoint_versions" && finalArgs?.endpoint_name && !finalArgs?.endpoint_id) {
+            try {
+              const pid = finalArgs.project_id
+              const sqlArgs = { project_id: pid, sql: `SELECT id FROM system.endpoints WHERE name = '${String(finalArgs.endpoint_name).replace(/'/g, "''")}' LIMIT 1` }
+              const row = await proxyToolCall("execute_sql", sqlArgs)
+              const rows = Array.isArray(row?.rows) ? row.rows : (Array.isArray(row) ? row : null)
+              const id = rows?.[0]?.id
+              if (id) {
+                finalArgs = { ...finalArgs, endpoint_id: id }
+                delete finalArgs.endpoint_name
+              }
+            } catch { /* fall through, let the remote complain */ }
+          }
+
+          const raw = await proxyToolCall(name, finalArgs)
+          result = enrichSuccess(name, raw)
+
+          // Side effect: if the user ran schema-changing DDL via execute_sql,
+          // re-dump dypai/schema.sql so the validator stays in sync.
+          if (name === "execute_sql") {
+            const refresh = await maybeRefreshSchemaAfterExecuteSql(args || {}, result)
+            if (refresh.refreshed) {
+              result = { ...(typeof result === "object" ? result : { data: result }), schema_refreshed: true, schema_path: refresh.path }
+            } else if (refresh.error) {
+              result = { ...(typeof result === "object" ? result : { data: result }), schema_refresh_warning: refresh.error }
+            }
+          }
+
+          // Note: test_workflow is no longer agent-facing (wrapped by
+          // dypai_test_endpoint). dypai_trace is temporarily hidden until
+          // the engine captures debug traces for real production executions.
+        } catch (e) {
+          throw enrichError(name, e)
+        }
       }
       else {
         return makeError(id, -32601, `Unknown tool: ${name}`)