@ateam-ai/mcp 0.3.25 → 0.3.27

package/package.json

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

@@ -0,0 +1,248 @@
+/**
+ * CLAUDE.md agent-onboarding doc renderer.
+ *
+ * Produces a per-solution markdown file that auto-loads into Claude Code
+ * sessions when the developer clones the solution repo. Closes the gap where
+ * a fresh agent has no idea how to iterate, which tools to use, or what
+ * pitfalls to avoid.
+ *
+ * Structure:
+ *   - Auto-generated header (above SENTINEL) — rewritten on every regen
+ *   - SENTINEL line — marks the boundary
+ *   - Solution-specific notes (below SENTINEL) — preserved across regens
+ *
+ * Callers:
+ *   - ateam_write_agent_doc({ solution_id, overwrite? }) — explicit backfill
+ *   - ateam_build_and_run — auto-invoked post-deploy (non-fatal)
+ */
+
+export const AGENT_DOC_SENTINEL = "<!-- SOLUTION-SPECIFIC NOTES BELOW — not auto-regenerated -->";
+
+/**
+ * Render the auto-generated section of CLAUDE.md.
+ *
+ * @param {object} params
+ * @param {object} params.solution    - Full solution definition
+ * @param {Array}  params.skills      - Array of skill definitions
+ * @param {Array}  [params.connectors] - Solution-connector metadata
+ * @returns {string} markdown
+ */
+export function renderAgentDocHeader({ solution, skills = [], connectors = [] }) {
+  const solId = solution?.id || "unknown";
+  const solName = solution?.name || solId;
+  const solDesc = solution?.description || "";
+  const orchestratorId = solution?.orchestrator_skill || null;
+  const tenantHint = inferTenantFromId(solId);
+
+  const skillsList = skills.map((s) => {
+    const role = s.role || (s.id === orchestratorId ? "orchestrator" : "worker");
+    const desc = s.description || s.problem?.statement || "";
+    return `- **${s.id}** _(${role})_ — ${oneLine(desc)}`;
+  }).join("\n") || "_(no skills defined)_";
+
+  const platformConnectorIds = (solution?.platform_connectors || []).map((c) => c.id);
+  const solutionConnectorIds = [
+    ...new Set(connectors.map((c) => c.id).filter(Boolean)),
+  ];
+  const connectorTable = buildConnectorTable({
+    platform: platformConnectorIds,
+    solution: solutionConnectorIds,
+  });
+
+  const uiPlugins = (solution?.ui_plugins || []).map((p) => {
+    const mode = p.render?.mode || "?";
+    return `- **${p.name || p.id}** (\`${p.id}\`, ${mode})`;
+  }).join("\n") || "_(none)_";
+
+  const tools = buildToolTable();
+  const pitfalls = buildUniversalPitfalls();
+  const repoLayout = buildRepoLayout({ skills, connectors });
+
+  return `# ${solName} — Agent Onboarding
+
+> This file is auto-generated by A-Team on every deploy.
+> Everything ABOVE the sentinel line is regenerated.
+> Solution-specific notes go BELOW the sentinel — they are preserved.
+
+You are working on A-Team solution **${solId}**. Read this entire file before your first tool call.
+
+---
+
+## 1. What this solution is
+
+${solDesc || "_(no description set — add one to solution.json)_"}
+
+${tenantHint ? `- **Tenant:** \`${tenantHint}\`` : ""}
+- **Orchestrator skill:** ${orchestratorId ? `\`${orchestratorId}\`` : "_(none set)_"}
+
+---
+
+## 2. Skills
+
+${skillsList}
+
+---
+
+## 3. Connectors
+
+${connectorTable}
+
+---
+
+## 4. UI plugins
+
+${uiPlugins}
+
+---
+
+## 5. Repo layout
+
+\`\`\`
+${repoLayout}
+\`\`\`
+
+---
+
+## 6. Dev workflow (single-branch, GitHub-first)
+
+Everything lands on \`main\` directly. Checkpoints via \`safe-*\` tags.
+
+\`\`\`
+1. git clone <this repo>
+2. edit code in your IDE / agent
+3. git commit && git push origin main
+4. ateam_build_and_run(solution_id: "${solId}", github: true)
+5. ateam_test_skill / ateam_test_connector  — verify
+6. ateam_github_promote(solution_id)          — checkpoint when green
+\`\`\`
+
+Or edit remotely via \`ateam_github_patch\` / \`ateam_github_write\` — same effect.
+
+**First tool call every session:** \`ateam_auth(api_key: "adas_${tenantHint || "<tenant>"}_<hex>")\`.
+
+---
+
+## 7. Which MCP tool for what
+
+${tools}
+
+**Rule:** prefer \`ateam_patch\` over \`ateam_github_patch\` + \`ateam_build_and_run\` when changing skill definitions — it's one call and always redeploys.
+
+---
+
+## 8. Universal pitfalls (apply to every A-Team solution)
+
+${pitfalls}
+
+---
+
+## 9. Spec & examples
+
+- \`ateam_get_spec(topic: "skill")\` — full skill schema
+- \`ateam_get_spec(topic: "solution")\` — solution schema
+- \`ateam_get_examples(type: "skill" | "connector" | "connector-ui" | "solution")\`
+- \`ateam_get_workflows()\` — builder workflow state machines
+
+Read these on your first edit into an area you haven't touched.
+
+---
+
+${AGENT_DOC_SENTINEL}
+
+`;
+}
+
+/**
+ * Merge the newly-rendered header with an existing CLAUDE.md, preserving
+ * anything below the sentinel (solution-specific notes).
+ *
+ * @param {string} freshHeader   - Output of renderAgentDocHeader
+ * @param {string|null} existing - Current CLAUDE.md contents (or null if new file)
+ * @returns {string} merged markdown
+ */
+export function mergeAgentDoc(freshHeader, existing) {
+  if (!existing) return freshHeader;
+  const idx = existing.indexOf(AGENT_DOC_SENTINEL);
+  if (idx === -1) {
+    // Existing file has no sentinel — treat the whole file as manual notes,
+    // prepend the auto-generated header, separate by sentinel.
+    return freshHeader + "\n" + existing.trimStart();
+  }
+  const tail = existing.slice(idx + AGENT_DOC_SENTINEL.length);
+  return freshHeader + tail;
+}
+
+// ──────────────────────────────────────────────────────────────────────────
+
+function oneLine(s) {
+  return String(s || "").replace(/\s+/g, " ").trim().slice(0, 200);
+}
+
+function inferTenantFromId() {
+  // Can't reliably infer from solution_id alone; caller can override by
+  // setting tenant on the rendered header via post-processing if needed.
+  return null;
+}
+
+function buildConnectorTable({ platform, solution }) {
+  const rows = [];
+  if (solution.length) {
+    rows.push("**Solution connectors** (live in this repo under `connectors/`):");
+    for (const id of solution) rows.push(`  - \`${id}\``);
+    rows.push("");
+  }
+  if (platform.length) {
+    rows.push("**Platform connectors** (shared infrastructure, not in this repo):");
+    for (const id of platform) rows.push(`  - \`${id}\``);
+    rows.push("");
+  }
+  if (!rows.length) rows.push("_(no connectors declared)_");
+  return rows.join("\n");
+}
+
+function buildToolTable() {
+  return [
+    "| Task | Tool |",
+    "|------|------|",
+    "| Edit connector source code | `ateam_github_patch` / `ateam_github_write` → `ateam_build_and_run(github:true)` |",
+    "| Edit skill definition (persona, tools, intents, guardrails) | `ateam_patch(target:\"skill\", skill_id, updates)` |",
+    "| Edit solution definition | `ateam_patch(target:\"solution\", updates)` |",
+    "| First deploy / redeploy from GitHub | `ateam_build_and_run(github:true)` |",
+    "| Run a skill end-to-end | `ateam_test_skill(solution_id, skill_id, message)` |",
+    "| Call one connector tool in isolation | `ateam_test_connector(solution_id, connector_id, tool, args)` |",
+    "| Inspect deployed state | `ateam_get_solution(solution_id, view: \"definition\"|\"skills\"|\"health\")` |",
+    "| Read file from repo | `ateam_github_read(solution_id, path)` |",
+    "| Checkpoint | `ateam_github_promote(solution_id, label)` |",
+    "| Rollback | `ateam_github_rollback(solution_id, tag)` |",
+    "| List checkpoints | `ateam_github_list_versions(solution_id)` |",
+  ].join("\n");
+}
+
+function buildUniversalPitfalls() {
+  return [
+    "- **`ateam_test_connector` runs as `_system_service`.** Core strips user-provided `_adas_actor` when you call via the test harness. Use it for connector-level bugs; use `ateam_test_skill` / `ateam_conversation` for per-user-actor flows.",
+    "- **`.ateam/export.json` is auto-generated.** Never hand-edit. Deploys read it, so stale copies silently break things.",
+    "- **Prefer `ateam_patch` over `github_patch` + `build_and_run`** for skill-definition edits. One call, guaranteed redeploy, no drift.",
+    "- **Always refetch dynamic ids.** Corpus ids, job ids, actor ids change. Call `docs.corpus.list` / `ateam_list_solutions` / etc. in the current job — don't reuse ids from memory or previous sessions.",
+    "- **MCP tool param names are strict.** `top_k` (not `k`), `corpus_id` (not `corpus`). Passing wrong names silently fails zod validation.",
+    "- **Don't count `{ok:false}` as success.** When calling one MCP from another, always check `result.ok` before incrementing a success counter.",
+    "- **Connectors are stdio, not HTTP.** Use `StdioServerTransport`. Never `app.listen()`. Log with `console.error` (stdout is the JSON-RPC channel).",
+    "- **Shared-tenant resources need `shared: true`.** When a resource (corpus, bind, etc.) is used across users in a tenant, pass `shared: true` at create time — otherwise per-user actor isolation blocks cross-user access.",
+  ].map((s) => "- " + s.replace(/^- /, "")).join("\n");
+}
+
+function buildRepoLayout({ skills, connectors }) {
+  const skillDirs = skills.map((s) => `  ${s.id}/skill.json`).join("\n") || "  _(no skills)_";
+  const connDirs = connectors.length
+    ? connectors.map((c) => `  ${c.id}/\n    server.js\n    package.json`).join("\n")
+    : "  _(no solution connectors)_";
+  return [
+    "solution.json                    # full solution definition",
+    "skills/",
+    skillDirs,
+    "connectors/                      # solution connectors (stdio MCPs)",
+    connDirs,
+    ".ateam/export.json               # auto-generated deploy bundle (don't hand-edit)",
+    "CLAUDE.md                        # this file — auto-regenerated above sentinel",
+  ].join("\n");
+}

