@radaros/transport 0.3.14 → 0.3.16

package/README.md

@@ -29,8 +29,9 @@ app.listen(3000);
 
 ## Features
 
-- **Express Router** — REST API with streaming support
-- **Socket.IO Gateway** — Real-time WebSocket communication
+- **Auto-Discovery** — Reads from the global `Registry` at request time; agents created after server start are immediately available
+- **Express Router** — REST API with streaming support and list endpoints (`GET /agents`, `/teams`, `/workflows`, `/tools`)
+- **Socket.IO Gateway** — Real-time WebSocket communication with dynamic agent/team lookup and tool discovery
 - **A2A Server** — Agent-to-Agent protocol support
 - **CORS & Rate Limiting** — Built-in security middleware
 - **Swagger** — Auto-generated API documentation

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { Agent, A2AAgentCard, Registry, Servable, Team, Workflow, EventBus, VoiceAgent } from '@radaros/core';
+import { Agent, A2AAgentCard, MCPToolProviderConfig, ToolDef, MCPToolProvider, Registry, Servable, Team, Workflow, Toolkit, EventBus, VoiceAgent } from '@radaros/core';
 
 interface A2AServerOptions {
     agents: Record<string, Agent>;
@@ -34,6 +34,85 @@ declare function generateMultiAgentCard(agents: Record<string, Agent>, serverUrl
     url?: string;
 }, version?: string): A2AAgentCard;
 
+interface MCPServerEntry {
+    id: string;
+    config: MCPToolProviderConfig;
+    provider: MCPToolProvider;
+    status: "disconnected" | "connecting" | "connected" | "error";
+    error?: string;
+    toolCount: number;
+    connectedAt?: Date;
+}
+interface MCPServerSummary {
+    id: string;
+    name: string;
+    transport: string;
+    url?: string;
+    command?: string;
+    status: string;
+    toolCount: number;
+    error?: string;
+    connectedAt?: string;
+}
+/**
+ * Manages multiple MCP server connections at runtime.
+ * Servers can be added/removed/connected/disconnected dynamically,
+ * and their tools can be collected for injection into agents.
+ */
+declare class MCPManager {
+    private servers;
+    /** Add a server config. Auto-generates an id from the name if not provided. */
+    add(config: MCPToolProviderConfig, id?: string): MCPServerSummary;
+    /** Connect a server by id. Discovers tools on success. */
+    connect(id: string): Promise<MCPServerSummary>;
+    /** Disconnect a server by id. */
+    disconnect(id: string): Promise<MCPServerSummary>;
+    /** Remove a server entirely. Disconnects first if connected. */
+    remove(id: string): Promise<void>;
+    /** Get all tools from all connected servers, merged into one array. */
+    getAllTools(): Promise<ToolDef[]>;
+    /** Get tools from a specific server. */
+    getTools(id: string): Promise<ToolDef[]>;
+    /** List all registered servers. */
+    list(): MCPServerSummary[];
+    /** Get a single server summary. */
+    get(id: string): MCPServerSummary;
+    has(id: string): boolean;
+    /** Disconnect all servers. */
+    closeAll(): Promise<void>;
+    private getEntry;
+    private summarize;
+}
+
+interface AdminRouterOptions {
+    /** Shared MCPManager instance. If omitted, a new one is created. */
+    mcpManager?: MCPManager;
+}
+/**
+ * Creates an Express sub-router with admin endpoints for managing
+ * MCP servers and the toolkit catalog at runtime.
+ *
+ * Mount under a prefix: `app.use("/admin", createAdminRouter())`
+ *
+ * Routes:
+ *   GET    /mcp              — list MCP servers
+ *   POST   /mcp              — add + connect an MCP server
+ *   GET    /mcp/:id          — single server details
+ *   POST   /mcp/:id/connect  — connect a server
+ *   POST   /mcp/:id/disconnect — disconnect
+ *   DELETE /mcp/:id          — remove a server
+ *   GET    /mcp/:id/tools    — tools from a specific server
+ *   GET    /mcp/tools        — all tools across connected servers
+ *
+ *   GET    /toolkits         — list toolkit catalog
+ *   GET    /toolkits/:id     — single toolkit meta
+ *   POST   /toolkits/:id     — instantiate a toolkit with config
+ */
+declare function createAdminRouter(opts?: AdminRouterOptions): {
+    router: any;
+    mcpManager: MCPManager;
+};
+
 interface FileUploadOptions {
     maxFileSize?: number;
     maxFiles?: number;
@@ -104,6 +183,17 @@ interface RouterOptions {
         windowMs?: number;
         max?: number;
     } | boolean;
+    /** Named tool library exposed via GET /tools. Tools from toolkits are auto-collected. */
+    toolLibrary?: Record<string, ToolDef>;
+    /** Toolkit instances whose tools are exposed via GET /tools. Merged with toolLibrary. */
+    toolkits?: Toolkit[];
+    /**
+     * Enable admin routes under `/admin` for managing MCP servers and the toolkit catalog.
+     * Pass `true` to use defaults, or provide an MCPManager instance to share state.
+     */
+    admin?: boolean | {
+        mcpManager?: MCPManager;
+    };
 }
 
 declare function createAgentRouter(opts: RouterOptions): any;
