@ateam-ai/mcp 0.4.48 → 0.4.49

package/package.json

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

@@ -0,0 +1,48 @@
+// src/mcpFailure.js
+//
+// Failure classification for the MCP tool dispatcher (used by handleToolCall in
+// tools.js). A tool call can succeed at the TRANSPORT layer (MCP returns a
+// result) while FAILING logically — the classic case being an upstream that
+// answers HTTP 200 with "Authentication required" sitting in the body. MCP's
+// `isError` and a machine-readable `code` are exactly for that gap: they let a
+// caller (e.g. the ateam-proxy connector) ask "did this actually work?" WITHOUT
+// parsing English.
+//
+// The human sentence STAYS in the result's content[].text — the reasoning loop
+// reads it to decide what to do next — we only ADD `isError` +
+// `structuredContent.code` alongside it. Never strip the prose.
+//
+//   node --test src/mcpFailure.test.js
+
+// This is the ONE boundary where recognizing the auth phrase from text is
+// correct: we translate the upstream lie into a structured code exactly once,
+// here, so nothing downstream ever has to.
+export const AUTH_SIGNAL_RX = /\b(unauthenticated|authentication required|authentication failed|not authenticated|no api_key in session|call ateam_auth|master key required|invalid api key|expired token|401)\b/i;
+
+/**
+ * Map a failure to a machine-readable code. An explicit code (set by a handler
+ * or carried on a thrown error) always wins; otherwise recognize the auth
+ * signal at this single boundary; otherwise a generic TOOL_FAILED.
+ * @param {string|object} source  the message/result the failure came with
+ * @param {string} [explicit]     a code the handler/error already set
+ * @returns {string}
+ */
+export function deriveErrorCode(source, explicit) {
+  if (explicit && typeof explicit === "string") return explicit;
+  const s = typeof source === "string"
+    ? source
+    : (() => { try { return JSON.stringify(source || ""); } catch { return String(source); } })();
+  if (AUTH_SIGNAL_RX.test(s)) return "UNAUTHENTICATED";
+  return "TOOL_FAILED";
+}
+
+/**
+ * A top-level object result with ok:false is a logical failure. Nested *.ok
+ * (widget_health.ok / validation.valid) are their own advisory signals and do
+ * NOT flip the tool to error — only the tool's OWN primary `ok` does.
+ * @param {any} result
+ * @returns {boolean}
+ */
+export function isLogicalFailure(result) {
+  return Boolean(result) && typeof result === "object" && !Array.isArray(result) && result.ok === false;
+}

package/src/mcpFailure.test.js