package/src/tools.js

@@ -14,6 +14,7 @@ import {
   getCredentials, parseApiKey, touchSession, getSessionContext,
   setAuthOverride, switchTenant, isMasterMode, listTenants,
 } from "./api.js";
+import { renderAgentDocHeader, mergeAgentDoc, AGENT_DOC_SENTINEL } from "./agentDoc.js";
 
 // ─── Tool definitions ───────────────────────────────────────────────
 
@@ -921,6 +922,24 @@ export const tools = [
       required: ["solution_id", "path"],
     },
   },
+  {
+    name: "ateam_write_agent_doc",
+    core: false,
+    description:
+      "Render + write (or refresh) CLAUDE.md in the solution's GitHub repo. Auto-generates the onboarding header from the deployed solution/skill/connector definitions and preserves any solution-specific notes below the sentinel line. " +
+      "Normally called automatically on every ateam_build_and_run so CLAUDE.md stays in sync — use this tool directly to backfill existing solutions or to force a refresh.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        solution_id: { type: "string", description: "The solution ID" },
+        overwrite: {
+          type: "boolean",
+          description: "If true, rewrite the whole file (discards any solution-specific notes below the sentinel). Default false — preserves notes.",
+        },
+      },
+      required: ["solution_id"],
+    },
+  },
   {
     name: "ateam_github_write",
     core: true,
@@ -1697,6 +1716,24 @@ const handlers = {
       }
     }
 