@@ -218,6 +308,10 @@ interface GatewayOptions {
     authMiddleware?: (socket: any, next: (err?: Error) => void) => void;
     /** Max requests per minute per socket. Default: 60 */
     maxRequestsPerMinute?: number;
+    /** Named tool library exposed via tools.list event. */
+    toolLibrary?: Record<string, ToolDef>;
+    /** Toolkit instances whose tools are exposed via tools.list. Merged with toolLibrary. */
+    toolkits?: Toolkit[];
 }
 
 declare function createAgentGateway(opts: GatewayOptions): void;
@@ -230,4 +324,4 @@ interface VoiceGatewayOptions {
 }
 declare function createVoiceGateway(opts: VoiceGatewayOptions): void;
 
-export { type A2AServerOptions, type BrowserGatewayOptions, type FileUploadOptions, type GatewayOptions, type RouterOptions, type SwaggerOptions, type VoiceGatewayOptions, buildMultiModalInput, createA2AServer, createAgentGateway, createAgentRouter, createBrowserGateway, createFileUploadMiddleware, createVoiceGateway, errorHandler, generateAgentCard, generateMultiAgentCard, generateOpenAPISpec, requestLogger };
+export { type A2AServerOptions, type AdminRouterOptions, type BrowserGatewayOptions, type FileUploadOptions, type GatewayOptions, MCPManager, type MCPServerEntry, type MCPServerSummary, type RouterOptions, type SwaggerOptions, type VoiceGatewayOptions, buildMultiModalInput, createA2AServer, createAdminRouter, createAgentGateway, createAgentRouter, createBrowserGateway, createFileUploadMiddleware, createVoiceGateway, errorHandler, generateAgentCard, generateMultiAgentCard, generateOpenAPISpec, requestLogger };

package/dist/index.js

@@ -341,9 +341,263 @@ function handleTasksCancel(res, body, store) {
   });
 }
 
-// src/express/file-upload.ts
+// src/express/admin-router.ts
 import { createRequire as createRequire2 } from "module";
