@ateam-ai/mcp 0.2.2 → 0.2.4

package/package.json

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

@@ -11,11 +11,12 @@
  */
 
 const BASE_URL = process.env.ADAS_API_URL || "https://api.ateam-ai.com";
+const CORE_URL = process.env.ADAS_CORE_URL || "";  // Direct Core access (for tenant list, etc.)
 const ENV_TENANT = process.env.ADAS_TENANT || "";
 const ENV_API_KEY = process.env.ADAS_API_KEY || "";
 
-// Request timeout (30 seconds)
-const REQUEST_TIMEOUT_MS = 30_000;
+// Request timeout (120 seconds — deploys can take 60-90s)
+const REQUEST_TIMEOUT_MS = 120_000;
 
 // Session TTL — sessions idle longer than this are swept
 const SESSION_TTL = 60 * 60 * 1000; // 60 minutes
@@ -27,6 +28,16 @@ const SWEEP_INTERVAL = 5 * 60 * 1000; // every 5 minutes
 // context: { activeSolutionId, lastSkillId, lastToolName }
 const sessions = new Map();
 
+// ── Bearer-based auth (persistent across sessions) ──────────────
+// The OAuth bearer token IS the user's API key (oauth.js exchangeAuthorizationCode).
+// Each user has a unique bearer. MCP clients create new sessions per tool call,
+// so we use the bearer as the persistent actor identity.
+//
+// When a user calls ateam_auth to override (e.g., switch tenants), the override
+// is stored per bearer and applied to all future sessions from that user.
+const authOverrides = new Map();  // bearerToken → { tenant, apiKey, updatedAt }
+const sessionBearers = new Map(); // sessionId → bearerToken
+
 /**
  * Parse a tenant-embedded API key.
  * Format: adas_<tenant>_<32hex>
@@ -43,10 +54,12 @@ export function parseApiKey(key) {
 }
 
 /**
- * Set credentials for a session (called by ateam_auth tool).
+ * Set credentials for a session.
  * If tenant is not provided, it's auto-extracted from the key.
+ * Set explicit=true when called from ateam_auth (not from seedCredentials).
+ * Set masterKey for cross-tenant master mode (uses shared secret auth).
  */
