toolnexus 0.3.1 → 0.5.0

package/src/index.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/src/mcp.ts

@@ -55,9 +55,9 @@ export function parseMcpConfig(input: string | object): McpConfig {
   const wrapped = raw.mcpServers ?? raw.servers ?? raw.mcp
   if (wrapped !== undefined) return wrapped as McpConfig
   // 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 as McpConfig
 }
 

package/src/mcpserve.ts

@@ -0,0 +1,95 @@
+/**
+ * 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"
+import type { Tool, ToolSource } from "./types.js"
+
+const DEFAULT_NAME = "toolnexus"
+const DEFAULT_VERSION = "0.1.0"
+
+/** 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 function exposedMcpTools(tools: Tool[], cfg?: MCPServeConfig): Tool[] {
+  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: Tool[], cfg?: MCPServeConfig, onCall?: OnCall): Server {
+  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/src/serve.ts

@@ -18,10 +18,12 @@ import http from "node:http"
 import fs from "node:fs"
 import path from "node:path"
 import { randomUUID } from "node:crypto"
-import { sanitize } from "./types.js"
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js"
+import { sanitize, type Tool } from "./types.js"
 import type { SkillInfo } from "./skill.js"
 import type { RunResult } from "./client.js"
 import type { A2AArtifact, A2ATask, A2ATaskState, AgentCard } from "./a2a.js"
+import { buildMcpServer, exposedMcpTools, type MCPServeConfig, type OnCall } from "./mcpserve.js"
 
 // ---------------------------------------------------------------------------
 // TaskStore adapter — pluggable persistence for served Tasks.
@@ -162,6 +164,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
 }
 
 /** Extract the concatenated text of a JSON-RPC `SendMessage` message's parts. */
@@ -182,14 +190,23 @@ function readBody(req: http.IncomingMessage): Promise<string> {
   })
 }
 
+function safeJson(body: string): unknown {
+  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: StartServerOptions): Promise<ServeHandle> {
-  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: unknown, payload: object) => {
@@ -199,7 +216,38 @@ export async function startA2AServer(opts: StartServerOptions): Promise<ServeHan
     const rpcOk = (id: unknown, result: unknown) => rpcRes(id, { result })
     const rpcErr = (id: unknown, code: number, message: string) => 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/src/toolkit.ts

@@ -8,6 +8,7 @@ import { loadSkills, type SkillSource } from "./skill.js"
 import { selectBuiltins, type BuiltinsConfig } from "./builtin.js"
 import { agentTools, parseAgentsConfig, type Agent } from "./a2a.js"
 import { startA2AServer, type A2AConfig, type OnTask, type ServeHandle } from "./serve.js"
+import { type MCPServeConfig, type OnCall } from "./mcpserve.js"
 import { toAnthropic, toGemini, toOpenAI } from "./adapters.js"
 import type { Client } from "./client.js"
 
@@ -31,6 +32,8 @@ export class Toolkit {
     extraTools: Tool[],
     /** A2A profile read from a top-level `a2a` config block (serve() falls back to this). */
     private readonly a2aConfig: A2AConfig | undefined,
+    /** MCP serve profile read from a top-level `mcpServer` config block. */
+    private readonly mcpServerConfig: MCPServeConfig | undefined,
   ) {
     // Builtins are the lowest-precedence source: a host extraTools entry with
     // the same name shadows a builtin (SPEC §4). Drop shadowed builtins up
@@ -87,7 +90,15 @@ export class Toolkit {
       a2aConfig = (opts.mcpConfig as { a2a?: A2AConfig }).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: MCPServeConfig | undefined
+    if (opts.mcpConfig && typeof opts.mcpConfig === "object" && "mcpServer" in opts.mcpConfig) {
+      mcpServerConfig = (opts.mcpConfig as { mcpServer?: MCPServeConfig }).mcpServer
+    }
+
+    return new Toolkit(mcp, skill, builtins, agentToolsFlat, opts.extraTools ?? [], a2aConfig, mcpServerConfig)
   }
 
   tools(): Tool[] {
@@ -129,8 +140,12 @@ export class Toolkit {
    * peer's turns are remembered through the client's ConversationStore.
    * When `a2a` is absent, no A2A routes are mounted. Returns a stoppable handle.
    */
-  serve(addr: string, opts: { client: Client; a2a?: A2AConfig; onTask?: OnTask }): Promise<ServeHandle> {
+  serve(
+    addr: string,
+    opts: { client?: Client; a2a?: A2AConfig; onTask?: OnTask; mcp?: MCPServeConfig; onCall?: OnCall },
+  ): Promise<ServeHandle> {
     const a2a = opts.a2a ?? this.a2aConfig
+    const mcp = opts.mcp ?? this.mcpServerConfig
     const skills = this.skill ? Object.values(this.skill.skills) : []
     return startA2AServer({
       addr,
@@ -138,9 +153,12 @@ export class Toolkit {
       skills,
       runTask: (text, contextId) =>
         contextId
-          ? opts.client.ask(text, { toolkit: this, id: contextId })
-          : opts.client.run(text, { toolkit: this }),
+          ? 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,
     })
   }