+import { toolkitCatalog } from "@radaros/core";
+
+// src/express/mcp-manager.ts
+import { MCPToolProvider } from "@radaros/core";
+var MCPManager = class {
+  servers = /* @__PURE__ */ new Map();
+  /** Add a server config. Auto-generates an id from the name if not provided. */
+  add(config, id) {
+    const serverId = id ?? config.name;
+    if (this.servers.has(serverId)) {
+      throw new Error(`MCP server "${serverId}" already exists`);
+    }
+    const provider = new MCPToolProvider(config);
+    const entry = {
+      id: serverId,
+      config,
+      provider,
+      status: "disconnected",
+      toolCount: 0
+    };
+    this.servers.set(serverId, entry);
+    return this.summarize(entry);
+  }
+  /** Connect a server by id. Discovers tools on success. */
+  async connect(id) {
+    const entry = this.getEntry(id);
+    entry.status = "connecting";
+    entry.error = void 0;
+    try {
+      await entry.provider.connect();
+      const tools = await entry.provider.getTools();
+      entry.status = "connected";
+      entry.toolCount = tools.length;
+      entry.connectedAt = /* @__PURE__ */ new Date();
+    } catch (err) {
+      entry.status = "error";
+      entry.error = err.message;
+    }
+    return this.summarize(entry);
+  }
+  /** Disconnect a server by id. */
+  async disconnect(id) {
+    const entry = this.getEntry(id);
+    try {
+      await entry.provider.close();
+    } catch {
+    }
+    entry.status = "disconnected";
+    entry.toolCount = 0;
+    entry.connectedAt = void 0;
+    return this.summarize(entry);
+  }
+  /** Remove a server entirely. Disconnects first if connected. */
+  async remove(id) {
+    const entry = this.getEntry(id);
+    if (entry.status === "connected" || entry.status === "connecting") {
+      try {
+        await entry.provider.close();
+      } catch {
+      }
+    }
+    this.servers.delete(id);
+  }
+  /** Get all tools from all connected servers, merged into one array. */
+  async getAllTools() {
+    const all = [];
+    for (const entry of this.servers.values()) {
+      if (entry.status === "connected") {
+        try {
+          const tools = await entry.provider.getTools();
+          all.push(...tools);
+        } catch {
+        }
+      }
+    }
+    return all;
+  }
+  /** Get tools from a specific server. */
+  async getTools(id) {
+    const entry = this.getEntry(id);
+    if (entry.status !== "connected") {
+      throw new Error(`MCP server "${id}" is not connected`);
+    }
+    return entry.provider.getTools();
+  }
+  /** List all registered servers. */
+  list() {
+    return Array.from(this.servers.values()).map((e) => this.summarize(e));
+  }
+  /** Get a single server summary. */
+  get(id) {
+    return this.summarize(this.getEntry(id));
+  }
+  has(id) {
+    return this.servers.has(id);
+  }
+  /** Disconnect all servers. */
+  async closeAll() {
+    const promises = Array.from(this.servers.values()).map(async (entry) => {
+      if (entry.status === "connected") {
+        try {
+          await entry.provider.close();
+        } catch {
+        }
+        entry.status = "disconnected";
+        entry.toolCount = 0;
+      }
+    });
+    await Promise.all(promises);
+  }
+  getEntry(id) {
+    const entry = this.servers.get(id);
+    if (!entry) throw new Error(`MCP server "${id}" not found`);
+    return entry;
+  }
+  summarize(entry) {
+    return {
+      id: entry.id,
+      name: entry.config.name,
+      transport: entry.config.transport,
+      url: entry.config.url,
+      command: entry.config.command,
+      status: entry.status,
+      toolCount: entry.toolCount,
+      error: entry.error,
+      connectedAt: entry.connectedAt?.toISOString()
+    };
+  }
+};
+
+// src/express/admin-router.ts
 var _require2 = createRequire2(import.meta.url);
