@ateam-ai/mcp 0.3.55 → 0.3.57

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ateam-ai/mcp",
-  "version": "0.3.55",
+  "version": "0.3.57",
   "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/tools.js

@@ -131,15 +131,15 @@ export const tools = [
     name: "ateam_get_spec",
     core: true,
     description:
-      "Get the A-Team specification — schemas, validation rules, system tools, agent guides, and templates. Start here after bootstrap to understand how to build skills and solutions. Use 'section' to get just one part of the skill spec (much smaller than the full spec). Use 'search' to find specific fields or concepts across the spec.\n\nWhen designing a persona that orchestrates logic via run_python_script (the Python-as-orchestrator pattern), also fetch topic='python_helpers' — that returns the adas.* helper namespace reference. Skills designed without knowing about adas.* produce 5-10x larger / brittler scripts.",
+      "Get the A-Team specification — schemas, validation rules, system tools, agent guides, and templates. Start here after bootstrap to understand how to build skills and solutions. Use 'section' to get just one part of the skill spec (much smaller than the full spec). Use 'search' to find specific fields or concepts across the spec.\n\nWhen designing a persona that orchestrates logic via run_python_script (the Python-as-orchestrator pattern), also fetch topic='python_helpers' — that returns the adas.* helper namespace reference. Skills designed without knowing about adas.* produce 5-10x larger / brittler scripts.\n\nWhen wiring widgets (UI plugins) into a solution, fetch topic='widgets' — that returns the widget spec (catalog model, how_to_use blocks, opener_call shape, persona phrasing rules, binding semantics) so you can declare `ui_plugins` correctly. For the live catalog of widgets actually available in a deployed tenant, use ateam_get_widget_catalog instead.",
     inputSchema: {
       type: "object",
       properties: {
         topic: {
           type: "string",
-          enum: ["overview", "skill", "solution", "enums", "connector-multi-user", "python_helpers"],
+          enum: ["overview", "skill", "solution", "enums", "connector-multi-user", "python_helpers", "widgets"],
           description:
-            "What to fetch: 'overview' = API overview + endpoints, 'skill' = full skill spec, 'solution' = full solution spec, 'enums' = all enum values, 'connector-multi-user' = multi-user connector guide, 'python_helpers' = adas.* helper namespace for run_python_script orchestration (read this when designing personas that read state → call tools → checkpoint → status; without it, scripts hand-roll JSON parsing and tool delegation = 5-10x larger and brittler).",
+            "What to fetch: 'overview' = API overview + endpoints, 'skill' = full skill spec, 'solution' = full solution spec, 'enums' = all enum values, 'connector-multi-user' = multi-user connector guide, 'python_helpers' = adas.* helper namespace for run_python_script orchestration (read this when designing personas that read state → call tools → checkpoint → status; without it, scripts hand-roll JSON parsing and tool delegation = 5-10x larger and brittler), 'widgets' = widget (UI plugin) spec: catalog model, how_to_use block shape (solution.json snippet + opener_call + persona_phrasing + binding_notes), and rules for declaring ui_plugins. Pair with ateam_get_widget_catalog for the live per-tenant inventory.",
         },
         section: {
           type: "string",
@@ -673,18 +673,16 @@ export const tools = [
     name: "ateam_upload_connector",
     core: true,
     description:
-      "Upload connector code to Core and restart — WITHOUT redeploying skills. " +
-      "Use this to update connector source code (server.js, UI assets, plugins) quickly. " +
-      "Set github=true to pull files from the solution's GitHub repo, or pass files directly. " +
-      "Much faster than ateam_build_and_run for connector-only changes.\n\n" +
-      "⚠️ REPLACE, NOT MERGE: this overwrites the ENTIRE connector directory. Any file you do not " +
-      "include is DELETED — omit ui-dist/ and the UI plugins 404 with {\"error\":\"Not found\"}; omit " +
-      "src/ and the connector won't start. When passing `files`, send the WHOLE connector (every " +
-      "source file AND every ui-dist asset), not just what you changed. (node_modules survives only " +
-      "because npm install re-runs on restart — that is NOT a merge.)\n" +
-      "⚠️ github=true reads the `main` branch, NOT `dev`. A change that's only on dev will deploy " +
-      "STALE. Either promote first (ateam_github_promote dev→main) then github=true, or pass `files` " +
-      "directly for a dev-only deploy.",
+      "Upload connector code to Core and restart — WITHOUT redeploying skills.\n\n" +
+      "MERGES with the GitHub state at `ref` by default (default ref: 'dev'). Sending a partial file set ONLY overlays those files — the rest of the connector is preserved from GitHub. To fully replace the connector dir (historical behavior), pass replace:true.\n\n" +
+      "Modes:\n" +
+      "  • github:true (no files)        — deploy the GitHub state at `ref` as-is.\n" +
+      "  • github:true + files:[]        — GitHub state at `ref` as BASE, your files overlay on top (incoming wins).\n" +
+      "  • files:[] (no github)          — default MERGE with GitHub state at `ref`. Refuses if no GitHub base exists (no silent nuke).\n" +
+      "  • files:[] + replace:true       — full replace. Wipes connector dir + writes only the provided files. Use deliberately.\n\n" +
+      "Common traps this design prevents:\n" +
+      "  • Pre-fix bug (2026-06-06): sending just ui-dist HTML wiped server.js + node_modules — connector broke until a full re-upload. Now: those files merge with the GitHub base.\n" +
+      "  • Pre-fix bug: github:true silently read from `main` even when patches were on `dev`. Now: defaults to dev; pass ref:'main' to opt into the legacy path.",
     inputSchema: {
       type: "object",
       properties: {
@@ -698,7 +696,11 @@ export const tools = [
         },
         github: {
           type: "boolean",
-          description: "If true, pull the FULL connector from GitHub and replace the deployed dir. Reads the `main` branch (NOT dev) — promote dev→main first or it deploys stale code. Default: false.",
+          description: "If true, pull connector files from GitHub repo at `ref`. Default: false. Combine with files:[] to use GitHub as the base and overlay your files.",
+        },
+        ref: {
+          type: "string",
+          description: "GitHub branch to read from for the BASE state. Default: 'dev' (matches ateam_github_patch). Pass 'main' to read from production. Pre-2026-06-05 callers that relied on the silent-main default must pass ref:'main' explicitly.",
         },
         files: {
           type: "array",
@@ -710,7 +712,11 @@ export const tools = [
             },
             required: ["path", "content"],
           },
-          description: "Files to upload. Alternative to github=true. REPLACES the whole connector dir — include EVERY file (all source + all ui-dist assets), not just the ones you changed; any file omitted here is deleted from the deployment.",
+          description: "Files to upload. By default merges with the GitHub state at `ref`. Set replace:true to wipe the connector dir and write only these files.",
+        },
+        replace: {
+          type: "boolean",
+          description: "Opt into FULL REPLACE: wipe the connector dir and write only the provided `files`. Default: false (= merge with GitHub state at `ref`). Use with intent — sending an incomplete file set with replace:true will break the connector.",
         },
       },
       required: ["solution_id", "connector_id"],
@@ -828,8 +834,7 @@ export const tools = [
     name: "ateam_upload_connector_files",
     core: false,
     description:
-      "Upload source files for a connector's MCP server. Use this INSTEAD of mcp_store in ateam_build_and_run when the source code is too large to inline. Upload files first, then build_and_run without mcp_store. (Advanced.)\n\n" +
-      "⚠️ STAGES ONLY — these files are saved for your NEXT solution deploy; they do NOT update the running connector (the response says \"staged for next deploy\"). To push connector code to the LIVE runtime and restart it immediately, use ateam_upload_connector (which replaces the whole connector dir).",
+      "Upload source files for a connector's MCP server. Use this INSTEAD of mcp_store in ateam_build_and_run when the source code is too large to inline. Upload files first, then build_and_run without mcp_store. (Advanced.)",
     inputSchema: {
       type: "object",
       properties: {
@@ -988,6 +993,45 @@ export const tools = [
       required: ["job_id"],
     },
   },
+  {
+    name: "ateam_get_widget_catalog",
+    core: true,
+    description:
+      "Get the live catalog of widgets (UI plugins) available in this tenant's solution. Returns platform-bundled + solution-bundled + skill-declared widgets, each with a paste-ready how_to_use block (solution.json snippet + opener_call + persona_phrasing + binding_notes).\n\n" +
+      "Use this when wiring widgets into a skill or solution — the how_to_use block is designed to be copied verbatim into the solution.json ui_plugins[] entry and into the persona's opener phrasing, so you don't have to hand-roll either. The catalog reflects what is actually deployed in the tenant right now, not the abstract spec (for the spec itself, use ateam_get_spec topic='widgets').\n\n" +
+      "Origins:\n" +
+      "  • 'platform' = widgets bundled with the platform (always available).\n" +
+      "  • 'solution' = widgets bundled with this tenant's solution.\n" +
+      "  • 'skill' = widgets declared by a specific skill in the solution.\n\n" +
+      "Auth: forwards your authed api_key to Core (no master-secret involvement). Tenant scope is pinned by the key itself.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        solution_id: {
+          type: "string",
+          description: "Optional. The solution to query. Defaults to the tenant's current solution.",
+        },
+        origin: {
+          type: "string",
+          enum: ["all", "platform", "solution", "skill"],
+          description:
+            "Optional. Filter by widget origin. 'all' (default) returns everything. 'platform' = platform-bundled only. 'solution' = solution-bundled only. 'skill' = skill-declared only.",
+        },
+        include_unused: {
+          type: "boolean",
+          description:
+            "Optional. If true, includes widgets that are available but not currently referenced by any skill or ui_plugins entry. Default false (only widgets actually wired into the solution).",
+        },
+        format: {
+          type: "string",
+          enum: ["summary", "full"],
+          description:
+            "Optional. 'full' (default) returns each widget with its paste-ready how_to_use block (solution.json snippet, opener_call, persona_phrasing, binding_notes). 'summary' returns just id/name/origin/description for a quick overview.",
+        },
+      },
+      required: [],
+    },
+  },
   {
     name: "ateam_test_abort",
     core: true,
@@ -1507,6 +1551,7 @@ const SPEC_PATHS = {
   enums: "/spec/enums",
   "connector-multi-user": "/spec/multi-user-connector",
   python_helpers: "/spec/python_helpers",
+  widgets: "/spec/widgets",
 };
 
 const EXAMPLE_PATHS = {
@@ -1549,6 +1594,7 @@ const TENANT_TOOLS = new Set([
   "ateam_test_status",
   "ateam_test_abort",
   "ateam_get_chain",
+  "ateam_get_widget_catalog",
   "ateam_get_connector_source",
   "ateam_get_metrics",
   "ateam_diff",
@@ -3092,6 +3138,84 @@ const handlers = {
     return data;
   },
 
+  ateam_get_widget_catalog: async ({ origin, format }, sid) => {
+    // Wraps Core's existing GET /api/ui-plugins (merged tenant plugin list)
+    // and enriches each entry with the documentation/how-to-use layer.
+    // Filtering by origin and the summary/full format projection happen
+    // client-side here — Core just returns the raw merged plugins[].
+    const creds = getCredentials(sid);
+    const apiKey = creds?.apiKey;
+    if (!apiKey) throw new Error("No api_key in session — call ateam_auth(api_key) first.");
+    const coreUrl = process.env.ADAS_CORE_URL || "http://adas-backend:4000";
+    const res = await fetch(`${coreUrl}/api/ui-plugins`, {
+      method: "GET",
+      headers: { "x-api-key": apiKey, "X-ADAS-SERVICE": "ateam-mcp.get_widget_catalog" },
+      signal: AbortSignal.timeout(15_000),
+    });
+    const text = await res.text();
+    let data;
+    try { data = JSON.parse(text); } catch { data = { ok: false, error: text.slice(0, 400) }; }
+    if (!res.ok) {
+      throw new Error(`Core /api/ui-plugins returned ${res.status}: ${data.error || JSON.stringify(data).slice(0, 200)}`);
+    }
+
+    // Project each plugin into the catalog shape with how_to_use guidance.
+    const plugins = Array.isArray(data?.plugins) ? data.plugins : [];
+    const wantSummary = format === "summary";
+    const filterOrigin = origin && origin !== "all" ? origin : null;
+
+    const widgets = plugins.map((p) => {
+      const id = p?.id || "";
+      const shortId = id.split(":").pop() || id;
+      // origin classification: platform vs solution vs skill
+      const src = p?._source || "";
+      const inferredOrigin = src === "mcp_introspection" ? "platform"
+        : src === "skill_declared" ? "skill"
+        : "solution";
+      const opener = Array.isArray(p?.capabilities?.commands) && p.capabilities.commands.length > 0
+        ? `ui.${shortId}.${p.capabilities.commands[0].name || "open"}({ /* args per input_schema */ })`
+        : `sys.focusUiPlugin({ plugin_id: "${id}" })`;
+      const entry = {
+        id,
+        name: p?.name,
+        version: p?.version,
+        description: p?.description,
+        type: p?.type || "ui",
+        origin: inferredOrigin,
+        owned_by_connector: p?._connector_id,
+        render: p?.render,
+        surface: p?.surface,
+        capabilities: p?.capabilities,
+        channels: p?.channels,
+        commands: p?.capabilities?.commands || p?.commands || [],
+        uiActions: p?.uiActions,
+      };
+      if (!wantSummary) {
+        entry.how_to_use = {
+          solution_json_snippet: { id, name: p?.name, version: p?.version, render: p?.render },
+          opener_call: opener,
+          persona_phrasing: `When the user wants to view ${(p?.description || p?.name || shortId).toString().toLowerCase()}, call ${opener.split("(")[0]}.`,
+          binding_notes: {
+            commands_input_schemas: (p?.capabilities?.commands || []).map(c => ({ command: c.name, schema: c.input_schema })),
+            deeplink_template: p?.uiActions?.deeplink || null,
+            view_entity_kinds: p?.uiActions?.intents?.view_entity?.entity_kinds || null,
+            host_auto_routes_intents: Object.keys(p?.uiActions?.intents || {}),
+          },
+        };
+      }
+      return entry;
+    });
+
+    const filtered = filterOrigin ? widgets.filter(w => w.origin === filterOrigin) : widgets;
+    const counts = {
+      total: filtered.length,
+      platform: filtered.filter(w => w.origin === "platform").length,
+      solution: filtered.filter(w => w.origin === "solution").length,
+      skill: filtered.filter(w => w.origin === "skill").length,
+    };
+    return { ok: true, generated_at: new Date().toISOString(), counts, widgets: filtered };
+  },
+
   ateam_test_abort: async ({ solution_id, skill_id, job_id }, sid) =>
     del(`/deploy/solutions/${solution_id}/skills/${skill_id}/test/${job_id}`, sid),
 
@@ -3249,10 +3373,15 @@ const handlers = {
   ateam_delete_connector: async ({ solution_id, connector_id }, sid) =>
     del(`/deploy/solutions/${solution_id}/connectors/${connector_id}`, sid),
 
-  ateam_upload_connector: async ({ solution_id, connector_id, github, files }, sid) =>
+  ateam_upload_connector: async ({ solution_id, connector_id, github, files, ref, replace }, sid) =>
     post(
       `/deploy/solutions/${solution_id}/connectors/${connector_id}/upload`,
-      { github, files },
+      {
+        github,
+        files,
+        ...(ref ? { ref } : {}),
+        ...(replace === true ? { replace: true } : {}),
+      },
       sid,
       { timeoutMs: 300_000, retries: 1 },
     ),