@ateam-ai/mcp 0.3.48 → 0.3.50

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ateam-ai/mcp",
-  "version": "0.3.48",
+  "version": "0.3.50",
   "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

@@ -188,22 +188,29 @@ export const tools = [
     name: "ateam_build_and_run",
     core: true,
     description:
-      "Build and deploy a governed AI Team solution in one step. ⚠️ HEAVIEST OPERATION (60-180s): validates solution+skills → deploys all connectors+skills to A-Team Core (regenerates MCP servers) → health-checks → optionally runs a warm test → auto-pushes to GitHub. AUTO-DETECTS GitHub repo: if you omit mcp_store and a repo exists, connector code is pulled from GitHub automatically. First deploy requires mcp_store. After that, write files via ateam_github_write, then just call build_and_run without mcp_store. For small changes to an already-deployed solution, prefer ateam_patch (faster, incremental). Requires authentication.",
+      "DEPLOY THE CURRENT MAIN BRANCH TO A-TEAM CORE. ⚠️ HEAVIEST OPERATION (60-180s): validates solution+skills → deploys all connectors+skills to Core (regenerates MCP servers) → health-checks → optionally runs a warm test → auto-pushes to GitHub.\n\n" +
+      "🌳 DEV/PROD WORKFLOW:\n" +
+      "  1. Edit files → ateam_github_patch (writes to `dev` branch by default)\n" +
+      "  2. (Optional) Preview what's about to ship → ateam_github_diff\n" +
+      "  3. Ship dev → main → ateam_github_promote (merges + auto-tags `prod-YYYY-MM-DD-NNN`)\n" +
+      "  4. Deploy main to Core → ateam_build_and_run\n\n" +
+      "This tool ALWAYS deploys the `main` branch — there is no `ref` parameter. To deploy in-progress dev work, first promote it.\n\n" +
+      "AUTO-DETECTS GitHub repo: if you omit mcp_store and a repo exists, connector code is pulled from main automatically. First deploy requires mcp_store. After that, edit via ateam_github_patch + promote, then build_and_run. For small changes prefer ateam_patch (faster, incremental). Requires authentication.",
     inputSchema: {
       type: "object",
       properties: {
         solution_id: {
           type: "string",
-          description: "The solution ID. Use this INSTEAD of passing the full solution object — the solution definition is auto-pulled from GitHub. Required if solution object is omitted.",
+          description: "The solution ID. Use this INSTEAD of passing the full solution object — the solution definition is auto-pulled from main. Required if solution object is omitted.",
         },
         solution: {
           type: "object",
-          description: "Full solution definition. Required on first deploy. After first deploy, just pass solution_id instead — everything is auto-pulled from GitHub.",
+          description: "Full solution definition. Required on first deploy. After first deploy, just pass solution_id instead — everything is auto-pulled from GitHub main.",
         },
         skills: {
           type: "array",
           items: { type: "object" },
-          description: "Optional after first deploy: skill definitions. If omitted, auto-pulled from GitHub repo (skills/{id}/skill.json).",
+          description: "Optional after first deploy: skill definitions. If omitted, auto-pulled from main (skills/{id}/skill.json).",
         },
         connectors: {
           type: "array",
@@ -216,7 +223,7 @@ export const tools = [
         },
         github: {
           type: "boolean",
-          description: "Optional: if true, pull connector source code from the solution's GitHub repo. AUTO-DETECTED: if you omit both mcp_store and github, the system checks if a repo exists and pulls from it automatically. You rarely need to set this explicitly.",
+          description: "Optional: if true, pull connector source code from main. AUTO-DETECTED: if you omit both mcp_store and github, the system checks if a repo exists and pulls from main automatically.",
         },
         test_message: {
           type: "string",
@@ -264,6 +271,62 @@ export const tools = [
       required: ["solution_id", "skill_id", "message"],
     },
   },
+  {
+    name: "ateam_test_notification",
+    core: true,
+    description:
+      "Fire a REAL notification at an existing actor in a deployed solution — for end-to-end testing of the system-initiated notification path (telegram/push/app channels + reply routing + engagement-flip).\n\n" +
+      "Unlike ateam_test_skill (synthetic test actor with no channels) and ateam_conversation (user-initiated thread), this calls the /api/internal/notify-user path that PCM and other sibling services use — so the actor's real enabled channels actually receive the message.\n\n" +
+      "Use for:\n" +
+      "  • Routing-hook tests (does user's next reply route to the right skill given reply_handler?)\n" +
+      "  • Engagement-flip tests (does the receiver-skill's tool call flip engaged:true on the right notification?)\n" +
+      "  • Channel fan-out smoke (does telegram/push/app actually receive it?)\n\n" +
+      "⚠️ SAFETY:\n" +
+      "  • The text is prefixed with [TEST] in the actual notification — visible to the user, anti-phishing.\n" +
+      "  • Rate-limited: 10 calls/min per session.\n" +
+      "  • Every call is audited (caller, tenant, actor, content hash) regardless of outcome.\n" +
+      "  • actor_id is scoped to your tenant — cross-tenant targeting is rejected by Core.\n" +
+      "  • reply_handler is passed through unchanged (Core handles TTL). v2 will add a tenant allowlist + context schema validation; until then, only set reply_handler against skills you trust to receive arbitrary context.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        solution_id: {
+          type: "string",
+          description: "The solution ID (required for tenant scoping + audit context).",
+        },
+        actor_id: {
+          type: "string",
+          description: "Target actor ID in your tenant (e.g. 'usr_arie_admin_0001'). Must exist; Core rejects if not found in your tenant.",
+        },
+        content: {
+          type: "string",
+          description: "Notification text. Will be sent to all of the actor's enabled channels, prefixed with [TEST] for the recipient.",
+        },
+        urgency: {
+          type: "string",
+          enum: ["low", "normal", "high"],
+          description: "Notification urgency. Default 'normal'.",
+        },
+        source: {
+          type: "string",
+          description: "Audit label for message.source. Default 'ateam-test'.",
+        },
+        metadata: {
+          type: "object",
+          description: "Optional metadata merged into message.metadata. Useful for correlation IDs.",
+        },
+        reply_handler: {
+          type: "object",
+          description: "OPTIONAL — install a routing hook so the user's next reply goes to a specific skill with injected context. Shape: { skill: 'skill_id', context: { ...arbitrary } }. Common contexts: dialogueId, observationId, proposalId, candidateSpecs, patternId, mode.\n\n⚠️ This semantically hijacks the user's next reply. Only use against skills designed to receive notification replies (e.g. 'ui-companion', 'pcm-companion'). v2 will enforce a tenant allowlist.",
+          properties: {
+            skill: { type: "string", description: "Skill ID to route the next reply to." },
+            context: { type: "object", description: "Object injected into the receiving job's triggerContext." },
+          },
+        },
+      },
+      required: ["solution_id", "actor_id", "content"],
+    },
+  },
   {
     name: "ateam_conversation",
     core: true,
@@ -1219,14 +1282,35 @@ export const tools = [
     name: "ateam_github_diff",
     core: true,
     description:
-      "Compare two branches. Default base=main, head=dev — shows what's about to ship if you call ateam_github_promote(). " +
-      "Returns the list of commits and files that would land on main.",
+      "PRE-FLIGHT BEFORE PROMOTE. Compares `dev` (head) vs `main` (base) by default — shows exactly which commits and files are about to ship if you call ateam_github_promote() next.\n\n" +
+      "Use this when you want to:\n" +
+      "  • Review changes before promoting to prod\n" +
+      "  • See if dev is ahead of main at all (returns ahead_by: 0 if nothing to promote)\n" +
+      "  • Inspect arbitrary branch/tag/commit comparisons (override base/head)",
     inputSchema: {
       type: "object",
       properties: {
         solution_id: { type: "string", description: "The solution ID" },
-        base: { type: "string", description: "Base branch (the target). Default: 'main'.", default: "main" },
-        head: { type: "string", description: "Head branch (the source). Default: 'dev'.", default: "dev" },
+        base: { type: "string", description: "Base branch/tag/sha (the target — what you're comparing TO). Default: 'main'.", default: "main" },
+        head: { type: "string", description: "Head branch/tag/sha (the source — what you're comparing FROM). Default: 'dev'.", default: "dev" },
+      },
+      required: ["solution_id"],
+    },
+  },
+  {
+    name: "ateam_verify_consistency",
+    core: true,
+    description:
+      "Check that the Builder filesystem state and GitHub state are in sync for a solution. Read-only probe — does NOT trigger a deploy.\n\n" +
+      "Returns:\n" +
+      "  • ok: true + drifts: [] if everything matches\n" +
+      "  • ok: false + drifts: [{path, kind}] listing files that differ (kinds: fs_missing, gh_missing, content_differs)\n\n" +
+      "Drift can creep in when GitHub writes happen but Builder FS doesn't get the mirror update (network blip, container restart mid-write). Boot sync heals most of it on next backend restart; this tool surfaces drift earlier.\n\n" +
+      "Run after a series of ateam_github_patch calls to confirm the Builder backend is consistent with GitHub before you ateam_build_and_run.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        solution_id: { type: "string", description: "The solution ID to verify" },
       },
       required: ["solution_id"],
     },
@@ -1411,6 +1495,7 @@ const TENANT_TOOLS = new Set([
   "ateam_get_execution_logs",
   "ateam_conversation",
   "ateam_test_skill",
+  "ateam_test_notification",
   "ateam_test_pipeline",
   "ateam_test_voice",
   "ateam_test_status",
@@ -2723,6 +2808,108 @@ const handlers = {
     return post(`/deploy/solutions/${solution_id}/skills/${skill_id}/test`, body, sid, { timeoutMs });
   },
 
+  ateam_test_notification: async ({ solution_id, actor_id, content, urgency, source, metadata, reply_handler }, sid) => {
+    if (!solution_id) throw new Error("solution_id required");
+    if (!actor_id) throw new Error("actor_id required");
+    if (!content || typeof content !== "string") throw new Error("content required (string)");
+
+    // Rate limit: 10 calls / minute / session. In-memory; bounded leak fine
+    // for a test tool. Survives until process restart, which is acceptable
+    // (the bound is per-session, not per-tenant).
+    const RATE_LIMIT = 10;
+    const RATE_WINDOW_MS = 60_000;
+    if (!globalThis.__notifyRateLimit) globalThis.__notifyRateLimit = new Map();
+    const bucket = globalThis.__notifyRateLimit;
+    const now = Date.now();
+    const entry = bucket.get(sid) || { times: [] };
+    entry.times = entry.times.filter(t => now - t < RATE_WINDOW_MS);
+    if (entry.times.length >= RATE_LIMIT) {
+      const waitMs = RATE_WINDOW_MS - (now - entry.times[0]);
+      throw new Error(`Rate limited: max ${RATE_LIMIT} ateam_test_notification calls per minute per session. Retry in ${Math.ceil(waitMs / 1000)}s.`);
+    }
+    entry.times.push(now);
+    bucket.set(sid, entry);
+
+    // Get the authed tenant — used for X-ADAS-TENANT header (Core scopes
+    // the actor lookup by tenant, so cross-tenant targeting is rejected at
+    // Core regardless of what we pass).
+    const creds = getCredentials(sid);
+    const tenant = creds?.tenant;
+    if (!tenant) throw new Error("No tenant in session — call ateam_auth first.");
+
+    const coreUrl = process.env.ADAS_CORE_URL || "http://adas-backend:4000";
+    const coreSecret = process.env.CORE_MCP_SECRET;
+    if (!coreSecret) {
+      throw new Error("Server config error: CORE_MCP_SECRET not set. ateam_test_notification requires the platform shared secret (sibling-service auth). Contact platform admin.");
+    }
+
+    // Force [TEST] prefix on the user-visible content. Anti-phishing rail:
+    // even if a tenant admin api key were misused, the recipient sees
+    // [TEST] on the actual message — they can't be fooled into thinking
+    // it's a system-initiated production notification.
+    const safeContent = content.startsWith("[TEST]") ? content : `[TEST] ${content}`;
+
+    // Audit log (cheap — console). Replace with structured audit when one exists.
+    const contentHash = (await import("node:crypto")).createHash("sha256").update(content).digest("hex").slice(0, 12);
+    console.log(JSON.stringify({
+      audit: "ateam_test_notification",
+      tenant,
+      solution_id,
+      actor_id,
+      caller_session: sid?.slice(0, 8),
+      content_preview: content.slice(0, 60),
+      content_hash: contentHash,
+      reply_handler_skill: reply_handler?.skill || null,
+      urgency: urgency || "normal",
+      at: new Date().toISOString(),
+    }));
+
+    if (reply_handler) {
+      console.warn(`[ateam_test_notification] reply_handler set → next user reply will route to skill="${reply_handler.skill}" with caller-supplied context. v2 will enforce a tenant allowlist + context schema validation.`);
+    }
+
+    const body = {
+      actorId: actor_id,
+      content: safeContent,
+      urgency: urgency || "normal",
+      metadata: { ...(metadata || {}), source: source || "ateam-test", _test: true },
+      ...(reply_handler ? { reply_handler } : {}),
+    };
+
+    const res = await fetch(`${coreUrl}/api/internal/notify-user`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "X-ADAS-TOKEN": coreSecret,
+        "X-ADAS-TENANT": tenant,
+        "X-ADAS-SERVICE": "ateam-mcp.test_notification",
+      },
+      body: JSON.stringify(body),
+      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) {
+      // Surface Core's actual reason — "actor not found in tenant" is the
+      // most common (caller mistyped the actor_id), 502 = notif-router down.
+      throw new Error(`Core /api/internal/notify-user returned ${res.status}: ${data.error || JSON.stringify(data).slice(0, 200)}`);
+    }
+
+    return {
+      ok: true,
+      tenant,
+      actor_id,
+      dispatchId: data.dispatchId || null,
+      notification_id: data.dispatchId || null, // alias matching the spec
+      results: data.results || [],
+      content_preview: safeContent.slice(0, 80),
+      ...(reply_handler && { reply_handler_armed: { skill: reply_handler.skill } }),
+    };
+  },
+
   ateam_test_pipeline: async ({ solution_id, skill_id, message }, sid) =>
     post(`/deploy/solutions/${solution_id}/skills/${skill_id}/test-pipeline`, { message }, sid, { timeoutMs: 30_000 }),
 
@@ -2875,6 +3062,9 @@ const handlers = {
     return get(`/deploy/solutions/${solution_id}/github/diff${q ? '?' + q : ''}`, sid);
   },
 
+  ateam_verify_consistency: async ({ solution_id }, sid) =>
+    get(`/deploy/solutions/${solution_id}/verify`, sid),
+
   ateam_github_promote: async ({ solution_id, label, dry_run, skip_tag }, sid) =>
     post(`/deploy/solutions/${solution_id}/promote`, { label, dry_run, skip_tag }, sid),