@ateam-ai/mcp 0.4.16 → 0.4.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ateam-ai/mcp",
-  "version": "0.4.16",
+  "version": "0.4.18",
   "mcpName": "io.github.ariekogan/ateam-mcp",
   "description": "A-Team MCP Server — build, validate, and deploy multi-agent solutions from any AI environment",
   "type": "module",

package/src/api.js

@@ -393,7 +393,7 @@ function headers(sessionId) {
 /**
  * Format an API error into a user-friendly message with actionable hints.
  */
-function formatError(method, path, status, body) {
+function formatError(method, path, status, body, baseUrl) {
   const hints = {
     400: "Bad request — see the error details above for what to fix.",
     401: "Your API key may be invalid or expired. Get a valid key at https://mcp.ateam-ai.com/get-api-key then call ateam_auth(api_key: \"your_key\").",
@@ -434,7 +434,12 @@ function formatError(method, path, status, body) {
   const hint = hints[status] || "";
   const detail = typeof body === "string" && body.length > 0 && body.length < 2000 ? body : "";
 
-  let msg = `A-Team API error: ${method} ${path} returned ${status}`;
+  // Always show the FULL URL actually hit — ateam-mcp is a PUBLIC MCP with a
+  // configurable base (prod default, dev/self-host overrides), so a bare
+  // "POST /deploy/..." 404 is ambiguous: is the route missing, or did the
+  // request go to the wrong base? The full URL disambiguates instantly.
+  const target = baseUrl ? `${baseUrl}${path}` : path;
+  let msg = `A-Team API error: ${method} ${target} returned ${status}`;
   if (detail) msg += ` — ${detail}`;
   if (hint) msg += `\nHint: ${hint}`;
 
@@ -486,7 +491,7 @@ async function request(method, path, body, sessionId, opts = {}) {
 
       if (!res.ok) {
         const text = await res.text().catch(() => "");
-        throw new Error(formatError(method, path, res.status, text));
+        throw new Error(formatError(method, path, res.status, text, baseUrl));
       }
 
       return res.json();

package/src/tools.js

@@ -74,6 +74,88 @@ async function pollDeployJob(jobId, sid, { label = 'deploy', maxMs = 15 * 60_000
   };
 }
 
+// ─── Widget health verification ────────────────────────────────────
+//
+// A skill/solution that declares UI plugins (ui_plugins[]) can silently ship
+// a NON-RENDERING widget: the connector may not expose the plugin via
+// ui.listPlugins, the manifest may lack a render block, or the declared id may
+// be mistyped. Core's live catalog (GET /api/ui-plugins) reflects what Core
+// ACTUALLY discovered — it calls each connector's ui.listPlugins live — so we
+// cross-check every declared plugin against it AND assert a usable render
+// block. Callers fold the report into deploy/verify output so a broken widget
+// is surfaced at deploy time, not discovered later as a blank panel.
+//
+// Returns null when the solution declares no widgets (nothing to check), else
+// { ok, checked, healthy, plugins[], issues[]?, hint? }.
+function _widgetHasRender(r) {
+  if (!r || typeof r !== "object" || !r.mode) return false;
+  const hasIframe = !!(r.iframeUrl || r.iframe?.iframeUrl);
+  const hasRn = !!(r.reactNative?.component);
+  if (r.mode === "iframe") return hasIframe;
+  if (r.mode === "react-native") return hasRn;
+  if (r.mode === "adaptive") return hasIframe || hasRn;
+  return true; // unknown mode — don't false-positive on a custom render
+}
+
+async function verifyWidgetHealth(solution_id, sid) {
+  // 1. Declared plugins — solution.ui_plugins[]
+  let declared = [];
+  try {
+    const def = await get(`/deploy/solutions/${solution_id}/definition`, sid);
+    const sol = def?.solution || def?.definition || def || {};
+    declared = Array.isArray(sol.ui_plugins) ? sol.ui_plugins : [];
+  } catch (e) {
+    return { ok: false, error: `widget health: could not read solution definition — ${e.message}` };
+  }
+  if (declared.length === 0) return null; // no widgets → nothing to verify
+
+  // 2. Live catalog — what Core actually discovered/serves right now
+  const apiKey = getCredentials(sid)?.apiKey;
+  let live = [];
+  try {
+    const coreUrl = process.env.ADAS_CORE_URL || "http://adas-backend:4000";
+    const res = await fetch(`${coreUrl}/api/ui-plugins`, {
+      headers: { "x-api-key": apiKey, "X-ADAS-SERVICE": "ateam-mcp.verify_widget_health" },
+      signal: AbortSignal.timeout(15_000),
+    });
+    const data = await res.json().catch(() => ({}));
+    live = Array.isArray(data?.plugins) ? data.plugins : [];
+  } catch (e) {
+    return { ok: false, error: `widget health: could not read live plugin catalog — ${e.message}` };
+  }
+  const liveById = new Map(live.map((p) => [p?.id, p]));
+
+  // 3. Cross-check each declared plugin against live discovery + render block
+  const plugins = declared.map((d) => {
+    const id = typeof d === "string" ? d : d?.id;
+    const problems = [];
+    const found = id ? liveById.get(id) : null;
+    if (!id) {
+      problems.push("ui_plugins entry has no id");
+    } else if (!found) {
+      problems.push("not discovered by Core — the owning connector's ui.listPlugins does not return this id (check the plugin id, and that the connector is ui_capable + deployed)");
+    }
+    const render = found?.render || (typeof d === "object" ? d?.render : null);
+    const render_ok = _widgetHasRender(render);
+    if (found && !render_ok) {
+      problems.push("no usable render block — need render.mode + iframeUrl (iframe) or reactNative.component (RN)");
+    }
+    return { id: id || "(missing)", discovered: !!found, render_ok, problems };
+  });
+
+  const unhealthy = plugins.filter((p) => p.problems.length);
+  return {
+    ok: unhealthy.length === 0,
+    checked: plugins.length,
+    healthy: plugins.length - unhealthy.length,
+    plugins,
+    ...(unhealthy.length && {
+      issues: unhealthy.map((p) => `${p.id}: ${p.problems.join("; ")}`),
+      hint: "A declared widget Core doesn't discover will render as a blank panel. If the connector was scaffolded by ateam_create_connector, confirm the plugin's ui-dist/<plugin>/manifest.json deployed; for a hardcoded-list connector, add the plugin to its ui.listPlugins/getPlugin. Re-check with ateam_get_widget_catalog.",
+    }),
+  };
+}
+
 // ─── Dotted-field resolver ─────────────────────────────────────────
 //
 // Given an object and a dotted field name, walk down the path creating
@@ -1780,80 +1862,151 @@ function _scaffoldConnectorFiles({ connectorId, displayName, uiCapable }) {
   const safeName = displayName || connectorId;
   const files = [];
 
-  // server.js — minimal stdio MCP server with one tool stub + ui handlers if ui_capable
+  // server.js — raw-stdio JSON-RPC 2.0 MCP server. This mirrors the PROVEN
+  // pattern deployed connectors use (e.g. nutrition-mcp): tools declared in
+  // tools/list, dispatched in tools/call, no MCP SDK. UI plugins are exposed
+  // as the `ui.listPlugins` / `ui.getPlugin` TOOLS, which is how Core detects a
+  // UI-capable connector (it checks the tools/list output) and fetches each
+  // manifest. Those two tools read the connector's OWN ui-dist/<plugin>/
+  // manifest.json at call time — drop a plugin's files and it renders, with no
+  // server.js edit needed.
   const serverJs = `#!/usr/bin/env node
-// ${connectorId} — stdio MCP server. Generated by ateam_create_connector.
+// ${connectorId} — stdio JSON-RPC 2.0 MCP server. Generated by ateam_create_connector.
 //
-// Fill in the tool implementations below. The MCP scaffolding
-// (server setup, tool registration, error handling, stdio transport)
-// is template-provided. You write the integration logic.
+// Fill in your real tools below (see TOOLS + the tools/call dispatch). The
+// JSON-RPC framing, actor isolation, stdio loop${uiCapable ? ", and ui-dist plugin discovery" : ""} are template-provided.
+${uiCapable ? `
+import { readdirSync, readFileSync, existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+` : ""}
+const PROTOCOL_VERSION = "2024-11-05";
+
+// ── JSON-RPC helpers ──
+function ok(id, result) { return { jsonrpc: "2.0", id, result }; }
+function err(id, code, message) { return { jsonrpc: "2.0", id, error: { code, message } }; }
+function toText(data) { return { content: [{ type: "text", text: JSON.stringify(data) }] }; }
+
+// ── Actor isolation ── every data tool is per-actor. Core injects _adas_actor
+// into the call args; refuse to operate without it (prevents cross-actor leaks).
+function getActorId(args) {
+  const id = args?._adas_actor;
+  if (!id) throw new Error("${connectorId}: no actor context — _adas_actor missing.");
+  return id;
+}
+${uiCapable ? `
+// ── UI plugin discovery ── read ui-dist/<plugin>/manifest.json at call time so
+// a newly-uploaded plugin appears with no server.js change. The manifest is the
+// single source of truth for the render block (ateam_create_plugin writes it).
+const __dir = dirname(fileURLToPath(import.meta.url));
+const UI_DIST = join(__dir, "ui-dist");
+
+function discoverPlugins() {
+  const out = [];
+  if (!existsSync(UI_DIST)) return out;
+  for (const entry of readdirSync(UI_DIST, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const mp = join(UI_DIST, entry.name, "manifest.json");
+    if (!existsSync(mp)) continue;
+    try {
+      const m = JSON.parse(readFileSync(mp, "utf8"));
+      out.push({ ...m, id: m.id || entry.name });
+    } catch (e) {
+      console.error(\`[${connectorId}] bad manifest for \${entry.name}: \${e.message}\`);
+    }
+  }
+  return out;
+}
+` : ""}
+// ── Tool definitions ── Core reads this list. A tool named "ui.listPlugins"
+// is how Core knows this connector is UI-capable.
+function toolSchemas() {
+  const actor = { _adas_actor: { type: "string" }, _adas_tenant: { type: "string" } };
+  return [
+    {
+      name: "${connectorId}.echo",
+      description: "Echo back the input. Replace with your real tools.",
+      inputSchema: { type: "object", properties: { message: { type: "string" }, ...actor }, required: ["message"] },
+    },${uiCapable ? `
+    { name: "ui.listPlugins", description: "List available UI plugins.", inputSchema: { type: "object", properties: {} } },
+    { name: "ui.getPlugin", description: "Get a UI plugin manifest by id.", inputSchema: { type: "object", properties: { id: { type: "string" } }, required: ["id"] } },` : ""}
+  ];
+}
 
-import { Server } from "@modelcontextprotocol/sdk/server/index.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+// ── Request handler ──
+async function handle(req) {
+  const { id, method, params } = req || {};
 
-const server = new Server(
-  { name: "${connectorId}", version: "1.0.0" },
-  { capabilities: { tools: {}${uiCapable ? ', ui: {}' : ''} } },
-);
+  if (method === "initialize") {
+    return ok(id, { protocolVersion: PROTOCOL_VERSION, serverInfo: { name: "${connectorId}", version: "1.0.0" }, capabilities: { tools: {} } });
+  }
+  if (method === "tools/list") return ok(id, { tools: toolSchemas() });
 
-// ── Tool definitions ────────────────────────────────────────────────
-const TOOLS = [
-  {
-    name: "${connectorId}.echo",
-    description: "Echo back the input. Replace with your real tools.",
-    inputSchema: {
-      type: "object",
-      properties: { message: { type: "string" } },
-      required: ["message"],
-    },
-  },
-];
+  if (method === "tools/call") {
+    const name = params?.name;
+    const args = params?.arguments || {};
+    try {
+${uiCapable ? `      // ── UI registry plumbing (no actor required) ──
+      if (name === "ui.listPlugins") {
+        const plugins = discoverPlugins().map((p) => ({
+          id: p.id, name: p.name || p.id, version: p.version || "1.0.0",
+          description: p.description || "",
+          ...(p.uiActions ? { uiActions: p.uiActions } : {}),
+          ...(p.surface ? { surface: p.surface } : {}),
+        }));
+        return ok(id, toText({ plugins }));
+      }
+      if (name === "ui.getPlugin") {
+        const p = discoverPlugins().find((pl) => pl.id === args.id);
+        if (!p) return ok(id, toText({ error: \`Plugin \${args.id} not found\` }));
+        return ok(id, toText(p)); // manifest already carries the render block
+      }
+` : ""}      // ── Your tools (actor-scoped) ──
+      const actorId = getActorId(args);
+      if (name === "${connectorId}.echo") {
+        return ok(id, toText({ ok: true, echo: args.message, actor: actorId }));
+      }
+      return err(id, -32601, \`Unknown tool: \${name}\`);
+    } catch (e) {
+      return err(id, -32000, String(e?.message || e));
+    }
+  }
 
-server.setRequestHandler({ method: "tools/list" }, async () => ({ tools: TOOLS }));
+  if (typeof method === "string" && method.startsWith("notifications/")) return null;
+  return err(id, -32601, \`Unknown method: \${method}\`);
+}
 
-server.setRequestHandler({ method: "tools/call" }, async (req) => {
-  const { name, arguments: args } = req.params;
-  switch (name) {
-    case "${connectorId}.echo":
-      return { content: [{ type: "text", text: \`Echo: \${args.message}\` }] };
-    default:
-      throw new Error(\`Unknown tool: \${name}\`);
+// ── stdio loop ──
+let buf = "";
+process.stdin.setEncoding("utf8");
+process.stdin.on("data", async (chunk) => {
+  buf += chunk;
+  const lines = buf.split("\\n");
+  buf = lines.pop() || "";
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    let msg;
+    try { msg = JSON.parse(trimmed); } catch { continue; }
+    const resp = await handle(msg);
+    if (resp) process.stdout.write(JSON.stringify(resp) + "\\n");
   }
 });
-${uiCapable ? `
-// ── UI plugin handlers (ui_capable connector) ──────────────────────
-server.setRequestHandler({ method: "ui.listPlugins" }, async () => ({
-  plugins: [
-    // List your plugins here. Plugin source files live in
-    // plugins/<plugin-name>/ (RN) and ui-dist/<plugin-name>/ (iframe).
-    // Plugin manifests are auto-discovered at deploy time per Phase 5
-    // of the strip — no need to repeat them here unless you want overrides.
-  ],
-}));
-
-server.setRequestHandler({ method: "ui.getPlugin" }, async (req) => {
-  const { id } = req.params;
-  // Return plugin manifest by id. Auto-discovery covers the default case.
-  return { ok: false, error: \`Plugin \${id} not found\` };
-});
-` : ''}
-// ── Boot ────────────────────────────────────────────────────────────
-const transport = new StdioServerTransport();
-await server.connect(transport);
-console.error("[${connectorId}] connected via stdio");
+process.stdin.on("end", () => process.exit(0));
+
+console.error("[${connectorId}] Server started (stdio)");
 `;
   files.push({ path: "server.js", content: serverJs });
 
-  // package.json
+  // package.json — raw stdio needs ZERO npm deps (node built-ins only), so
+  // deploys skip npm install entirely.
   const pkg = {
     name: connectorId,
     version: "1.0.0",
     type: "module",
     description: `${safeName} — A-Team MCP connector`,
     main: "server.js",
-    dependencies: {
-      "@modelcontextprotocol/sdk": "^1.0.0",
-    },
+    dependencies: {},
   };
   files.push({ path: "package.json", content: JSON.stringify(pkg, null, 2) + "\n" });
 
@@ -1865,21 +2018,21 @@ ${uiCapable ? "UI-capable: yes" : ""}
 
 ## Adding tools
 
-Edit \`server.js\`. Add entries to the \`TOOLS\` array, then add a
-matching case in the \`tools/call\` handler.
+Edit \`server.js\`: add an entry to \`toolSchemas()\` and a matching branch in
+the \`tools/call\` dispatch. Data tools are per-actor — call \`getActorId(args)\`.
 
 ## Adding UI plugins (ui_capable connectors)
 
-Drop iframe plugins under \`ui-dist/<plugin-name>/index.html\` and/or
-React Native plugins under \`plugins/<plugin-name>/index.tsx\`.
-Phase 5 of the strip auto-discovers them at deploy — no manifest
-declaration needed unless you want overrides (drop a
-\`manifest.json\` next to the source).
+Use \`ateam_create_plugin\` (or drop the files yourself): iframe plugins go under
+\`ui-dist/<plugin-name>/index.html\` with a \`ui-dist/<plugin-name>/manifest.json\`
+(RN under \`plugins/<plugin-name>/index.tsx\`). This connector's
+\`ui.listPlugins\` / \`ui.getPlugin\` read those manifests at call time, so a new
+plugin renders with NO server.js edit.
 
 ## Deploy
 
-Use \`ateam_upload_connector\` to push the latest source to Core
-without a full skill redeploy.
+Use \`ateam_upload_connector\` to push the latest source to Core without a full
+skill redeploy.
 `;
   files.push({ path: "README.md", content: readme });
 
@@ -2028,10 +2181,10 @@ export default {
   // ui.listPlugins is generated from ui-dist/<plugin>/manifest.json pick it up
   // automatically, and for connectors with a HARDCODED plugin list (e.g.
   // personal-assistant-ui-mcp) copy this render block into their ui.getPlugin.
-  const mode = k === "iframe" ? "iframe" : k === "rn" ? "react-native" : "adaptive";
+  const mode = kind === "iframe" ? "iframe" : kind === "rn" ? "react-native" : "adaptive";
   const render = { mode };
-  if (k === "iframe" || k === "adaptive") render.iframeUrl = `/ui/${pluginName}/index.html`;
-  if (k === "rn" || k === "adaptive") render.reactNative = { component: pluginName };
+  if (kind === "iframe" || kind === "adaptive") render.iframeUrl = `/ui/${pluginName}/index.html`;
+  if (kind === "rn" || kind === "adaptive") render.reactNative = { component: pluginName };
   const prettyName = pluginName.replace(/-/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
   files.push({
     path: `ui-dist/${pluginName}/manifest.json`,
@@ -2726,6 +2879,17 @@ const handlers = {
       phases.push({ phase: "agent_doc", status: "skipped", reason: err.message });
     }
 
+    // Phase 6: Widget health — if the solution declares UI plugins, verify each
+    // one actually renders (Core discovered it + it has a render block). Catches
+    // the silent "declared but non-rendering" widget at deploy time.
+    let widget_health = null;
+    try {
+      widget_health = await verifyWidgetHealth(solutionId, sid);
+      if (widget_health) {
+        phases.push({ phase: "widget_health", status: widget_health.ok ? "done" : "warn", checked: widget_health.checked });
+      }
+    } catch { /* advisory — never fail a successful deploy on the health check */ }
+
     return {
       ok: true,
       solution_id: solutionId,
@@ -2738,11 +2902,14 @@ const handlers = {
         ...(deploy.auto_expanded_skills?.length > 0 && { auto_expanded: deploy.auto_expanded_skills }),
       },
       health,
+      ...(widget_health && { widget_health }),
       ...(test_result && { test_result }),
       ...(github_result && !github_result.error && !github_result.skipped && { github: github_result }),
       ...(agent_doc_result && !agent_doc_result.error && { agent_doc: agent_doc_result }),
       ...(validation.warnings?.length > 0 && { validation_warnings: validation.warnings }),
-      _status: '✅ Deployed to Core + pushed to main.',
+      _status: widget_health && !widget_health.ok
+        ? `✅ Deployed to Core + pushed to main. ⚠️ ${widget_health.issues?.length || 0} widget(s) not rendering — see widget_health.`
+        : '✅ Deployed to Core + pushed to main.',
       _next: 'Create a checkpoint before making more changes: ateam_github_promote(solution_id)',
     };
   },
@@ -3087,6 +3254,17 @@ const handlers = {
 
     const redeployOk = phases.some(p => p.phase === "redeploy" && p.status === "done");
     const store = isLocal ? "Builder store (local)" : "GitHub";
+
+    // Widget health — if the redeploy landed and the solution declares UI
+    // plugins, verify each renders (Core discovered it + has a render block).
+    let widget_health = null;
+    if (redeployOk) {
+      try {
+        widget_health = await verifyWidgetHealth(solution_id, sid);
+        if (widget_health) phases.push({ phase: "widget_health", status: widget_health.ok ? "done" : "warn", checked: widget_health.checked });
+      } catch { /* advisory — never downgrade a successful patch on the health check */ }
+    }
+
     return {
       ok: true,
       solution_id,
@@ -3096,9 +3274,12 @@ const handlers = {
       patched: patched,
       ...(isNewSkill && { created_skill: skill_id }),
       ...(redeployResult && { redeploy: redeployResult }),
+      ...(widget_health && { widget_health }),
       ...(test_result && { test_result }),
       _status: redeployOk
-        ? `✅ Patched on ${store} + redeployed.`
+        ? (widget_health && !widget_health.ok
+            ? `✅ Patched on ${store} + redeployed. ⚠️ ${widget_health.issues?.length || 0} widget(s) not rendering — see widget_health.`
+            : `✅ Patched on ${store} + redeployed.`)
         : `⚠️ Patched on ${store} ✅ but redeploy timed out. Run: ateam_redeploy(solution_id` + (skill_id ? `, skill_id: "${skill_id}"` : '') + ')',
       _next: isLocal
         ? 'Local edit saved + redeployed. When the tenant connects a GitHub repo, the local state is pushed → GitHub (which then becomes master).'
@@ -3871,9 +4052,14 @@ const handlers = {
       displayName: name || connector_id,
       uiCapable: !!ui_capable,
     });
+    // replace:true — this is a NEW connector: the scaffold IS the complete file
+    // set, and there's nothing to merge against (no GitHub base, nothing
+    // deployed yet). Without it the upload route's merge-protection 409s a
+    // brand-new connector on a repo-less tenant ("no existing base to merge").
+    // Partial uploads (ateam_create_plugin) still merge; a full create replaces.
     const result = await post(
       `/deploy/solutions/${solution_id}/connectors/${connector_id}/upload`,
-      { files },
+      { files, replace: true },
       sid,
       { timeoutMs: 120_000, retries: 1 },
     );
@@ -3915,12 +4101,45 @@ const handlers = {
       sid,
       { timeoutMs: 120_000, retries: 1 },
     );
+
+    // Verify the plugin actually became RENDERABLE — poll Core's live catalog
+    // (which calls the connector's ui.listPlugins) for this plugin id. The
+    // connector restarts on upload, so allow a few seconds to re-scan ui-dist
+    // and re-announce. Turns create_plugin into a VERIFIED result (renders:true
+    // or a concrete reason) instead of a hopeful "files written".
+    const pluginId = `mcp:${connector_id}:${plugin_name}`;
+    let verified = { renders: false, note: "not yet discovered by Core after upload" };
+    try {
+      const apiKey = getCredentials(sid)?.apiKey;
+      const coreUrl = process.env.ADAS_CORE_URL || "http://adas-backend:4000";
+      for (let attempt = 0; attempt < 4; attempt++) {
+        await new Promise((r) => setTimeout(r, attempt === 0 ? 1500 : 2500));
+        const res = await fetch(`${coreUrl}/api/ui-plugins`, {
+          headers: { "x-api-key": apiKey, "X-ADAS-SERVICE": "ateam-mcp.create_plugin_verify" },
+          signal: AbortSignal.timeout(15_000),
+        }).catch(() => null);
+        if (!res || !res.ok) continue;
+        const data = await res.json().catch(() => ({}));
+        const found = (data?.plugins || []).find((p) => p?.id === pluginId);
+        if (found) {
+          verified = _widgetHasRender(found.render)
+            ? { renders: true, render_ok: true, note: "discovered by Core with a valid render block — it will render" }
+            : { renders: false, render_ok: false, note: "discovered, but its manifest has no usable render block (need render.mode + iframeUrl/reactNative)" };
+          break;
+        }
+      }
+      if (!verified.renders && !("render_ok" in verified)) {
+        verified.hint = "Not in Core's live catalog yet. If the connector is lazy (stopped until first call), its plugins only appear once declared in solution ui_plugins[] — declare it, or ensure the connector is ui_capable + connected. Re-check with ateam_get_widget_catalog.";
+      }
+    } catch { /* advisory — never fail the create on the verify probe */ }
+
     return {
       ok: true,
-      plugin_id: `mcp:${connector_id}:${plugin_name}`,
+      plugin_id: pluginId,
       kind: k,
       files_created: files.map(f => f.path),
       upload_result: result,
+      verified,
       next_steps: [
         k === "rn" || k === "adaptive"
           ? `Edit plugins/${plugin_name}/index.tsx — fill in the Component body.`
@@ -3928,8 +4147,9 @@ const handlers = {
         k === "iframe" || k === "adaptive"
           ? `Edit ui-dist/${plugin_name}/index.html — replace the placeholder UI.`
           : null,
-        `A manifest.json (with the required render block) was written to ui-dist/${plugin_name}/manifest.json.`,
-        `⚠️ REQUIRED to render: the plugin must appear in this connector's ui.listPlugins / ui.getPlugin output WITH that render block. Dropping the files alone does NOT register it. If the connector has a HARDCODED plugin list (e.g. personal-assistant-ui-mcp: UI_PLUGINS[] + PLUGIN_MANIFESTS{} in server.js), add this plugin there — copy the render block from the manifest.json. Verify with ateam_get_solution(solution_id, "connectors_health") or ateam_get_widget_catalog after deploy.`,
+        `A manifest.json (with the render block) was written to ui-dist/${plugin_name}/manifest.json — this is the source of truth Core reads.`,
+        `If this connector was scaffolded by ateam_create_connector, its ui.listPlugins / ui.getPlugin read ui-dist/*/manifest.json automatically — nothing else to register, it renders on the next deploy. ⚠️ ONLY a connector with a HARDCODED plugin list (legacy, e.g. personal-assistant-ui-mcp: UI_PLUGINS[] + PLUGIN_MANIFESTS{} in server.js) needs this plugin added there by hand — copy the render block from manifest.json.`,
+        `Verify with ateam_get_widget_catalog (or ateam_get_solution(solution_id, "connectors_health")) after deploy.`,
         `Then declare it at solution level (ui_plugins[]) so a skill can open it via sys.focusUiPlugin — see ateam_get_spec(topic:"widgets").`,
       ].filter(Boolean),
     };
@@ -3995,7 +4215,7 @@ const handlers = {
     const deployedCount = result.deployed ?? (result.ok ? (skill_id ? 1 : (result.skills?.filter(s => s.ok !== false).length || 0)) : 0);
     const totalCount = result.total ?? (deployedCount + failedCount);
 
-    return {
+    const out = {
       ok: result.ok,
       solution_id,
       ...(skill_id && { skill_id }),
@@ -4017,6 +4237,19 @@ const handlers = {
             ? `Re-deploy failed: ${result.error}${result.hint ? ` — ${result.hint}` : ''}`
             : `Re-deploy had ${failedCount} failure(s). Check skills array or call the underlying endpoint with verbose:true.`),
     };
+    // If the deploy landed and the solution declares widgets, verify each one
+    // actually renders (discovered by Core + has a render block). A silently
+    // non-rendering widget is a common, hard-to-notice failure — surface it here.
+    if (result.ok) {
+      try {
+        const wh = await verifyWidgetHealth(solution_id, sid);
+        if (wh) {
+          out.widget_health = wh;
+          if (!wh.ok) out.message += ` ⚠️ ${wh.issues?.length || 0} widget issue(s) — see widget_health.`;
+        }
+      } catch { /* health check is advisory — never fail the deploy on it */ }
+    }
+    return out;
   },
 
   // ─── Master Key Bulk Tools ───────────────────────────────────────────