toolnexus 0.24.0 → 0.26.0

package/src/mcpheader.ts

@@ -0,0 +1,19 @@
+/** Internal (not exported from index): MCP 2026-07-28 header helpers shared by the handler and McpServerAuth. */
+
+/** Decodes the `=?base64?<std-base64>?=` sentinel (SPEC §2.3); an absent header is not ok. */
+export function decodeHeaderValue(v: string): [string, boolean] {
+  if (v.startsWith("=?base64?") && v.endsWith("?=") && v.length >= 11) {
+    const b = v.slice(9, -2)
+    if (b.length % 4 !== 0 || !/^[A-Za-z0-9+/]*={0,2}$/.test(b)) return ["", false]
+    return [Buffer.from(b, "base64").toString("utf8"), true]
+  }
+  return [v, v !== ""]
+}
+
+/** GET a JSON document (200 only). */
+export async function getJson(f: typeof fetch, url: string): Promise<any> {
+  const r = await f(url, { headers: { Accept: "application/json" } })
+  if (r.status !== 200) throw new Error(`GET ${url}: HTTP ${r.status}`)
+  return r.json()
+}
+

package/src/mcpserve.ts

@@ -12,7 +12,11 @@
  * server alongside the A2A routes (see serve.ts), built on the same
  * `@modelcontextprotocol/sdk` the client side already uses.
  */
+import http from "node:http"
+import type { AddressInfo } from "node:net"
+import { randomBytes, timingSafeEqual } from "node:crypto"
 import { Server } from "@modelcontextprotocol/sdk/server/index.js"
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js"
 import { ListToolsRequestSchema, CallToolRequestSchema, McpError, ErrorCode } from "@modelcontextprotocol/sdk/types.js"
 import type { Tool, ToolSource, ToolResult } from "./types.js"
 import type { ContentPart } from "./content.js"
@@ -66,7 +70,11 @@ export function buildMcpServer(tools: Tool[], cfg?: MCPServeConfig, onCall?: OnC
   )
 
   server.setRequestHandler(ListToolsRequestSchema, async () => ({
-    tools: tools.map((t) => ({ name: t.name, description: t.description, inputSchema: t.inputSchema })),
+    tools: tools.map((t) =>
+      t.outputSchema
+        ? { name: t.name, description: t.description, inputSchema: t.inputSchema, outputSchema: t.outputSchema }
+        : { name: t.name, description: t.description, inputSchema: t.inputSchema },
+    ),
   }))
 
   server.setRequestHandler(CallToolRequestSchema, async (req, extra) => {
@@ -89,12 +97,36 @@ export function buildMcpServer(tools: Tool[], cfg?: MCPServeConfig, onCall?: OnC
         // Host callback errors are isolated.
       }
     }
-    return { content: [{ type: "text", text: result.output }, ...partBlocks(result.parts)], isError: result.isError }
+    return toolResultToMcp(result) as any
   })
 
   return server
 }
 
