@ateam-ai/mcp 0.1.11 → 0.1.13

package/src/tools.js

@@ -1,6 +1,6 @@
 /**
  * A-Team MCP tool definitions and handlers.
- * 15 tools covering the full A-Team External Agent API + auth + bootstrap.
+ * 18 tools covering the full A-Team External Agent API + auth + bootstrap.
  */
 
 import {
@@ -120,7 +120,7 @@ export const tools = [
   {
     name: "ateam_deploy_solution",
     description:
-      "Deploy a governed AI Team solution to A-Team Core — identity, connectors, skills. The Skill Builder auto-generates MCP servers from tool definitions. Used after defining system architecture. Always validate first using ateam_validate_solution. Requires authentication (call ateam_auth first if not using env vars).",
+      "Deploy a governed AI Team solution to A-Team Core — identity, connectors, skills. The Skill Builder auto-generates MCP servers from tool definitions. For connectors with UI or Node.js code, send SOURCE files only via mcp_store — the server runs npm install + npm run build automatically (like Vercel/Netlify). Never send dist/ or node_modules/. Always validate first using ateam_validate_solution. Requires authentication (call ateam_auth first if not using env vars).",
     inputSchema: {
       type: "object",
       properties: {
@@ -136,12 +136,12 @@ export const tools = [
         connectors: {
           type: "array",
           items: { type: "object" },
-          description: "Array of connector metadata (id, name, transport, command, args)",
+          description: "Array of connector metadata (id, name, transport). command and args are OPTIONAL when mcp_store provides the code — the system auto-detects the entry point (server.js, index.js, package.json main, server.py) and runtime (node, python3). You can still provide explicit command/args to override auto-detection.",
         },
         mcp_store: {
           type: "object",
           description:
-            "Optional: connector source code files. Key = connector id, value = array of {path, content}",
+            "Optional: connector source code files. Key = connector id, value = array of {path, content}. Send SOURCE files only (server.js, package.json, src/*.jsx, etc.) — the server runs npm install + npm run build automatically. Never include node_modules/ or dist/ folders. Entry point is auto-detected from the uploaded files.",
         },
       },
       required: ["solution", "skills"],
@@ -179,6 +179,35 @@ export const tools = [
       required: ["connector"],
     },
   },
+  {
+    name: "ateam_upload_connector_files",
+    description:
+      "Upload source files for a connector's MCP server. Use this INSTEAD of mcp_store in ateam_deploy_solution when the source code is too large to inline. Upload files first (one call per file or a few small files at a time), then deploy the solution without mcp_store, then redeploy. Files are staged and automatically included in the next deploy. Requires authentication.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        connector_id: {
+          type: "string",
+          description: "The connector ID (must match the connector's id in the solution)",
+        },
+        files: {
+          type: "array",
+          items: {
+            type: "object",
+            properties: {
+              path: { type: "string", description: 'Relative file path (e.g. "server.js", "package.json", "src/utils.js")' },
+              content: { type: "string", description: "File content as a string. Use for small files." },
+              content_base64: { type: "string", description: "File content as base64-encoded string. Use when content has complex escaping." },
+              url: { type: "string", description: "URL to fetch file content from (e.g. raw GitHub URL). Server fetches it — no large payload needed." },
+            },
+            required: ["path"],
+          },
+          description: "Array of files to upload. Each file needs 'path' plus ONE of: 'content' (inline string), 'content_base64' (base64), or 'url' (server fetches it). Send one file per call for large files.",
+        },
+      },
+      required: ["connector_id", "files"],
+    },
+  },
   {
     name: "ateam_list_solutions",
     description: "List all solutions deployed in the Skill Builder.",
@@ -279,6 +308,186 @@ export const tools = [
       required: ["solution_id", "message"],
     },
   },
+
+  // ─── Developer Tools ────────────────────────────────────────────
+
+  {
+    name: "ateam_get_execution_logs",
+    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.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        solution_id: {
+          type: "string",
+          description: "The solution ID",
+        },
+        skill_id: {
+          type: "string",
+          description: "Optional: filter logs to a specific skill",
+        },
+        job_id: {
+          type: "string",
+          description: "Optional: get detailed trace for a specific job ID",
+        },
+        limit: {
+          type: "number",
+          description: "Max jobs to return (default: 10, max: 50)",
+        },
+      },
+      required: ["solution_id"],
+    },
+  },
+  {
+    name: "ateam_test_skill",
+    description:
+      "Send a test message to a deployed skill and get the full execution result. By default waits for completion (up to 60s). Set wait=false for async mode — returns job_id immediately, then poll with ateam_test_status.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        solution_id: {
+          type: "string",
+          description: "The solution ID",
+        },
+        skill_id: {
+          type: "string",
+          description: "The skill ID to test (original or internal ID)",
+        },
+        message: {
+          type: "string",
+          description: "The test message to send to the skill",
+        },
+        wait: {
+          type: "boolean",
+          description:
+            "If true (default), wait for completion. If false, return job_id immediately for polling via ateam_test_status.",
+        },
+      },
+      required: ["solution_id", "skill_id", "message"],
+    },
+  },
+  {
+    name: "ateam_test_status",
+    description:
+      "Poll the progress of an async skill test. Returns iteration count, tool call steps, status, pending questions, and result when done. Uses the same data pipeline as the Job Progress UI.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        solution_id: {
+          type: "string",
+          description: "The solution ID",
+        },
+        skill_id: {
+          type: "string",
+          description: "The skill ID",
+        },
+        job_id: {
+          type: "string",
+          description: "The job ID returned by ateam_test_skill",
+        },
+      },
+      required: ["solution_id", "skill_id", "job_id"],
+    },
+  },
+  {
+    name: "ateam_test_abort",
+    description:
+      "Abort a running skill test. Stops the job execution at the next iteration boundary.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        solution_id: {
+          type: "string",
+          description: "The solution ID",
+        },
+        skill_id: {
+          type: "string",
+          description: "The skill ID",
+        },
+        job_id: {
+          type: "string",
+          description: "The job ID to abort",
+        },
+      },
+      required: ["solution_id", "skill_id", "job_id"],
+    },
+  },
+  {
+    name: "ateam_get_connector_source",
+    description:
+      "Read the source code of a connector's MCP server. Returns the files that make up the connector implementation.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        solution_id: {
+          type: "string",
+          description: "The solution ID",
+        },
+        connector_id: {
+          type: "string",
+          description: "The connector ID",
+        },
+      },
+      required: ["solution_id", "connector_id"],
+    },
+  },
+  {
+    name: "ateam_get_metrics",
+    description:
+      "Get execution metrics — timing, tool stats, bottlenecks, signals, and recommendations. Use job_id for single-job deep analysis, or skill_id for recent history overview.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        solution_id: {
+          type: "string",
+          description: "The solution ID",
+        },
+        job_id: {
+          type: "string",
+          description: "Optional: deep analysis for a specific job",
+        },
+        skill_id: {
+          type: "string",
+          description: "Optional: recent metrics for a specific skill",
+        },
+      },
+      required: ["solution_id"],
+    },
+  },
+  {
+    name: "ateam_diff",
+    description:
+      "Compare the current Builder definition against what's deployed in ADAS Core. Shows which skills are undeployed, orphaned, or have changed fields. Use skill_id to diff a single skill.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        solution_id: {
+          type: "string",
+          description: "The solution ID",
+        },
+        skill_id: {
+          type: "string",
+          description: "Optional: diff a single skill instead of the whole solution",
+        },
+      },
+      required: ["solution_id"],
+    },
+  },
+  {
+    name: "ateam_delete_solution",
+    description:
+      "Delete a deployed solution and all its skills from A-Team. Use with caution — this removes the solution from both the Skill Builder and A-Team Core. Useful for cleaning up test solutions or starting fresh.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        solution_id: {
+          type: "string",
+          description: "The solution ID to delete",
+        },
+      },
+      required: ["solution_id"],
+    },
+  },
 ];
 
 // ─── Tool handlers ──────────────────────────────────────────────────