@@ -0,0 +1,64 @@
+// src/mcpFailure.test.js
+//
+// Proves the dispatcher's failure-classification rule: a logically-failed tool
+// result (returned ok:false, or an upstream 200-with-auth-text) is recognized
+// structurally and mapped to a machine-readable code — so the ateam-proxy never
+// has to read English to know a call failed. Tests the REAL exported functions.
+//   node --test src/mcpFailure.test.js
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { deriveErrorCode, isLogicalFailure, AUTH_SIGNAL_RX } from "./mcpFailure.js";
+
+test("auth phrases → UNAUTHENTICATED (the upstream 200-with-auth-text lie)", () => {
+  for (const s of [
+    "Authentication required — call ateam_auth first.",
+    "No api_key in session — call ateam_auth(api_key) first.",
+    "Master key required. Call ateam_auth(master_key) first.",
+    "Authentication failed: bad key",
+    "upstream said 401 Unauthorized",
+    "invalid API key",
+  ]) {
+    assert.equal(deriveErrorCode(s), "UNAUTHENTICATED", `expected UNAUTHENTICATED for: ${s}`);
+  }
+});
+
+test("non-auth failure → TOOL_FAILED", () => {
+  assert.equal(deriveErrorCode("could not read solution definition"), "TOOL_FAILED");
+  assert.equal(deriveErrorCode("redeploy timed out"), "TOOL_FAILED");
+});
+
+test("an explicit handler/error code always wins over text sniffing", () => {
+  // Even auth-looking text must not override a code the handler already set.
+  assert.equal(deriveErrorCode("Authentication required", "RATE_LIMITED"), "RATE_LIMITED");
+  assert.equal(deriveErrorCode("boom", "MISSING_SOLUTION"), "MISSING_SOLUTION");
+});
+
+test("object sources are stringified before matching (not just plain strings)", () => {
+  assert.equal(deriveErrorCode({ ok: false, message: "Authentication required" }), "UNAUTHENTICATED");
+  assert.equal(deriveErrorCode({ ok: false, error: "disk full" }), "TOOL_FAILED");
+});
+
+test("nullish / weird sources never throw, fall back to TOOL_FAILED", () => {
+  assert.equal(deriveErrorCode(null), "TOOL_FAILED");
+  assert.equal(deriveErrorCode(undefined), "TOOL_FAILED");
+});
+
+test("top-level ok:false is a logical failure; ok:true / missing / nested are not", () => {
+  assert.equal(isLogicalFailure({ ok: false, message: "x" }), true);
+  assert.equal(isLogicalFailure({ ok: true }), false);
+  assert.equal(isLogicalFailure({}), false);
+  // Nested advisory signals must NOT flip the tool to error (patch succeeded,
+  // widget just isn't rendering / def isn't valid yet).
+  assert.equal(isLogicalFailure({ ok: true, widget_health: { ok: false } }), false);
+  assert.equal(isLogicalFailure({ ok: true, validation: { valid: false } }), false);
+  // Arrays / primitives / null are never a logical failure.
+  assert.equal(isLogicalFailure([{ ok: false }]), false);
+  assert.equal(isLogicalFailure(null), false);
+  assert.equal(isLogicalFailure("ok:false"), false);
+});
+
+test("AUTH_SIGNAL_RX is exported for reuse and is case-insensitive", () => {
+  assert.ok(AUTH_SIGNAL_RX.test("AUTHENTICATION REQUIRED"));
+  assert.ok(!AUTH_SIGNAL_RX.test("everything is fine"));
+});

package/src/tools.js

@@ -29,6 +29,7 @@ const STAMP_WHERE_TOOLS = new Set([
   "ateam_verify_surface",
 ]);
 import { renderAgentDocHeader, mergeAgentDoc, AGENT_DOC_SENTINEL } from "./agentDoc.js";
+import { deriveErrorCode, isLogicalFailure } from "./mcpFailure.js";
 
 // ─── Async deploy helper ────────────────────────────────────────────
 //
@@ -5216,6 +5217,10 @@ function summarizeLargeResult(result, toolName) {
   return JSON.stringify(result, null, 2).slice(0, MAX_RESPONSE_CHARS);
 }
 
+// Failure classification (isError + a machine-readable code, WITHOUT parsing
+// English) lives in ./mcpFailure.js — imported at the top — so the rule is
+// unit-testable in isolation (mcpFailure.test.js).
+
 // ─── Dispatcher ─────────────────────────────────────────────────────
 
 export async function handleToolCall(name, args, sessionId) {
@@ -5259,6 +5264,7 @@ export async function handleToolCall(name, args, sessionId) {
         ].join("\n"),
       }],
       isError: true,
+      structuredContent: { ok: false, code: "UNAUTHENTICATED" },
     };
   }
 
@@ -5315,13 +5321,28 @@ export async function handleToolCall(name, args, sessionId) {
       } catch { /* non-fatal — unauthed sessions or API blips shouldn't break bootstrap */ }
     }
 
+    const text = formatResult(result, name);
+    if (isLogicalFailure(result)) {
+      // Logical failure RETURNED (not thrown) — e.g. { ok:false, message:"…
+      // Authentication required" } or an upstream 200-with-auth-text. Flag it
+      // so a caller detects it from isError/code, not by reading the prose.
+      // The sentence stays in content[].text for the reasoning loop.
+      const code = deriveErrorCode(result.message || result.error || text, result.code);
+      return {
+        content: [{ type: "text", text }],
+        isError: true,
+        structuredContent: { ok: false, code },
+      };
+    }
     return {
-      content: [{ type: "text", text: formatResult(result, name) }],
+      content: [{ type: "text", text }],
     };
   } catch (err) {
+    const code = deriveErrorCode(err.message, err.code);
     return {
       content: [{ type: "text", text: err.message }],
       isError: true,
+      structuredContent: { ok: false, code },
     };
   }
 }