@ateam-ai/mcp 0.4.40 → 0.4.42

package/package.json

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

@@ -87,6 +87,63 @@ async function pollDeployJob(jobId, sid, { label = 'deploy', maxMs = 15 * 60_000
 //
 // Returns null when the solution declares no widgets (nothing to check), else
 // { ok, checked, healthy, plugins[], issues[]?, hint? }.
+// ─────────────────────────────────────────────────────────────────────────────
+// Authored-source representation marker
+//
+// A skill/solution definition read from GitHub is NOT the runtime. It is a
+// mirror that drifts: on solution 'ada' (2026-08-04) the `dev` copy declared 29
+// tools while production was running 66, because deploy-time connector imports
+// are regenerated on every deploy and only mirrored to `main`. An agent that
+// answers "what tools does this skill have?" from a repo read gets a wrong
+// answer today, and would get an emptier one once generated data leaves the
+// committed file.
+//
+// So every read of a definition path carries an ADDITIVE `_ateam_representation`
+// telling the caller what it is holding and which tool returns the live view.
+// Additive on purpose — wrapping or reshaping the existing response would break
+// callers that expect the raw payload.
+//
+// `kind` reports what the file ACTUALLY is right now, not what we intend it to
+// become: files without `source_schema_version >= 2` still carry generated data,
+// so calling them "authored_source" today would be a lie.
+// See Docs/WIP/SKILL_JSON_SPLIT_PLAN_2026-08-04.md (Phase C).
+// ─────────────────────────────────────────────────────────────────────────────
+const _SKILL_JSON_RE = /^skills\/([^/]+)\/skill\.json$/;
+
+function _representationFor(filePath, content, solution_id) {
+  const p = String(filePath || "");
+  const skillMatch = p.match(_SKILL_JSON_RE);
+  if (p !== "solution.json" && !skillMatch) return null;
+
+  let schemaVersion = null;
+  try {
+    const parsed = typeof content === "string" ? JSON.parse(content) : content;
+    schemaVersion = parsed?.source_schema_version ?? null;
+  } catch { /* not JSON, or truncated — fall through to the v1 wording */ }
+
+  const authoredOnly = typeof schemaVersion === "number" && schemaVersion >= 2;
+
+  return {
+    kind: authoredOnly ? "authored_source" : "git_mirror_v1",
+    is_runtime_state: false,
+    runtime_state_may_differ: true,
+    may_include_generated_fields: !authoredOnly,
+    ...(authoredOnly
+      ? { generated_fields_omitted: ["auto_imported_tools", "deployment_timestamps"] }
+      : { contains_generated_fields: ["auto_imported_tools", "deployment_timestamps"] }),
+    warning: authoredOnly
+      ? "Authored source only. Connector-imported tools are NOT in this file — they are regenerated at deploy time. Do not answer capability questions from it."
+      : "This is a git mirror, not runtime state. Its tools[] and timestamps are a snapshot from the last write to this branch and may not match what is deployed. Do not answer capability questions from it.",
+    live_state_tool: {
+      name: "ateam_get_solution",
+      arguments: {
+        solution_id,
+        ...(skillMatch ? { skill_id: skillMatch[1], section: "tools" } : {}),
+      },
+    },
+  };
+}
+
 // Compress a skill/solution definition to a small, non-truncating summary for
 // tool results — enough to confirm the shape without the 10s-of-KB full doc.
 function _summarizeDef(def) {
@@ -773,7 +830,7 @@ export const tools = [
           type: "string",
           enum: ["github", "local"],
           description:
-            "Where the solution/skill definition lives. 'github' (DEFAULT) — read from and write to the tenant's GitHub repo (GitHub is master; the normal path). 'local' — read from and write to the Builder FS store (no GitHub repo required). Use 'local' ONLY for a repo-less bootstrap tenant (e.g. freshly onboarded from a template, before GitHub is connected). This is a DEDICATED, EXPLICIT switch — never a fallback. Redeploy is local in both modes.",
+            "Where the solution/skill definition lives. Omit (DEFAULT) — prefer the tenant's GitHub repo (GitHub is master), but AUTO-DEGRADE to the Builder FS store if the tenant hasn't connected a repo, so a simple def patch always succeeds (it's pushed to GitHub once connected). 'github' — force GitHub; fails loud if not connected (use when you specifically require the repo write). 'local' — force the Builder FS store, no GitHub (repo-less bootstrap tenant). Redeploy is local in all modes.",
         },
         include_definition: {
           type: "boolean",
@@ -1610,7 +1667,11 @@ export const tools = [
     core: true,
     description:
       "Read any file from a solution's GitHub repo. Returns the file content. Use this to read connector source code, skill definitions, or any versioned file. " +
-      "Default reads from `main` (deployed/prod state). Pass `ref: 'dev'` to read in-progress work.",
+      "Default reads from `main` (deployed/prod state). Pass `ref: 'dev'` to read in-progress work.\n\n" +
+      "⚠️ NOT RUNTIME STATE. For `solution.json` and `skills/<id>/skill.json` this returns a git MIRROR, not what is deployed. " +
+      "Connector-imported tools are regenerated at deploy time, so a repo copy's `tools[]` can differ from production (on one solution `dev` showed 29 tools while production ran 66). " +
+      "Reads of those paths carry an `_ateam_representation` field saying what you are holding. " +
+      "To answer \"what can this skill actually do?\", call ateam_get_solution(solution_id, skill_id, section:'tools') — never this tool.",
     inputSchema: {
       type: "object",
       properties: {
@@ -1764,7 +1825,9 @@ export const tools = [
       "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)",
+      "  • **Diagnose a failed promote** — check `behind_by` and `status`. `status: 'diverged'` (behind_by > 0) means main holds commits dev never received, which is what makes ateam_github_promote return 409 Merge conflict. ALWAYS call this after a promote failure, before reporting anything to the user.\n" +
+      "  • Inspect arbitrary branch/tag/commit comparisons (override base/head)\n\n" +
+      "Note: `files[]` lists what DIFFERS, not what conflicts. For solution.json and skills/*/skill.json the difference is often deploy-generated data (regenerated connector tools, timestamps) rather than authored change — see ateam_github_read's `_ateam_representation`.",
     inputSchema: {
       type: "object",
       properties: {
@@ -3240,7 +3303,15 @@ const handlers = {
     //     yet connected). GitHub is still master overall; local is a temporary
     //     bootstrap until the tenant connects a repo (then local is pushed → GitHub).
     // Redeploy (Phase 4) is local (Builder FS → Core) in BOTH modes.
-    const isLocal = source === "local";
+    let isLocal = source === "local";
+    // Was a source EXPLICITLY chosen? An unspecified source is the default ("github")
+    // and MAY auto-degrade to local when the tenant hasn't connected a repo — a simple
+    // def patch must work FS-only (Arie's rule: create/patch allowed offline; only
+    // GitHub-native ops refuse). An explicit source:'github' is honored as-is (the
+    // caller asked for GitHub → it fails loud if not connected), and explicit 'local'
+    // stays local.
+    const sourceExplicit = source === "github" || source === "local";
+    let degradedToLocal = false;
 
     // Phase 1: Read current state (or create scaffold if new skill)
     let current;
@@ -3263,8 +3334,39 @@ const handlers = {
           throw new Error(`Local ${filePath} not found (empty definition)`);
         }
       } else {
-        const readResult = await get(`/deploy/solutions/${solution_id}/github/read?path=${encodeURIComponent(filePath)}`, sid);
-        current = JSON.parse(readResult.content);
+        try {
+          const readResult = await get(`/deploy/solutions/${solution_id}/github/read?path=${encodeURIComponent(filePath)}`, sid);
+          current = JSON.parse(readResult.content);
+        } catch (ghErr) {
+          // Auto-degrade a DEFAULT-source patch to the Builder FS when the tenant
+          // hasn't connected GitHub. A github/read failure alone is ambiguous (could
+          // be a wrong solution_id or a transient Core hiccup — both must still fail
+          // loud), so disambiguate with the definitive /github/connected probe and
+          // only degrade on a genuine "not connected". Explicit source:'github' never
+          // degrades. The local write below reconciles to GitHub once connected.
+          let connected = true;
+          if (!sourceExplicit) {
+            try {
+              const probe = await get(`/deploy/solutions/${solution_id}/github/connected`, sid);
+              connected = probe?.connected !== false && probe?.enabled !== false;
+            } catch { connected = true; /* probe failed → don't mask the real read error */ }
+          }
+          if (!sourceExplicit && !connected) {
+            isLocal = true;
+            degradedToLocal = true;
+            const r = target === "skill" && skill_id
+              ? await get(`/deploy/solutions/${solution_id}/skills/${encodeURIComponent(skill_id)}`, sid)
+              : await get(`/deploy/solutions/${solution_id}/definition?raw=1`, sid);
+            current = target === "skill" && skill_id
+              ? (r.skill || r.definition || r)
+              : (r.solution || r);
+            if (!current || typeof current !== "object") {
+              throw new Error(`Local ${filePath} not found (empty definition)`);
+            }
+          } else {
+            throw ghErr; // connected (real error) or explicit github → surface it
+          }
+        }
       }
     } catch (err) {
       // OPEN-31 guard: only scaffold-create when the skill is GENUINELY ABSENT.
@@ -3496,7 +3598,17 @@ const handlers = {
         // output cap and truncates the rest of the result. Return a compact
         // summary by default; pass include_definition:true for the whole thing.
         ...(include_definition
-          ? { after_state: patched }
+          ? {
+              after_state: patched,
+              // The base of this after-state came from a git read, so it inherits
+              // that copy's staleness — notably regenerated connector tools. Say so
+              // rather than letting an agent treat it as runtime truth.
+              _ateam_representation: _representationFor(
+                target === "skill" && skill_id ? `skills/${skill_id}/skill.json` : "solution.json",
+                patched,
+                solution_id,
+              ),
+            }
           : { after_state_summary: _summarizeDef(patched) }),
         would_write,
         would_write_bytes: JSON.stringify(patched, null, 2).length,
@@ -3646,6 +3758,10 @@ const handlers = {
       ok: true,
       solution_id,
       source: isLocal ? "local" : "github",
+      ...(degradedToLocal && {
+        degraded_to_local: true,
+        _degrade_note: `GitHub isn't connected for this tenant, so this patch was saved to the Builder store only (the edit succeeded). It will be pushed to GitHub automatically once the tenant connects a repo (Tenant Admin → GitHub). GitHub-native actions (promote, connector-source patch, github-sourced deploy) will refuse until then.`,
+      }),
       ...(isLocal ? {} : {
         branch: writeBranch,
         // Be explicit: a github write lands on `dev`, not prod. The change is
@@ -4394,7 +4510,12 @@ const handlers = {
   ateam_github_read: async ({ solution_id, path: filePath, ref }, sid) => {
     const qs = new URLSearchParams({ path: filePath });
     if (ref) qs.set('branch', ref);
-    return get(`/deploy/solutions/${solution_id}/github/read?${qs.toString()}`, sid);
+    const result = await get(`/deploy/solutions/${solution_id}/github/read?${qs.toString()}`, sid);
+    // Additive only — never reshape `result`, callers depend on the raw payload.
+    const rep = _representationFor(filePath, result?.content, solution_id);
+    return rep && result && typeof result === "object"
+      ? { ...result, _ateam_representation: rep }
+      : result;
   },
 
   ateam_github_patch: async ({ solution_id, path: filePath, content, search, replace, message, ref }, sid) =>