+/**
+ * §7C / §1. Map a ToolResult to an MCP `CallToolResult`: `output` → the text block (or, when
+ * `output` is empty and `structured` is set, the JSON text of `structured`), `parts` → extra
+ * blocks, `structured` → `structuredContent`, `meta` → `_meta`. With neither set the shape is
+ * byte-identical to the pre-§7C.1 result. `omitFalseIsError` drops `isError:false` (the
+ * hand-written §7C.1 handler wire, like Go's omitempty); the SDK serve path keeps it.
+ */
+export function toolResultToMcp(result: ToolResult, omitFalseIsError = false): Record<string, unknown> {
+  let text = result.output ?? ""
+  if (result.structured !== undefined && result.structured !== null && text === "") {
+    try {
+      text = JSON.stringify(result.structured)
+    } catch {
+      // leave the text empty when structured is not serialisable
+    }
+  }
+  const out: Record<string, unknown> = { content: [{ type: "text", text }, ...partBlocks(result.parts)] }
+  if (!omitFalseIsError) out.isError = result.isError
+  else if (result.isError) out.isError = true
+  if (result.structured !== undefined && result.structured !== null) out.structuredContent = result.structured
+  if (result.meta) out._meta = result.meta
+  return out
+}
+
 /**
  * §7C. A served tool's `ToolResult.parts` become MCP content blocks appended after the
  * text part, in order — image ⇒ image content, audio ⇒ audio content, file ⇒ an embedded
@@ -116,3 +148,84 @@ function partBlocks(parts: ContentPart[] | undefined): any[] {
   }
   return out
 }
+
+/** A loopback MCP endpoint for a local agent (SPEC §8C, {@link Toolkit.asMcpServer}). */
+export interface LocalMcpServer {
+  /** `http://127.0.0.1:<port>/mcp`. */
+  url: string
+  /** 64 lowercase hex chars; required as `Authorization: Bearer <token>`. Never logged. */
+  token: string
+  /** Stops the listener. Idempotent. */
+  close(): Promise<void>
+}
+
+/**
+ * Serves `tools` (filtered by `cfg.tools`) as the stateless §7C streamable-HTTP MCP endpoint on
+ * `127.0.0.1:<ephemeral>/mcp` behind a fresh bearer token. Other paths ⇒ 404; missing/wrong
+ * token ⇒ 401 + `WWW-Authenticate: Bearer` (constant-time compare); a non-POST ⇒ 405.
+ */
+export async function serveLocalMcp(tools: Tool[], cfg?: MCPServeConfig): Promise<LocalMcpServer> {
+  const exposed = exposedMcpTools(tools, cfg)
+  const token = randomBytes(32).toString("hex")
+  const want = Buffer.from("Bearer " + token)
+  const server = http.createServer((req, res) => {
+    const u = req.url ?? ""
+    if (u !== "/mcp" && !u.startsWith("/mcp?")) {
+      res.writeHead(404).end("not found")
+      return
+    }
+    const got = Buffer.from(String(req.headers.authorization ?? ""))
+    if (got.length !== want.length || !timingSafeEqual(got, want)) {
+      res.writeHead(401, { "WWW-Authenticate": "Bearer" }).end("unauthorized")
+      return
+    }
+    if (req.method !== "POST") {
+      res.writeHead(405, { Allow: "POST" }).end("method not allowed")
+      return
+    }
+    void (async () => {
+      const body = await readBody(req)
+      let parsed: unknown
+      try {
+        parsed = body ? JSON.parse(body) : undefined
+      } catch {
+        parsed = undefined
+      }
+      const mcp = buildMcpServer(exposed, cfg)
+      const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined })
+      res.on("close", () => {
+        void transport.close()
+        void mcp.close()
+      })
+      await mcp.connect(transport)
+      await transport.handleRequest(req, res, parsed)
+    })().catch(() => {
+      if (!res.headersSent) res.writeHead(500).end("mcp error")
+    })
+  })
+  await new Promise<void>((resolve, reject) => {
+    server.once("error", reject)
+    server.listen(0, "127.0.0.1", () => resolve())
+  })
+  const port = (server.address() as AddressInfo).port
+  let closing: Promise<void> | undefined
+  return {
+    url: `http://127.0.0.1:${port}/mcp`,
+    token,
+    close: () =>
+      (closing ??= new Promise<void>((resolve) => {
+        server.close(() => resolve())
+        server.closeAllConnections()
+      })),
+  }
+}
+
+function readBody(req: http.IncomingMessage): Promise<string> {
+  return new Promise((resolve, reject) => {
+    let data = ""
+    req.setEncoding("utf8")
+    req.on("data", (c: string) => (data += c))
+    req.on("end", () => resolve(data))
+    req.on("error", reject)
+  })
+}

package/src/mcpserverauth.ts