+function createAdminRouter(opts) {
+  let express;
+  try {
+    express = _require2("express");
+  } catch {
+    throw new Error("express is required for createAdminRouter. Install it: npm install express");
+  }
+  const router = express.Router();
+  const mcpManager = opts?.mcpManager ?? new MCPManager();
+  router.get("/mcp", (_req, res) => {
+    res.json(mcpManager.list());
+  });
+  router.get("/mcp/tools", async (_req, res) => {
+    try {
+      const tools = await mcpManager.getAllTools();
+      res.json(
+        tools.map((t) => ({
+          name: t.name,
+          description: t.description,
+          parameters: Object.keys(t.parameters?.shape ?? {})
+        }))
+      );
+    } catch (err) {
+      res.status(500).json({ error: err.message });
+    }
+  });
+  router.post("/mcp", async (req, res) => {
+    try {
+      const { name, transport, url, command, args, env, headers, id, autoConnect } = req.body;
+      if (!name || !transport) {
+        return res.status(400).json({ error: "name and transport are required" });
+      }
+      const config = { name, transport };
+      if (url) config.url = url;
+      if (command) config.command = command;
+      if (args) config.args = args;
+      if (env) config.env = env;
+      if (headers) config.headers = headers;
+      const summary = mcpManager.add(config, id);
+      if (autoConnect !== false) {
+        const connected = await mcpManager.connect(summary.id);
+        return res.status(201).json(connected);
+      }
+      res.status(201).json(summary);
+    } catch (err) {
+      res.status(400).json({ error: err.message });
+    }
+  });
+  router.get("/mcp/:id", (req, res) => {
+    try {
+      res.json(mcpManager.get(req.params.id));
+    } catch (err) {
+      res.status(404).json({ error: err.message });
+    }
+  });
+  router.post("/mcp/:id/connect", async (req, res) => {
+    try {
+      const summary = await mcpManager.connect(req.params.id);
+      res.json(summary);
+    } catch (err) {
+      res.status(400).json({ error: err.message });
+    }
+  });
+  router.post("/mcp/:id/disconnect", async (req, res) => {
+    try {
+      const summary = await mcpManager.disconnect(req.params.id);
+      res.json(summary);
+    } catch (err) {
+      res.status(400).json({ error: err.message });
+    }
+  });
+  router.delete("/mcp/:id", async (req, res) => {
+    try {
+      await mcpManager.remove(req.params.id);
+      res.json({ ok: true });
+    } catch (err) {
+      res.status(404).json({ error: err.message });
+    }
+  });
+  router.get("/mcp/:id/tools", async (req, res) => {
+    try {
+      const tools = await mcpManager.getTools(req.params.id);
+      res.json(
+        tools.map((t) => ({
+          name: t.name,
+          description: t.description,
+          parameters: Object.keys(t.parameters?.shape ?? {})
+        }))
+      );
+    } catch (err) {
+      res.status(400).json({ error: err.message });
+    }
+  });
+  router.get("/toolkits", (_req, res) => {
+    res.json(toolkitCatalog.list());
+  });
+  router.get("/toolkits/:id", (req, res) => {
+    const meta = toolkitCatalog.get(req.params.id);
+    if (!meta) return res.status(404).json({ error: `Toolkit "${req.params.id}" not found` });
+    res.json(meta);
+  });
+  router.post("/toolkits/:id", (req, res) => {
+    try {
+      const toolkit = toolkitCatalog.create(req.params.id, req.body ?? {});
+      const tools = toolkit.getTools().map((t) => ({
+        name: t.name,
+        description: t.description
+      }));
+      res.status(201).json({
+        id: req.params.id,
+        name: toolkit.name,
+        tools
+      });
+    } catch (err) {
+      res.status(400).json({ error: err.message });
+    }
+  });
+  return { router, mcpManager };
+}
+
+// src/express/file-upload.ts
+import { createRequire as createRequire3 } from "module";
+var _require3 = createRequire3(import.meta.url);
 var MIME_TO_PART_TYPE = {
   "image/png": "image",
   "image/jpeg": "image",
@@ -365,7 +619,7 @@ function getPartType(mimeType) {
 function createFileUploadMiddleware(opts = {}) {
   let multer;
   try {
-    multer = _require2("multer");
+    multer = _require3("multer");
   } catch {
     throw new Error("multer is required for file uploads. Install it: npm install multer");
   }
@@ -430,15 +684,15 @@ function requestLogger(options) {
 }
 
 // src/express/router-factory.ts
-import { createRequire as createRequire4 } from "module";
-import { classifyServables, registry as globalRegistry } from "@radaros/core";
+import { createRequire as createRequire5 } from "module";
+import { classifyServables, collectToolkitTools, describeToolLibrary, registry as globalRegistry } from "@radaros/core";
 
 // src/express/swagger.ts
-import { createRequire as createRequire3 } from "module";
-var _require3 = createRequire3(import.meta.url);
+import { createRequire as createRequire4 } from "module";
+var _require4 = createRequire4(import.meta.url);
 function zodSchemaToJsonSchema(schema) {
   try {
-    const zodToJsonSchema = _require3("zod-to-json-schema").default ?? _require3("zod-to-json-schema");
+    const zodToJsonSchema = _require4("zod-to-json-schema").default ?? _require4("zod-to-json-schema");
     const result = zodToJsonSchema(schema, { target: "openApi3" });
     const { $schema, ...rest } = result;
     return rest;
@@ -861,7 +1115,7 @@ ${agentDesc}`,
 function serveSwaggerUI(spec) {
   let swaggerUiExpress;
   try {
-    swaggerUiExpress = _require3("swagger-ui-express");
+    swaggerUiExpress = _require4("swagger-ui-express");
   } catch {
     throw new Error("swagger-ui-express is required for Swagger UI. Install it: npm install swagger-ui-express");
   }
@@ -875,7 +1129,7 @@ function serveSwaggerUI(spec) {
 }
 
 // src/express/router-factory.ts
-var _require4 = createRequire4(import.meta.url);
+var _require5 = createRequire5(import.meta.url);
 function corsMiddleware(origins) {
   return (req, res, next) => {
     const origin = req.headers.origin;
@@ -968,7 +1222,7 @@ function createAgentRouter(opts) {
   const reg = opts.registry === false ? null : opts.registry ?? globalRegistry;
   let express;
   try {
-    express = _require4("express");
+    express = _require5("express");
   } catch {
     throw new Error("express is required for createAgentRouter. Install it: npm install express");
   }
@@ -1287,6 +1541,29 @@ function createAgentRouter(opts) {
       res.json(reg.list());
     });
   }
+  if (opts.admin) {
+    const adminOpts = typeof opts.admin === "object" ? opts.admin : {};
+    const { router: adminRouter } = createAdminRouter({
+      mcpManager: adminOpts.mcpManager
+    });
+    router.use("/admin", adminRouter);
+  }
+  const fromToolkits = opts.toolkits ? collectToolkitTools(opts.toolkits) : {};
+  const mergedTools = { ...fromToolkits, ...opts.toolLibrary ?? {} };
+  if (Object.keys(mergedTools).length > 0) {
+    router.get("/tools", (_req, res) => {
+      res.json(describeToolLibrary(mergedTools));
+    });
+    router.get("/tools/:name", (req, res) => {
+      const tool = mergedTools[req.params.name];
+      if (!tool) return res.status(404).json({ error: `Tool "${req.params.name}" not found` });
+      res.json({
+        name: tool.name,
+        description: tool.description,
+        parameters: Object.keys(tool.parameters.shape ?? {})
+      });
+    });
+  }
   return router;
 }
 
@@ -1404,7 +1681,7 @@ function createBrowserGateway(opts) {
 }
 
 // src/socketio/gateway.ts
-import { classifyServables as classifyServables2, registry as globalRegistry2 } from "@radaros/core";
+import { classifyServables as classifyServables2, collectToolkitTools as collectToolkitTools2, describeToolLibrary as describeToolLibrary2, registry as globalRegistry2 } from "@radaros/core";
 function createSocketRateLimiter(maxPerMinute = 60) {
   return () => {
     let count = 0;
@@ -1482,6 +1759,54 @@ function createAgentGateway(opts) {
         socket.emit("agent.error", { error: error.message });
       }
     });
+    socket.on("agents.list", (_data, ack) => {
+      if (reg) {
+        ack?.(reg.describeAgents());
+      } else {
+        const names = Object.keys(opts.agents ?? {});
+        ack?.(names.map((n) => ({ name: n })));
+      }
+    });
+    socket.on("teams.list", (_data, ack) => {
+      if (reg) {
+        ack?.(reg.describeTeams());
+      } else {
+        const names = Object.keys(opts.teams ?? {});
+        ack?.(names.map((n) => ({ name: n })));
+      }
+    });
+    socket.on("workflows.list", (_data, ack) => {
+      if (reg) {
+        ack?.(reg.describeWorkflows());
+      } else {
+        ack?.([]);
+      }
+    });
+    socket.on("registry.list", (_data, ack) => {
+      if (reg) {
+        ack?.(reg.list());
+      } else {
+        ack?.({
+          agents: Object.keys(opts.agents ?? {}),
+          teams: Object.keys(opts.teams ?? {}),
+          workflows: []
+        });
+      }
+    });
+    const fromToolkits = opts.toolkits ? collectToolkitTools2(opts.toolkits) : {};
+    const mergedTools = { ...fromToolkits, ...opts.toolLibrary ?? {} };
+    socket.on("tools.list", (_data, ack) => {
+      ack?.(describeToolLibrary2(mergedTools));
+    });
+    socket.on("tools.get", (data, ack) => {
+      const tool = mergedTools[data?.name];
+      if (!tool) return ack?.({ error: `Tool "${data?.name}" not found` });
+      ack?.({
+        name: tool.name,
+        description: tool.description,
+        parameters: Object.keys(tool.parameters.shape ?? {})
+      });
+    });
     socket.on("disconnect", () => {
     });
     socket.on("team.run", async (data) => {
@@ -1634,8 +1959,10 @@ function createVoiceGateway(opts) {
   });
 }
 export {
+  MCPManager,
   buildMultiModalInput,
   createA2AServer,
+  createAdminRouter,
   createAgentGateway,
   createAgentRouter,
   createBrowserGateway,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@radaros/transport",
-  "version": "0.3.14",
+  "version": "0.3.16",
   "description": "HTTP and WebSocket transport layer for RadarOS agents",
   "license": "MIT",
   "repository": {
@@ -39,7 +39,7 @@
     "typescript": "^5.6.0"
   },
   "peerDependencies": {
-    "@radaros/core": "^0.3.14",
+    "@radaros/core": "^0.3.16",
     "@types/express": "^4.0.0 || ^5.0.0",
     "express": "^4.0.0 || ^5.0.0",
     "multer": ">=2.0.0",