mcp-authz 0.3.0 → 0.4.0

package/README.md

@@ -22,7 +22,7 @@ Plenty of good tools solve the neighbouring problems. Take one of them when its
 | OAuth plumbing                 | official SDK, mcp-auth | Authentication and resource-server mechanics, with no permission model |
 | Embedded dependency            | **mcp-authz**          | One package, and a policy engine that stays small by design            |
 
-Two cases need none of this. A stdio server on one laptop already has the OS account as its boundary. A server where every caller gets identical access wants one service credential and no policy.
+Two cases need none of this. A stdio server on one laptop already has the OS account as its boundary. A server where every caller gets identical access wants one service credential and no policy. To have that stdio server show the model fewer tools, [`mcp-authz wrap`](#mcp-authz-wrap-fewer-tools-from-a-stdio-server) does that with no policy ([walkthrough](https://jagreehal.github.io/mcp-authz/wrap/)).
 
 ### You need one integration seam
 
@@ -592,8 +592,6 @@ as served, so a snapshot turns that into a diff on the pull request. Nothing is
 enforced at boot: a digest in production is a second source of truth, and would
 make a description edit an outage.
 
-`@modelcontextprotocol/client` is an optional peer, needed only by this subpath.
-
 ### `mcp-authz/openapi` — the same bet on an HTTP API
 
 An OpenAPI document is the other catalogue an agent reads. A tool that is never
@@ -863,6 +861,41 @@ and on an invalid policy, and 0 on an unused permission, which stays a warning
 because granting a role ahead of the tool that will use it is how a staged
 rollout works.
 
+### `mcp-authz wrap`: fewer tools from a stdio server
+
+`wrap` sits in front of any stdio MCP server and hides the tools you leave out,
+so a model reaches less than your API key allows.
+
+```bash
+npx -y mcp-authz tools --out cases.jsonc -- npx -y @acme/cases-mcp
+```
+
+`tools` saves the server's tools to `cases.jsonc`, one line each with what the
+tool does and what the server says about it, destructive ones commented out.
+A schema beside it gives your editor completion and typo checks. `tools` also
+prints the `mcpServers` entry to paste, or writes it into a client config file
+with `--client-out .mcp.json`:
+
+```json
+"cases": {
+  "command": "npx",
+  "args": ["-y", "mcp-authz", "wrap", "--config", "/Users/you/mcp/cases.jsonc"],
+  "env": { "CASES_API_KEY": "..." }
+}
+```
+
+`wrap` drops unlisted tools from `tools/list` and answers a call to one with an
+error that names it, so the server never receives it. Tools the server adds
+later stay hidden until you list them. `mcp-authz tools --check cases.jsonc` reports
+what changed on the server since you saved, and `tools --config cases.jsonc
+--refresh` records it, keeping your choices. For a quick trial, `wrap --deny
+a,b -- <command>` takes the list as arguments.
+
+`wrap` limits one session; scope the key itself where the service supports it.
+When the client disconnects, `wrap` stops the whole process tree, `npx` and the
+server it started. The [walkthrough](https://jagreehal.github.io/mcp-authz/wrap/)
+covers the rest.
+
 ### `mcp-authz/policy`
 
 The policy half on its own (`definePolicy`, `definePermissions`,

package/dist/cli.d.ts

@@ -1,4 +1,3 @@
 //#region src/cli.d.ts
-declare function main(argv: readonly string[]): number | Promise<number>;
-//#endregion
-export { main };
+export declare function main(argv: readonly string[]): number | Promise<number>;
+//#endregion

package/dist/cli.js

@@ -1,9 +1,661 @@
 #!/usr/bin/env node
 import { i as reconcile, r as definePolicy } from "./policy-BBp3Jq6G.js";
-import { readFileSync, writeFileSync } from "node:fs";
-import { resolve } from "node:path";
+import { createRequire } from "node:module";
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { basename, dirname, extname, join, relative, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { parseArgs } from "node:util";
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+import { setTimeout } from "node:timers/promises";
+import { tmpdir } from "node:os";
+//#region src/windows-job.ts
+/** Quote one argument for CreateProcessW's command line (not a shell). */
+function quoteWindowsArgument(value) {
+	return `"${value.replace(/(\\*)"/g, "$1$1\\\"").replace(/(\\+)$/, "$1$1")}"`;
+}
+/**
+* A PowerShell supervisor owns a kill-on-close Job Object. A small Node
+* launcher enters it while suspended, before it can create any descendants.
+* The supervisor keeps its handle until the launcher exits; closing it kills
+* every remaining descendant, even after their immediate parent has exited.
+* Only the supervisor owns the handle, so terminating it also kills the job.
+*/
+function windowsJobCommand(command, args) {
+	const crossSpawn = createRequire(import.meta.url).resolve("cross-spawn");
+	const directory = mkdtempSync(join(tmpdir(), "mcp-authz-job-"));
+	const specPath = join(directory, "spec.json");
+	writeFileSync(specPath, JSON.stringify({
+		command,
+		args
+	}), { mode: 384 });
+	const cleanup = () => rmSync(directory, {
+		recursive: true,
+		force: true
+	});
+	const launcher = [
+		`const fs = require('fs');`,
+		`const spawn = require(${JSON.stringify(crossSpawn)});`,
+		`const spec = JSON.parse(fs.readFileSync(${JSON.stringify(specPath)}, 'utf8'));`,
+		`fs.rmSync(${JSON.stringify(directory)}, { recursive: true, force: true });`,
+		`const child = spawn(spec.command, spec.args, { stdio: 'inherit' });`,
+		`child.on('error', error => { console.error(error.message); process.exit(1); });`,
+		`child.on('exit', code => process.exit(code ?? 1));`
+	].join("\n");
+	const commandLine = [
+		process.execPath,
+		"--input-type=commonjs",
+		"-e",
+		launcher
+	].map(quoteWindowsArgument).join(" ");
+	const encoded = Buffer.from(commandLine, "utf8").toString("base64");
+	const script = [
+		"$ErrorActionPreference = \"Stop\"",
+		"$ProgressPreference = 'SilentlyContinue'",
+		"Add-Type -TypeDefinition @'",
+		JOB_SUPERVISOR,
+		"'@",
+		`$line = [Text.Encoding]::UTF8.GetString([Convert]::FromBase64String('${encoded}'))`,
+		"try { exit ([McpAuthzJob]::Run($line)) }",
+		"catch { [Console]::Error.WriteLine($_.Exception.Message); exit 1 }"
+	].join("\n");
+	return {
+		specPath,
+		/** Remove the spec if the launcher never got to; safe to call twice. */
+		cleanup,
+		command: join(process.env.SystemRoot ?? "C:\\Windows", "System32", "WindowsPowerShell", "v1.0", "powershell.exe"),
+		args: [
+			"-NoLogo",
+			"-NoProfile",
+			"-NonInteractive",
+			"-EncodedCommand",
+			Buffer.from(script, "utf16le").toString("base64")
+		]
+	};
+}
+const JOB_SUPERVISOR = String.raw`
+using System;
+using System.ComponentModel;
+using System.Runtime.InteropServices;
+using System.Text;
+
+public static class McpAuthzJob {
+    [StructLayout(LayoutKind.Sequential)]
+    struct BasicLimits {
+        public long ProcessTime, JobTime;
+        public uint Flags;
+        public UIntPtr MinimumWorkingSet, MaximumWorkingSet;
+        public uint ActiveProcessLimit;
+        public UIntPtr Affinity;
+        public uint PriorityClass, SchedulingClass;
+    }
+    [StructLayout(LayoutKind.Sequential)]
+    struct IoCounters { public ulong ReadOps, WriteOps, OtherOps, ReadBytes, WriteBytes, OtherBytes; }
+    [StructLayout(LayoutKind.Sequential)]
+    struct ExtendedLimits {
+        public BasicLimits Basic;
+        public IoCounters Io;
+        public UIntPtr ProcessMemory, JobMemory, PeakProcessMemory, PeakJobMemory;
+    }
+    [StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)]
+    struct StartupInfo {
+        public uint Size;
+        public string Reserved, Desktop, Title;
+        public uint X, Y, XSize, YSize, XChars, YChars, Fill, Flags;
+        public ushort Show, ReservedSize;
+        public IntPtr ReservedData, Input, Output, Error;
+    }
+    [StructLayout(LayoutKind.Sequential)]
+    struct ProcessInfo { public IntPtr Process, Thread; public uint ProcessId, ThreadId; }
+
+    [DllImport("kernel32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
+    static extern IntPtr CreateJobObjectW(IntPtr security, string name);
+    [DllImport("kernel32.dll", SetLastError = true)]
+    static extern bool SetInformationJobObject(IntPtr job, int infoClass, ref ExtendedLimits info, uint size);
+    [DllImport("kernel32.dll", SetLastError = true)]
+    static extern bool AssignProcessToJobObject(IntPtr job, IntPtr process);
+    [DllImport("kernel32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
+    static extern bool CreateProcessW(string app, StringBuilder line, IntPtr processSecurity,
+        IntPtr threadSecurity, bool inherit, uint flags, IntPtr environment, string cwd,
+        ref StartupInfo startup, out ProcessInfo process);
+    [DllImport("kernel32.dll", SetLastError = true)]
+    static extern uint ResumeThread(IntPtr thread);
+    [DllImport("kernel32.dll", SetLastError = true)]
+    static extern uint WaitForSingleObject(IntPtr handle, uint milliseconds);
+    [DllImport("kernel32.dll", SetLastError = true)]
+    static extern bool GetExitCodeProcess(IntPtr process, out uint code);
+    [DllImport("kernel32.dll")]
+    static extern IntPtr GetStdHandle(int handle);
+    [DllImport("kernel32.dll", SetLastError = true)]
+    static extern bool TerminateProcess(IntPtr process, uint code);
+    [DllImport("kernel32.dll")]
+    static extern bool CloseHandle(IntPtr handle);
+
+    static void Check(bool success) {
+        if (!success) throw new Win32Exception(Marshal.GetLastWin32Error());
+    }
+
+    public static int Run(string commandLine) {
+        IntPtr job = CreateJobObjectW(IntPtr.Zero, null);
+        Check(job != IntPtr.Zero);
+        ProcessInfo process = new ProcessInfo();
+        bool assigned = false;
+        try {
+            ExtendedLimits limits = new ExtendedLimits();
+            limits.Basic.Flags = 0x2000; // JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE
+            Check(SetInformationJobObject(job, 9, ref limits, (uint)Marshal.SizeOf(typeof(ExtendedLimits))));
+            StartupInfo startup = new StartupInfo();
+            startup.Size = (uint)Marshal.SizeOf(typeof(StartupInfo));
+            startup.Flags = 0x100; // STARTF_USESTDHANDLES
+            startup.Input = GetStdHandle(-10);
+            startup.Output = GetStdHandle(-11);
+            startup.Error = GetStdHandle(-12);
+            Check(CreateProcessW(null, new StringBuilder(commandLine), IntPtr.Zero, IntPtr.Zero,
+                true, 0x4, IntPtr.Zero, null, ref startup, out process)); // CREATE_SUSPENDED
+            Check(AssignProcessToJobObject(job, process.Process));
+            assigned = true;
+            Check(ResumeThread(process.Thread) != UInt32.MaxValue);
+            Check(WaitForSingleObject(process.Process, UInt32.MaxValue) != UInt32.MaxValue);
+            uint code;
+            Check(GetExitCodeProcess(process.Process, out code));
+            return unchecked((int)code);
+        } finally {
+            // If assignment failed, the suspended launcher must also be reaped.
+            if (!assigned && process.Process != IntPtr.Zero) TerminateProcess(process.Process, 1);
+            CloseHandle(job);
+            if (process.Thread != IntPtr.Zero) CloseHandle(process.Thread);
+            if (process.Process != IntPtr.Zero) CloseHandle(process.Process);
+        }
+    }
+}
+`;
+//#endregion
+//#region src/wrap.ts
+/** Resolves with the upstream's exit code. */
+function wrap(options, io) {
+	const visible = (name) => options.allow ? options.allow.includes(name) : !options.deny?.includes(name);
+	const windows = process.platform === "win32";
+	const upstream = windows ? windowsJobCommand(options.command, options.args) : void 0;
+	const child = spawn(upstream?.command ?? options.command, [...upstream?.args ?? options.args], {
+		stdio: [
+			"pipe",
+			"pipe",
+			"pipe"
+		],
+		detached: !windows,
+		windowsHide: true,
+		...options.cwd ? { cwd: options.cwd } : {}
+	});
+	child.stdin.on("error", () => {});
+	const listing = /* @__PURE__ */ new Set();
+	const seen = /* @__PURE__ */ new Set();
+	let reported = false;
+	const report = () => {
+		if (reported) return;
+		reported = true;
+		const hidden = [...seen].filter((name) => !visible(name)).sort();
+		io.log(`mcp-authz wrap: ${seen.size - hidden.length}/${seen.size} tools exposed` + (hidden.length > 0 ? `, hidden: ${hidden.join(", ")}` : ""));
+		for (const name of options.allow ?? options.deny ?? []) if (!seen.has(name)) io.log(`mcp-authz wrap: no tool named ${name}`);
+	};
+	onLines(io.input, (line) => {
+		if (stopping || line.trim() === "") return;
+		let value;
+		const refuse = (code, reason) => {
+			const id = value?.id;
+			send(JSON.stringify({
+				jsonrpc: "2.0",
+				id: typeof id === "string" || typeof id === "number" ? id : null,
+				error: {
+					code,
+					message: reason
+				}
+			}));
+		};
+		try {
+			value = JSON.parse(line);
+		} catch {
+			refuse(-32700, "Parse error: mcp-authz wrap forwards only messages it can read");
+			return;
+		}
+		if (typeof value !== "object" || value === null || Array.isArray(value)) {
+			refuse(-32600, "Invalid request: mcp-authz wrap forwards single JSON-RPC messages, not batches");
+			return;
+		}
+		if (hasDuplicateKey(line)) {
+			refuse(-32600, "Invalid request: mcp-authz wrap refuses a message that repeats a key");
+			return;
+		}
+		const message = value;
+		if (message.method === "tools/list" && message.id !== void 0) listing.add(message.id);
+		const name = message.method === "tools/call" ? message.params?.name : void 0;
+		if (message.method === "tools/call" && (typeof name !== "string" || !visible(name))) {
+			const error = {
+				code: -32602,
+				message: typeof name === "string" ? `Tool "${name}" is blocked by mcp-authz wrap` : "tools/call needs a tool name"
+			};
+			send(JSON.stringify({
+				jsonrpc: "2.0",
+				id: message.id ?? null,
+				error
+			}));
+			return;
+		}
+		child.stdin.write(`${line}\n`);
+	});
+	io.output.on("error", () => void stop());
+	const send = (line) => {
+		if (io.output.writable) io.output.write(`${line}\n`);
+	};
+	const treeAlive = () => {
+		if (child.pid === void 0) return false;
+		if (windows) return child.exitCode === null && child.signalCode === null;
+		try {
+			process.kill(-child.pid, 0);
+			return true;
+		} catch {
+			return false;
+		}
+	};
+	const signalTree = (signal) => {
+		if (child.pid === void 0) return;
+		if (windows) {
+			child.kill("SIGKILL");
+			return;
+		}
+		try {
+			process.kill(-child.pid, signal);
+		} catch {}
+	};
+	const goneWithin = async (ms) => {
+		for (const deadline = Date.now() + ms; Date.now() < deadline; await setTimeout(25)) if (!treeAlive()) return true;
+		return !treeAlive();
+	};
+	const grace = options.graceMs ?? 2e3;
+	let stopping;
+	const stop = () => stopping ??= (async () => {
+		child.stdin.end();
+		for (const signal of ["SIGTERM", "SIGKILL"]) {
+			if (await goneWithin(grace)) return;
+			signalTree(signal);
+		}
+		await goneWithin(grace);
+	})();
+	io.input.on("end", stop);
+	if (io.signal?.aborted) stop();
+	else io.signal?.addEventListener("abort", stop, { once: true });
+	onLines(child.stdout, (line) => {
+		const message = parse(line);
+		if (message?.method === void 0 && message?.id !== void 0 && listing.delete(message.id) && message.result?.tools) {
+			for (const tool of message.result.tools) seen.add(tool.name);
+			if (!message.result.nextCursor) report();
+			message.result.tools = message.result.tools.filter((tool) => visible(tool.name));
+			line = JSON.stringify(message);
+		}
+		send(line);
+	});
+	createInterface({ input: child.stderr }).on("line", io.log);
+	return new Promise((resolve) => {
+		child.on("exit", (code) => resolve(code ?? 1));
+		child.on("error", (error) => {
+			io.log(`mcp-authz wrap: could not start ${options.command}: ${error.message}. Install it, or give its full path in your config.`);
+			resolve(1);
+		});
+	}).then(async (code) => {
+		await stop();
+		upstream?.cleanup();
+		return code;
+	});
+}
+/**
+* Call `onLine` for each newline-terminated line, framed as the MCP SDKs frame
+* stdio: split on `\n` alone, with a trailing `\r` dropped. node:readline also
+* splits on `\r`, U+2028 and U+2029, which JSON allows unescaped inside a
+* string, so it would read one message as two where the server reads one.
+*/
+function onLines(stream, onLine) {
+	let buffered = "";
+	stream.setEncoding("utf8");
+	stream.on("data", (chunk) => {
+		buffered += chunk;
+		let newline;
+		while ((newline = buffered.indexOf("\n")) !== -1) {
+			onLine(buffered.slice(0, newline).replace(/\r$/, ""));
+			buffered = buffered.slice(newline + 1);
+		}
+	});
+	stream.on("end", () => {
+		if (buffered !== "") onLine(buffered.replace(/\r$/, ""));
+		buffered = "";
+	});
+}
+/**
+* Whether any object repeats a key, compared after unescaping, so `"name"` and
+* `"na\u006de"` are the same key. Only called on text JSON.parse accepted,
+* which is what lets it skip validating anything else.
+*/
+function hasDuplicateKey(text) {
+	const scopes = [];
+	for (let i = 0; i < text.length; i++) {
+		const char = text[i];
+		if (char === "{") scopes.push(/* @__PURE__ */ new Set());
+		else if (char === "[") scopes.push(void 0);
+		else if (char === "}" || char === "]") scopes.pop();
+		else if (char === "\"") {
+			let end = i + 1;
+			while (text[end] !== "\"") end += text[end] === "\\" ? 2 : 1;
+			let next = end + 1;
+			while (text[next] === " " || text[next] === "	" || text[next] === "\r" || text[next] === "\n") next++;
+			const scope = scopes.at(-1);
+			if (scope && text[next] === ":") {
+				const key = JSON.parse(text.slice(i, end + 1));
+				if (scope.has(key)) return true;
+				scope.add(key);
+			}
+			i = end;
+		}
+	}
+	return false;
+}
+function parse(line) {
+	try {
+		const value = JSON.parse(line);
+		return typeof value === "object" && value !== null ? value : void 0;
+	} catch {
+		return;
+	}
+}
+//#endregion
+//#region src/wrap-config.ts
+/** Ask a stdio server for its tools, the way a client would. */
+async function discover$1(command, args, cwd) {
+	const { Client } = await import("@modelcontextprotocol/client");
+	const { StdioClientTransport } = await import("@modelcontextprotocol/client/stdio");
+	const client = new Client({
+		name: "mcp-authz-tools",
+		version: "1.0.0"
+	});
+	const env = Object.fromEntries(Object.entries(process.env).filter((entry) => entry[1] !== void 0));
+	await client.connect(new StdioClientTransport({
+		command,
+		args: [...args],
+		env,
+		...cwd ? { cwd } : {}
+	}));
+	try {
+		const tools = [];
+		let cursor;
+		do {
+			const page = await client.listTools(cursor ? { cursor } : void 0);
+			for (const tool of page.tools) tools.push({
+				name: tool.name,
+				hint: tool.annotations?.readOnlyHint ? "read-only" : tool.annotations?.destructiveHint ? "destructive" : "unknown",
+				description: tool.description?.split("\n")[0]?.trim() ?? "",
+				params: Object.keys(tool.inputSchema.properties ?? {}).map((param) => tool.inputSchema.required?.includes(param) ? `${param} (required)` : param)
+			});
+			cursor = page.nextCursor;
+		} while (cursor);
+		return tools.sort((a, b) => a.name.localeCompare(b.name));
+	} finally {
+		await client.close();
+	}
+}
+/** Where the schema for a config lives: beside it, named after it. */
+function schemaPathFor(configPath) {
+	return join(dirname(configPath), `${basename(configPath, extname(configPath))}.schema.json`);
+}
+/**
+* Write the config and its schema.
+*
+* In a fresh config, destructive tools start commented out. Over an existing
+* config, the choices in it are kept and a tool the server added since starts
+* commented out, so a refresh keeps your edits and waits for you to switch new
+* tools on.
+*/
+function writeWrapConfig(configPath, server, tools, previous) {
+	const schemaPath = schemaPathFor(configPath);
+	const isNew = (name) => previous?.recorded !== void 0 && !previous.recorded.includes(name);
+	const chosen = (tool) => {
+		if (!previous) return tool.hint !== "destructive";
+		if (isNew(tool.name)) return false;
+		const { allow, deny } = previous.options;
+		return allow ? allow.includes(tool.name) : !deny?.includes(tool.name);
+	};
+	const on = tools.filter(chosen);
+	const off = tools.filter((tool) => !chosen(tool));
+	const note = (tool) => ` // ${tool.hint}${tool.description ? ` · ${clip(tool.description)}` : ""}`;
+	const entries = [...on.map((tool) => `    ${JSON.stringify(tool.name)},${note(tool)}`), ...off.map((tool) => `    // ${JSON.stringify(tool.name)},${note(tool)}`)];
+	const text = [
+		"{",
+		`  "$schema": ${JSON.stringify(`./${basename(schemaPath)}`)},`,
+		"  // The server `mcp-authz wrap` runs. Its env comes from your client config.",
+		`  "server": {`,
+		`    "command": ${JSON.stringify(server.command)},`,
+		`    "args": [${server.args.map((arg) => JSON.stringify(arg)).join(", ")}],`,
+		"    // Where the server runs, relative to this file, so relative paths in",
+		"    // \"args\" mean the same wherever the client starts it.",
+		`    "cwd": ${JSON.stringify(storedCwd(configPath, server.cwd))}`,
+		"  },",
+		"  // The tools this session may see. Anything not listed is hidden, including",
+		"  // tools the server adds later. Uncomment a line to switch a tool on.",
+		"  \"allow\": [",
+		...entries,
+		"  ]",
+		"}",
+		""
+	].join("\n");
+	writeFileSync(configPath, text);
+	writeFileSync(schemaPath, `${JSON.stringify(schemaFor(tools), null, 2)}\n`);
+	return {
+		allowed: on.length,
+		commented: off.length,
+		added: tools.filter((tool) => isNew(tool.name)).length
+	};
+}
+function schemaFor(tools) {
+	const names = {
+		type: "array",
+		items: { $ref: "#/definitions/tool" },
+		uniqueItems: true
+	};
+	return {
+		$schema: "http://json-schema.org/draft-07/schema#",
+		title: "mcp-authz wrap config",
+		type: "object",
+		required: ["server"],
+		additionalProperties: false,
+		not: { required: ["allow", "deny"] },
+		properties: {
+			$schema: { type: "string" },
+			server: {
+				type: "object",
+				required: ["command"],
+				additionalProperties: false,
+				properties: {
+					command: { type: "string" },
+					args: {
+						type: "array",
+						items: { type: "string" }
+					},
+					cwd: {
+						type: "string",
+						description: "Where the server runs, relative to this file or absolute."
+					}
+				}
+			},
+			allow: {
+				...names,
+				description: "Only these tools are shown."
+			},
+			deny: {
+				...names,
+				description: "Every tool but these is shown."
+			}
+		},
+		definitions: { tool: tools.length > 0 ? { anyOf: tools.map((tool) => ({
+			const: tool.name,
+			description: note(tool)
+		})) } : { not: {} } }
+	};
+	function note(tool) {
+		const said = tool.description ? `${tool.hint} · ${tool.description}` : tool.hint;
+		return tool.params.length > 0 ? `${said}\n\nTakes: ${tool.params.join(", ")}` : said;
+	}
+}
+/** Every tool name the schema beside a config recorded, if it is there. */
+function recordedTools(configPath) {
+	try {
+		const tool = JSON.parse(readFileSync(schemaPathFor(configPath), "utf8")).definitions?.tool;
+		return tool ? (tool.anyOf ?? []).map((entry) => entry.const) : void 0;
+	} catch {
+		return;
+	}
+}
+/** Read a config into what `wrap` takes, saying which file is wrong and how. */
+function readWrapConfig(configPath) {
+	const fail = (problem) => {
+		throw new Error(`${configPath}: ${problem}`);
+	};
+	let text;
+	try {
+		text = readFileSync(configPath, "utf8");
+	} catch {
+		return fail(`cannot read it. Create it with: mcp-authz tools --out ${configPath} -- <server command>`);
+	}
+	let value;
+	try {
+		value = parseJsonc(text);
+	} catch (error) {
+		return fail(`not valid JSONC (${error instanceof Error ? error.message : String(error)}). Look for a missing comma or quote, or start again: move it aside (mv ${configPath} ${configPath}.bak), then run mcp-authz tools --out ${configPath} -- <server command>`);
+	}
+	const config = value;
+	const unknown = (object, known, prefix = "") => {
+		if (typeof object !== "object" || object === null) return;
+		for (const key of Object.keys(object)) if (!known.includes(key)) fail(`unknown key "${prefix}${key}"; expected one of: ${known.join(", ")}.`);
+	};
+	unknown(config, [
+		"$schema",
+		"server",
+		"allow",
+		"deny"
+	]);
+	unknown(config?.server, [
+		"command",
+		"args",
+		"cwd"
+	], "server.");
+	const strings = (list) => Array.isArray(list) && list.every((item) => typeof item === "string");
+	if (typeof config?.server?.command !== "string") fail("\"server.command\" must be a string.");
+	const cwd = config.server.cwd ?? ".";
+	if (typeof cwd !== "string") fail("\"server.cwd\" must be a path.");
+	const args = config.server.args ?? [];
+	if (!strings(args)) fail("\"server.args\" must be a list of strings.");
+	if (config.allow !== void 0 && config.deny !== void 0) fail("use \"allow\" or \"deny\", not both.");
+	for (const key of ["allow", "deny"]) if (config[key] !== void 0 && !strings(config[key])) fail(`"${key}" must be a list of tool names.`);
+	return {
+		command: config.server.command,
+		args,
+		cwd: resolve(dirname(resolve(configPath)), cwd),
+		...config.allow ? { allow: config.allow } : {},
+		...config.deny ? { deny: config.deny } : {}
+	};
+}
+function entryFor(configPath) {
+	return {
+		name: basename(configPath, extname(configPath)),
+		entry: {
+			command: "npx",
+			args: [
+				"-y",
+				"mcp-authz",
+				"wrap",
+				"--config",
+				resolve(configPath)
+			]
+		}
+	};
+}
+/**
+* Add the entry to a client's MCP config file, creating it if need be. Only how
+* the server starts changes. Other servers, and every other setting on this one
+* (`env`, `disabled`, `timeout`, whatever the client supports), stay as they
+* were, so a rerun keeps your API key and your on/off choice.
+*/
+function writeClientConfig(clientPath, configPath) {
+	const { name, entry } = entryFor(configPath);
+	let existing = {};
+	if (existsSync(clientPath)) try {
+		existing = parseJsonc(readFileSync(clientPath, "utf8"));
+	} catch (error) {
+		const reason = error instanceof Error ? error.message : String(error);
+		throw new Error(`${clientPath}: not valid JSON (${reason}). Fix it, or pass --client-out a new file.`, { cause: error });
+	}
+	const kept = { ...existing.mcpServers?.[name] };
+	delete kept.url;
+	if (kept.type !== void 0 && kept.type !== "stdio") delete kept.type;
+	const merged = {
+		...existing,
+		mcpServers: {
+			...existing.mcpServers,
+			[name]: {
+				...kept,
+				...entry
+			}
+		}
+	};
+	writeFileSync(clientPath, `${JSON.stringify(merged, null, 2)}\n`);
+}
+/** The `mcpServers` entry that runs a config, ready to paste. */
+function clientEntry(configPath) {
+	const { name, entry } = entryFor(configPath);
+	const args = entry.args.map((arg) => JSON.stringify(arg));
+	return [
+		`${JSON.stringify(name)}: {`,
+		"  \"command\": \"npx\",",
+		`  "args": [${args.join(", ")}]`,
+		"}"
+	].join("\n");
+}
+/**
+* JSON with comments and trailing commas, which is what a person editing the
+* file will produce. Strings are copied whole, so `//` inside one is safe.
+*/
+function parseJsonc(text) {
+	let out = "";
+	for (let i = 0; i < text.length; i++) {
+		const char = text[i];
+		if (char === "\"") {
+			let end = i + 1;
+			while (end < text.length && text[end] !== "\"") end += text[end] === "\\" ? 2 : 1;
+			out += text.slice(i, end + 1);
+			i = end;
+		} else if (char === "/" && text[i + 1] === "/") {
+			while (i < text.length && text[i] !== "\n") i++;
+			out += "\n";
+		} else if (char === "/" && text[i + 1] === "*") {
+			const end = text.indexOf("*/", i + 2);
+			i = end === -1 ? text.length : end + 1;
+		} else {
+			if (char === "]" || char === "}") out = out.replace(/,\s*$/, "");
+			out += char;
+		}
+	}
+	return JSON.parse(out);
+}
+/**
+* Relative to the config when that is the shorter way to say it, as it is for
+* a config kept beside its server in a repo; otherwise absolute, so a copied
+* file still finds the server.
+*/
+function storedCwd(configPath, cwd) {
+	const relativeTo = relative(dirname(resolve(configPath)), cwd) || ".";
+	return relativeTo.length <= cwd.length ? relativeTo : cwd;
+}
+/** The first sentence, and no more than a line's worth of it. */
+function clip(text, max = 80) {
+	const sentence = /^.*?[.!?](?=\s|$)/.exec(text)?.[0] ?? text;
+	return sentence.length > max ? `${sentence.slice(0, max - 1)}…` : sentence;
+}
+//#endregion
 //#region src/cli.ts
 /**
 * Two questions a policy file cannot answer by being read.
@@ -14,6 +666,10 @@ import { parseArgs } from "node:util";
 * decision carries the permissions, and only `policy.explain` carries the rules
 * that produced them.
 *
+* `tools` and `wrap` answer a third: which of a server's tools should this
+* session see. `wrap` reads JSON lines and nothing more, so it works in front of
+* any stdio server; `tools` is the one command that speaks MCP as a client.
+*
 * Deliberately no colour library and no argument parser. `node:util` has one,
 * and a dependency here would be a dependency in every install of the package.
 */
@@ -24,6 +680,12 @@ const USAGE = `mcp-authz — inspect a policy without running a server
   mcp-authz record --upstream <url> [--token <bearer>] [--out <permissions.ts>]
   mcp-authz record <connector.ts|--upstream <url>> --check <permissions.ts>
   mcp-authz explain <policy.json> --identity <identity.json>|- [--capabilities <map.json>]
+  mcp-authz tools -- <command> [args...]
+  mcp-authz tools --out <name.jsonc> [--client-out <mcp.json>] -- <command> [args...]
+  mcp-authz tools --config <name.jsonc> --refresh
+  mcp-authz wrap [--allow <a,b> | --deny <a,b>] -- <command> [args...]
+  mcp-authz wrap --config <name.jsonc>
+  mcp-authz tools --check <name.jsonc>
 
 Files
   <policy.json>     the object you would hand definePolicy
@@ -32,6 +694,11 @@ Files
   --identity        an Identity, or a decoded token payload (iss, sub, email,
                     email_verified, hd). Use - to read it from stdin.
 
+wrap
+  Runs a stdio MCP server and hides tools from whoever connects. Put it in
+  front of the server in your client's MCP config. With neither flag every
+  tool passes through; names are exact and comma-separated.
+
 Exit codes
   0  fine, warnings included
   1  the policy is invalid, or a capability no role can reach
@@ -47,6 +714,11 @@ function main(argv) {
 			upstream: { type: "string" },
 			token: { type: "string" },
 			check: { type: "string" },
+			allow: { type: "string" },
+			deny: { type: "string" },
+			config: { type: "string" },
+			refresh: { type: "boolean" },
+			"client-out": { type: "string" },
 			help: {
 				type: "boolean",
 				short: "h"
@@ -54,10 +726,17 @@ function main(argv) {
 		}
 	});
 	const [command, policyPath] = positionals;
+	const dashes = argv.indexOf("--");
+	const upstream = dashes === -1 ? [] : argv.slice(dashes + 1);
 	if (values.help || !command) {
 		process.stdout.write(USAGE);
 		return values.help ? 0 : 1;
 	}
+	if (command === "tools") {
+		if (values.check) return checkWrapConfig(values.check, upstream);
+		return listTools(upstream, values);
+	}
+	if (command === "wrap") return runWrap(upstream, values);
 	if (command === "record") {
 		if (values.upstream) return record({
 			upstream: values.upstream,
@@ -73,6 +752,10 @@ function main(argv) {
 		process.stderr.write(`${command} needs a path to a policy file.\n`);
 		return 1;
 	}
+	if (command === "check" && isWrapConfig(policyPath)) {
+		process.stderr.write(`${policyPath} is a wrap config. To compare it with its server, which starts the command it names, run: mcp-authz tools --check ${policyPath}\n`);
+		return 1;
+	}
 	const policy = definePolicy(readJson(policyPath));
 	const run = (capabilities) => {
 		if (command === "check") return check(policy, capabilities);
@@ -90,6 +773,139 @@ function main(argv) {
 	if (values.capabilities.endsWith(".json")) return run(new Map(Object.entries(readJson(values.capabilities))));
 	return importCapabilities(values.capabilities).then(run);
 }
+/**
+* Print the names `wrap` takes, with the hints that help choose between them,
+* and with --out or --refresh save them as a config `wrap --config` runs.
+*/
+function listTools(upstream, flags) {
+	const refuse = (message) => (process.stderr.write(`${message}\n`), 1);
+	if (flags.refresh && !flags.config) return refuse("--refresh rewrites a saved config: tools --config <name>.jsonc --refresh");
+	if (flags.config && upstream.length > 0) return refuse("tools takes --config or a command after --, not both: the config names its server.");
+	const saved = flags.config ? readWrapConfig(flags.config) : void 0;
+	const [command, ...args] = saved ? [saved.command, ...saved.args] : upstream;
+	const cwd = saved?.cwd ?? process.cwd();
+	if (saved) announce(saved, flags.config);
+	if (!command) return refuse("tools needs the server command after --, e.g. tools -- npx -y some-mcp");
+	const target = flags.refresh ? flags.config : flags.out;
+	return discover(command, args, cwd).then((tools) => {
+		if (tools === void 0) return 1;
+		const width = Math.max(...tools.map((tool) => tool.name.length));
+		for (const tool of tools) process.stdout.write(`${tool.name.padEnd(width)}  ${tool.hint.padEnd(11)}  ${tool.description}`.trimEnd() + "\n");
+		if (!target) {
+			process.stderr.write("\nSave these as a config wrap can run: tools --out <name>.jsonc -- ...\n");
+			return 0;
+		}
+		const previous = existsSync(target) ? {
+			options: readWrapConfig(target),
+			recorded: recordedTools(target)
+		} : void 0;
+		const { allowed, commented, added } = writeWrapConfig(target, {
+			command,
+			args,
+			cwd
+		}, tools, previous);
+		const summary = previous ? `${allowed} allowed, ${commented} commented out, ${added} new since last saved, left commented out` : `${allowed} allowed, ${commented} destructive commented out`;
+		const lines = ["", `Saved ${target} (${summary}) and ${schemaPathFor(target)}.`];
+		if (flags["client-out"]) {
+			writeClientConfig(flags["client-out"], target);
+			lines.push(`Added it to ${flags["client-out"]}; give it the env the server needs there.`);
+		}
+		lines.push("Add this to your client's mcpServers, with the env the server needs:", "", clientEntry(target), "");
+		process.stdout.write(lines.join("\n"));
+		return 0;
+	});
+}
+/**
+* Discovery with a next step for the two common stops: a command that is not
+* installed, and a server that exits at once, which usually means it wants an
+* API key. The server's own message is already on stderr above this one.
+*/
+async function discover(command, args, cwd) {
+	try {
+		return await discover$1(command, args, cwd);
+	} catch (error) {
+		const code = error.code;
+		process.stderr.write(code === "ENOENT" ? `Could not start ${command}: command not found. Install it, or give its full path.\n` : "The server exited before listing its tools. Its own error, if it printed one, is above.\nIf it needs credentials, export them in this shell first: the env in your client\nconfig is not seen here.\n");
+		return;
+	}
+}
+/** Say what is about to run when the command comes from a file. */
+function announce(options, path) {
+	process.stderr.write(`Running ${[options.command, ...options.args].join(" ")} from ${path}\n`);
+}
+function isWrapConfig(path) {
+	if (path === "-") return false;
+	try {
+		const value = parseJsonc(readFileSync(path, "utf8"));
+		return typeof value === "object" && value !== null && "server" in value;
+	} catch {
+		return false;
+	}
+}
+/**
+* Ask the server what it offers now, and compare it with the config and with
+* the catalogue recorded beside it. Exits 1 on any difference, the way
+* `record --check` does, so CI notices an upgrade that renamed a tool.
+*/
+async function checkWrapConfig(path, upstream) {
+	if (upstream.length > 0) {
+		process.stderr.write("tools --check runs the server its config names, so it takes no command after --.\n");
+		return 1;
+	}
+	const options = readWrapConfig(path);
+	announce(options, path);
+	const discovered = await discover(options.command, options.args, options.cwd);
+	if (discovered === void 0) return 1;
+	const live = discovered.map((tool) => tool.name);
+	const recorded = recordedTools(path);
+	const missing = (options.allow ?? options.deny ?? []).filter((name) => !live.includes(name));
+	const added = recorded ? live.filter((name) => !recorded.includes(name)) : [];
+	const removed = recorded ? recorded.filter((name) => !live.includes(name)) : [];
+	if (missing.length === 0 && added.length === 0 && removed.length === 0) {
+		const against = recorded ? `as recorded in ${schemaPathFor(path)}` : `every name in ${path} found`;
+		process.stdout.write(`${live.length} tools, ${against}\n`);
+		return 0;
+	}
+	const lines = [`${path} does not match the server:`, ""];
+	for (const name of missing) lines.push(`  ? ${name}`, `      in "${options.allow ? "allow" : "deny"}", but the server has no such tool`);
+	for (const name of added) lines.push(`  + ${name}`, `      new since last saved; ${options.allow ? "hidden, since it is not in \"allow\"" : "shown"}`);
+	for (const name of removed) lines.push(`  - ${name}`, "      recorded, but the server no longer offers it");
+	lines.push("", missing.length > 0 ? `Fix or remove the "?" names in ${path}, then run tools --config ${path} --refresh to record the rest.` : `Run tools --config ${path} --refresh to record the change. Your choices are kept; new tools stay off.`, "");
+	process.stdout.write(lines.join("\n"));
+	return 1;
+}
+function runWrap(upstream, { allow, deny, config }) {
+	const refuse = (message) => (process.stderr.write(`${message}\n`), 1);
+	if (allow !== void 0 && deny !== void 0) return refuse("wrap takes --allow or --deny, not both.");
+	if (config !== void 0) {
+		if (upstream.length > 0) return refuse("wrap takes --config or a command after --, not both.");
+		if (allow !== void 0 || deny !== void 0) return refuse("wrap takes --config or --allow/--deny, not both: the list lives in the file.");
+	}
+	const names = (list) => list?.split(",").map((name) => name.trim()).filter(Boolean);
+	const [command, ...args] = upstream;
+	if (config === void 0 && !command) return refuse("wrap needs the server command after --, e.g. wrap --deny x -- npx -y some-mcp");
+	const options = config ? readWrapConfig(config) : {
+		command,
+		args,
+		allow: names(allow),
+		deny: names(deny)
+	};
+	const stopped = new AbortController();
+	for (const signal of [
+		"SIGINT",
+		"SIGTERM",
+		"SIGHUP"
+	]) process.once(signal, () => stopped.abort());
+	return wrap(options, {
+		input: process.stdin,
+		output: process.stdout,
+		log: (line) => process.stderr.write(`${line}\n`),
+		signal: stopped.signal
+	}).then((code) => {
+		process.stdin.destroy();
+		return code;
+	});
+}
 /** Read the map out of a module `record` produced, or one written by hand. */
 async function importCapabilities(path) {
 	const loaded = await import(pathToFileURL(resolve(path)).href);
@@ -98,13 +914,7 @@ async function importCapabilities(path) {
 	return new Map(Object.entries(map));
 }
 async function record(source, out, against) {
-	let toolkit;
-	try {
-		toolkit = await import("./testing.js");
-	} catch {
-		process.stderr.write("record needs @modelcontextprotocol/client, which is an optional peer.\n  npm install -D @modelcontextprotocol/client\n");
-		return 1;
-	}
+	const toolkit = await import("./testing.js");
 	let capabilities;
 	if ("upstream" in source) capabilities = await toolkit.recordUpstream(source.upstream, { bearer: source.token });
 	else {

package/dist/index.d.ts

@@ -8,7 +8,7 @@ type DiscoverOptions = {
   /** Swap in for tests, or to add a timeout or proxy. Defaults to global fetch. */
   fetch?: typeof globalThis.fetch;
 };
-declare function discoverOAuth(issuer: string, options?: DiscoverOptions): Promise<OAuthMetadata>;
+export declare function discoverOAuth(issuer: string, options?: DiscoverOptions): Promise<OAuthMetadata>;
 //#endregion
 //#region src/gate.d.ts
 /**
@@ -60,7 +60,7 @@ type GateOptions = {
 };
 /** Bare name for a tool, `prompt:`/`resource:` prefixed for the rest. */
 type PermissionMap<P extends string> = Readonly<Record<string, P>> | ReadonlyMap<string, P>;
-declare function gate<P extends string>(server: McpServer, principal: Principal<P>, permissions: PermissionMap<P>, options?: GateOptions): McpServer;
+export declare function gate<P extends string>(server: McpServer, principal: Principal<P>, permissions: PermissionMap<P>, options?: GateOptions): McpServer;
 //#endregion
 //#region src/handler.d.ts
 /**
@@ -189,20 +189,20 @@ type McpFetchOptions<TContext, P extends string = string> = {
  * policy ran first and already refused anyone it grants nothing. Saying so here
  * saves every caller the same non-null assertion.
  */
-declare function createMcpFetch<TContext = Principal<string>, P extends string = string>(options: Omit<McpFetchOptions<TContext, P>, 'policy' | 'authorize' | 'resolve'> & {
+export declare function createMcpFetch<TContext = Principal<string>, P extends string = string>(options: Omit<McpFetchOptions<TContext, P>, 'policy' | 'authorize' | 'resolve'> & {
   policy: Policy<P>;
   authorize?: never;
   resolve?: (identity: Identity, principal: Principal<P>) => Promise<TContext> | TContext;
 }): (request: Request) => Promise<Response>;
-declare function createMcpFetch<TContext = Principal<string>, P extends string = string>(options: Omit<McpFetchOptions<TContext, P>, 'policy' | 'authorize' | 'resolve'> & {
+export declare function createMcpFetch<TContext = Principal<string>, P extends string = string>(options: Omit<McpFetchOptions<TContext, P>, 'policy' | 'authorize' | 'resolve'> & {
   policy?: never;
   authorize: (identity: Identity) => Promise<Principal<P>> | Principal<P>;
   resolve?: (identity: Identity, principal: Principal<P>) => Promise<TContext> | TContext;
 }): (request: Request) => Promise<Response>;
-declare function createMcpFetch<TContext = Principal<string>, P extends string = string>(options: Omit<McpFetchOptions<TContext, P>, 'policy' | 'authorize' | 'resolve'> & {
+export declare function createMcpFetch<TContext = Principal<string>, P extends string = string>(options: Omit<McpFetchOptions<TContext, P>, 'policy' | 'authorize' | 'resolve'> & {
   policy?: never;
   authorize?: never;
   resolve: (identity: Identity, principal: undefined) => Promise<TContext> | TContext;
 }): (request: Request) => Promise<Response>;
 //#endregion
-export { AccessDeniedError, type ApprovalDecision, ApprovalRefusedError, type ApprovalRequest, type ApprovalSink, type AuditDeliveryFailure, type AuditErrorSink, type AuditEvent, type AuditSink, type AuthorizationDecisionEvent, type AuthorizationDecisionSink, type Capability, type CapabilityScopeMap, type Definition, type DenialReason, type DiscoverOptions, type Explanation, type GateOptions, type Identity, type Match, type MatchedRule, type McpFetchOptions, type PermissionCatalog, type PermissionMap, type PermissionOf, type Policy, type PolicySpec, type Principal, type PromptConfig, type ResourceConfig, type Rule, type ScopeRequirement, type ServerOptions, type ToolConfig, type ToolScopeMap, type TrustedMcpRoute, type VerifierOptions, authz, createMcpFetch, createPrincipal, decodeMcpNameHeader, definePermissions, definePolicy, discoverOAuth, gate, identityFromAuth, jwksVerifier, reconcile, scopesForCapability, scopesFromMcpHeaders };
+export { AccessDeniedError, type ApprovalDecision, ApprovalRefusedError, type ApprovalRequest, type ApprovalSink, type AuditDeliveryFailure, type AuditErrorSink, type AuditEvent, type AuditSink, type AuthorizationDecisionEvent, type AuthorizationDecisionSink, type Capability, type CapabilityScopeMap, type Definition, type DenialReason, type DiscoverOptions, type Explanation, type GateOptions, type Identity, type Match, type MatchedRule, type McpFetchOptions, type PermissionCatalog, type PermissionMap, type PermissionOf, type Policy, type PolicySpec, type Principal, type PromptConfig, type ResourceConfig, type Rule, type ScopeRequirement, type ServerOptions, type ToolConfig, type ToolScopeMap, type TrustedMcpRoute, type VerifierOptions, authz, createPrincipal, decodeMcpNameHeader, definePermissions, definePolicy, identityFromAuth, jwksVerifier, reconcile, scopesForCapability, scopesFromMcpHeaders };

package/dist/node.d.ts

@@ -1,6 +1,6 @@
 import { Server } from "node:http";
 //#region src/node.d.ts
-type ListenMcpOptions = {
+export type ListenMcpOptions = {
   port: number;
   /** Log label. Defaults to `mcp-authz`. */
   name?: string;
@@ -11,6 +11,5 @@ type ListenMcpOptions = {
  * Bind a `createMcpFetch` handler to every interface. Safe because the
  * bearer gate is the security boundary, not the bind address.
  */
-declare function listenMcp(fetch: (request: Request) => Promise<Response>, options: ListenMcpOptions): Promise<Server>;
-//#endregion
-export { ListenMcpOptions, listenMcp };
+export declare function listenMcp(fetch: (request: Request) => Promise<Response>, options: ListenMcpOptions): Promise<Server>;
+//#endregion

package/dist/openapi.d.ts

@@ -1,7 +1,7 @@
 import { _ as Identity, l as Principal, s as Policy } from "./policy-DuZbwrKf.js";
 import { c as AuditSink, o as AuditErrorSink } from "./tools-BQE1O-7P.js";
 import { a as AuthorizationDecisionSink, t as VerifierOptions } from "./verifier-DF6gUMQ6.js";
-import { t as PermissionMapRecord } from "./permissions-module-DxCHuE-N.js";
+import { t as PermissionMapRecord } from "./permissions-module-Cr0K1a7x.js";
 import { AuthInfo, OAuthMetadata, OAuthTokenVerifier } from "@modelcontextprotocol/server";
 //#region src/openapi.d.ts
 /**
@@ -22,11 +22,11 @@ import { AuthInfo, OAuthMetadata, OAuthTokenVerifier } from "@modelcontextprotoc
  * rides along untouched, so a document with `components`, `webhooks` or a
  * vendor extension comes back out the way it went in.
  */
-type OpenApiDocument = {
+export type OpenApiDocument = {
   paths?: Record<string, Record<string, unknown> | undefined>;
   [key: string]: unknown;
 };
-type OpenApiOperation = {
+export type OpenApiOperation = {
   /** The document's own `operationId`, which is what the permission map is keyed by. */
   operationId: string;
   /** Lowercased HTTP method. */
@@ -34,7 +34,7 @@ type OpenApiOperation = {
   /** The templated path, e.g. `/cases/{id}`. */
   path: string;
 };
-type OperationRecord = PermissionMapRecord & {
+export type OperationRecord = PermissionMapRecord & {
   /** Every operation the document describes, in document order. */
   operations: OpenApiOperation[];
 };
@@ -47,7 +47,7 @@ type OperationRecord = PermissionMapRecord & {
  * role grants and the boot refuses until somebody decides what each operation
  * costs.
  */
-declare function recordOperations(spec: OpenApiDocument): OperationRecord;
+export declare function recordOperations(spec: OpenApiDocument): OperationRecord;
 /**
  * The document as this caller should see it: their operations, and nothing else.
  *
@@ -56,8 +56,8 @@ declare function recordOperations(spec: OpenApiDocument): OperationRecord;
  * means walking the `$ref` graph, and a schema nobody references costs a few
  * hundred tokens where a wrongly-pruned one breaks the document.
  */
-declare function filterSpec<P extends string>(spec: OpenApiDocument, principal: Principal<P>, permissions: Readonly<Record<string, string>>): OpenApiDocument;
-type OpenApiFetchOptions<P extends string = string> = {
+export declare function filterSpec<P extends string>(spec: OpenApiDocument, principal: Principal<P>, permissions: Readonly<Record<string, string>>): OpenApiDocument;
+export type OpenApiFetchOptions<P extends string = string> = {
   /** The document describing this API. Also the catalogue served to callers. */
   spec: OpenApiDocument;
   /** `operationId` to the permission it costs. Every operation needs an entry. */
@@ -107,6 +107,5 @@ type OpenApiFetchOptions<P extends string = string> = {
  * out of the spec (a health check, static files) belong outside this wrapper
  * rather than behind it.
  */
-declare function createOpenApiFetch<P extends string = string>(options: OpenApiFetchOptions<P>): (request: Request) => Promise<Response>;
-//#endregion
-export { OpenApiDocument, OpenApiFetchOptions, OpenApiOperation, OperationRecord, createOpenApiFetch, filterSpec, recordOperations };
+export declare function createOpenApiFetch<P extends string = string>(options: OpenApiFetchOptions<P>): (request: Request) => Promise<Response>;
+//#endregion

package/dist/{permissions-module-DxCHuE-N.d.ts → permissions-module-Cr0K1a7x.d.ts}

@@ -3,9 +3,9 @@
  * Rendering a permission map as source, shared by everything that records a
  * catalogue.
  *
- * Its own module because the MCP recorder needs an optional peer dependency to
- * talk to a server, and the OpenAPI one only needs a file it was handed. A
- * caller after the scaffold should not have to install a client to get it.
+ * Its own module because the MCP recorder loads a client to talk to a server,
+ * and the OpenAPI one only needs a file it was handed. A caller after the
+ * scaffold should not have to load a client to get it.
  */
 type PermissionMapRecord = {
   /** Every capability, sorted, labelled the way the gate labels it. */

package/dist/proxy.d.ts

@@ -11,7 +11,7 @@ type UpstreamConfig = {
 };
 //#endregion
 //#region src/proxy.d.ts
-type McpProxyOptions<P extends string = string> = {
+export type McpProxyOptions<P extends string = string> = {
   /** This proxy's public URL, e.g. `https://mcp.acme.com/mcp`. */
   resourceServerUrl: URL;
   /** RFC 8414 metadata for the authorization server in front of the proxy. */
@@ -41,6 +41,5 @@ type McpProxyOptions<P extends string = string> = {
   healthPath?: string;
   maxRequestBytes?: number;
 };
-declare function createMcpProxy<P extends string = string>(options: McpProxyOptions<P>): (request: Request) => Promise<Response>;
-//#endregion
-export { McpProxyOptions, createMcpProxy };
+export declare function createMcpProxy<P extends string = string>(options: McpProxyOptions<P>): (request: Request) => Promise<Response>;
+//#endregion

package/dist/testing.d.ts

@@ -1,4 +1,4 @@
-import { n as UNASSIGNED, r as toPermissionsModule, t as PermissionMapRecord } from "./permissions-module-DxCHuE-N.js";
+import { n as UNASSIGNED, r as toPermissionsModule, t as PermissionMapRecord } from "./permissions-module-Cr0K1a7x.js";
 import { McpServer } from "@modelcontextprotocol/server";
 //#region src/testing.d.ts
 /**
@@ -13,7 +13,7 @@ import { McpServer } from "@modelcontextprotocol/server";
  * listing one would hand you a map missing exactly the capabilities that most
  * need a price.
  */
-type CapabilityRecord = {
+export type CapabilityRecord = {
   /** Every capability, labelled as `gate()` labels them, sorted. */
   names: string[];
   /** A digest per capability, so a snapshot can catch one changing under you. */
@@ -27,7 +27,7 @@ type CapabilityRecord = {
    */
   resourceUris: Record<string, string>;
 };
-declare function recordCapabilities(factory: () => McpServer | Promise<McpServer>): Promise<CapabilityRecord>;
+export declare function recordCapabilities(factory: () => McpServer | Promise<McpServer>): Promise<CapabilityRecord>;
 /**
  * Record a server you can only reach by URL.
  *
@@ -36,9 +36,9 @@ declare function recordCapabilities(factory: () => McpServer | Promise<McpServer
  * the map is complete. Pass `fetch` to drive a handler directly instead of a
  * socket.
  */
-declare function recordUpstream(url: string | URL, options?: {
+export declare function recordUpstream(url: string | URL, options?: {
   bearer?: string;
   fetch?: typeof fetch;
 }): Promise<CapabilityRecord>;
 //#endregion
-export { CapabilityRecord, type PermissionMapRecord, UNASSIGNED, recordCapabilities, recordUpstream, toPermissionsModule };
+export { type PermissionMapRecord, UNASSIGNED, toPermissionsModule };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-authz",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Authorization for MCP servers: OAuth 2.1 resource server, roles/permissions policy, permission-gated tools (2026-07-28)",
   "repository": {
     "type": "git",
@@ -59,31 +59,29 @@
   "author": "Jag Reehal <jag@jagreehal.com> (https://jagreehal.com)",
   "license": "MIT",
   "dependencies": {
-    "@modelcontextprotocol/server": "^2.1.0",
+    "@modelcontextprotocol/client": "^2.3.0",
+    "@modelcontextprotocol/server": "^2.3.0",
     "awaitly": "6.2.0",
+    "cross-spawn": "^7.0.6",
     "jose": "^6.2.12"
   },
   "peerDependencies": {
-    "@modelcontextprotocol/client": "^2.0.0",
     "@modelcontextprotocol/node": "^2.0.0"
   },
   "peerDependenciesMeta": {
     "@modelcontextprotocol/node": {
       "optional": true
-    },
-    "@modelcontextprotocol/client": {
-      "optional": true
     }
   },
   "devDependencies": {
-    "@modelcontextprotocol/client": "^2.0.0",
-    "@modelcontextprotocol/node": "^2.1.0",
-    "@types/node": "^26.2.0",
+    "@modelcontextprotocol/node": "^2.1.1",
+    "@types/node": "^26.6.4",
     "@typescript/native": "npm:typescript@^7.0.2",
-    "executable-stories-vitest": "8.8.0",
-    "tsdown": "^0.22.14",
+    "ajv": "^8.20.0",
+    "executable-stories-vitest": "8.10.1",
+    "tsdown": "^0.23.0",
     "typescript": "npm:@typescript/typescript6@^6.0.2",
-    "vitest": "^4.1.11",
+    "vitest": "^5.0.3",
     "zod": "^4.6.5"
   },
   "engines": {