mcp-authz 0.3.0 → 0.5.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
 
@@ -566,10 +566,10 @@ reads it off the server instead.
 ```ts
 import { recordCapabilities, toPermissionsModule } from 'mcp-authz/testing';
 
-const { names, fingerprints } = await recordCapabilities(() => buildServer(TEST_CONFIG));
+const { names, definitions } = await recordCapabilities(() => buildServer(TEST_CONFIG));
 
 expect(names).toEqual(Object.keys(PERMISSIONS).sort());
-expect(fingerprints).toMatchSnapshot();
+expect(definitions).toMatchSnapshot();
 ```
 
 It builds your server, connects a client over an in-memory transport, and lists
@@ -585,14 +585,13 @@ a person has decided what each one costs. Permissions are never guessed from
 decisions must not be made from them.
 
 `gate()` already refuses to start on a capability with no price, which covers a
-dependency that adds a tool. `fingerprints` covers the one it cannot see — a
+dependency that adds a tool. `definitions` covers the one it cannot see — a
 capability that keeps its name while its description, input schema, prompt
-arguments or URI template change underneath. Each digests the whole definition
-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.
+arguments or URI template change underneath. Each holds the whole definition as
+served (key order sorted, `_meta` and `icons` left out), so a snapshot turns that
+into a diff of the exact words on the pull request. With `gate()` in your own
+server, that snapshot is the check; `createMcpProxy` enforces the same record at
+runtime.
 
 ### `mcp-authz/openapi` — the same bet on an HTTP API
 
@@ -657,6 +656,7 @@ export default createMcpProxy({
   verifier: { jwksUri: process.env.OAUTH_JWKS_URI! },
   policy,
   permissions: PERMISSIONS, // from recordUpstream → toPermissionsModule
+  definitions: DEFINITIONS, // same module; what each capability said when recorded
   resourceUris: RESOURCE_URIS, // same module; a read names a URI, not a label
   upstream: {
     url: process.env.UPSTREAM_URL!,
@@ -665,15 +665,44 @@ export default createMcpProxy({
 });
 ```
 
-Record the upstream with `recordUpstream` or `mcp-authz record --upstream`, price
-the map, deploy the proxy.
+Record the upstream with `recordUpstream` or `mcp-authz record --upstream`, which
+connect as a 2026-07-28 client, price the map, deploy the proxy. `record --check`
+exits 1 when the upstream drifts, when its instructions change, and when a priced
+capability has no entry in `DEFINITIONS`.
+
+The proxy speaks MCP 2026-07-28 only: anything but a POST is a 405, and a
+request without validated `Mcp-Method` and `Mcp-Name` routing headers is a 400.
+Clients that still open with the 2025 `initialize` handshake cannot use it.
+
+`definitions` is required, and the proxy refuses to boot if a priced label has
+none. An upstream can keep a name you approved and rewrite the description to
+steer the model, or add an argument to carry data out. So a capability whose
+definition differs from the record is left out of listings, with a
+`console.warn` naming it and the changed fields. A call to a capability not
+checked in the last 60 seconds makes the proxy list the upstream itself first;
+one that changed or is no longer listed is refused with a 403. The upstream's
+instructions are held to `DEFINITIONS['server:instructions']` and removed when
+they differ. Re-recording is how a change is approved. This catches a change in
+what the model is told; it does not prove a remote tool behaves as it did, or
+that its output is free of prompt injection.
 
 The proxy is stricter than embed mode, because nothing downstream of it re-checks
 anything and it forwards on a service credential that outranks the caller.
-Routing headers that disagree with the body are refused rather than forwarded; a
-request with no routing headers is authorized from the body, which is what the
-upstream will act on; and a capability the map does not price is refused outright.
-The caller's `Authorization` and `Cookie` stay at the edge.
+Methods are on an explicit list: listings, `server/discover`, `ping` and two
+notifications pass; calls, prompt gets and reads are priced; a
+`completion/complete` is priced as the prompt or resource it completes, and a
+`subscriptions/listen` as a read of each URI it names, scopes included; anything else is a 400
+with `-32601`. Routing headers that disagree with the body, and a body that
+repeats a JSON key, are refused rather than forwarded. A read must satisfy every
+priced resource covering its URI. A capability the map does not price is refused
+outright. Filtered listings are marked private and `no-store`.
+A `tools/call` whose arguments break the recorded `inputSchema` is a 400.
+Answers are screened: `structuredContent` that breaks the recorded
+`outputSchema` is withheld, and output carrying invisible characters or text
+addressed to the model arrives after a notice to treat it as data. That notice
+is not a guarantee, and nothing verifies what a remote tool actually does; keep
+the service credential to least privilege. The caller's
+`Authorization` and `Cookie` stay at the edge.
 
 See [proxy mode](https://jagreehal.github.io/mcp-authz/typescript/proxy/) and the
 [`proxy-example`](../../apps/proxy-example) app.
@@ -863,6 +892,59 @@ 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, what the server says about it and roughly how many tokens its
+definition costs the model. Only tools the server marks read-only start switched
+on; destructive, unknown and flagged ones start commented out, and a tool that
+claims both read-only and destructive counts as destructive. The marks are the
+server's claims, shown to help you choose, not an approval.
+A schema beside it gives your editor completion and typo checks, and records
+each tool's definition and the server's instructions; `wrap` will not start
+without it. `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", "/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. So does a tool whose description or
+schema has changed since you saved it, which stops a rug pull: a server can't
+keep an approved name and rewrite what it tells the model. A call to a tool
+`wrap` has not yet checked waits while `wrap` lists the server itself, so a
+client that calls without listing cannot skip the check, and a
+`list_changed` from the server means every tool is checked again. Instructions
+that differ from the record are removed from the server's reply. Arguments that
+break the recorded `inputSchema` are refused, `structuredContent` that breaks
+the `outputSchema` is withheld, and output carrying text addressed to the model
+arrives after a notice to treat it as data. The notice catches only obvious
+injections, and nothing checks what a tool actually does.
+`mcp-authz tools --check cases.jsonc` reports
+what changed on the server since you saved, and `tools --refresh cases.jsonc`
+records it, keeping your choices. For a quick trial, `wrap --deny
+a,b -- <command>` takes the list as arguments. For a remote server, wrap the
+bridge: `-- npx -y mcp-remote https://…`.
+
+`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