@desplega.ai/agent-swarm 1.52.1 → 1.53.0

package/src/tools/mcp-servers/mcp-server-delete.ts

@@ -0,0 +1,72 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { deleteMcpServer, getAgentById, getMcpServerById } from "@/be/db";
+import { createToolRegistrar } from "@/tools/utils";
+
+export const registerMcpServerDeleteTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "mcp-server-delete",
+    {
+      title: "Delete MCP Server",
+      annotations: { destructiveHint: true },
+      description: "Delete an MCP server definition. Only the owning agent or lead can delete.",
+      inputSchema: z.object({
+        id: z.string().describe("ID of the MCP server to delete"),
+      }),
+      outputSchema: z.object({
+        yourAgentId: z.string().uuid().optional(),
+        success: z.boolean(),
+        message: z.string(),
+      }),
+    },
+    async (args, requestInfo, _meta) => {
+      if (!requestInfo.agentId) {
+        return {
+          content: [{ type: "text", text: "Agent ID not found." }],
+          structuredContent: { success: false, message: "Agent ID not found." },
+        };
+      }
+
+      const existing = getMcpServerById(args.id);
+      if (!existing) {
+        return {
+          content: [{ type: "text", text: "MCP server not found." }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: false,
+            message: "MCP server not found.",
+          },
+        };
+      }
+
+      const agent = getAgentById(requestInfo.agentId);
+      if (existing.ownerAgentId !== requestInfo.agentId && !agent?.isLead) {
+        return {
+          content: [
+            { type: "text", text: "Only the owning agent or lead can delete this MCP server." },
+          ],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: false,
+            message: "Permission denied.",
+          },
+        };
+      }
+
+      const deleted = deleteMcpServer(args.id);
+      return {
+        content: [
+          {
+            type: "text",
+            text: deleted ? `Deleted MCP server "${existing.name}".` : "Delete failed.",
+          },
+        ],
+        structuredContent: {
+          yourAgentId: requestInfo.agentId,
+          success: deleted,
+          message: deleted ? `Deleted MCP server "${existing.name}".` : "Delete failed.",
+        },
+      };
+    },
+  );
+};

package/src/tools/mcp-servers/mcp-server-get.ts

@@ -0,0 +1,80 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { getMcpServerById, getMcpServerByName } from "@/be/db";
+import { createToolRegistrar } from "@/tools/utils";
+
+export const registerMcpServerGetTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "mcp-server-get",
+    {
+      title: "Get MCP Server",
+      annotations: { destructiveHint: false },
+      description:
+        "Get MCP server details by ID or name. Name resolution uses scope cascade: agent > swarm > global.",
+      inputSchema: z.object({
+        id: z.string().optional().describe("MCP server ID"),
+        name: z.string().optional().describe("MCP server name (resolved with scope cascade)"),
+      }),
+      outputSchema: z.object({
+        yourAgentId: z.string().uuid().optional(),
+        success: z.boolean(),
+        message: z.string(),
+        server: z.any().optional(),
+      }),
+    },
+    async (args, requestInfo, _meta) => {
+      if (!args.id && !args.name) {
+        return {
+          content: [{ type: "text", text: "Provide id or name." }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: false,
+            message: "Provide id or name.",
+          },
+        };
+      }
+
+      let mcpServer = null;
+
+      if (args.id) {
+        mcpServer = getMcpServerById(args.id);
+      } else if (args.name && requestInfo.agentId) {
+        // Scope cascade: agent > swarm > global
+        mcpServer =
+          getMcpServerByName(args.name, "agent", requestInfo.agentId) ||
+          getMcpServerByName(args.name, "swarm", null) ||
+          getMcpServerByName(args.name, "global", null);
+      } else if (args.name) {
+        mcpServer =
+          getMcpServerByName(args.name, "swarm", null) ||
+          getMcpServerByName(args.name, "global", null);
+      }
+
+      if (!mcpServer) {
+        return {
+          content: [{ type: "text", text: "MCP server not found." }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: false,
+            message: "MCP server not found.",
+          },
+        };
+      }
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: `MCP server "${mcpServer.name}" (${mcpServer.id}): ${mcpServer.transport} transport, scope=${mcpServer.scope}`,
+          },
+        ],
+        structuredContent: {
+          yourAgentId: requestInfo.agentId,
+          success: true,
+          message: `Found MCP server "${mcpServer.name}".`,
+          server: mcpServer,
+        },
+      };
+    },
+  );
+};

