@ateam-ai/mcp 0.4.50 → 0.4.52

package/package.json

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

@@ -10,7 +10,7 @@ import {
   CallToolRequestSchema,
   ListToolsRequestSchema,
 } from "@modelcontextprotocol/sdk/types.js";
-import { tools, coreTools, handleToolCall } from "./tools.js";
+import { tools, coreTools, handleToolCall, MCP_VERSION } from "./tools.js";
 
 /**
  * @param {string} sessionId — identifier for credential isolation.
@@ -18,7 +18,11 @@ import { tools, coreTools, handleToolCall } from "./tools.js";
  */
 export function createServer(sessionId = "stdio") {
   const server = new Server(
-    { name: "ateam-mcp", version: "0.3.0" },
+    // Read the REAL version from package.json. This was hardcoded "0.3.0" while
+    // the package shipped 0.4.x — so the MCP handshake advertised a version that
+    // had been wrong for dozens of releases, and "which build am I talking to?"
+    // could not be answered from the protocol at all.
+    { name: "ateam-mcp", version: MCP_VERSION },
     {
       capabilities: { tools: {} },
       instructions: [

package/src/tools.js

@@ -31,6 +31,18 @@ const STAMP_WHERE_TOOLS = new Set([
 import { renderAgentDocHeader, mergeAgentDoc, AGENT_DOC_SENTINEL } from "./agentDoc.js";
 import { deriveErrorCode, isLogicalFailure } from "./mcpFailure.js";
 
+// The RUNNING version, read from package.json — never hardcoded. "Deployed" means
+// three different things here (the mac1 container, npm, and each developer's local
+// checkout+process), and a stale local PROCESS is indistinguishable from a broken
+// fix without this. Surfaced in the MCP handshake and in ateam_bootstrap so
+// "which build am I talking to?" is a five-second check, not a three-message
+// round-trip (2026-08-16).
+import { createRequire as _createRequire } from "node:module";
+export const MCP_VERSION = (() => {
+  try { return _createRequire(import.meta.url)("../package.json").version; }
+  catch { return "unknown"; }
+})();
+
 // ─── Async deploy helper ────────────────────────────────────────────
 //
 // All long-running deploy endpoints (build_and_run, redeploy, github_pull)
@@ -450,9 +462,9 @@ export const tools = [
       properties: {
         topic: {
           type: "string",
-          enum: ["overview", "skill", "solution", "enums", "connector-multi-user", "python_helpers", "widgets", "ui-plugins", "actor-storage", "voice", "voice-native", "triggers", "sub-agent", "consumer-roles", "mobile-connector"],
+          enum: ["overview", "skill", "solution", "enums", "connector-multi-user", "python_helpers", "widgets", "ui-plugins", "actor-storage", "voice", "voice-native", "triggers", "sub-agent", "consumer-roles", "mobile-connector", "monitoring"],
           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), '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. 'ui-plugins' = the DEEP React Native (mobile) plugin build guide: author in rn-src/, compile with a build:rn esbuild script (format=cjs, target=es2015, external react/react-native/@adas/plugin-sdk) to rn-bundle/index.bundle.js, plain-object export — read this before authoring any MOBILE widget.",
+            "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. 'ui-plugins' = the DEEP React Native (mobile) plugin build guide: author in rn-src/, compile with a build:rn esbuild script (format=cjs, target=es2015, external react/react-native/@adas/plugin-sdk) to rn-bundle/index.bundle.js, plain-object export — read this before authoring any MOBILE widget. 'monitoring' = THE MONITORING CONTRACT: which tools are safe to call in a poll loop (with cost / poll interval / whether output stays bounded as the run grows), which are not and what to use instead, plus the running ateam-mcp version. Read this BEFORE writing any loop that watches a build — the safe poll is ateam_chain_status, never ateam_get_chain.",
         },
         section: {
           type: "string",
@@ -1324,7 +1336,10 @@ export const tools = [
   },
   {
     name: "ateam_get_execution_logs",
-    core: false,
+    // Advertised (was core:false): these are the RUNTIME DIAGNOSTICS a caller needs
+    // mid-run, but a connector-wildcard grant expands over ADVERTISED tools only, so
+    // hiding them made them ungrantable — invisible to every agent that needed them.
+    core: true,
     description:
       "Get execution logs for a solution — recent jobs with step traces, tool calls, errors, and timing. Essential for debugging what actually happened during skill execution. (Advanced.)",
     inputSchema: {
@@ -1353,6 +1368,10 @@ export const tools = [
   {
     name: "ateam_test_status",
     core: true,
+    // Monitoring-safe for ONE test job (bounded), but include_chain:true pulls the
+    // full tree — that call is NOT safe to loop.
+    monitoring: { safe: true, cost: "cheap", latency_ms_p95: 500, output: "bounded", poll_interval_s: 2,
+      note: "safe:false when include_chain:true (that fetches the full tree)." },
     description:
       "Poll the progress of an async skill test. Returns iteration count, tool call steps, status (running/completed/failed), and result when done.\n\n" +
       "Set include_chain:true to ALSO include the full chain tree (every job in the chain, rooted at this job_id, with parent/child linkage). Use when this job dispatched askAnySkill subcalls and you want a single snapshot of the whole multi-skill state instead of polling each child job_id separately.",
@@ -1383,6 +1402,10 @@ export const tools = [
   {
     name: "ateam_get_chain",
     core: true,
+    // NOT monitoring-safe: returns the FULL job tree — output grows with the run
+    // (a 200-step job returns 200 steps), which is the property that silently
+    // degrades. Use once at the end; poll ateam_chain_status instead.
+    monitoring: { safe: false, cost: "heavy", output: "grows_with_run", use_instead: "ateam_chain_status" },
     description:
       "Inspect the full chain tree for any job — rooted at the given job_id, walking down through every handoff and askAnySkill subcall.\n\n" +
       "Use when a chain has already run and you want to analyze the structure: which skill called which, how deep the call tree went, which tool inside which job invoked which sub-tool. The two main shapes:\n" +
@@ -1408,6 +1431,17 @@ export const tools = [
   {
     name: "ateam_chain_status",
     core: true,
+    // MONITORING-SAFE — the one tool built for a poll loop. See MONITORING_CONTRACT.
+    // cheap: one status read, no tree walk, no LLM. bounded: the response does NOT
+    // grow with the run (a 200-step job returns the same shape as a 2-step one).
+    monitoring: {
+      safe: true,
+      cost: "cheap",
+      latency_ms_p95: 500,
+      output: "bounded",
+      poll_interval_s: 2,
+      note: "Returns last_activity_at / idle_seconds / activity_source. A LARGE idle_seconds does NOT mean dead — on this platform a healthy build sits minutes inside a single provider call. Read activity_source (what it was doing) with it; never apply an 'idle > N ⇒ dead' rule.",
+    },
     description:
       "SLIM chain status — the chip-quick poll. Given a chain_id (from ateam_conversation), returns the WHOLE-CHAIN aggregate status cheaply: chain_status + chain_done (true only when the ENTIRE chain — root job + every handoff + askAnySkill subcall — is terminal), plus pending_question, result, and a short progress line.\n\n" +
       "This is what you poll on a loop after ateam_conversation — NOT ateam_get_chain (that returns the full tree; too heavy for periodic polling). A single job can finish while the chain is still running, so poll chain_done, not a job's status.\n\n" +
@@ -1540,7 +1574,11 @@ export const tools = [
   },
   {
     name: "ateam_get_metrics",
-    core: false,
+    monitoring: { safe: true, cost: "cheap", latency_ms_p95: 1000, output: "bounded", poll_interval_s: 30 },
+    // Advertised (was core:false): these are the RUNTIME DIAGNOSTICS a caller needs
+    // mid-run, but a connector-wildcard grant expands over ADVERTISED tools only, so
+    // hiding them made them ungrantable — invisible to every agent that needed them.
+    core: true,
     description:
       "Get execution metrics — timing, tool stats, bottlenecks, signals, and recommendations. (Advanced.)",
     inputSchema: {
@@ -1565,6 +1603,9 @@ export const tools = [
   {
     name: "ateam_verify",
     core: true,
+    // Real end-state check — probes connectors/widgets/skills. Correct but SLOW;
+    // for a run in flight poll ateam_chain_status and call this once at the end.
+    monitoring: { safe: false, cost: "heavy", output: "bounded", use_instead: "ateam_chain_status" },
     description:
       "ONE call that returns the REAL runtime end-state of a solution — connectors connected + tools discovered, every declared widget actually rendering, skills deployed — with the EXACT failing gaps. Use this instead of guess-and-check after a deploy/patch: it tells you the truth (what's actually live) and names precisely what's broken, not a generic warning. Reliable from any connection (routes through the Builder, not a direct Core call).",
     inputSchema: {
@@ -1970,6 +2011,8 @@ export const tools = [
   {
     name: "ateam_connector_logs",
     core: true,
+    // Bounded by the caller's line limit, but it reads container logs — poll slowly.
+    monitoring: { safe: true, cost: "moderate", latency_ms_p95: 3000, output: "bounded", poll_interval_s: 30 },
     description:
       "Read what a connector process actually PRINTED to stderr. This is the only place a connector's " +
       "internal failure is visible: a tool that catches its own error still returns ok:true, and the widget " +
@@ -2021,6 +2064,8 @@ export const tools = [
   {
     name: "ateam_status_all",
     core: true,
+    // Safe but not cheap-per-second: health across ALL solutions. Poll sparingly.
+    monitoring: { safe: true, cost: "moderate", latency_ms_p95: 3000, output: "bounded", poll_interval_s: 30 },
     description:
       "Show GitHub sync status for ALL tenants and solutions in one call. Requires master key authentication. Returns a summary table of every tenant's solutions with their GitHub sync state.",
     inputSchema: {
@@ -2055,6 +2100,23 @@ export const tools = [
  */
 export const coreTools = tools.filter(t => t.core !== false);
 
+// MONITORING CONTRACT — machine-filterable answer to "what may I poll on a loop?"
+// The knowledge used to exist only as prose, scattered and contradictory across
+// tool descriptions ("too heavy to loop on" in one, "poll every ~2s" in another,
+// different words, different tools), so a caller had to read paragraphs carefully
+// to learn which call was safe in a loop. Now it is a field.
+//   safe            — may be called repeatedly in a poll loop
+//   cost            — cheap | moderate | heavy
+//   output          — "bounded" means bounded IN THE RUN'S SIZE, not merely small
+//                     today. The silent-degradation failure is a tool that is
+//                     concise on a 5-step job and returns 200 steps on a 200-step
+//                     job; that is output:"grows_with_run", never safe.
+//   poll_interval_s — the interval the tool is designed for
+// A tool with NO monitoring field is UNCLASSIFIED — treat as unsafe to poll.
+export const monitoringTools = tools
+  .filter(t => t.monitoring?.safe === true)
+  .map(t => ({ name: t.name, ...t.monitoring }));
+
 // ─── Tool handlers ──────────────────────────────────────────────────
 
 const SPEC_PATHS = {
@@ -2606,6 +2668,11 @@ module.exports.default = plugin;
 
 const handlers = {
   ateam_bootstrap: async () => ({
+    runtime: {
+      ateam_mcp_version: MCP_VERSION,
+      base_url: getBaseUrl(),
+      _note: "The version of the ateam-mcp process actually serving this call, and the API it talks to. If a fix looks missing, check this FIRST — a local MCP process keeps running the code it loaded at session start, so a pushed/published fix is not live until the process restarts.",
+    },
     platform_positioning: {
       name: "A-Team",
       category: "AI Team Solution Platform",
@@ -2971,6 +3038,25 @@ const handlers = {
   },
 
   ateam_get_spec: async ({ topic, section, search }, sid) => {
+    // Served LOCALLY (no round-trip): the monitoring contract is a property of
+    // THIS ateam-mcp build, so it must answer even when the API is unreachable —
+    // that is exactly when a caller is asking "what can I poll to find out?".
+    if (topic === "monitoring") {
+      return {
+        ateam_mcp_version: MCP_VERSION,
+        safe_to_poll: monitoringTools,
+        not_safe_to_poll: tools
+          .filter(t => t.monitoring?.safe === false)
+          .map(t => ({ name: t.name, cost: t.monitoring.cost, output: t.monitoring.output, use_instead: t.monitoring.use_instead })),
+        unclassified_are_unsafe: true,
+        rules: [
+          "output:'bounded' means bounded IN THE RUN'S SIZE — not merely small today. A tool that returns 200 steps for a 200-step job is grows_with_run and is never poll-safe.",
+          "A tool with no monitoring field is UNCLASSIFIED — treat it as unsafe to poll.",
+          "NEVER apply an 'idle_seconds > N ⇒ dead' rule. On this platform a healthy build regularly sits minutes inside a single provider call; read activity_source alongside it.",
+        ],
+        watching_a_run: "Poll ateam_chain_status (every ~2s, or ~30s for a long build) and read chain_done + last_activity_at/idle_seconds/activity_source. Call ateam_get_chain ONCE at the end for the full tree.",
+      };
+    }
     let path = SPEC_PATHS[topic];
     const params = new URLSearchParams();
     if (section) params.set('section', section);
@@ -4178,12 +4264,9 @@ const handlers = {
     while (Date.now() - startedAt < totalTimeoutMs) {
       const qs = new URLSearchParams();
       qs.set("skillSlug", skill_id);
-      const res = await fetch(`${coreUrl}/api/job/${encodeURIComponent(rootJobId)}/chain?${qs}`, {
-        method: "GET",
-        headers: { "x-api-key": apiKey, "X-ADAS-SERVICE": "ateam-mcp.test_skill_chain" },
-        signal: AbortSignal.timeout(15_000),
-      }).catch(err => ({ ok: false, _err: err.message }));
-      const data = res.ok === false && res._err ? { ok: false, error: res._err } : await res.json().catch(() => ({ ok: false, error: "non-json chain response" }));
+      // Builder proxy, not ADAS_CORE_URL (docker-internal; see ateam_chain_status).
+      const data = await get(`/deploy/jobs/${encodeURIComponent(rootJobId)}/chain?${qs}`, sid)
+        .catch(err => ({ ok: false, error: err.message }));
       lastChain = data;
       const jobs = Array.isArray(data?.chainJobsList) ? data.chainJobsList : Array.isArray(data?.chainJobs) ? data.chainJobs : null;
       if (jobs && jobs.length > 0 && jobs.every(j => isTerminal(j.status))) {
@@ -4337,15 +4420,11 @@ const handlers = {
     const creds = getCredentials(sid);
     const apiKey = creds?.apiKey;
     if (!apiKey) return { ...single, chain: { ok: false, error: "include_chain requires api-key auth (call ateam_auth)" } };
-    const coreUrl = process.env.ADAS_CORE_URL || "http://adas-backend:4000";
     const qs = new URLSearchParams();
     if (skill_id) qs.set("skillSlug", skill_id);
-    const res = await fetch(`${coreUrl}/api/job/${encodeURIComponent(job_id)}/chain?${qs}`, {
-      method: "GET",
-      headers: { "x-api-key": apiKey, "X-ADAS-SERVICE": "ateam-mcp.test_status_chain" },
-      signal: AbortSignal.timeout(15_000),
-    }).catch(err => ({ ok: false, _err: err.message }));
-    const chain = res.ok === false && res._err ? { ok: false, error: res._err } : await res.json().catch(() => ({ ok: false, error: "non-json chain response" }));
+    // Builder proxy, not ADAS_CORE_URL (docker-internal; see ateam_chain_status).
+    const chain = await get(`/deploy/jobs/${encodeURIComponent(job_id)}/chain?${qs}`, sid)
+      .catch(err => ({ ok: false, error: err.message }));
     return { ...single, chain };
   },
 
@@ -4354,21 +4433,12 @@ const handlers = {
     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";
+    // Via the Builder proxy (see ateam_chain_status) — Core's hostname is
+    // docker-internal and unreachable from a desktop/laptop MCP process.
     const qs = new URLSearchParams();
     if (skill_slug) qs.set("skillSlug", skill_slug);
-    const res = await fetch(`${coreUrl}/api/job/${encodeURIComponent(job_id)}/chain?${qs}`, {
-      method: "GET",
-      headers: { "x-api-key": apiKey, "X-ADAS-SERVICE": "ateam-mcp.get_chain" },
-      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/job/${job_id}/chain returned ${res.status}: ${data.error || JSON.stringify(data).slice(0, 200)}`);
-    }
-    return data;
+    const suffix = qs.toString() ? `?${qs}` : "";
+    return await get(`/deploy/jobs/${encodeURIComponent(job_id)}/chain${suffix}`, sid);
   },
 
   // SLIM chain status — the chip-quick poll. Hits Core /api/job/:id/status
@@ -4380,21 +4450,26 @@ const handlers = {
   ateam_chain_status: async ({ chain_id, job_id }, sid) => {
     const id = chain_id || job_id;
     if (!id) throw new Error("chain_id required");
-    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/job/${encodeURIComponent(id)}/status`, {
-      method: "GET",
-      headers: { "x-api-key": apiKey, "X-ADAS-SERVICE": "ateam-mcp.chain_status" },
-      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/job/${id}/status returned ${res.status}: ${data.error || JSON.stringify(data).slice(0, 200)}`);
-    }
+    // Routed through the BUILDER proxy (/deploy/jobs/:id/status), not
+    // ADAS_CORE_URL directly. Core is the only holder of job state, but its
+    // hostname is docker-internal — every laptop MCP session got a bare "fetch
+    // failed" that read as "job not found" (2026-08-15: a full day spent reading
+    // Mongo by hand to answer "is this run alive?"). Same reason ateam_verify
+    // proxies. `get()` also carries the session's auth/tenant headers.
+    const data = await get(`/deploy/jobs/${encodeURIComponent(id)}/status`, sid);
+    // LAST ACTIVITY — the running-vs-corpse discriminator. `status:"running"` is
+    // true for a healthy build AND a dead one; the only way to tell them apart
+    // was querying llm_traces for the newest timestamp. Core bumps job.lastUpdate
+    // in the same setStatus() call that writes job.subStatus, so the timestamp
+    // and "what it was doing" move together — one cheap read, no tree walk, so
+    // this stays safe to poll. idle_seconds alone needs interpreting (a live
+    // build can sit minutes inside one provider call), which is why
+    // activity_source ships with it: "idle 180s — in provider call" is a state
+    // you can act on; "idle 180s" is a number you have to guess about.
+    const lastActivityAt = data.lastUpdate ?? data.last_update ?? null;
+    const idleSeconds = lastActivityAt
+      ? Math.max(0, Math.round((Date.now() - new Date(lastActivityAt).getTime()) / 1000))
+      : null;
     // Surface the chain-aggregate truth as the primary fields; keep the raw
     // slim job under `job` for callers that want per-job detail.
     return {
@@ -4404,6 +4479,9 @@ const handlers = {
       pending_question: data.pendingQuestion || null,
       result: data.result ?? null,
       progress: data.progress || null,
+      last_activity_at: lastActivityAt,
+      idle_seconds: idleSeconds,
+      activity_source: data.subStatus || null,
       job: data,
     };
   },