mcp-expose 1.0.0 → 1.1.1

package/CHANGELOG.md

@@ -6,6 +6,39 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+## [1.1.1] - 2026-09-28
+
+### Added
+
+- `transformResponse` hook for route tools, on every marker and adapter, plus a server-level default. It shapes what
+  the agent sees from a route's response (hide or format fields, add hints) without turning the route into a custom
+  tool. The hook receives the status, headers, body and parsed JSON, the tool arguments and the MCP call context.
+  `ctx.callRoute()` enriches the response with other routes of the app, using the same credentials and the same
+  middleware, guards and validation. Placeholders are URL-encoded, and `.` / `..` segments are rejected.
+- `ResponseTransform`, `ResponseTransformContext` and `RouteToolResponse` types.
+
+### Fixed
+
+- A tool handler or hook that returns plain data with its own `content` array (for example a CMS post) is no longer
+  mistaken for an MCP `ToolResult`; only `content` arrays of MCP content items (`{ type: ... }`) are.
+
+## [1.1.0] - 2026-09-27
+
+### Added
+
+- **OAuth 2.1 support** following the MCP authorization spec, on every adapter, enabled with the new `oauth` server option:
+  - Protected Resource Metadata (RFC 9728) served at `/.well-known/oauth-protected-resource[/<path>]`, public and CORS-enabled.
+  - `401` / `403` responses with `WWW-Authenticate` challenges (`resource_metadata`, `scope`, `invalid_token`,
+    `insufficient_scope`), so MCP clients discover the authorization server and sign the user in by themselves.
+  - Audience-checked token verification with `requiredScopes`; the verified token is available to tools as `ctx.auth`.
+  - Per-tool `scopes` with `403 insufficient_scope` step-up.
+  - New `mcp-expose/oauth` entry point: `jwtVerifier()` (JWKS, via the optional `jose` peer dependency),
+    `introspectionVerifier()` (RFC 7662) and `discoverAuthorizationServer()`.
+- NestJS: `decorators` option to add decorators (such as `Public()`) to the MCP controller.
+- E2E: every scenario (each supported framework major) also runs in OAuth mode with `jwtVerifier`, and a new
+  scenario has the official MCP SDK client register dynamically, sign in with authorization code + PKCE and a
+  resource indicator, and step up scopes.
+
 ## [1.0.0] - 2026-09-25
 
 First stable release. The public API (`mcp-expose` and `mcp-expose/<framework>` exports, tool and server
@@ -35,5 +68,7 @@ options, default tool naming) now follows Semantic Versioning.
 - Path parameters that are empty, `.` or `..` are rejected, so an agent cannot use them to reach routes
   that were never exposed as tools (for example `/orders/../admin`).
 
-[Unreleased]: https://github.com/NITINKACHHADIYA/Node-MCP/compare/v1.0.0...HEAD
+[Unreleased]: https://github.com/NITINKACHHADIYA/Node-MCP/compare/v1.1.1...HEAD
+[1.1.1]: https://github.com/NITINKACHHADIYA/Node-MCP/releases/tag/v1.1.1
+[1.1.0]: https://github.com/NITINKACHHADIYA/Node-MCP/releases/tag/v1.1.0
 [1.0.0]: https://github.com/NITINKACHHADIYA/Node-MCP/releases/tag/v1.0.0

package/README.md

@@ -32,6 +32,7 @@ router.get('/orders/:id', [OrdersController, 'show']).use(middleware.auth()).mcp
 - Zero runtime dependencies. Dual ESM/CJS. Node.js 20, 22 and 24, plus Bun, Deno and Workers for Hono.
 - Supports the current **and the two previous major versions** of every framework, verified end to end.
 - Speaks MCP Streamable HTTP (protocol `2024-11-05` → `2025-11-25`), stateless, so it scales horizontally and runs serverless.