@@ -0,0 +1,216 @@
+/**
+ * MCP server authorization (SPEC §2A.2, §7C.2): an `mcpHandler` as an OAuth 2.1 protected
+ * resource. `McpServerAuth` is a plain helper producing the handler's `authenticate` hook and the
+ * RFC 9728 metadata listener; the host mounts both. Identity, tenants and token storage stay the
+ * host's.
+ *
+ *   const auth = new McpServerAuth({ issuer: "https://login.example", scopes: { "*": ["mcp"] } })
+ *   const mcp = toolkit.mcpHandler({ protocolVersions: ["2026-07-28"], authenticate: auth.authenticate })
+ *   const meta = auth.metadata()  // mount at /.well-known/oauth-protected-resource[/mcp]
+ */
+import { createPublicKey, verify as cryptoVerify, type KeyObject } from "node:crypto"
+import type { IncomingMessage, ServerResponse } from "node:http"
+import { McpAuthError } from "./mcphandler.js"
+import { decodeHeaderValue, getJson } from "./mcpheader.js"
+
+/** The verified caller; under McpServerAuth, `identityFrom(ctx)` returns it. */
+export interface McpPrincipal {
+  subject: string
+  scopes: string[]
+  claims?: Record<string, unknown>
+}
+
+export interface McpServerAuthOptions {
+  /** The authorization server's issuer (advertised in the PRM, and the JWT `iss` required). */
+  issuer: string
+  /** Canonical resource URI (PRM `resource`, JWT `aud`). Omit ⇒ `<scheme>://<Host><resourcePath>` per request. */
+  audience?: string
+  /** Where the handler is mounted. Default "/mcp". */
+  resourcePath?: string
+  /** "*" is required on every request (and advertised); a tool name adds scopes for that tools/call. */
+  scopes?: Record<string, string[]>
+  /** Replaces the default RS256/JWKS verifier (opaque tokens, introspection). Throw ⇒ invalid_token. */
+  verify?: (req: IncomingMessage, token: string, audience: string) => Promise<McpPrincipal> | McpPrincipal
+  /** Fetches AS metadata and JWKS. Default: global fetch with a 10 s timeout. */
+  fetch?: typeof fetch
+}
+
+const PRM_PATH = "/.well-known/oauth-protected-resource"
+
+function header(req: IncomingMessage, name: string): string {
+  const v = req.headers[name.toLowerCase()]
+  return Array.isArray(v) ? (v[0] ?? "") : (v ?? "")
+}
+
+function origin(req: IncomingMessage): string {
+  const scheme = (req.socket as { encrypted?: boolean }).encrypted ? "https" : "http"
+  return `${scheme}://${header(req, "Host")}`
+}
+
+/** Protects an `mcpHandler` with bearer tokens (SPEC §2A.2). */
+export class McpServerAuth {
+  readonly issuer: string
+  readonly audience?: string
+  readonly resourcePath: string
+  readonly scopes: Record<string, string[]>
+  private readonly verifyHook?: McpServerAuthOptions["verify"]
+  private readonly fetchImpl: typeof fetch
+  private keys?: Map<string, KeyObject>
+  private fetched = 0
+
+  constructor(opts: McpServerAuthOptions) {
+    this.issuer = opts.issuer
+    this.audience = opts.audience || undefined
+    this.resourcePath = opts.resourcePath || "/mcp"
+    this.scopes = opts.scopes ?? {}
+    this.verifyHook = opts.verify
+    this.fetchImpl = opts.fetch ?? ((u, init) => fetch(u, { ...init, signal: AbortSignal.timeout(10_000) }))
+  }
+
+  private audienceFor(req: IncomingMessage): string {
+    return this.audience ?? origin(req) + this.resourcePath
+  }
+
+  /** The RFC 9728 metadata URL the challenge names. */
+  metadataUrl(req: IncomingMessage): string {
+    if (this.audience) {
+      try {
+        const u = new URL(this.audience)
+        if (u.host) {
+          const path = /^[^:]+:\/\/[^/?#]*\//.test(this.audience) ? u.pathname : ""
+          return `${u.protocol}//${u.host}${PRM_PATH}${path}`
+        }
+      } catch {
+        // fall through to the request-derived URL
+      }
+    }
+    return origin(req) + PRM_PATH + this.resourcePath
+  }
+
+  /** Request listener serving the protected resource metadata at the two PRM paths; anything else 404. */
+  metadata(): (req: IncomingMessage, res: ServerResponse) => void {
+    return (req, res) => {
+      const path = (req.url ?? "/").split("?")[0]
+      if (req.method !== "GET" || (path !== PRM_PATH && path !== PRM_PATH + this.resourcePath)) {
+        res.writeHead(404, { "Content-Type": "text/plain; charset=utf-8" }).end("404 page not found\n")
+        return
+      }
+      res.writeHead(200, { "Content-Type": "application/json" })
+      res.end(
+        JSON.stringify({
+          resource: this.audienceFor(req),
+          authorization_servers: [this.issuer],
+          scopes_supported: this.scopes["*"] ?? [],
+          bearer_methods_supported: ["header"],
+        }) + "\n",
+      )
+    }
+  }
+
+  private challenge(req: IncomingMessage, status: number, scopes: string[] | undefined, err: string): McpAuthError {
+    let v = `Bearer resource_metadata="${this.metadataUrl(req)}"`
+    if (scopes && scopes.length > 0) v += `, scope="${scopes.join(" ")}"`
+    if (err) v += `, error="${err}"`
+    return new McpAuthError(status, v, err)
+  }
+
+  /**
+   * The `mcpHandler` `authenticate` hook (bound). Missing token ⇒ 401; invalid ⇒ 401
+   * error="invalid_token"; a missing scope ⇒ 403 error="insufficient_scope" naming the full needed
+   * set. Per-tool scopes come from the Mcp-Method / Mcp-Name headers (the 2026-07-28 wire).
+   */
+  readonly authenticate = async (req: IncomingMessage): Promise<McpPrincipal> => {
+    const authz = header(req, "Authorization")
+    const tok = authz.startsWith("Bearer ") ? authz.slice(7) : ""
+    if (tok.trim() === "") throw this.challenge(req, 401, this.scopes["*"], "")
+    let p: McpPrincipal
+    try {
+      const aud = this.audienceFor(req)
+      p = this.verifyHook ? await this.verifyHook(req, tok, aud) : await this.verifyJwt(tok, aud)
+    } catch {
+      throw this.challenge(req, 401, this.scopes["*"], "invalid_token")
+    }
+    const need = [...(this.scopes["*"] ?? [])]
+    if (header(req, "Mcp-Method") === "tools/call") {
+      const [name, ok] = decodeHeaderValue(header(req, "Mcp-Name"))
+      if (ok) for (const s of this.scopes[name] ?? []) if (!need.includes(s)) need.push(s)
+    }
+    const have = p.scopes ?? []
+    if (need.some((s) => !have.includes(s))) throw this.challenge(req, 403, need, "insufficient_scope")
+    return p
+  }
+
+  private async verifyJwt(tok: string, aud: string): Promise<McpPrincipal> {
+    const parts = tok.split(".")
+    if (parts.length !== 3) throw new Error("malformed jwt")
+    const hdr = decodeSeg(parts[0]!)
+    const claims = decodeSeg(parts[1]!)
+    if (!hdr || !claims || hdr.alg !== "RS256") throw new Error("bad jwt header or claims")
+    const key = await this.key(typeof hdr.kid === "string" ? hdr.kid : "")
+    if (!/^[A-Za-z0-9_-]*$/.test(parts[2]!)) throw new Error("bad signature encoding")
+    const sig = Buffer.from(parts[2]!, "base64url")
+    if (!cryptoVerify("RSA-SHA256", Buffer.from(parts[0] + "." + parts[1]), key, sig)) throw new Error("bad signature")
+    if (claims.iss !== this.issuer) throw new Error("wrong issuer")
+    const a = claims.aud
+    if (!(typeof a === "string" ? a === aud : Array.isArray(a) && a.includes(aud))) throw new Error("wrong audience")
+    const exp = typeof claims.exp === "number" ? Math.trunc(claims.exp) : 0
+    if (exp <= Math.floor(Date.now() / 1000)) throw new Error("expired")
+    const scope = typeof claims.scope === "string" ? claims.scope : ""
+    return {
+      subject: typeof claims.sub === "string" ? claims.sub : "",
+      scopes: scope.split(/\s+/).filter(Boolean),
+      claims,
+    }
+  }
+
+  /** The JWKS key for kid; an unknown kid refetches at most every 30 s. */
+  private async key(kid: string): Promise<KeyObject> {
+    const k = this.keys?.get(kid)
+    if (k) return k
+    if (this.keys && Date.now() - this.fetched < 30_000) throw new Error("unknown kid")
+    const md = await discoverAs(this.fetchImpl, this.issuer)
+    const jwks = await getJson(this.fetchImpl, String(md.jwks_uri ?? ""))
+    const keys = new Map<string, KeyObject>()
+    for (const j of Array.isArray(jwks?.keys) ? jwks.keys : []) {
+      if (j?.kty !== "RSA" || typeof j.n !== "string" || typeof j.e !== "string") continue
+      try {
+        keys.set(String(j.kid ?? ""), createPublicKey({ key: { kty: "RSA", n: j.n, e: j.e }, format: "jwk" }))
+      } catch {
+        // skip a malformed key
+      }
+    }
+    this.keys = keys
+    this.fetched = Date.now()
+    const got = keys.get(kid)
+    if (!got) throw new Error("unknown kid")
+    return got
+  }
+}
+
+function decodeSeg(s: string): Record<string, any> | undefined {
+  if (!/^[A-Za-z0-9_-]+$/.test(s)) return undefined
+  try {
+    const v = JSON.parse(Buffer.from(s, "base64url").toString("utf8"))
+    return v && typeof v === "object" && !Array.isArray(v) ? v : undefined
+  } catch {
+    return undefined
+  }
+}
+
+/** AS metadata in SPEC §2A.1 step 3 order; the metadata `issuer` must equal the issuer. */
+async function discoverAs(f: typeof fetch, issuer: string): Promise<Record<string, unknown>> {
+  const u = new URL(issuer)
+  const org = `${u.protocol}//${u.host}`
+  const path = (/^[^:]+:\/\/[^/?#]*\//.test(issuer) ? u.pathname : "").replace(/\/$/, "")
+  const cands = [`${org}/.well-known/oauth-authorization-server${path}`, `${org}/.well-known/openid-configuration${path}`]
+  if (path) cands.push(`${org}${path}/.well-known/openid-configuration`)
+  for (const c of cands) {
+    try {
+      const md = await getJson(f, c)
+      if (md && md.issuer === issuer) return md
+    } catch {
+      // next candidate
+    }
+  }
+  throw new Error("authorization server metadata not found for " + issuer)
+}

package/src/serve.ts

@@ -233,6 +233,13 @@ export async function startA2AServer(opts: StartServerOptions): Promise<ServeHan
     // 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?"))) {
+      // Stateless profile: no server-initiated SSE stream exists, so only POST is
+      // served. Refuse anything else at once (§7C) instead of holding a GET open.
+      if (req.method !== "POST") {
+        res.writeHead(405, { Allow: "POST" })
+        res.end()
+        return
+      }
       void (async () => {
         const body = req.method === "POST" ? await readBody(req) : ""
         const parsed = body ? safeJson(body) : undefined

package/src/skill.ts

@@ -517,3 +517,53 @@ export function loadSkills(input: string | string[] | LoadSkillsOptions): SkillS
     },
   }
 }
+
+/**
+ * §7C.2: one skill published through the MCP 2026-07-28 skills extension (SEP-2640) by
+ * `mcpHandler({listSkills})`. `files` are paths relative to the skill directory
+ * ("/"-separated) and MUST include "SKILL.md". Frontmatter defaults to `{name}`.
+ */
+export interface McpSkill {
+  name: string
+  frontmatter?: Record<string, unknown>
+  files: { path: string; text: string }[]
+}
+
+/**
+ * §7C.2: every skill under `dir` (any depth, `**∕SKILL.md`, symlinks NOT followed) for
+ * `mcpHandler({listSkills})`. Frontmatter is `{name, description}` parsed as §3 (trimmed); a
+ * skill whose frontmatter has no `name` is skipped. Files are every regular file under the
+ * skill directory that is valid UTF-8 (binary files are skipped — the wire carries text),
+ * sorted by path; skills sorted by name. A missing `dir` throws.
+ */
+export function loadMcpSkills(dir: string): McpSkill[] {
+  const utf8 = new TextDecoder("utf-8", { fatal: true })
+  const out: McpSkill[] = []
+  const walk = (d: string, visit: (full: string) => void) => {
+    for (const e of sortEntriesByName(readdirSync(d, { withFileTypes: true }))) {
+      const full = path.join(d, e.name)
+      if (e.isDirectory()) walk(full, visit)
+      else if (e.isFile()) visit(full)
+    }
+  }
+  walk(dir, (p) => {
+    if (path.basename(p) !== "SKILL.md") return
+    const fm = parseFrontmatter(readFileSync(p, "utf8"))
+    if (fm.malformed || !fm.data.name) return
+    const root = path.dirname(p)
+    const files: { path: string; text: string }[] = []
+    walk(root, (fp) => {
+      let text: string
+      try {
+        text = utf8.decode(readFileSync(fp))
+      } catch (e) {
+        if (e instanceof TypeError) return // not UTF-8
+        throw e
+      }
+      files.push({ path: path.relative(root, fp).split(path.sep).join("/"), text })
+    })
+    files.sort((a, b) => compareCodePoints(a.path, b.path))
+    out.push({ name: fm.data.name, frontmatter: { name: fm.data.name, description: fm.data.description ?? "" }, files })
+  })
+  return out.sort((a, b) => compareCodePoints(a.name, b.name))
+}

package/src/toolkit.ts

@@ -8,7 +8,8 @@ import { loadSkills, type SkillDef, 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 { serveLocalMcp, type LocalMcpServer, type MCPServeConfig, type OnCall } from "./mcpserve.js"
+import { createMcpHandler, type McpHandler, type McpHandlerConfig } from "./mcphandler.js"
 import { toAnthropic, toGemini, toOpenAI } from "./adapters.js"
 import type { Client } from "./client.js"
 import type { Media } from "./media.js"
@@ -48,6 +49,10 @@ export interface ToolkitOptions {
   /** §2 Gap 3. Bounds the MCP load: each connect/list is capped by the server timeout and the
    * whole load aborts promptly if this signal fires. Omit ⇒ unbounded as before. */
   signal?: AbortSignal
+  /** §2A.1a where MCP OAuth tokens live (default: in memory, per load). */
+  tokenStore?: import("./mcp2026/auth.js").TokenStore
+  /** §2A.1a how `auto` MCP OAuth opens the authorization URL (default: the OS opener). */
+  openUrl?: (url: string) => unknown | Promise<unknown>
 }
 
 export class Toolkit {
@@ -83,12 +88,13 @@ export class Toolkit {
   }
 
   static async create(opts: ToolkitOptions = {}): Promise<Toolkit> {
-    const mcp = opts.mcpConfig !== undefined ? await loadMcp(opts.mcpConfig, { waitFor: opts.waitFor, signal: opts.signal }) : undefined
+    const mcp = opts.mcpConfig !== undefined ? await loadMcp(opts.mcpConfig, { waitFor: opts.waitFor, signal: opts.signal, tokenStore: opts.tokenStore, openUrl: opts.openUrl, disableTools: opts.disableTools }) : undefined
     // Skills come from directories, in-memory data, and/or a lazy provider (§3,
     // S1). The provider is resolved here (create() is async) and merged with the
     // data list; a provider failure is isolated so other sources still load.
     let skill: SkillSource | undefined
-    if (opts.skillsDir !== undefined || opts.skills !== undefined || opts.skillProvider !== undefined) {
+    const mcpSkills = mcp?.skills ?? []
+    if (opts.skillsDir !== undefined || opts.skills !== undefined || opts.skillProvider !== undefined || mcpSkills.length > 0) {
       let providerDefs: SkillDef[] = []
       if (opts.skillProvider) {
         try {
@@ -98,7 +104,8 @@ export class Toolkit {
           providerDefs = []
         }
       }
-      const dataDefs = [...(opts.skills ?? []), ...providerDefs]
+      // §2.7 remote skills (MCP skills extension) join the same inventory, after local ones.
+      const dataDefs = [...(opts.skills ?? []), ...providerDefs, ...mcpSkills]
       // disableSkills is sugar over a skillsFilter drop-list: fold each name in as false
       // WITHOUT overriding an explicit skillsFilter entry (explicit entries win).
       const filter =
@@ -221,6 +228,26 @@ export class Toolkit {
     })
   }
 
+  /**
+   * §7C.1 (ADR 0039). An embeddable streamable-HTTP MCP server as a Node request listener
+   * `(req, res) => void` (+ `notifyToolsChanged()`), to mount on the host's own server/router
+   * behind its own TLS, CORS and OAuth. Every policy is a hook in `cfg`; `serve()` is unchanged.
+   * Without `cfg.listTools` it exposes this toolkit's tools.
+   */
+  mcpHandler(cfg: McpHandlerConfig = {}): McpHandler {
+    return createMcpHandler(() => this.tools(), cfg)
+  }
+
+  /**
+   * SPEC §8C. Serves this toolkit for a local agent to call: the §7C MCP mapping (tool names
+   * verbatim, `skill` stays `skill`, optional `config` filter) on `127.0.0.1:<ephemeral>/mcp`
+   * behind a fresh 64-hex bearer token. The caller builds whatever `mcpServers` entry its agent
+   * accepts from `{url, token}`; `close()` stops it (idempotent).
+   */
+  asMcpServer(config?: MCPServeConfig): Promise<LocalMcpServer> {
+    return serveLocalMcp(this.tools(), config)
+  }
+
   async execute(name: string, args: Record<string, unknown>, ctx?: ToolContext): Promise<ToolResult> {
     const tool = this.byName.get(name)
     if (!tool) {

package/src/types.ts

@@ -25,6 +25,22 @@ export interface ToolResult {
    */
   parts?: ContentPart[]
   metadata?: Record<string, unknown>
+  /**
+   * Machine-readable result (MCP `structuredContent`, SPEC §1). Absent ⇒ byte-identical wire.
+   * When set and `output` is empty, MCP serve emits the JSON text of `structured` as the text block.
+   */
+  structured?: unknown
+  /** Protocol metadata for the wire result (MCP `_meta`, SPEC §1). Absent ⇒ omitted. */
+  meta?: Record<string, unknown>
+}
+
+/** MCP tool annotations (SPEC §1, §7C.1), sent verbatim on an MCP `tools/list` entry. */
+export interface ToolAnnotations {
+  title?: string
+  readOnlyHint?: boolean
+  destructiveHint?: boolean
+  idempotentHint?: boolean
+  openWorldHint?: boolean
 }
 
 export interface ToolContext {
@@ -35,6 +51,9 @@ export interface ToolContext {
   /** The model's id for this tool call, set by the client loop (§4C). A message's calls run
    * concurrently, so this is how a tool tells its sibling calls apart. Absent outside the loop. */
   callId?: string
+  /** Set by `toolkit.mcpHandler` (§7C.1): the inbound MCP request this call serves. Read it with
+   * `identityFrom(ctx)` / `requestFrom(ctx)` / `mcpSessionIdFrom(ctx)` / `mcpRequestMetaFrom(ctx)`. */
+  mcp?: import("./mcphandler.js").McpContext
 }
 
 /**
@@ -133,6 +152,10 @@ export interface Tool {
   /** Decides per call whether this tool may run alongside other safe calls of the same model
    * response (SPEC §8 "Tool scheduling"). Absent ⇒ safe only when `hints.readOnly`. */
   concurrencySafe?: (args: Record<string, unknown>) => boolean
+  /** JSON Schema of `ToolResult.structured` (SPEC §1); absent ⇒ omitted everywhere. */
+  outputSchema?: Record<string, unknown>
+  /** MCP annotations (§7C.1), verbatim on the MCP wire; absent ⇒ derived from `hints`, else omitted. */
+  annotations?: ToolAnnotations
 }
 
 export type McpStatus = "connected" | "disabled" | "failed"