+    // Auto-seed / refresh the agent onboarding doc. Non-fatal — any failure
+    // here is swallowed so it can't break a successful deploy. The tool is
+    // idempotent: if the rendered doc is byte-identical to what's in the
+    // repo, it returns unchanged:true and writes no commit.
+    let agent_doc_result = null;
+    try {
+      agent_doc_result = await handlers.ateam_write_agent_doc({ solution_id: solutionId }, sid);
+      phases.push({
+        phase: "agent_doc",
+        status: agent_doc_result?.unchanged ? "unchanged" : "done",
+        created: agent_doc_result?.created || false,
+        preserved_notes: agent_doc_result?.preserved_notes || false,
+      });
+    } catch (err) {
+      agent_doc_result = { error: err.message };
+      phases.push({ phase: "agent_doc", status: "skipped", reason: err.message });
+    }
+
     return {
       ok: true,
       solution_id: solutionId,
@@ -1711,6 +1748,7 @@ const handlers = {
       health,
       ...(test_result && { test_result }),
       ...(github_result && !github_result.error && !github_result.skipped && { github: github_result }),
+      ...(agent_doc_result && !agent_doc_result.error && { agent_doc: agent_doc_result }),
       ...(validation.warnings?.length > 0 && { validation_warnings: validation.warnings }),
       _status: '✅ Deployed to Core + pushed to main.',
       _next: 'Create a checkpoint before making more changes: ateam_github_promote(solution_id)',
@@ -2063,6 +2101,68 @@ const handlers = {
   ateam_get_connector_source: async ({ solution_id, connector_id }, sid) =>
     get(`/deploy/solutions/${solution_id}/connectors/${connector_id}/source`, sid),
 
+  // Render + write CLAUDE.md into the solution's GitHub repo.
+  // Preserves content below the sentinel unless overwrite=true.
+  // Swallows errors internally when invoked non-interactively (see _writeAgentDocSafe).
+  ateam_write_agent_doc: async ({ solution_id, overwrite = false }, sid) => {
+    if (!solution_id) throw new Error("solution_id required");
+    // Gather source material: the deployed solution definition + skills list.
+    // These come straight from Core, so the doc always reflects what's running.
+    const def = await get(`/deploy/solutions/${solution_id}/definition`, sid);
+    const solution = def?.solution || def;
+    let skills = [];
+    try {
+      const skillsRes = await get(`/deploy/solutions/${solution_id}/skills`, sid);
+      skills = Array.isArray(skillsRes?.skills) ? skillsRes.skills : Array.isArray(skillsRes) ? skillsRes : [];
+    } catch { /* no skills yet — render anyway */ }
+    const connectors = Array.isArray(solution?.connectors) ? solution.connectors : [];
+
+    const freshHeader = renderAgentDocHeader({ solution, skills, connectors });
+    let existing = null;
+    try {
+      const r = await get(
+        `/deploy/solutions/${solution_id}/github/read?path=${encodeURIComponent("CLAUDE.md")}`,
+        sid,
+      );
+      existing = r?.content || null;
+    } catch { /* file doesn't exist yet — treat as fresh create */ }
+    const merged = overwrite ? freshHeader : mergeAgentDoc(freshHeader, existing);
+
+    // Idempotent write: if the merged content is byte-identical to what's
+    // already committed, skip the patch entirely. Prevents a noise commit on
+    // every build_and_run when nothing meaningful changed.
+    if (existing && existing === merged) {
+      return {
+        ok: true,
+        solution_id,
+        unchanged: true,
+        created: false,
+        preserved_notes: existing.includes(AGENT_DOC_SENTINEL),
+        bytes: merged.length,
+      };
+    }
+
+    const res = await post(
+      `/deploy/solutions/${solution_id}/github/patch`,
+      {
+        path: "CLAUDE.md",
+        content: merged,
+        message: existing ? "CLAUDE.md: refresh auto-generated header" : "CLAUDE.md: seed agent onboarding doc",
+      },
+      sid,
+    );
+    return {
+      ok: Boolean(res?.ok ?? true),
+      solution_id,
+      unchanged: false,
+      created: !existing,
+      preserved_notes: Boolean(existing && existing.includes(AGENT_DOC_SENTINEL)),
+      bytes: merged.length,
+      commit_url: res?.commit_url || null,
+      commit_sha: res?.commit_sha || null,
+    };
+  },
+
   ateam_get_metrics: async ({ solution_id, job_id, skill_id }, sid) => {
     const qs = new URLSearchParams();
     if (job_id) qs.set("job_id", job_id);