-export function setSessionCredentials(sessionId, { tenant, apiKey }) {
+export function setSessionCredentials(sessionId, { tenant, apiKey, apiUrl, explicit = false, masterKey = null }) {
   let resolvedTenant = tenant;
   if (!resolvedTenant && apiKey) {
     const parsed = parseApiKey(apiKey);
@@ -56,10 +69,36 @@ export function setSessionCredentials(sessionId, { tenant, apiKey }) {
   sessions.set(sessionId, {
     tenant: resolvedTenant || "main",
     apiKey,
+    apiUrl: apiUrl || existing?.apiUrl || null,
+    authExplicit: explicit || existing?.authExplicit || false,
+    masterKey: masterKey || existing?.masterKey || null,
     lastActivity: Date.now(),
     context: existing?.context || {},
   });
-  console.log(`[Auth] Credentials set for session ${sessionId} (tenant: ${resolvedTenant || "main"})`);
+  const urlNote = apiUrl ? `, url: ${apiUrl}` : "";
+  const masterNote = masterKey ? ", MASTER MODE" : "";
+  console.log(`[Auth] Credentials set for session ${sessionId} (tenant: ${resolvedTenant || "main"}${explicit ? ", explicit" : ""}${urlNote}${masterNote})`);
+}
+
+/**
+ * Switch the active tenant for a master-key session (no re-auth needed).
+ * Returns true if switched, false if not in master mode.
+ */
+export function switchTenant(sessionId, newTenant) {
+  const session = sessions.get(sessionId);
+  if (!session?.masterKey) return false;
+  session.tenant = newTenant;
+  session.lastActivity = Date.now();
+  console.log(`[Auth] Master mode tenant switch: ${newTenant} (session ${sessionId})`);
+  return true;
+}
+
+/**
+ * Check if a session is in master key mode.
+ */
+export function isMasterMode(sessionId) {
+  const session = sessions.get(sessionId);
+  return !!(session?.masterKey);
 }
 
 /**
@@ -95,13 +134,17 @@ export function isAuthenticated(sessionId) {
 
 /**
  * Check if a session has been explicitly authenticated via ateam_auth.
- * This checks ONLY per-session credentials, ignoring env vars.
+ * Checks per-session credentials AND bearer auth overrides.
  * Used to gate tenant-aware operations — env vars alone are not sufficient
  * to deploy, update, or read solutions.
  */
 export function isExplicitlyAuthenticated(sessionId) {
   if (!sessionId) return false;
-  return sessions.has(sessionId);
+  // Session has credentials AND they came from ateam_auth (not just seedCredentials)
+  const session = sessions.get(sessionId);
+  if (session?.authExplicit) return true;
+  // Bearer has an active auth override from a previous session's ateam_auth
+  return hasBearerAuth(sessionId);
 }
 
 /**
@@ -134,9 +177,69 @@ export function getSessionContext(sessionId) {
  * Remove session credentials (on disconnect).
  */
 export function clearSession(sessionId) {
+  sessionBearers.delete(sessionId);
   sessions.delete(sessionId);
 }
 
+// ── Bearer identity functions ──────────────────────────────────────
+
+/** Bind a session to its OAuth bearer token. Called from seedCredentials. */
+export function bindSessionBearer(sessionId, bearerToken) {
+  sessionBearers.set(sessionId, bearerToken);
+  console.log(`[Auth] Bearer bound for session ${sessionId} (bearer: ${bearerToken.substring(0, 25)}...)`);
+}
+
+/** Store ateam_auth override for this user (by bearer). Called from tools.js. */
+export function setAuthOverride(sessionId, { tenant, apiKey, apiUrl }) {
+  const bearer = sessionBearers.get(sessionId);
+  if (!bearer) {
+    console.log(`[Auth] WARNING: No bearer bound for session ${sessionId} — override NOT stored. sessionBearers has ${sessionBearers.size} entries.`);
+    return;
+  }
+  authOverrides.set(bearer, { tenant, apiKey, apiUrl: apiUrl || null, updatedAt: Date.now() });
+  console.log(`[Auth] Override stored for bearer (tenant: ${tenant}${apiUrl ? ", url: " + apiUrl : ""})`);
+}
+
+/** Get ateam_auth override for a bearer token. Returns null if none/expired. */
+export function getAuthOverride(bearerToken) {
+  const entry = authOverrides.get(bearerToken);
+  if (!entry) return null;
+  if (Date.now() - entry.updatedAt > SESSION_TTL) {
+    authOverrides.delete(bearerToken);
+    return null;
+  }
+  return { tenant: entry.tenant, apiKey: entry.apiKey, apiUrl: entry.apiUrl || null };
+}
+
+/**
+ * Get the base URL for a session. Resolution order:
+ *   1. Per-session apiUrl (set via ateam_auth url parameter)
+ *   2. Bearer auth override apiUrl
+ *   3. Environment variable ADAS_API_URL
+ *   4. Default: https://api.ateam-ai.com
+ */
+export function getBaseUrl(sessionId) {
+  // 1. Per-session
+  const session = sessionId ? sessions.get(sessionId) : null;
+  if (session?.apiUrl) return session.apiUrl;
+  // 2. Bearer override
+  if (sessionId) {
+    const bearer = sessionBearers.get(sessionId);
+    if (bearer) {
+      const override = getAuthOverride(bearer);
+      if (override?.apiUrl) return override.apiUrl;
+    }
+  }
+  // 3/4. Env or default
+  return BASE_URL;
+}
+
+/** Check if a bearer has an active auth override. */
+export function hasBearerAuth(sessionId) {
+  const bearer = sessionBearers.get(sessionId);
+  return bearer ? authOverrides.has(bearer) : false;
+}
+
 /**
  * Sweep expired sessions — removes sessions idle longer than SESSION_TTL.
  * Returns the number of sessions removed.
@@ -146,12 +249,21 @@ export function sweepStaleSessions() {
   let swept = 0;
   for (const [sid, session] of sessions) {
     if (now - session.lastActivity > SESSION_TTL) {
+      sessionBearers.delete(sid);
       sessions.delete(sid);
       swept++;
     }
   }
-  if (swept > 0) {
-    console.log(`[Session] Swept ${swept} stale session(s). ${sessions.size} active.`);
+  // Also sweep expired auth overrides
+  let overridesSwept = 0;
+  for (const [bearer, entry] of authOverrides) {
+    if (now - entry.updatedAt > SESSION_TTL) {
+      authOverrides.delete(bearer);
+      overridesSwept++;
+    }
+  }
+  if (swept > 0 || overridesSwept > 0) {
+    console.log(`[Session] Swept ${swept} session(s), ${overridesSwept} override(s). ${sessions.size} active, ${authOverrides.size} overrides.`);
   }
   return swept;
 }
@@ -186,6 +298,17 @@ export function getSessionStats() {
 }
 
 function headers(sessionId) {
+  const session = sessionId ? sessions.get(sessionId) : null;
+
+  // Master mode: use shared secret auth (x-adas-token) instead of API key
+  if (session?.masterKey) {
+    const h = { "Content-Type": "application/json" };
+    h["x-adas-token"] = session.masterKey;
+    h["X-ADAS-TENANT"] = session.tenant || "main";
+    return h;
+  }
+
+  // Normal mode: API key auth
   const { tenant, apiKey } = getCredentials(sessionId);
   const h = { "Content-Type": "application/json" };
   if (tenant) h["X-ADAS-TENANT"] = tenant;
@@ -232,6 +355,7 @@ async function request(method, path, body, sessionId, opts = {}) {
   const timeoutMs = opts.timeoutMs || REQUEST_TIMEOUT_MS;
   const controller = new AbortController();
   const timeout = setTimeout(() => controller.abort(), timeoutMs);
+  const baseUrl = getBaseUrl(sessionId);
 
   try {
     const fetchOpts = {
@@ -243,7 +367,7 @@ async function request(method, path, body, sessionId, opts = {}) {
       fetchOpts.body = JSON.stringify(body);
     }
 
-    const res = await fetch(`${BASE_URL}${path}`, fetchOpts);
+    const res = await fetch(`${baseUrl}${path}`, fetchOpts);
 
     if (!res.ok) {
       const text = await res.text().catch(() => "");
@@ -255,18 +379,18 @@ async function request(method, path, body, sessionId, opts = {}) {
     if (err.name === "AbortError") {
       throw new Error(
         `A-Team API timeout: ${method} ${path} did not respond within ${timeoutMs / 1000}s.\n` +
-        `Hint: The A-Team API at ${BASE_URL} may be down. Check https://api.ateam-ai.com/health`
+        `Hint: The A-Team API at ${baseUrl} may be down. Check ${baseUrl}/health`
       );
     }
     if (err.cause?.code === "ECONNREFUSED") {
       throw new Error(
-        `Cannot connect to A-Team API at ${BASE_URL}.\n` +
-        `Hint: The service may be down. Check https://api.ateam-ai.com/health`
+        `Cannot connect to A-Team API at ${baseUrl}.\n` +
+        `Hint: The service may be down. Check ${baseUrl}/health`
       );
     }
     if (err.cause?.code === "ENOTFOUND") {
       throw new Error(
-        `Cannot resolve A-Team API host: ${BASE_URL}.\n` +
+        `Cannot resolve A-Team API host: ${baseUrl}.\n` +
         `Hint: Check your internet connection and ADAS_API_URL setting.`
       );
     }
@@ -291,3 +415,36 @@ export async function patch(path, body, sessionId, opts) {
 export async function del(path, sessionId, opts) {
   return request("DELETE", path, undefined, sessionId, opts);
 }
+
+/**
+ * List all active tenants from Core API (requires master key).
+ * Calls Core directly (not through Builder) using shared secret auth.
+ */
+export async function listTenants(sessionId) {
+  const session = sessionId ? sessions.get(sessionId) : null;
+  if (!session?.masterKey) throw new Error("listTenants requires master key auth");
+
+  // Resolve Core URL: env var > derive from Builder URL > fallback
+  const coreUrl = CORE_URL || BASE_URL.replace(/:\d+$/, ":4000");
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+
+  try {
+    const res = await fetch(`${coreUrl}/api/tenants/list`, {
+      method: "GET",
+      headers: {
+        "Content-Type": "application/json",
+        "x-adas-token": session.masterKey,
+      },
+      signal: controller.signal,
+    });
+    if (!res.ok) {
+      const text = await res.text().catch(() => "");
+      throw new Error(`Core API error: GET /api/tenants/list returned ${res.status} — ${text}`);
+    }
+    const data = await res.json();
+    return data.tenants || [];
+  } finally {
+    clearTimeout(timeout);
+  }
+}

package/src/http.js

@@ -26,6 +26,7 @@ import { createServer } from "./server.js";
 import {
   clearSession, setSessionCredentials, parseApiKey,
   startSessionSweeper, getSessionStats, sweepStaleSessions,
+  bindSessionBearer, getAuthOverride,
 } from "./api.js";
 import { mountOAuth } from "./oauth.js";
 
@@ -197,8 +198,13 @@ export function startHttpServer(port = 3100) {
         // Reuse existing session — seed credentials if Bearer token present
         transport = transports[sessionId];
         seedCredentials(req, sessionId);
-      } else if (!sessionId && isInitializeRequest(req.body)) {
-        // New session — generate ID upfront so we can bind it to the server
+      } else if (isInitializeRequest(req.body)) {
+        // New session (or stale session after server restart) — create fresh session.
+        // Accept initialize requests even if they carry a stale mcp-session-id.
+        if (sessionId) {
+          console.log(`[HTTP] Stale session ${sessionId} — creating new session (server was restarted)`);
+        }
+
         const newSessionId = randomUUID();
 
         // Seed credentials from OAuth Bearer token before server starts
@@ -224,6 +230,16 @@ export function startHttpServer(port = 3100) {
         await server.connect(transport);
         await transport.handleRequest(req, res, req.body);
         return;
+      } else if (sessionId && !transports[sessionId]) {
+        // Stale session (non-initialize request) — tell client to re-initialize.
+        // This happens after server restarts when the client still has the old session ID.
+        console.log(`[HTTP] Stale session ${sessionId} — returning 400 to trigger re-init`);
+        res.status(400).json({
+          jsonrpc: "2.0",
+          error: { code: -32600, message: "Session expired. Please re-initialize." },
+          id: req.body?.id || null,
+        });
+        return;
       } else {
         res.status(400).json({
           jsonrpc: "2.0",
@@ -326,13 +342,27 @@ function getNewestToken() {
 }
 
 /**
- * If the request has a validated Bearer token (set by requireBearerAuth),
- * auto-seed session credentials so the user doesn't need to call ateam_auth.
+ * Seed session credentials from the OAuth bearer token.
+ *
+ * The bearer IS the user's API key (set during OAuth authorization).
+ * If the user previously called ateam_auth to override (e.g., switch tenants),
+ * that override is stored per bearer and takes priority here.
  */
 function seedCredentials(req, sessionId) {
   const token = req.auth?.token;
   if (!token) return;
 
+  // Track bearer → session (persistent actor identity)
+  bindSessionBearer(sessionId, token);
+
+  // Check for ateam_auth override for this bearer
+  const override = getAuthOverride(token);
+  if (override) {
+    setSessionCredentials(sessionId, { ...override, explicit: true });
+    return;
+  }
+
+  // Default: use the bearer token itself as credentials
   const parsed = parseApiKey(token);
   if (parsed.isValid) {
     setSessionCredentials(sessionId, { tenant: parsed.tenant, apiKey: token });

package/src/tools.js

@@ -12,6 +12,7 @@ import {
   get, post, patch, del,
   setSessionCredentials, isAuthenticated, isExplicitlyAuthenticated,
   getCredentials, parseApiKey, touchSession, getSessionContext,
+  setAuthOverride, switchTenant, isMasterMode, listTenants,
 } from "./api.js";
 
 // ─── Tool definitions ───────────────────────────────────────────────
@@ -35,7 +36,7 @@ export const tools = [
     name: "ateam_auth",
     core: true,
     description:
-      "Authenticate with A-Team. Required before any tenant-aware operation (reading solutions, deploying, testing, etc.). The user can get their API key at https://mcp.ateam-ai.com/get-api-key. Only global endpoints (spec, examples, validate) work without auth. IMPORTANT: Even if environment variables (ADAS_API_KEY) are configured, you MUST call ateam_auth explicitly — env vars alone are not sufficient.",
+      "Authenticate with A-Team. Required before any tenant-aware operation (reading solutions, deploying, testing, etc.). The user can get their API key at https://mcp.ateam-ai.com/get-api-key. Only global endpoints (spec, examples, validate) work without auth. IMPORTANT: Even if environment variables (ADAS_API_KEY) are configured, you MUST call ateam_auth explicitly — env vars alone are not sufficient. For cross-tenant admin operations, use master_key instead of api_key.",
     inputSchema: {
       type: "object",
       properties: {
@@ -43,12 +44,19 @@ export const tools = [
           type: "string",
           description: "Your A-Team API key (e.g., adas_xxxxx)",
         },
+        master_key: {
+          type: "string",
+          description: "Master key for cross-tenant operations. Authenticates across ALL tenants without per-tenant API keys. Requires tenant parameter.",
+        },
         tenant: {
           type: "string",
-          description: "Tenant name (e.g., dev, main). Optional if your key has the format adas_<tenant>_<hex> — the tenant is auto-extracted.",
+          description: "Tenant name (e.g., dev, main). Optional with api_key if format is adas_<tenant>_<hex>. REQUIRED with master_key.",
+        },
+        url: {
+          type: "string",
+          description: "Optional API URL override (e.g., https://dev-api.ateam-ai.com). Use this to target a different environment without restarting the MCP server.",
         },
       },
-      required: ["api_key"],
     },
   },
   {
@@ -61,9 +69,9 @@ export const tools = [
       properties: {
         topic: {
           type: "string",
-          enum: ["overview", "skill", "solution", "enums"],
+          enum: ["overview", "skill", "solution", "enums", "connector-multi-user"],
           description:
-            "What to fetch: 'overview' = API overview + endpoints, 'skill' = full skill spec, 'solution' = full solution spec, 'enums' = all enum values",
+            "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 (actor isolation, zod gotcha, complete examples)",
         },
       },
       required: ["topic"],
@@ -123,6 +131,10 @@ export const tools = [
           type: "object",
           description: "Optional: connector source code files. Key = connector id, value = array of {path, content}.",
         },
+        github: {
+          type: "boolean",
+          description: "Optional: if true, pull connector source code from the solution's GitHub repo instead of requiring mcp_store. Use this after the first deploy (which creates the repo). Cannot be used on first deploy.",
+        },
         test_message: {
           type: "string",
           description: "Optional: send a test message after deployment to verify the skill works. Returns the full execution result.",
@@ -164,6 +176,63 @@ export const tools = [
       required: ["solution_id", "skill_id", "message"],
     },
   },
+  {
+    name: "ateam_test_pipeline",
+    core: true,
+    description:
+      "Test the decision pipeline (intent detection → planning) for a skill WITHOUT executing tools. Returns intent classification, first planned action, and timing. Use this to debug why a skill classifies intent incorrectly or plans the wrong action.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        solution_id: {
+          type: "string",
+          description: "The solution ID",
+        },
+        skill_id: {
+          type: "string",
+          description: "The skill ID to test",
+        },
+        message: {
+          type: "string",
+          description: "The test message to classify and plan for",
+        },
+      },
+      required: ["solution_id", "skill_id", "message"],
+    },
+  },
+  {
+    name: "ateam_test_voice",
+    core: true,
+    description:
+      "Simulate a voice conversation with a deployed solution. Runs the full voice pipeline (session → caller verification → prompt → skill dispatch → response) using text instead of audio. Returns each turn with bot response, verification status, tool calls, and entities. Use this to test voice-enabled solutions end-to-end without making a phone call.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        solution_id: {
+          type: "string",
+          description: "The solution ID",
+        },
+        messages: {
+          type: "array",
+          items: { type: "string" },
+          description: "Array of user messages to send sequentially (simulates a multi-turn phone conversation)",
+        },
+        phone_number: {
+          type: "string",
+          description: "Optional: simulated caller phone number (e.g., '+14155551234'). If the number is in the solution's known phones list, the caller is auto-verified.",
+        },
+        skill_slug: {
+          type: "string",
+          description: "Optional: target a specific skill by slug instead of using voice routing.",
+        },
+        timeout_ms: {
+          type: "number",
+          description: "Optional: max wait time per skill execution in milliseconds (default: 60000).",
+        },
+      },
+      required: ["solution_id", "messages"],
+    },
+  },
   {
     name: "ateam_patch",
     core: true,
@@ -249,6 +318,26 @@ export const tools = [
       required: ["solution_id"],
     },
   },
+  {
+    name: "ateam_delete_connector",
+    core: true,
+    description:
+      "Remove a connector from a deployed solution. Stops and deletes it from A-Team Core, removes references from the solution definition (grants, platform_connectors) and skill definitions (connectors array), and cleans up mcp-store files.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        solution_id: {
+          type: "string",
+          description: "The solution ID (e.g. 'smart-home-assistant')",
+        },
+        connector_id: {
+          type: "string",
+          description: "The connector ID to remove (e.g. 'device-mock-mcp')",
+        },
+      },
+      required: ["solution_id", "connector_id"],
+    },
+  },
 
   // ═══════════════════════════════════════════════════════════════════
   // ADVANCED TOOLS — hidden from tools/list, still callable by name
@@ -535,19 +624,19 @@ export const tools = [
   },
   {
     name: "ateam_get_connector_source",
-    core: false,
+    core: true,
     description:
-      "Read the source code of a connector's MCP server. Returns the files that make up the connector implementation. (Advanced.)",
+      `Read the source code files of a deployed MCP connector. Returns all files (server.js, package.json, etc.) stored in the mcp_store for this connector. Use this BEFORE patching or rewriting a connector — always read the current code first so you can make surgical fixes instead of blind full rewrites.`,
     inputSchema: {
       type: "object",
       properties: {
         solution_id: {
           type: "string",
-          description: "The solution ID",
+          description: "The solution ID (e.g. 'smart-home-assistant')",
         },
         connector_id: {
           type: "string",
-          description: "The connector ID",
+          description: "The connector ID to read (e.g. 'home-assistant-mcp')",
         },
       },
       required: ["solution_id", "connector_id"],
@@ -597,6 +686,181 @@ export const tools = [
       required: ["solution_id"],
     },
   },
+
+  // ═══════════════════════════════════════════════════════════════════
+  // GITHUB TOOLS — version control for solutions
+  // ═══════════════════════════════════════════════════════════════════
+
+  {
+    name: "ateam_github_push",
+    core: true,
+    description:
+      "Push the current deployed solution to GitHub. Auto-creates the repo on first use. Commits the full bundle (solution + skills + connector source) atomically. Use after ateam_build_and_run to version your solution, or anytime you want to snapshot the current state.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        solution_id: {
+          type: "string",
+          description: "The solution ID (e.g. 'smart-home-assistant')",
+        },
+        message: {
+          type: "string",
+          description: "Optional commit message (default: 'Deploy <solution_id>')",
+        },
+      },
+      required: ["solution_id"],
+    },
+  },
+  {
+    name: "ateam_github_pull",
+    core: true,
+    description:
+      "Deploy a solution FROM its GitHub repo. Reads .ateam/export.json + connector source from the repo and feeds it into the deploy pipeline. Use this to restore a previous version or deploy from GitHub as the source of truth.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        solution_id: {
+          type: "string",
+          description: "The solution ID to pull and deploy from GitHub",
+        },
+      },
+      required: ["solution_id"],
+    },
+  },
+  {
+    name: "ateam_github_status",
+    core: true,
+    description:
+      "Check if a solution has a GitHub repo, its URL, and the latest commit. Use this to verify GitHub integration is working for a solution.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        solution_id: {
+          type: "string",
+          description: "The solution ID",
+        },
+      },
+      required: ["solution_id"],
+    },
+  },
+  {
+    name: "ateam_github_read",
+    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. Great for reviewing previous versions or understanding what's in the repo.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        solution_id: {
+          type: "string",
+          description: "The solution ID",
+        },
+        path: {
+          type: "string",
+          description: "File path in the repo (e.g. 'connectors/home-assistant-mcp/server.js', 'solution.json', 'skills/order-support/skill.json')",
+        },
+      },
+      required: ["solution_id", "path"],
+    },
+  },
+  {
+    name: "ateam_github_patch",
+    core: true,
+    description:
+      "Edit a specific file in the solution's GitHub repo and commit. Creates the file if it doesn't exist. Use this to make surgical fixes to connector source code, update skill definitions, or add new files directly in the repo.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        solution_id: {
+          type: "string",
+          description: "The solution ID",
+        },
+        path: {
+          type: "string",
+          description: "File path to create/update (e.g. 'connectors/home-assistant-mcp/server.js')",
+        },
+        content: {
+          type: "string",
+          description: "The full file content to write",
+        },
+        message: {
+          type: "string",
+          description: "Optional commit message (default: 'Update <path>')",
+        },
+      },
+      required: ["solution_id", "path", "content"],
+    },
+  },
+  {
+    name: "ateam_github_log",
+    core: true,
+    description:
+      "View commit history for a solution's GitHub repo. Shows recent commits with messages, SHAs, timestamps, and links. Use this to see what changes have been made and when.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        solution_id: {
+          type: "string",
+          description: "The solution ID",
+        },
+        limit: {
+          type: "number",
+          description: "Max commits to return (default: 10)",
+        },
+      },
+      required: ["solution_id"],
+    },
+  },
+
+  // ═══════════════════════════════════════════════════════════════════
+  // MASTER KEY TOOLS — cross-tenant bulk operations (master key only)
+  // ═══════════════════════════════════════════════════════════════════
+
+  {
+    name: "ateam_redeploy",
+    core: true,
+    description:
+      "Re-deploy all skills in a solution without changing anything. Regenerates MCP servers and pushes to A-Team Core. Use after connector restarts, Core hiccups, or when you just need a fresh deploy without modifying the solution/skill definitions.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        solution_id: {
+          type: "string",
+          description: "The solution ID to redeploy (e.g. 'smart-home-assistant')",
+        },
+      },
+      required: ["solution_id"],
+    },
+  },
+  {
+    name: "ateam_status_all",
+    core: true,
+    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: {
+      type: "object",
+      properties: {},
+    },
+  },
+  {
+    name: "ateam_sync_all",
+    core: true,
+    description:
+      "Sync ALL tenants: push Builder FS → GitHub, then pull GitHub → Core MongoDB. Requires master key authentication. Returns a summary table with results for each tenant/solution.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        push_only: {
+          type: "boolean",
+          description: "Only push to GitHub (skip pull to Core). Default: false (full sync).",
+        },
+        pull_only: {
+          type: "boolean",
+          description: "Only pull from GitHub to Core (skip push). Default: false (full sync).",
+        },
+      },
+    },
+  },
 ];
 
 /**
@@ -612,6 +876,7 @@ const SPEC_PATHS = {
   skill: "/spec/skill",
   solution: "/spec/solution",
   enums: "/spec/enums",
+  "connector-multi-user": "/spec/multi-user-connector",
 };
 
 const EXAMPLE_PATHS = {
@@ -637,17 +902,31 @@ const TENANT_TOOLS = new Set([
   "ateam_update",
   "ateam_redeploy",
   "ateam_delete_solution",
+  "ateam_delete_connector",
+  "ateam_redeploy",
   "ateam_solution_chat",
   // Read operations (tenant-specific data)
   "ateam_list_solutions",
   "ateam_get_solution",
   "ateam_get_execution_logs",
   "ateam_test_skill",
+  "ateam_test_pipeline",
+  "ateam_test_voice",
   "ateam_test_status",
   "ateam_test_abort",
   "ateam_get_connector_source",
   "ateam_get_metrics",
   "ateam_diff",
+  // GitHub operations
+  "ateam_github_push",
+  "ateam_github_pull",
+  "ateam_github_status",
+  "ateam_github_read",
+  "ateam_github_patch",
+  "ateam_github_log",
+  // Master key bulk operations
+  "ateam_status_all",
+  "ateam_sync_all",
 ]);
 
 /** Small delay helper */
