toolnexus 0.24.0 → 0.26.0

package/dist/mcpheader.d.ts

@@ -0,0 +1,5 @@
+/** 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 declare function decodeHeaderValue(v: string): [string, boolean];
+/** GET a JSON document (200 only). */
+export declare function getJson(f: typeof fetch, url: string): Promise<any>;

package/dist/mcpheader.js

@@ -0,0 +1,18 @@
+/** 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) {
+    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, url) {
+    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/dist/mcpserve.d.ts

@@ -1,19 +1,5 @@
-/**
- * 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";
+import type { Tool, ToolSource, ToolResult } 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". */
@@ -45,3 +31,26 @@ export declare function exposedMcpTools(tools: Tool[], cfg?: MCPServeConfig): To
  * request (stateless).
  */
 export declare function buildMcpServer(tools: Tool[], cfg?: MCPServeConfig, onCall?: OnCall): 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 declare function toolResultToMcp(result: ToolResult, omitFalseIsError?: boolean): Record<string, unknown>;
+/** 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 declare function serveLocalMcp(tools: Tool[], cfg?: MCPServeConfig): Promise<LocalMcpServer>;

package/dist/mcpserve.js

@@ -12,7 +12,10 @@
  * 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 { 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";
 const DEFAULT_NAME = "toolnexus";
 const DEFAULT_VERSION = "0.1.0";
@@ -38,7 +41,9 @@ 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 })),
+        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) => {
         const tool = byName.get(req.params.name);
@@ -63,10 +68,38 @@ export function buildMcpServer(tools, cfg, onCall) {
                 // Host callback errors are isolated.
             }
         }
-        return { content: [{ type: "text", text: result.output }, ...partBlocks(result.parts)], isError: result.isError };
+        return toolResultToMcp(result);
     });
     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, omitFalseIsError = false) {
+    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 = { 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
@@ -93,3 +126,73 @@ function partBlocks(parts) {
     }
     return out;
 }
+/**
+ * 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, cfg) {
+    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;
+            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((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(0, "127.0.0.1", () => resolve());
+    });
+    const port = server.address().port;
+    let closing;
+    return {
+        url: `http://127.0.0.1:${port}/mcp`,
+        token,
+        close: () => (closing ??= new Promise((resolve) => {
+            server.close(() => resolve());
+            server.closeAllConnections();
+        })),
+    };
+}
+function readBody(req) {
+    return new Promise((resolve, reject) => {
+        let data = "";
+        req.setEncoding("utf8");
+        req.on("data", (c) => (data += c));
+        req.on("end", () => resolve(data));
+        req.on("error", reject);
+    });
+}

package/dist/mcpserverauth.d.ts

@@ -0,0 +1,48 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+/** 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;
+}
+/** Protects an `mcpHandler` with bearer tokens (SPEC §2A.2). */
+export declare class McpServerAuth {
+    readonly issuer: string;
+    readonly audience?: string;
+    readonly resourcePath: string;
+    readonly scopes: Record<string, string[]>;
+    private readonly verifyHook?;
+    private readonly fetchImpl;
+    private keys?;
+    private fetched;
+    constructor(opts: McpServerAuthOptions);
+    private audienceFor;
+    /** The RFC 9728 metadata URL the challenge names. */
+    metadataUrl(req: IncomingMessage): string;
+    /** Request listener serving the protected resource metadata at the two PRM paths; anything else 404. */
+    metadata(): (req: IncomingMessage, res: ServerResponse) => void;
+    private challenge;
+    /**
+     * 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: (req: IncomingMessage) => Promise<McpPrincipal>;
+    private verifyJwt;
+    /** The JWKS key for kid; an unknown kid refetches at most every 30 s. */
+    private key;
+}

package/dist/mcpserverauth.js