+- Built-in [OAuth 2.1](#oauth-sign-in-from-ai-clients): AI clients discover your identity provider and sign the user in by themselves (Auth0, Okta, Keycloak, Entra ID, Clerk, Cognito, ...).
 
 ---
 
@@ -44,14 +45,16 @@ router.get('/orders/:id', [OrdersController, 'show']).use(middleware.auth()).mcp
 5. [Framework guides](#framework-guides)
    - [NestJS](#nestjs) · [Express](#express) · [Fastify](#fastify) · [Koa](#koa) · [Hono](#hono) · [AdonisJS](#adonisjs) · [Any API via OpenAPI](#any-api-via-openapi-standalone-gateway)
 6. [Connect an AI client](#connect-an-ai-client)
-7. [Defining tool inputs (schemas)](#defining-tool-inputs-schemas)
-8. [Configuration reference](#configuration-reference)
-9. [Custom (non-HTTP) tools](#custom-non-http-tools)
-10. [Security checklist](#security-checklist)
-11. [Writing tools agents use well](#writing-tools-agents-use-well)
-12. [Limitations and roadmap](#limitations-and-roadmap)
-13. [Development](#development)
-14. [Versioning and support](#versioning-and-support)
+7. [OAuth: sign in from AI clients](#oauth-sign-in-from-ai-clients)
+8. [Defining tool inputs (schemas)](#defining-tool-inputs-schemas)
+9. [Shaping and enriching responses](#shaping-and-enriching-responses)
+10. [Configuration reference](#configuration-reference)
+11. [Custom (non-HTTP) tools](#custom-non-http-tools)
+12. [Security checklist](#security-checklist)
+13. [Writing tools agents use well](#writing-tools-agents-use-well)
+14. [Limitations and roadmap](#limitations-and-roadmap)
+15. [Development](#development)
+16. [Versioning and support](#versioning-and-support)
 
 ---
 
@@ -466,7 +469,8 @@ This also works with `@nestjs/swagger`, `@fastify/swagger`, tsoa and hono-openap
 ## Connect an AI client
 
 Start your app, then point a client at `http://localhost:3000/mcp`. Pass the same credentials a normal API
-client would use. They are forwarded to your routes.
+client would use. They are forwarded to your routes. (With the [`oauth` option](#oauth-sign-in-from-ai-clients)
+you skip the header: the client signs the user in by itself.)
 
 **Claude Code**
 
@@ -534,6 +538,89 @@ curl -s localhost:3000/mcp -H 'content-type: application/json' \
 
 ---
 
+## OAuth: sign in from AI clients
+
+Pasting a token into a client config works for development. For real users, turn on the `oauth` option:
+mcp-expose then implements the [MCP authorization spec](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization),
+so Claude, Cursor, VS Code and other clients open your normal login page, get a token for the user, and
+send it on every call. Nothing is pasted by hand.
+
+```
+AI client ── POST /mcp (no token) ─────────────▶ 401  WWW-Authenticate: Bearer resource_metadata=".../.well-known/oauth-protected-resource/mcp"
+AI client ── GET  /.well-known/oauth-protected-resource/mcp ─▶ { resource, authorization_servers: ["https://login.example.com"] }
+AI client ◀──── login in the browser (your IdP: Auth0, Okta, Keycloak, Entra ID, Clerk, Cognito, ...) ────▶ access token
+AI client ── POST /mcp  Authorization: Bearer <token> ─▶ mcp-expose checks the token ─▶ your route (token forwarded, guards run)
+```
+
+mcp-expose is the **resource server**. Your identity provider stays the **authorization server**, so user
+accounts, login pages and MFA stay where they are.
+
+### 1. Configure it
+
+```ts
+import { jwtVerifier } from 'mcp-expose/oauth'; // npm install jose
+
+const oauth = {
+  // The public URL of your MCP endpoint. Tokens must be issued for exactly this audience.
+  resource: 'https://api.example.com/mcp',
+  authorizationServers: ['https://example.auth0.com/'],
+  requiredScopes: ['mcp:tools'], // optional: needed for any MCP access
+  verifyToken: jwtVerifier({ issuer: 'https://example.auth0.com/' }),
+};
+```
+
+Pass it as `oauth` to any adapter:
+
+```ts
+McpModule.forRoot({ name: 'shop-api', oauth, decorators: [Public()] }); // NestJS (see note below)
+mountMcp(app, { name: 'shop-api', oauth }); // Express, Koa, Hono, AdonisJS
+await app.register(fastifyMcp, { name: 'shop-api', oauth }); // Fastify
+```
+
+That's it. The adapter:
+
+- serves the Protected Resource Metadata ([RFC 9728](https://www.rfc-editor.org/rfc/rfc9728)) at `/.well-known/oauth-protected-resource/mcp` (and `/.well-known/oauth-protected-resource`), public and CORS-enabled, outside any global prefix, guard or MCP middleware;
+- answers requests without a valid token with `401` and a `WWW-Authenticate` challenge that starts the client's login;
+- rejects tokens that were not issued for this resource (audience check), which blocks token passthrough from other services;
+- forwards the verified `Authorization` header to your routes, so your guards see the same user;
+- exposes the verified token to custom tools as `ctx.auth` (`subject`, `scopes`, `clientId`, `claims`).
+
+### 2. Per-tool scopes (step-up)
+
+```ts
+@Delete(':id')
+@McpTool({ name: 'cancel_order', scopes: ['orders:write'] })
+cancel(@Param('id') id: string) { ... }
+```
+
+A token without `orders:write` gets `403 insufficient_scope` naming the scopes it needs (plus the ones it already has, so the new token doesn't lose access). MCP clients then ask
+the user to approve the extra access and retry. All tool scopes are advertised in `scopes_supported`.
+`scopes` works on every marker (`mcpTool()`, `config.mcp`, `.mcp()`, `defineTool()`).
+
+### Token verifiers
+
+| Verifier                                                            | Use it for                                                                                                                                                                                            |
+| ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `jwtVerifier({ issuer })`                                           | JWT access tokens. Keys come from the issuer's JWKS (found through its metadata, or set `jwksUri` / `jwks`). Checks signature (asymmetric algorithms only), `iss`, `aud`, `exp`, `nbf`. Needs `jose`. |
+| `introspectionVerifier({ issuer, clientId, clientSecret })`         | Opaque tokens, via [RFC 7662](https://www.rfc-editor.org/rfc/rfc7662) introspection (Keycloak, Okta, ORY, Authlete, ...). Checks `active`, `aud` and `iss`, and caches results for 60 s.              |
+| `verifyToken: async (token, { resource }) => AuthInfo \| undefined` | Anything else, such as your existing session or API-key lookup. Return `undefined` to reject the token.                                                                                               |
+
+`jwtVerifier` checks that `aud` equals `resource` by default. If your provider uses another audience
+identifier (for example an Auth0 API identifier), set `audience`.
+
+### Provider notes
+
+- **The authorization server must support the MCP client flow:** authorization code with PKCE, and ideally
+  dynamic client registration ([RFC 7591](https://www.rfc-editor.org/rfc/rfc7591)) or client ID metadata documents,
+  so clients can register themselves. Many providers support this (for example Auth0, Keycloak, WorkOS and Stytch); with others, pre-register the client and give users its client ID.
+- **Your routes must accept the same token.** It is forwarded unchanged. If your API normally checks a different
+  audience, allow the MCP resource too, or set `forwardHeaders` to drop `authorization` and authorise
+  with a custom tool using `ctx.auth`.
+- **NestJS global guards** (an `APP_GUARD` that requires a session) run before the MCP controller and would answer 401 without the
+  OAuth challenge. Pass your "public" decorator with `decorators: [Public()]` so the guard lets MCP requests through;
+  mcp-expose checks the token itself. Likewise, don't also put auth `middleware`, `guards`, `routeOptions` hooks or `configureRoute` middleware on the MCP endpoint.
+- **Behind a proxy**, `resource` must be the public URL the client connects to (`https://...`), not the internal one.
+
 ## Defining tool inputs (schemas)
 
 The agent sees **one flat object** of arguments. mcp-expose maps each argument back to the right place:
@@ -562,28 +649,88 @@ Sources, from highest to lowest precedence:
 
 Your app's own validation always runs as well. The schema tells the agent what to send, and your API decides what it accepts.
 
+## Shaping and enriching responses
+
+By default the agent gets the route's response as it is. Add `transformResponse` to a route tool to change
+what the agent sees: hide internal fields, format values, add hints, or pull in related data from other
+routes. The route stays a route tool; there is no need to rewrite it as a custom tool.
+
+```ts
+@Get(':id')
+@McpTool({
+  name: 'get_order',
+  transformResponse: async (res, ctx) => {
+    if (!res.ok) return undefined; // keep the default error result
+    const { internalNotes, ...order } = res.json as Order;
+    // Another route of this app, with the same user's credentials, guards and pipes:
+    const customer = await ctx.callRoute({ path: '/api/customers/:id', params: { id: order.customerId } });
+    return { ...order, total: formatMoney(order.total), customer: customer.ok ? customer.json : null };
+  },
+})
+findOne(@Param('id') id: string) { ... }
+```
+
+It works the same with every marker: `mcpTool({ transformResponse })`, `config: { mcp: { transformResponse } }`,
+`.mcp({ transformResponse })`, and `toolsFromOpenApi(doc, dispatch, { transformResponse })`.
+
+**What the hook receives**
+
+- `res`: `status`, `headers`, the raw `body`, the parsed `json` (for JSON responses) and `ok` (status below 400).
+- `ctx.args`: the tool arguments. `ctx.request`: the internal request (method, path, query, body).
+- `ctx.toolContext`: the MCP request's headers, client IP and, with [OAuth](#oauth-sign-in-from-ai-clients), `auth`.
+- `ctx.defaultResult()`: the result mcp-expose would return without the hook.
+- `ctx.callRoute({ method, path, params, query, body, headers })`: calls another route of the same app.
+  - It forwards the same credentials (`Authorization`, cookies) and runs through the same middleware, guards and validation.
+  - `path` is the full path as your server sees it, including any global prefix or router mount path. Fill `:id` / `{id}`
+    placeholders from `params`: values are URL-encoded, and `.` or `..` are rejected, so agent input can't redirect the call.
+
+**What it returns**
+
+| Return value               | Result                                                                                              |
+| -------------------------- | --------------------------------------------------------------------------------------------------- |
+| a string or any JSON value | Sent to the agent (objects also as `structuredContent`). Still an error result if the route failed. |
+| a full `ToolResult`        | Used as is, so you control `isError` (e.g. `{ ...ctx.defaultResult(), content: [...] }`).           |
+| `undefined`                | The default result.                                                                                 |
+| a thrown error             | An error result with the message, which the agent sees.                                             |
+
+`maxResponseChars` still applies to whatever the hook returns.
+
+**For every tool at once**, set `transformResponse` in the server options, e.g. to strip fields everywhere:
+
+```ts
+mountMcp(app, {
+  name: 'shop-api',
+  transformResponse: (res) => (res.ok ? omitDeep(res.json, ['internalNotes', 'passwordHash']) : undefined),
+});
+```
+
+A tool's own `transformResponse` replaces the server-level one.
+
 ## Configuration reference
 
 ### Server options (all adapters)
 
-| Option             | Type                  | Default                                                    | Description                                                                                                                        |
-| ------------------ | --------------------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
-| `name`             | `string`              | required                                                   | Server name shown to clients.                                                                                                      |
-| `version`          | `string`              | `'1.0.0'`                                                  | Server version.                                                                                                                    |
-| `instructions`     | `string`              | none                                                       | Guidance for the model on how to use the tools together.                                                                           |
-| `path`             | `string`              | `'/mcp'`                                                   | Endpoint path.                                                                                                                     |
-| `allowedOrigins`   | `string[] \| '*'`     | `[]`                                                       | Browser origins allowed to call the endpoint. Requests without `Origin` (CLIs, IDEs, servers) are always allowed.                  |
-| `forwardHeaders`   | `string[]`            | `['authorization','cookie','x-api-key','accept-language']` | Headers copied from the MCP request to the internal API call.                                                                      |
-| `maxResponseChars` | `number`              | `100000`                                                   | Longer API responses are truncated before reaching the model.                                                                      |
-| `tools`            | `McpToolDefinition[]` | `[]`                                                       | Extra hand-written tools.                                                                                                          |
-| `baseUrl`          | `string`              | loopback                                                   | _Express/Koa/Nest/Adonis._ Where internal calls go. Set it for HTTPS with self-signed certs, unix sockets, or a separate API host. |
-| `routes`           | `{method,path,...}[]` | `[]`                                                       | _Express/Koa/Hono._ Expose routes without editing them.                                                                            |
-| `routers`          | see guide             | none                                                       | _Express:_ `{ '/prefix': router }`. _Koa:_ `[router]`.                                                                             |
-| `middleware`       | `Middleware[]`        | `[]`                                                       | _Express._ Middleware in front of `/mcp`, such as auth.                                                                            |
-| `guards`           | `CanActivate[]`       | `[]`                                                       | _NestJS._ Guards on the MCP controller.                                                                                            |
-| `pathPrefix`       | `string`              | none                                                       | _NestJS._ Extra prefix for tool routes. Global prefix and URI versioning are automatic.                                            |
-| `routeOptions`     | `object`              | none                                                       | _Fastify._ Extra route options for `/mcp`, such as `onRequest` hooks.                                                              |
-| `configureRoute`   | `(route) => void`     | none                                                       | _AdonisJS._ Configure the MCP route, e.g. add middleware.                                                                          |
+| Option              | Type                  | Default                                                    | Description                                                                                                                        |
+| ------------------- | --------------------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `name`              | `string`              | required                                                   | Server name shown to clients.                                                                                                      |
+| `version`           | `string`              | `'1.0.0'`                                                  | Server version.                                                                                                                    |
+| `instructions`      | `string`              | none                                                       | Guidance for the model on how to use the tools together.                                                                           |
+| `path`              | `string`              | `'/mcp'`                                                   | Endpoint path.                                                                                                                     |
+| `allowedOrigins`    | `string[] \| '*'`     | `[]`                                                       | Browser origins allowed to call the endpoint. Requests without `Origin` (CLIs, IDEs, servers) are always allowed.                  |
+| `forwardHeaders`    | `string[]`            | `['authorization','cookie','x-api-key','accept-language']` | Headers copied from the MCP request to the internal API call.                                                                      |
+| `maxResponseChars`  | `number`              | `100000`                                                   | Longer API responses are truncated before reaching the model.                                                                      |
+| `oauth`             | `OAuthOptions`        | none                                                       | Protect the endpoint with OAuth 2.1. See [OAuth](#oauth-sign-in-from-ai-clients).                                                  |
+| `transformResponse` | `ResponseTransform`   | none                                                       | Default response hook for route tools without their own. See [Shaping responses](#shaping-and-enriching-responses).                |
+| `tools`             | `McpToolDefinition[]` | `[]`                                                       | Extra hand-written tools.                                                                                                          |
+| `baseUrl`           | `string`              | loopback                                                   | _Express/Koa/Nest/Adonis._ Where internal calls go. Set it for HTTPS with self-signed certs, unix sockets, or a separate API host. |
+| `routes`            | `{method,path,...}[]` | `[]`                                                       | _Express/Koa/Hono._ Expose routes without editing them.                                                                            |
+| `routers`           | see guide             | none                                                       | _Express:_ `{ '/prefix': router }`. _Koa:_ `[router]`.                                                                             |
+| `middleware`        | `Middleware[]`        | `[]`                                                       | _Express._ Middleware in front of `/mcp`, such as auth.                                                                            |
+| `guards`            | `CanActivate[]`       | `[]`                                                       | _NestJS._ Guards on the MCP controller.                                                                                            |
+| `decorators`        | `ClassDecorator[]`    | `[]`                                                       | _NestJS._ Extra decorators on the MCP controller, e.g. `[Public()]` for global guards.                                             |
+| `pathPrefix`        | `string`              | none                                                       | _NestJS._ Extra prefix for tool routes. Global prefix and URI versioning are automatic.                                            |
+| `routeOptions`      | `object`              | none                                                       | _Fastify._ Extra route options for `/mcp`, such as `onRequest` hooks.                                                              |
+| `configureRoute`    | `(route) => void`     | none                                                       | _AdonisJS._ Configure the MCP route, e.g. add middleware.                                                                          |
 
 ### Tool options (`@McpTool()`, `mcpTool()`, `config.mcp`, `.mcp()`)
 
@@ -595,6 +742,8 @@ Your app's own validation always runs as well. The schema tells the agent what t
 | `input` / `params` / `query` / `body` | Schemas, see [above](#defining-tool-inputs-schemas).                                                                                                                |
 | `annotations`                         | MCP hints: `readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`. Defaults come from the HTTP method (GET → read-only, DELETE → destructive).        |
 | `headers`                             | Static headers added to the internal request.                                                                                                                       |
+| `scopes`                              | OAuth scopes the token needs to call this tool (with the `oauth` option). Missing scopes answer `403 insufficient_scope`.                                           |
+| `transformResponse`                   | Shape or enrich what the agent sees from this route's response. See [Shaping and enriching responses](#shaping-and-enriching-responses).                            |
 
 Each internal request also carries `X-Mcp-Tool: <tool name>`, so you can log or meter agent traffic separately.
 
@@ -616,12 +765,12 @@ const convert = defineTool({
 mountMcp(app, { name: 'shop-api', tools: [convert] });
 ```
 
-Handlers can return a string, any JSON value, or a full MCP `ToolResult`. `ctx.headers` holds the MCP request's headers, so you can authenticate there too.
+Handlers can return a string, any JSON value, or a full MCP `ToolResult`. `ctx.headers` holds the MCP request's headers, so you can authenticate there too. With the `oauth` option, `ctx.auth` holds the verified token (`subject`, `scopes`, `clientId`, `claims`).
 
 ## Security checklist
 
 - **Opt-in only.** Nothing is exposed unless you mark it. Review marked routes the way you review a public API, because an LLM can call them with any arguments.
-- **Use per-user credentials.** Clients send their own token, the token is forwarded, and your guards authorise the call. Avoid one shared super-token.
+- **Use per-user credentials.** Clients send their own token, the token is forwarded, and your guards authorise the call. Avoid one shared super-token. For remote servers, prefer the [`oauth` option](#oauth-sign-in-from-ai-clients): users sign in through your identity provider, tokens are audience-checked, and sensitive tools can require extra `scopes`.
 - **Protect discovery too** if tool names are sensitive (`guards`, `middleware`, `routeOptions`).
 - **Rate limits and IPs:** the agent IP is sent as `X-Forwarded-For`. For loopback adapters, trust loopback only: Express `app.set('trust proxy', 'loopback')`, Koa `app.proxy = true` behind a proxy that overwrites the header, Nest (Express) `app.set('trust proxy', 'loopback')`. Fastify `inject()` sets the IP directly.
 - **Browser access:** keep `allowedOrigins` empty unless a browser app must call `/mcp` directly.
@@ -649,9 +798,9 @@ Current scope (1.x):
 
 Planned (non-breaking, 1.x minor releases):
 
-- OAuth 2.1 protected-resource metadata (RFC 9728) helpers for remote MCP auth, and per-user tool lists
+- Per-user tool lists (hide tools the token's scopes can't call)
 - Next.js route handlers, Hapi and Elysia adapters
-- Structured output schemas, and binary/file responses
+- Structured output schemas (`outputSchema`), and binary/file responses
 - Streaming long-running responses over SSE
 - CLI to preview generated tools (`npx mcp-expose inspect`)
 - Resources from GET routes, and prompts
@@ -663,7 +812,7 @@ Contributions are welcome. See [Development](#development).
 ```bash
 npm install
 npm test            # vitest: core + all six adapters (real servers, real HTTP)
-npm run test:e2e    # pack → install into 18 fresh framework projects → official MCP SDK client
+npm run test:e2e    # pack → install into 19 fresh framework projects → official MCP SDK client (with and without OAuth)
 npm run typecheck
 npm run build       # ESM + CJS + .d.ts into dist/