@@ -303,9 +512,19 @@ const WRITE_TOOLS = new Set([
   "ateam_deploy_solution",
   "ateam_deploy_skill",
   "ateam_deploy_connector",
+  "ateam_upload_connector_files",
   "ateam_update",
   "ateam_redeploy",
   "ateam_solution_chat",
+  // Developer tools (read tenant-specific runtime data)
+  "ateam_get_execution_logs",
+  "ateam_test_skill",
+  "ateam_test_status",
+  "ateam_test_abort",
+  "ateam_get_connector_source",
+  "ateam_get_metrics",
+  "ateam_diff",
+  "ateam_delete_solution",
 ]);
 
 const handlers = {
@@ -334,8 +553,9 @@ const handlers = {
       { step: 1, title: "Clarify the goal", description: "Understand what the user wants their Team to do", suggested_tools: [] },
       { step: 2, title: "Generate Team map", description: "Design skills, solution architecture, and connectors", suggested_tools: ["ateam_get_spec", "ateam_get_examples", "ateam_get_workflows"] },
       { step: 3, title: "Validate", description: "Run validation before deploying", suggested_tools: ["ateam_validate_skill", "ateam_validate_solution"] },
-      { step: 4, title: "Deploy", description: "Push the Team to A-Team Core", suggested_tools: ["ateam_auth", "ateam_deploy_solution"] },
+      { step: 4, title: "Deploy", description: "Push the Team to A-Team Core. If connector source code is too large for mcp_store, use ateam_upload_connector_files first (one file per call), then deploy without mcp_store.", suggested_tools: ["ateam_auth", "ateam_upload_connector_files", "ateam_deploy_solution"] },
       { step: 5, title: "Iterate", description: "Inspect, update, and redeploy as needed", suggested_tools: ["ateam_get_solution", "ateam_update", "ateam_redeploy", "ateam_solution_chat"] },
+      { step: 6, title: "Operate & Debug", description: "Test skills (async or sync), poll progress, abort tests, read execution logs, analyze metrics, diff definitions, inspect connector source", suggested_tools: ["ateam_test_skill", "ateam_test_status", "ateam_test_abort", "ateam_get_execution_logs", "ateam_get_metrics", "ateam_diff", "ateam_get_connector_source"] },
     ],
     first_questions: [
       { id: "goal", question: "What do you want your Team to accomplish?", type: "text" },
@@ -349,6 +569,18 @@ const handlers = {
       security: "https://ateam-ai.com/#security",
       engine: "https://ateam-ai.com/#engine",
     },
+    critical_connector_rules: {
+      _note: "CRITICAL: Read this before writing ANY connector code. Violations are caught at deploy time and BLOCKED.",
+      transport: "A-Team connectors use STDIO transport — child processes communicating via stdin/stdout JSON-RPC.",
+      MUST_use: "StdioServerTransport from @modelcontextprotocol/sdk, or raw readline over process.stdin.",
+      MUST_NOT_use: [
+        "express(), fastify(), Koa, or any web framework",
+        "http.createServer() or app.listen(PORT)",
+        "HttpServerTransport, SSEServerTransport, or StreamableHTTPServerTransport",
+      ],
+      stdout_rule: "stdout = JSON-RPC channel. Use console.error() for logging, NOT console.log().",
+      lifecycle_rule: "MCP servers must stay alive. Never call process.exit().",
+    },
     assistant_behavior_contract: {
       first_run_requirements: [
         "Explain platform before endpoints",
@@ -362,11 +594,14 @@ const handlers = {
       always: [
         "Explain Skill vs Solution vs Connector before deploying anything",
         "Validate before deploy",
+        "Study the connector example (ateam_get_examples type='connector') before writing connector code",
         "Ask discovery questions if goal unclear",
       ],
       never: [
         "Deploy before validation",
         "Dump raw spec unless requested",
+        "Write connector code that starts a web server (express, http.createServer, app.listen) — connectors MUST use stdio transport",
+        "Use HttpServerTransport, SSEServerTransport, or any non-stdio MCP transport",
       ],
     },
   }),
@@ -416,6 +651,28 @@ const handlers = {
   ateam_deploy_connector: async ({ connector }, sid) =>
     post("/deploy/connector", { connector }, sid),
 
+  ateam_upload_connector_files: async ({ connector_id, files }, sid) => {
+    // Resolve content_base64 and url into plain content before sending to backend
+    const resolved = [];
+    for (const file of files) {
+      if (!file.path) continue;
+      let content = file.content;
+      if (!content && file.content_base64) {
+        content = Buffer.from(file.content_base64, "base64").toString("utf-8");
+      }
+      if (!content && file.url) {
+        const resp = await fetch(file.url);
+        if (!resp.ok) throw new Error(`Failed to fetch ${file.url}: ${resp.status}`);
+        content = await resp.text();
+      }
+      if (content === undefined || content === null) {
+        throw new Error(`File "${file.path}": provide one of content, content_base64, or url`);
+      }
+      resolved.push({ path: file.path, content });
+    }
+    return post(`/deploy/mcp-store/${connector_id}`, { files: resolved }, sid);
+  },
+
   ateam_list_solutions: async (_args, sid) => get("/deploy/solutions", sid),
 
   ateam_get_solution: async ({ solution_id, view, skill_id }, sid) => {
@@ -449,6 +706,49 @@ const handlers = {
 
   ateam_solution_chat: async ({ solution_id, message }, sid) =>
     post(`/deploy/solutions/${solution_id}/chat`, { message }, sid),
+
+  // ─── Developer Tools ────────────────────────────────────────────
+
+  ateam_get_execution_logs: async ({ solution_id, skill_id, job_id, limit }, sid) => {
+    const qs = new URLSearchParams();
+    if (skill_id) qs.set("skill_id", skill_id);
+    if (job_id) qs.set("job_id", job_id);
+    if (limit) qs.set("limit", String(limit));
+    const qsStr = qs.toString() ? `?${qs}` : "";
+    return get(`/deploy/solutions/${solution_id}/logs${qsStr}`, sid);
+  },
+
+  ateam_test_skill: async ({ solution_id, skill_id, message, wait }, sid) => {
+    const asyncMode = wait === false;
+    const body = { message, ...(asyncMode ? { async: true } : {}) };
+    const timeoutMs = asyncMode ? 15_000 : 90_000;
+    return post(`/deploy/solutions/${solution_id}/skills/${skill_id}/test`, body, sid, { timeoutMs });
+  },
+
+  ateam_test_status: async ({ solution_id, skill_id, job_id }, sid) =>
+    get(`/deploy/solutions/${solution_id}/skills/${skill_id}/test/${job_id}`, sid),
+
+  ateam_test_abort: async ({ solution_id, skill_id, job_id }, sid) =>
+    del(`/deploy/solutions/${solution_id}/skills/${skill_id}/test/${job_id}`, sid),
+
+  ateam_get_connector_source: async ({ solution_id, connector_id }, sid) =>
+    get(`/deploy/solutions/${solution_id}/connectors/${connector_id}/source`, sid),
+
+  ateam_get_metrics: async ({ solution_id, job_id, skill_id }, sid) => {
+    const qs = new URLSearchParams();
+    if (job_id) qs.set("job_id", job_id);
+    if (skill_id) qs.set("skill_id", skill_id);
+    const qsStr = qs.toString() ? `?${qs}` : "";
+    return get(`/deploy/solutions/${solution_id}/metrics${qsStr}`, sid);
+  },
+
+  ateam_diff: async ({ solution_id, skill_id }, sid) => {
+    const qs = skill_id ? `?skill_id=${encodeURIComponent(skill_id)}` : "";
+    return get(`/deploy/solutions/${solution_id}/diff${qs}`, sid);
+  },
+
+  ateam_delete_solution: async ({ solution_id }, sid) =>
+    del(`/deploy/solutions/${solution_id}`, sid),
 };
 
 // ─── Response formatting ────────────────────────────────────────────