@@ -676,12 +955,13 @@ const handlers = {
       { name: "Enterprise Compliance Platform", description: "Approval flows, audit logs, policy enforcement" },
     ],
     developer_loop: {
-      _note: "This is the recommended build loop. Only 4 steps from definition to running skill.",
+      _note: "This is the recommended build loop. 5 steps from definition to running skill with GitHub version control.",
       steps: [
         { step: 1, action: "Learn", description: "Get the spec and study examples", tools: ["ateam_get_spec", "ateam_get_examples"] },
-        { step: 2, action: "Build & Run", description: "Define your solution + skills, then validate, deploy, and health-check in one call. Optionally include a test_message to verify it works immediately.", tools: ["ateam_build_and_run"] },
-        { step: 3, action: "Test", description: "Send test messages to your deployed skill and see the full execution trace.", tools: ["ateam_test_skill"] },
-        { step: 4, action: "Iterate", description: "Patch the skill (update + redeploy + re-test in one call), repeat until satisfied.", tools: ["ateam_patch"] },
+        { step: 2, action: "Build & Run", description: "Define your solution + skills + connector code, then validate, deploy, and health-check in one call. Include mcp_store with connector source code on the first deploy.", tools: ["ateam_build_and_run"] },
+        { step: 3, action: "Version", description: "Every deploy auto-pushes to GitHub. The repo (tenant--solution-id) is the source of truth for connector code.", tools: ["ateam_github_status", "ateam_github_log"] },
+        { step: 4, action: "Iterate", description: "Edit connector code via ateam_github_patch, then redeploy with ateam_build_and_run(github:true). For skill definition changes (intents, tools, policy), use ateam_patch.", tools: ["ateam_github_patch", "ateam_build_and_run", "ateam_patch"] },
+        { step: 5, action: "Test & Debug", description: "Test the decision pipeline or full execution, then diagnose with logs and metrics. For voice-enabled solutions, use ateam_test_voice to simulate phone conversations.", tools: ["ateam_test_pipeline", "ateam_test_skill", "ateam_test_voice", "ateam_get_execution_logs", "ateam_get_metrics"] },
       ],
     },
     first_questions: [
@@ -690,6 +970,27 @@ const handlers = {
       { id: "systems", question: "Which systems should the Team connect to?", type: "multi_select", options: ["slack", "email", "zendesk", "shopify", "jira", "postgres", "custom_api", "none"] },
       { id: "security", question: "What environment constraints?", type: "enum", options: ["sandbox", "controlled", "regulated"] },
     ],
+    github_tools: {
+      _note: "Version control for solutions. Every deploy auto-pushes to GitHub. The repo is the source of truth for connector code.",
+      tools: ["ateam_github_push", "ateam_github_pull", "ateam_github_status", "ateam_github_read", "ateam_github_patch", "ateam_github_log"],
+      repo_structure: {
+        "solution.json": "Full solution definition",
+        "skills/{skill-id}/skill.json": "Individual skill definitions",
+        "connectors/{connector-id}/server.js": "Connector MCP server code",
+        "connectors/{connector-id}/package.json": "Connector dependencies",
+      },
+      iteration_workflow: {
+        code_changes: "ateam_github_patch (edit connector files) → ateam_build_and_run(github:true) (redeploy from repo)",
+        definition_changes: "ateam_patch (edit skill/solution definitions directly in Builder)",
+        first_deploy: "Must include mcp_store — this creates the GitHub repo",
+      },
+      when_to_use_what: {
+        ateam_github_patch: "Edit connector source code (server.js, utils, package.json, UI assets)",
+        ateam_patch: "Edit skill definitions (intents, tools, policy) or solution definitions (grants, handoffs, routing)",
+        "ateam_build_and_run(github:true)": "Redeploy solution pulling latest connector code from GitHub",
+        "ateam_build_and_run(mcp_store)": "First deploy or when you want to pass connector code inline",
+      },
+    },
     advanced_tools: {
       _note: "These tools are available but hidden from the default tool list. Call them by name when you need fine-grained control.",
       debugging: ["ateam_get_execution_logs", "ateam_get_metrics", "ateam_diff", "ateam_get_connector_source"],
@@ -728,7 +1029,8 @@ const handlers = {
       always: [
         "Explain Skill vs Solution vs Connector before building",
         "Use ateam_build_and_run for the full lifecycle (validates automatically)",
-        "Use ateam_patch for iterations (updates + redeploys automatically)",
+        "Use ateam_patch for skill/solution definition changes (updates + redeploys automatically)",
+        "Use ateam_github_patch + ateam_build_and_run(github:true) for connector code changes after first deploy",
         "Study the connector example (ateam_get_examples type='connector') before writing connector code",
         "Ask discovery questions if goal unclear",
       ],
@@ -741,21 +1043,52 @@ const handlers = {
     },
   }),
 
-  ateam_auth: async ({ api_key, tenant }, sessionId) => {
+  ateam_auth: async ({ api_key, master_key, tenant, url }, sessionId) => {
+    // Master key mode: cross-tenant auth using shared secret
+    if (master_key) {
+      if (!tenant) {
+        return { ok: false, message: "Master key requires a tenant parameter. Specify which tenant to operate on." };
+      }
+      const apiUrl = url ? url.replace(/\/+$/, "") : undefined;
+      setSessionCredentials(sessionId, { tenant, apiKey: null, apiUrl, explicit: true, masterKey: master_key });
+      // Verify by listing solutions
+      try {
+        const result = await get("/deploy/solutions", sessionId);
+        const urlNote = apiUrl ? ` (via ${apiUrl})` : "";
+        return {
+          ok: true,
+          tenant,
+          masterMode: true,
+          message: `Master key authenticated to tenant "${tenant}"${urlNote}. ${result.solutions?.length || 0} solution(s) found. Use tenant parameter on any tool to switch tenants without re-auth.`,
+        };
+      } catch (err) {
+        return { ok: false, tenant, message: `Master key auth failed: ${err.message}` };
+      }
+    }
+
+    // Normal API key mode
+    if (!api_key) {
+      return { ok: false, message: "Provide either api_key or master_key." };
+    }
     // Auto-extract tenant from key if not provided
     let resolvedTenant = tenant;
     if (!resolvedTenant) {
       const parsed = parseApiKey(api_key);
       resolvedTenant = parsed.tenant || "main";
     }
-    setSessionCredentials(sessionId, { tenant: resolvedTenant, apiKey: api_key });
+    // Normalize URL: strip trailing slash
+    const apiUrl = url ? url.replace(/\/+$/, "") : undefined;
+    setSessionCredentials(sessionId, { tenant: resolvedTenant, apiKey: api_key, apiUrl, explicit: true });
+    // Persist override per bearer (survives session changes)
+    setAuthOverride(sessionId, { tenant: resolvedTenant, apiKey: api_key, apiUrl });
     // Verify the key works by listing solutions
     try {
       const result = await get("/deploy/solutions", sessionId);
+      const urlNote = apiUrl ? ` (via ${apiUrl})` : "";
       return {
         ok: true,
         tenant: resolvedTenant,
-        message: `Authenticated to tenant "${resolvedTenant}". ${result.solutions?.length || 0} solution(s) found.`,
+        message: `Authenticated to tenant "${resolvedTenant}"${urlNote}. ${result.solutions?.length || 0} solution(s) found.`,
       };
     } catch (err) {
       return {
@@ -776,13 +1109,49 @@ const handlers = {
   // Validates → Deploys → Health-checks → Optionally tests
   // One call replaces: validate_solution + deploy_solution + get_solution(health)
 
-  ateam_build_and_run: async ({ solution, skills, connectors, mcp_store, test_message, test_skill_id }, sid) => {
+  ateam_build_and_run: async ({ solution, skills, connectors, mcp_store, github, test_message, test_skill_id }, sid) => {
     const phases = [];
 
+    // Phase 0: GitHub pull (if github:true — pull connector source from repo)
+    let effectiveMcpStore = mcp_store;
+    if (github && !mcp_store) {
+      try {
+        const pullResult = await post(
+          `/deploy/solutions/${solution.id}/github/pull-connectors`,
+          {},
+          sid,
+          { timeoutMs: 30_000 },
+        );
+        if (!pullResult.ok) {
+          return {
+            ok: false,
+            phase: "github_pull",
+            error: pullResult.error || "Failed to pull connectors from GitHub",
+            hint: pullResult.hint || "Deploy the solution first (with mcp_store) to auto-create the GitHub repo.",
+            message: "Cannot pull connector code from GitHub. The repo may not exist yet — deploy with mcp_store first.",
+          };
+        }
+        effectiveMcpStore = pullResult.mcp_store;
+        phases.push({
+          phase: "github_pull",
+          status: "done",
+          connectors_found: pullResult.connectors_found || 0,
+          files_loaded: pullResult.files_loaded || 0,
+        });
+      } catch (err) {
+        return {
+          ok: false,
+          phase: "github_pull",
+          error: err.message,
+          message: "Failed to pull connector code from GitHub. The repo may not exist yet — deploy with mcp_store first.",
+        };
+      }
+    }
+
     // Phase 1: Validate
     let validation;
     try {
-      validation = await post("/validate/solution", { solution, skills }, sid);
+      validation = await post("/validate/solution", { solution, skills, connectors, mcp_store: effectiveMcpStore }, sid, { timeoutMs: 120_000 });
       phases.push({ phase: "validate", status: "done" });
     } catch (err) {
       return {
@@ -808,7 +1177,7 @@ const handlers = {
     // Phase 2: Deploy
     let deploy;
     try {
-      deploy = await post("/deploy/solution", { solution, skills, connectors, mcp_store }, sid);
+      deploy = await post("/deploy/solution", { solution, skills, connectors, mcp_store: effectiveMcpStore }, sid, { timeoutMs: 300_000 });
       phases.push({ phase: "deploy", status: deploy.ok ? "done" : "failed" });
     } catch (err) {
       return {
@@ -863,6 +1232,25 @@ const handlers = {
       }
     }
 
+    // Phase 5: GitHub push (auto — non-blocking, failures don't fail the deploy)
+    let github_result;
+    try {
+      github_result = await post(
+        `/deploy/solutions/${solution.id}/github/push`,
+        { message: `Deploy: ${solution.name || solution.id}` },
+        sid,
+        { timeoutMs: 60_000 },
+      );
+      phases.push({
+        phase: "github",
+        status: github_result.skipped ? "skipped" : "done",
+        ...(github_result.repo_url && { repo_url: github_result.repo_url }),
+      });
+    } catch (err) {
+      github_result = { error: err.message };
+      phases.push({ phase: "github", status: "error", error: err.message });
+    }
+
     return {
       ok: true,
       solution_id: solution.id,
@@ -875,6 +1263,7 @@ const handlers = {
       },
       health,
       ...(test_result && { test_result }),
+      ...(github_result && !github_result.error && !github_result.skipped && { github: github_result }),
       ...(validation.warnings?.length > 0 && { validation_warnings: validation.warnings }),
     };
   },
@@ -956,8 +1345,8 @@ const handlers = {
 
   ateam_validate_skill: async ({ skill }, sid) => post("/validate/skill", { skill }, sid),
 
-  ateam_validate_solution: async ({ solution, skills }, sid) =>
-    post("/validate/solution", { solution, skills }, sid),
+  ateam_validate_solution: async ({ solution, skills, connectors, mcp_store }, sid) =>
+    post("/validate/solution", { solution, skills, connectors, mcp_store }, sid),
 
   ateam_deploy_solution: async ({ solution, skills, connectors, mcp_store }, sid) =>
     post("/deploy/solution", { solution, skills, connectors, mcp_store }, sid),
@@ -1042,6 +1431,20 @@ const handlers = {
     return post(`/deploy/solutions/${solution_id}/skills/${skill_id}/test`, body, sid, { timeoutMs });
   },
 
+  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 }),
+
+  ateam_test_voice: async ({ solution_id, messages, phone_number, skill_slug, timeout_ms }, sid) => {
+    const body = { messages };
+    if (phone_number) body.phone_number = phone_number;
+    if (skill_slug) body.skill_slug = skill_slug;
+    if (timeout_ms) body.timeout_ms = timeout_ms;
+    // Timeout scales with message count — each turn may invoke skills
+    const perTurnMs = timeout_ms || 60_000;
+    const timeoutTotal = Math.min(perTurnMs * messages.length + 30_000, 600_000);
+    return post(`/deploy/voice-test`, body, sid, { timeoutMs: timeoutTotal });
+  },
+
   ateam_test_status: async ({ solution_id, skill_id, job_id }, sid) =>
     get(`/deploy/solutions/${solution_id}/skills/${skill_id}/test/${job_id}`, sid),
 
@@ -1064,8 +1467,130 @@ const handlers = {
     return get(`/deploy/solutions/${solution_id}/diff${qs}`, sid);
   },
 
+  // ─── GitHub tools ──────────────────────────────────────────────────
+
+  ateam_github_push: async ({ solution_id, message }, sid) =>
+    post(`/deploy/solutions/${solution_id}/github/push`, { message }, sid, { timeoutMs: 60_000 }),
+
+  ateam_github_pull: async ({ solution_id }, sid) =>
+    post(`/deploy/solutions/${solution_id}/github/pull`, {}, sid, { timeoutMs: 300_000 }),
+
+  ateam_github_status: async ({ solution_id }, sid) =>
+    get(`/deploy/solutions/${solution_id}/github/status`, sid),
+
+  ateam_github_read: async ({ solution_id, path: filePath }, sid) =>
+    get(`/deploy/solutions/${solution_id}/github/read?path=${encodeURIComponent(filePath)}`, sid),
+
+  ateam_github_patch: async ({ solution_id, path: filePath, content, message }, sid) =>
+    post(`/deploy/solutions/${solution_id}/github/patch`, { path: filePath, content, message }, sid),
+
+  ateam_github_log: async ({ solution_id, limit }, sid) => {
+    const qs = limit ? `?limit=${limit}` : "";
+    return get(`/deploy/solutions/${solution_id}/github/log${qs}`, sid);
+  },
+
   ateam_delete_solution: async ({ solution_id }, sid) =>
     del(`/deploy/solutions/${solution_id}`, sid),
+
+  ateam_delete_connector: async ({ solution_id, connector_id }, sid) =>
+    del(`/deploy/solutions/${solution_id}/connectors/${connector_id}`, sid),
+
+  ateam_redeploy: async ({ solution_id }, sid) => {
+    const result = await post(`/deploy/solutions/${solution_id}/redeploy`, {}, sid, { timeoutMs: 300_000 });
+    return {
+      ok: result.ok,
+      solution_id,
+      deployed: result.deployed || 0,
+      failed: result.failed || 0,
+      total: result.total || 0,
+      skills: result.skills || [],
+      message: result.ok
+        ? `Re-deployed ${result.deployed || 0} skill(s) successfully.`
+        : `Re-deploy had ${result.failed || 0} failure(s). Check skills array for details.`,
+    };
+  },
+
+  // ─── Master Key Bulk Tools ───────────────────────────────────────────
+
+  ateam_status_all: async (_args, sid) => {
+    if (!isMasterMode(sid)) {
+      return { ok: false, message: "Master key required. Call ateam_auth(master_key: \"<key>\", tenant: \"<any>\") first." };
+    }
+    const tenants = await listTenants(sid);
+    const results = [];
+    for (const t of tenants) {
+      switchTenant(sid, t.id);
+      try {
+        const { solutions } = await get("/deploy/solutions", sid);
+        for (const sol of (solutions || [])) {
+          let ghStatus = null;
+          try {
+            ghStatus = await get(`/deploy/solutions/${sol.id}/github/status`, sid);
+          } catch { /* no github config */ }
+          results.push({
+            tenant: t.id,
+            solution: sol.id,
+            name: sol.name || sol.id,
+            github: ghStatus ? {
+              repo: ghStatus.repo || ghStatus.repoUrl,
+              lastCommit: ghStatus.lastCommit?.message?.slice(0, 60),
+              lastPush: ghStatus.lastCommit?.date,
+              branch: ghStatus.branch,
+            } : "not configured",
+          });
+        }
+      } catch (err) {
+        results.push({ tenant: t.id, error: err.message });
+      }
+    }
+    return { ok: true, tenants: tenants.length, solutions: results.length, results };
+  },
+
+  ateam_sync_all: async ({ push_only, pull_only }, sid) => {
+    if (!isMasterMode(sid)) {
+      return { ok: false, message: "Master key required. Call ateam_auth(master_key: \"<key>\", tenant: \"<any>\") first." };
+    }
+    const tenants = await listTenants(sid);
+    const results = [];
+    for (const t of tenants) {
+      switchTenant(sid, t.id);
+      try {
+        const { solutions } = await get("/deploy/solutions", sid);
+        for (const sol of (solutions || [])) {
+          const entry = { tenant: t.id, solution: sol.id, name: sol.name || sol.id };
+          // Push: Builder FS → GitHub
+          if (!pull_only) {
+            try {
+              const pushResult = await post(`/deploy/solutions/${sol.id}/github/push`, {}, sid);
+              entry.push = { ok: true, commit: pushResult.commitSha?.slice(0, 8), files: pushResult.filesCommitted };
+            } catch (err) {
+              entry.push = { ok: false, error: err.message.slice(0, 100) };
+            }
+          }
+          // Pull: GitHub → Core MongoDB
+          if (!push_only) {
+            try {
+              const pullResult = await post(`/deploy/solutions/${sol.id}/github/pull`, {}, sid);
+              entry.pull = { ok: true, skills: pullResult.skills?.length, connectors: pullResult.connectors?.length };
+            } catch (err) {
+              entry.pull = { ok: false, error: err.message.slice(0, 100) };
+            }
+          }
+          results.push(entry);
+        }
+      } catch (err) {
+        results.push({ tenant: t.id, error: err.message });
+      }
+    }
+    const pushCount = results.filter(r => r.push?.ok).length;
+    const pullCount = results.filter(r => r.pull?.ok).length;
+    const errors = results.filter(r => r.error || r.push?.ok === false || r.pull?.ok === false).length;
+    return {
+      ok: errors === 0,
+      summary: `Synced ${tenants.length} tenant(s), ${results.length} solution(s). Push: ${pushCount} ok. Pull: ${pullCount} ok. Errors: ${errors}.`,
+      results,
+    };
+  },
 };
 
 // ─── Response formatting ────────────────────────────────────────────
@@ -1172,6 +1697,11 @@ export async function handleToolCall(name, args, sessionId) {
     };
   }
 
+  // Master mode: per-call tenant override (no re-auth needed)
+  if (TENANT_TOOLS.has(name) && isMasterMode(sessionId) && args?.tenant) {
+    switchTenant(sessionId, args.tenant);
+  }
+
   try {
     const result = await handler(args, sessionId);