toolnexus 0.3.1 → 0.5.0

package/dist/index.d.ts

@@ -6,6 +6,7 @@ export * from "./native.js";
 export * from "./http.js";
 export * from "./a2a.js";
 export * from "./serve.js";
+export * from "./mcpserve.js";
 export * from "./adapters.js";
 export * from "./toolkit.js";
 export * from "./client.js";

package/dist/index.js

@@ -6,6 +6,7 @@ export * from "./native.js";
 export * from "./http.js";
 export * from "./a2a.js";
 export * from "./serve.js";
+export * from "./mcpserve.js";
 export * from "./adapters.js";
 export * from "./toolkit.js";
 export * from "./client.js";

package/dist/mcp.js

@@ -32,9 +32,9 @@ export function parseMcpConfig(input) {
     if (wrapped !== undefined)
         return wrapped;
     // Bare map of servers — but strip sibling top-level config keys (builtins/
-    // agents/a2a) so they are not mistaken for MCP servers when no wrapper key
-    // is present.
-    const { builtins: _builtins, agents: _agents, a2a: _a2a, ...servers } = raw;
+    // agents/a2a/mcpServer) so they are not mistaken for MCP servers when no
+    // wrapper key is present.
+    const { builtins: _builtins, agents: _agents, a2a: _a2a, mcpServer: _mcpServer, ...servers } = raw;
     return servers;
 }
 /**

package/dist/mcpserve.d.ts

@@ -0,0 +1,47 @@
+/**
+ * MCP — INBOUND: serve a toolkit as an MCP server (SPEC §7C).
+ *
+ * The inbound mirror of the A2A `serve` (§7B). Where A2A advertises the toolkit's
+ * **skills** and fulfils a Task through the whole client loop, MCP advertises the
+ * toolkit's **unified tools** (every source — mcp · skill · native · http ·
+ * builtin · a2a) and dispatches each `tools/call` straight to `Tool.execute`. The
+ * calling MCP client *is* the LLM host, so there is **no client, no Task, and no
+ * TaskStore** — just `tools/list` + `tools/call` over the toolkit registry.
+ *
+ * Transport: **streamable-HTTP**, mounted at `POST /mcp` on the `serve(addr, …)`
+ * server alongside the A2A routes (see serve.ts), built on the same
+ * `@modelcontextprotocol/sdk` the client side already uses.
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import type { Tool, ToolSource } from "./types.js";
+/** Opt-in MCP serve profile — the toolkit is exposed as an MCP server. */
+export interface MCPServeConfig {
+    /** Advertised server name (initialize `serverInfo.name`). Default "toolnexus". */
+    name?: string;
+    /** Advertised server version. Default "0.1.0". */
+    version?: string;
+    /** Subset of tool names to expose; omit ⇒ all. Unknown names are ignored. */
+    tools?: string[];
+}
+/** Surfaced on each inbound `tools/call`. */
+export interface OnCallEvent {
+    name: string;
+    source: ToolSource;
+    ms: number;
+    isError: boolean;
+}
+export type OnCall = (ev: OnCallEvent) => void | Promise<void>;
+/**
+ * The tools this profile exposes: every toolkit tool, filtered to `cfg.tools`
+ * when set (unknown names in the filter are ignored, never an error).
+ */
+export declare function exposedMcpTools(tools: Tool[], cfg?: MCPServeConfig): Tool[];
+/**
+ * Build a low-level MCP `Server` exposing `tools` as MCP tools. `tools/list`
+ * maps each Tool's name (verbatim — already sanitized at registration),
+ * description, and inputSchema; `tools/call` dispatches to `Tool.execute` and
+ * maps the `ToolResult` to a `CallToolResult` (`output` → text, `isError`
+ * propagates). A fresh server is cheap to build, so the HTTP path makes one per
+ * request (stateless).
+ */
+export declare function buildMcpServer(tools: Tool[], cfg?: MCPServeConfig, onCall?: OnCall): Server;

package/dist/mcpserve.js