@@ -0,0 +1,203 @@
+/**
+ * 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 } from "node:crypto";
+import { McpAuthError } from "./mcphandler.js";
+import { decodeHeaderValue, getJson } from "./mcpheader.js";
+const PRM_PATH = "/.well-known/oauth-protected-resource";
+function header(req, name) {
+    const v = req.headers[name.toLowerCase()];
+    return Array.isArray(v) ? (v[0] ?? "") : (v ?? "");
+}
+function origin(req) {
+    const scheme = req.socket.encrypted ? "https" : "http";
+    return `${scheme}://${header(req, "Host")}`;
+}
+/** Protects an `mcpHandler` with bearer tokens (SPEC §2A.2). */
+export class McpServerAuth {
+    issuer;
+    audience;
+    resourcePath;
+    scopes;
+    verifyHook;
+    fetchImpl;
+    keys;
+    fetched = 0;
+    constructor(opts) {
+        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) }));
+    }
+    audienceFor(req) {
+        return this.audience ?? origin(req) + this.resourcePath;
+    }
+    /** The RFC 9728 metadata URL the challenge names. */
+    metadataUrl(req) {
+        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() {
+        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");
+        };
+    }
+    challenge(req, status, scopes, err) {
+        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).
+     */
+    authenticate = async (req) => {
+        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;
+        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;
+    };
+    async verifyJwt(tok, aud) {
+        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. */
+    async key(kid) {
+        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();
+        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) {
+    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, issuer) {
+    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/dist/serve.js

@@ -153,6 +153,13 @@ export async function startA2AServer(opts) {
         // 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/dist/skill.d.ts

@@ -74,3 +74,24 @@ export interface SkillSource {
 export declare function listSkills(input: string | string[] | LoadSkillsOptions): SkillInventory;
 /** Discover skills (dirs and/or data) and build the `skill` loader tool. */
 export declare function loadSkills(input: string | string[] | LoadSkillsOptions): SkillSource;
+/**
+ * §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 declare function loadMcpSkills(dir: string): McpSkill[];

package/dist/skill.js

@@ -445,3 +445,47 @@ export function loadSkills(input) {
         },
     };
 }
+/**
+ * §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) {
+    const utf8 = new TextDecoder("utf-8", { fatal: true });
+    const out = [];
+    const walk = (d, visit) => {
+        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 = [];
+        walk(root, (fp) => {
+            let text;
+            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/dist/toolkit.d.ts

@@ -7,7 +7,8 @@ import { type SkillDef } from "./skill.js";
 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 LocalMcpServer, type MCPServeConfig, type OnCall } from "./mcpserve.js";
+import { type McpHandler, type McpHandlerConfig } from "./mcphandler.js";
 import type { Client } from "./client.js";
 import type { Media } from "./media.js";
 export interface ToolkitOptions {
@@ -45,6 +46,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 declare class Toolkit {
     private readonly mcp;
@@ -81,6 +86,20 @@ export declare class Toolkit {
         mcp?: MCPServeConfig;
         onCall?: OnCall;
     }): Promise<ServeHandle>;
+    /**
+     * §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;
+    /**
+     * 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>;
     execute(name: string, args: Record<string, unknown>, ctx?: ToolContext): Promise<ToolResult>;
     /** Markdown skill catalog for the system prompt. */
     skillsPrompt(): string;

package/dist/toolkit.js

@@ -3,6 +3,8 @@ import { loadSkills } from "./skill.js";
 import { selectBuiltins } from "./builtin.js";
 import { agentTools, parseAgentsConfig } from "./a2a.js";
 import { startA2AServer } from "./serve.js";
+import { serveLocalMcp } from "./mcpserve.js";
+import { createMcpHandler } from "./mcphandler.js";
 import { toAnthropic, toGemini, toOpenAI } from "./adapters.js";
 export class Toolkit {
     mcp;
@@ -39,12 +41,13 @@ export class Toolkit {
         }
     }
     static async create(opts = {}) {
-        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;
-        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 = [];
             if (opts.skillProvider) {
                 try {
@@ -55,7 +58,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 = opts.disableSkills && opts.disableSkills.length > 0
@@ -157,6 +161,24 @@ export class Toolkit {
             onCall: opts.onCall,
         });
     }
+    /**
+     * §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 = {}) {
+        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) {
+        return serveLocalMcp(this.tools(), config);
+    }
     async execute(name, args, ctx) {
         const tool = this.byName.get(name);
         if (!tool) {