@radaros/transport 0.3.15 → 0.3.17

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { Agent, A2AAgentCard, Registry, Servable, Team, Workflow, ToolDef, Toolkit, 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,91 @@ 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;
+    /**
+     * Express middleware for authentication/authorization.
+     * **IMPORTANT**: These endpoints can add MCP servers and execute tools.
+     * Always add auth middleware in production.
+     */
+    middleware?: any[];
+}
+/**
+ * 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;
@@ -108,6 +193,13 @@ interface RouterOptions {
     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;
@@ -238,4 +330,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,271 @@ 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();
+  if (opts?.middleware) {
+    for (const mw of opts.middleware) router.use(mw);
+  }
+  if (!opts?.middleware?.length && process.env.NODE_ENV === "production") {
+    console.warn(
+      "[admin-router] WARNING: Admin routes mounted without authentication middleware. These endpoints can add MCP servers, execute tools, and modify configurations. Pass middleware in AdminRouterOptions to secure them."
+    );
+  }
+  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 +627,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 +692,15 @@ function requestLogger(options) {
 }
 
 // src/express/router-factory.ts
-import { createRequire as createRequire4 } from "module";
+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 +1123,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 +1137,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 +1230,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 +1549,13 @@ 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) {
@@ -1643,6 +1912,9 @@ function createVoiceGateway(opts) {
               result: ev.result
             });
           });
+          session.on("usage", (ev) => {
+            socket.emit("voice.usage", ev);
+          });
           session.on("interrupted", () => {
             socket.emit("voice.interrupted");
           });
@@ -1698,8 +1970,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.15",
+  "version": "0.3.17",
   "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.15",
+    "@radaros/core": "^0.3.17",
     "@types/express": "^4.0.0 || ^5.0.0",
     "express": "^4.0.0 || ^5.0.0",
     "multer": ">=2.0.0",