@@ -0,0 +1,69 @@
+/**
+ * MCP — INBOUND: serve a toolkit as an MCP server (SPEC §7C).
+ *
+ * The inbound mirror of the A2A `serve` (§7B). Where A2A advertises the toolkit's
+ * **skills** and fulfils a Task through the whole client loop, MCP advertises the
+ * toolkit's **unified tools** (every source — mcp · skill · native · http ·
+ * builtin · a2a) and dispatches each `tools/call` straight to `Tool.execute`. The
+ * calling MCP client *is* the LLM host, so there is **no client, no Task, and no
+ * TaskStore** — just `tools/list` + `tools/call` over the toolkit registry.
+ *
+ * Transport: **streamable-HTTP**, mounted at `POST /mcp` on the `serve(addr, …)`
+ * server alongside the A2A routes (see serve.ts), built on the same
+ * `@modelcontextprotocol/sdk` the client side already uses.
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { ListToolsRequestSchema, CallToolRequestSchema, McpError, ErrorCode } from "@modelcontextprotocol/sdk/types.js";
+const DEFAULT_NAME = "toolnexus";
+const DEFAULT_VERSION = "0.1.0";
+/**
+ * The tools this profile exposes: every toolkit tool, filtered to `cfg.tools`
+ * when set (unknown names in the filter are ignored, never an error).
+ */
+export function exposedMcpTools(tools, cfg) {
+    if (!cfg?.tools)
+        return tools;
+    const wanted = new Set(cfg.tools);
+    return tools.filter((t) => wanted.has(t.name));
+}
+/**
+ * Build a low-level MCP `Server` exposing `tools` as MCP tools. `tools/list`
+ * maps each Tool's name (verbatim — already sanitized at registration),
+ * description, and inputSchema; `tools/call` dispatches to `Tool.execute` and
+ * maps the `ToolResult` to a `CallToolResult` (`output` → text, `isError`
+ * propagates). A fresh server is cheap to build, so the HTTP path makes one per
+ * request (stateless).
+ */
+export function buildMcpServer(tools, cfg, onCall) {
+    const byName = new Map(tools.map((t) => [t.name, t]));
+    const server = new Server({ name: cfg?.name ?? DEFAULT_NAME, version: cfg?.version ?? DEFAULT_VERSION }, { capabilities: { tools: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: tools.map((t) => ({ name: t.name, description: t.description, inputSchema: t.inputSchema })),
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (req, extra) => {
+        const tool = byName.get(req.params.name);
+        if (!tool)
+            throw new McpError(ErrorCode.InvalidParams, `Unknown tool: ${req.params.name}`);
+        const started = Date.now();
+        // The call is a single synchronous tool invocation honoring the MCP
+        // request's cancellation. An execute() throw becomes an isError result —
+        // never a crash.
+        let result;
+        try {
+            result = await tool.execute(req.params.arguments ?? {}, { signal: extra.signal });
+        }
+        catch (e) {
+            result = { output: e instanceof Error ? e.message : String(e), isError: true };
+        }
+        if (onCall) {
+            try {
+                await onCall({ name: tool.name, source: tool.source, ms: Date.now() - started, isError: result.isError });
+            }
+            catch {
+                // Host callback errors are isolated.
+            }
+        }
+        return { content: [{ type: "text", text: result.output }], isError: result.isError };
+    });
+    return server;
+}

package/dist/serve.d.ts

@@ -1,6 +1,8 @@
+import { type Tool } from "./types.js";
 import type { SkillInfo } from "./skill.js";
 import type { RunResult } from "./client.js";
 import type { A2ATask, A2ATaskState, AgentCard } from "./a2a.js";
+import { type MCPServeConfig, type OnCall } from "./mcpserve.js";
 /** Pluggable Task persistence. The-factory can plug NATS/JetStream the same way. */
 export interface TaskStore {
     get(id: string): Promise<A2ATask | undefined>;
@@ -71,6 +73,12 @@ export interface StartServerOptions {
      * message) keys the conversation so served turns are remembered via the store. */
     runTask: (text: string, contextId?: string) => Promise<RunResult>;
     onTask?: OnTask;
+    /** When present, mounts a streamable-HTTP MCP server at `/mcp`; absent ⇒ no MCP route. */
+    mcp?: MCPServeConfig;
+    /** The toolkit's unified tools, exposed by the MCP profile. */
+    mcpTools?: Tool[];
+    /** Surfaced on each inbound MCP `tools/call`. */
+    onCall?: OnCall;
 }
 /**
  * Start the HTTP server. Delegated to by `Toolkit.serve`. When `a2a` is absent,

package/dist/serve.js

@@ -18,7 +18,9 @@ import http from "node:http";
 import fs from "node:fs";
 import path from "node:path";
 import { randomUUID } from "node:crypto";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { sanitize } from "./types.js";
+import { buildMcpServer, exposedMcpTools } from "./mcpserve.js";
 /** Default in-memory store — Tasks live only for the lifetime of the process. */
 export class InMemoryTaskStore {
     tasks = new Map();
@@ -111,14 +113,23 @@ function readBody(req) {
         req.on("end", () => resolve(body));
     });
 }
+function safeJson(body) {
+    try {
+        return JSON.parse(body);
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * Start the HTTP server. Delegated to by `Toolkit.serve`. When `a2a` is absent,
  * the server answers 404 to everything (a minimal base for now).
  */
 export async function startA2AServer(opts) {
-    const { a2a, skills, runTask, onTask } = opts;
+    const { a2a, skills, runTask, onTask, mcp, mcpTools, onCall } = opts;
     const [host, portStr] = splitAddr(opts.addr);
     const store = a2a ? resolveStore(a2a.store) : undefined;
+    const exposedTools = mcp ? exposedMcpTools(mcpTools ?? [], mcp) : [];
     const server = http.createServer((req, res) => {
         const rpcRes = (id, payload) => {
             res.writeHead(200, { "content-type": "application/json" });
@@ -126,7 +137,36 @@ export async function startA2AServer(opts) {
         };
         const rpcOk = (id, result) => rpcRes(id, { result });
         const rpcErr = (id, code, message) => rpcRes(id, { error: { code, message } });
-        // No A2A profile ⇒ no routes.
+        // No profile at all ⇒ no routes.
+        if (!store && !mcp) {
+            res.writeHead(404);
+            res.end("not found");
+            return;
+        }
+        // MCP streamable-HTTP profile (independent of A2A): a fresh server+transport
+        // per request (stateless — sessionIdGenerator undefined). Checked first so
+        // `/mcp` is never shadowed by the A2A POST handler.
+        if (mcp && req.url && (req.url === "/mcp" || req.url.startsWith("/mcp?"))) {
+            void (async () => {
+                const body = req.method === "POST" ? await readBody(req) : "";
+                const parsed = body ? safeJson(body) : undefined;
+                const mcpServer = buildMcpServer(exposedTools, mcp, onCall);
+                const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+                res.on("close", () => {
+                    void transport.close();
+                    void mcpServer.close();
+                });
+                await mcpServer.connect(transport);
+                await transport.handleRequest(req, res, parsed);
+            })().catch(() => {
+                if (!res.headersSent) {
+                    res.writeHead(500);
+                    res.end("mcp error");
+                }
+            });
+            return;
+        }
+        // No A2A profile ⇒ no A2A routes (an MCP-only server 404s everything else).
         if (!a2a || !store) {
             res.writeHead(404);
             res.end("not found");

package/dist/toolkit.d.ts

@@ -6,6 +6,7 @@ import { type Tool, type ToolContext, type ToolResult, type McpStatus } from "./
 import { type BuiltinsConfig } from "./builtin.js";
 import { type Agent } from "./a2a.js";
 import { type A2AConfig, type OnTask, type ServeHandle } from "./serve.js";
+import { type MCPServeConfig, type OnCall } from "./mcpserve.js";
 import type { Client } from "./client.js";
 export interface ToolkitOptions {
     mcpConfig?: string | object;
@@ -21,6 +22,8 @@ export declare class Toolkit {
     private readonly skill;
     /** A2A profile read from a top-level `a2a` config block (serve() falls back to this). */
     private readonly a2aConfig;
+    /** MCP serve profile read from a top-level `mcpServer` config block. */
+    private readonly mcpServerConfig;
     private byName;
     private constructor();
     static create(opts: ToolkitOptions): Promise<Toolkit>;
@@ -43,9 +46,11 @@ export declare class Toolkit {
      * When `a2a` is absent, no A2A routes are mounted. Returns a stoppable handle.
      */
     serve(addr: string, opts: {
-        client: Client;
+        client?: Client;
         a2a?: A2AConfig;
         onTask?: OnTask;
+        mcp?: MCPServeConfig;
+        onCall?: OnCall;
     }): Promise<ServeHandle>;
     execute(name: string, args: Record<string, unknown>, ctx?: ToolContext): Promise<ToolResult>;
     /** Markdown skill catalog for the system prompt. */

package/dist/toolkit.js

@@ -8,13 +8,17 @@ export class Toolkit {
     mcp;
     skill;
     a2aConfig;
+    mcpServerConfig;
     byName = new Map();
     constructor(mcp, skill, builtins, agents, extraTools, 
     /** A2A profile read from a top-level `a2a` config block (serve() falls back to this). */
-    a2aConfig) {
+    a2aConfig, 
+    /** MCP serve profile read from a top-level `mcpServer` config block. */
+    mcpServerConfig) {
         this.mcp = mcp;
         this.skill = skill;
         this.a2aConfig = a2aConfig;
+        this.mcpServerConfig = mcpServerConfig;
         // Builtins are the lowest-precedence source: a host extraTools entry with
         // the same name shadows a builtin (SPEC §4). Drop shadowed builtins up
         // front, then apply the normal first-wins dedupe for MCP/skill/agents/extras.
@@ -60,7 +64,14 @@ export class Toolkit {
         if (opts.mcpConfig && typeof opts.mcpConfig === "object" && "a2a" in opts.mcpConfig) {
             a2aConfig = opts.mcpConfig.a2a;
         }
-        return new Toolkit(mcp, skill, builtins, agentToolsFlat, opts.extraTools ?? [], a2aConfig);
+        // MCP inbound profile: a top-level `mcpServer` (singular) block — distinct
+        // from the client-side `mcpServers` block. serve()/serveStdio() prefer their
+        // inline `mcp` over this.
+        let mcpServerConfig;
+        if (opts.mcpConfig && typeof opts.mcpConfig === "object" && "mcpServer" in opts.mcpConfig) {
+            mcpServerConfig = opts.mcpConfig.mcpServer;
+        }
+        return new Toolkit(mcp, skill, builtins, agentToolsFlat, opts.extraTools ?? [], a2aConfig, mcpServerConfig);
     }
     tools() {
         return [...this.byName.values()];
@@ -99,6 +110,7 @@ export class Toolkit {
      */
     serve(addr, opts) {
         const a2a = opts.a2a ?? this.a2aConfig;
+        const mcp = opts.mcp ?? this.mcpServerConfig;
         const skills = this.skill ? Object.values(this.skill.skills) : [];
         return startA2AServer({
             addr,
@@ -108,6 +120,9 @@ export class Toolkit {
                 ? opts.client.ask(text, { toolkit: this, id: contextId })
                 : opts.client.run(text, { toolkit: this }),
             onTask: opts.onTask,
+            mcp,
+            mcpTools: mcp ? this.tools() : undefined,
+            onCall: opts.onCall,
         });
     }
     async execute(name, args, ctx) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolnexus",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "description": "Dynamic MCP servers + agent skills as uniform tools for any LLM (opencode-style).",
   "type": "module",
   "main": "./dist/index.js",