package/src/tools/mcp-servers/mcp-server-install.ts

@@ -0,0 +1,110 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { getAgentById, getMcpServerById, installMcpServer } from "@/be/db";
+import { createToolRegistrar } from "@/tools/utils";
+
+export const registerMcpServerInstallTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "mcp-server-install",
+    {
+      title: "Install MCP Server",
+      annotations: { destructiveHint: false },
+      description:
+        "Install an MCP server for an agent. Self-install is always allowed; cross-agent install requires lead.",
+      inputSchema: z.object({
+        mcpServerId: z.string().describe("ID of the MCP server to install"),
+        agentId: z
+          .string()
+          .optional()
+          .describe("Target agent (default: calling agent). Lead can install for others."),
+      }),
+      outputSchema: z.object({
+        yourAgentId: z.string().uuid().optional(),
+        success: z.boolean(),
+        message: z.string(),
+        installation: z.any().optional(),
+      }),
+    },
+    async (args, requestInfo, _meta) => {
+      if (!requestInfo.agentId) {
+        return {
+          content: [{ type: "text", text: "Agent ID not found." }],
+          structuredContent: { success: false, message: "Agent ID not found." },
+        };
+      }
+
+      const targetAgentId = args.agentId ?? requestInfo.agentId;
+
+      // Cross-agent install requires lead
+      if (targetAgentId !== requestInfo.agentId) {
+        const agent = getAgentById(requestInfo.agentId);
+        if (!agent?.isLead) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: "Only leads can install MCP servers for other agents.",
+              },
+            ],
+            structuredContent: {
+              yourAgentId: requestInfo.agentId,
+              success: false,
+              message: "Permission denied.",
+            },
+          };
+        }
+      }
+
+      const mcpServer = getMcpServerById(args.mcpServerId);
+      if (!mcpServer) {
+        return {
+          content: [{ type: "text", text: "MCP server not found." }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: false,
+            message: "MCP server not found.",
+          },
+        };
+      }
+
+      if (!mcpServer.isEnabled) {
+        return {
+          content: [{ type: "text", text: "MCP server is disabled." }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: false,
+            message: "MCP server is disabled.",
+          },
+        };
+      }
+
+      try {
+        const installation = installMcpServer(targetAgentId, args.mcpServerId);
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Installed MCP server "${mcpServer.name}" for agent ${targetAgentId}.`,
+            },
+          ],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: true,
+            message: `Installed MCP server "${mcpServer.name}".`,
+            installation,
+          },
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown error";
+        return {
+          content: [{ type: "text", text: `Failed: ${message}` }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: false,
+            message: `Failed: ${message}`,
+          },
+        };
+      }
+    },
+  );
+};

package/src/tools/mcp-servers/mcp-server-list.ts

@@ -0,0 +1,67 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { getAgentMcpServers, listMcpServers } from "@/be/db";
+import { createToolRegistrar } from "@/tools/utils";
+
+export const registerMcpServerListTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "mcp-server-list",
+    {
+      title: "List MCP Servers",
+      annotations: { destructiveHint: false },
+      description:
+        "List MCP servers with optional filters. Use installedOnly to see servers installed for the calling agent.",
+      inputSchema: z.object({
+        scope: z.enum(["global", "swarm", "agent"]).optional().describe("Filter by scope"),
+        transport: z.enum(["stdio", "http", "sse"]).optional().describe("Filter by transport type"),
+        search: z.string().optional().describe("Search by name or description"),
+        installedOnly: z
+          .boolean()
+          .optional()
+          .describe("Only show servers installed for the calling agent"),
+      }),
+      outputSchema: z.object({
+        yourAgentId: z.string().uuid().optional(),
+        success: z.boolean(),
+        message: z.string(),
+        servers: z.array(z.any()),
+        total: z.number(),
+      }),
+    },
+    async (args, requestInfo, _meta) => {
+      try {
+        const servers =
+          args.installedOnly && requestInfo.agentId
+            ? getAgentMcpServers(requestInfo.agentId)
+            : listMcpServers({
+                scope: args.scope,
+                transport: args.transport,
+                search: args.search,
+              });
+
+        return {
+          content: [{ type: "text", text: `Found ${servers.length} MCP server(s).` }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: true,
+            message: `Found ${servers.length} MCP server(s).`,
+            servers,
+            total: servers.length,
+          },
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown error";
+        return {
+          content: [{ type: "text", text: `Failed: ${message}` }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: false,
+            message: `Failed: ${message}`,
+            servers: [],
+            total: 0,
+          },
+        };
+      }
+    },
+  );
+};

package/src/tools/mcp-servers/mcp-server-uninstall.ts

@@ -0,0 +1,71 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { getAgentById, uninstallMcpServer } from "@/be/db";
+import { createToolRegistrar } from "@/tools/utils";
+
+export const registerMcpServerUninstallTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "mcp-server-uninstall",
+    {
+      title: "Uninstall MCP Server",
+      annotations: { destructiveHint: true },
+      description:
+        "Uninstall an MCP server from an agent. Self-uninstall is always allowed; cross-agent requires lead.",
+      inputSchema: z.object({
+        mcpServerId: z.string().describe("ID of the MCP server to uninstall"),
+        agentId: z.string().optional().describe("Target agent (default: calling agent)"),
+      }),
+      outputSchema: z.object({
+        yourAgentId: z.string().uuid().optional(),
+        success: z.boolean(),
+        message: z.string(),
+      }),
+    },
+    async (args, requestInfo, _meta) => {
+      if (!requestInfo.agentId) {
+        return {
+          content: [{ type: "text", text: "Agent ID not found." }],
+          structuredContent: { success: false, message: "Agent ID not found." },
+        };
+      }
+
+      const targetAgentId = args.agentId ?? requestInfo.agentId;
+
+      if (targetAgentId !== requestInfo.agentId) {
+        const agent = getAgentById(requestInfo.agentId);
+        if (!agent?.isLead) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: "Only leads can uninstall MCP servers for other agents.",
+              },
+            ],
+            structuredContent: {
+              yourAgentId: requestInfo.agentId,
+              success: false,
+              message: "Permission denied.",
+            },
+          };
+        }
+      }
+
+      const removed = uninstallMcpServer(targetAgentId, args.mcpServerId);
+      return {
+        content: [
+          {
+            type: "text",
+            text: removed ? "MCP server uninstalled." : "MCP server was not installed.",
+          },
+        ],
+        structuredContent: {
+          yourAgentId: requestInfo.agentId,
+          success: removed,
+          message: removed
+            ? "MCP server uninstalled."
+            : "MCP server was not installed for this agent.",
+        },
+      };
+    },
+  );
+};

package/src/tools/mcp-servers/mcp-server-update.ts

@@ -0,0 +1,120 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { getAgentById, getMcpServerById, updateMcpServer } from "@/be/db";
+import { createToolRegistrar } from "@/tools/utils";
+
+export const registerMcpServerUpdateTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "mcp-server-update",
+    {
+      title: "Update MCP Server",
+      annotations: { destructiveHint: false },
+      description: "Update an MCP server's configuration. Only the owner or lead can update.",
+      inputSchema: z.object({
+        id: z.string().describe("ID of the MCP server to update"),
+        name: z.string().optional().describe("New name"),
+        description: z.string().optional().describe("New description"),
+        transport: z.enum(["stdio", "http", "sse"]).optional().describe("New transport type"),
+        command: z.string().optional().describe("New command (stdio)"),
+        args: z.string().optional().describe("New JSON array of arguments (stdio)"),
+        url: z.string().optional().describe("New URL (http/sse)"),
+        headers: z.string().optional().describe("New JSON object of non-secret headers"),
+        envConfigKeys: z.string().optional().describe("New env config key mappings"),
+        headerConfigKeys: z.string().optional().describe("New header config key mappings"),
+        isEnabled: z.boolean().optional().describe("Toggle enabled/disabled"),
+      }),
+      outputSchema: z.object({
+        yourAgentId: z.string().uuid().optional(),
+        success: z.boolean(),
+        message: z.string(),
+        server: z.any().optional(),
+      }),
+    },
+    async (args, requestInfo, _meta) => {
+      if (!requestInfo.agentId) {
+        return {
+          content: [{ type: "text", text: "Agent ID not found." }],
+          structuredContent: { success: false, message: "Agent ID not found." },
+        };
+      }
+
+      try {
+        const existing = getMcpServerById(args.id);
+        if (!existing) {
+          return {
+            content: [{ type: "text", text: "MCP server not found." }],
+            structuredContent: {
+              yourAgentId: requestInfo.agentId,
+              success: false,
+              message: "MCP server not found.",
+            },
+          };
+        }
+
+        // Only owner or lead can update
+        const agent = getAgentById(requestInfo.agentId);
+        if (existing.ownerAgentId !== requestInfo.agentId && !agent?.isLead) {
+          return {
+            content: [
+              { type: "text", text: "Only the owning agent or lead can update this MCP server." },
+            ],
+            structuredContent: {
+              yourAgentId: requestInfo.agentId,
+              success: false,
+              message: "Permission denied.",
+            },
+          };
+        }
+
+        const updates: Parameters<typeof updateMcpServer>[1] = {};
+        if (args.name !== undefined) updates.name = args.name;
+        if (args.description !== undefined) updates.description = args.description;
+        if (args.transport !== undefined) updates.transport = args.transport;
+        if (args.command !== undefined) updates.command = args.command;
+        if (args.args !== undefined) updates.args = args.args;
+        if (args.url !== undefined) updates.url = args.url;
+        if (args.headers !== undefined) updates.headers = args.headers;
+        if (args.envConfigKeys !== undefined) updates.envConfigKeys = args.envConfigKeys;
+        if (args.headerConfigKeys !== undefined) updates.headerConfigKeys = args.headerConfigKeys;
+        if (args.isEnabled !== undefined) updates.isEnabled = args.isEnabled;
+
+        const updated = updateMcpServer(args.id, updates);
+        if (!updated) {
+          return {
+            content: [{ type: "text", text: "Failed to update MCP server." }],
+            structuredContent: {
+              yourAgentId: requestInfo.agentId,
+              success: false,
+              message: "Update failed.",
+            },
+          };
+        }
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Updated MCP server "${updated.name}" (v${updated.version})`,
+            },
+          ],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: true,
+            message: `Updated MCP server "${updated.name}" to version ${updated.version}.`,
+            server: updated,
+          },
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown error";
+        return {
+          content: [{ type: "text", text: `Failed: ${message}` }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: false,
+            message: `Failed: ${message}`,
+          },
+        };
+      }
+    },
+  );
+};

package/src/tools/tool-config.ts

@@ -131,6 +131,15 @@ export const DEFERRED_TOOLS = new Set([
   "skill-sync-remote",
   "skill-publish",
 
+  // MCP Servers (7)
+  "mcp-server-create",
+  "mcp-server-delete",
+  "mcp-server-get",
+  "mcp-server-install",
+  "mcp-server-list",
+  "mcp-server-uninstall",
+  "mcp-server-update",
+
   // Other (3)
   "cancel-task",
   "inject-learning",