@ttoss/http-server-mcp 0.26.1 → 0.26.2

package/README.md

@@ -372,7 +372,7 @@ The `WWW-Authenticate: Bearer resource_metadata="…"` header is how MCP clients
 The two behaviors the [MCP authorization spec](https://spec.modelcontextprotocol.io/specification/2025-03-26/basic/authorization/) requires for client bootstrapping are built into the `auth` option, so you no longer need the hand-rolled middleware shown above:
 
 - **`publicMethods`** — JSON-RPC methods that bypass verification, read from the request body's `method` field. Defaults to `['initialize', 'tools/list']` so clients can discover the server before authenticating. Pass `[]` to require a token for every method, or a custom list to change the exempt set. Leaving it unset serves the full tool catalogue — every tool name, description, and input schema — to unauthenticated callers, and logs a one-time warning explaining that and how to close it. Set `publicMethods` explicitly (even to the same default) to silence the warning.
-- **`resourceMetadataUrl`** — the URL a `401` advertises as `WWW-Authenticate: Bearer resource_metadata="<url>"` (RFC 9728) instead of a bare `Bearer`, pointing MCP clients at the protected-resource metadata document. **You normally do not set it**: when the document is served — i.e. both `resourceServerUrl` and `authorizationServerUrl` are configured — it defaults to the RFC 9728 location this router serves it at, so the header and the routes cannot drift apart. Set it only to point at a document served elsewhere. When the document is not served, the header stays a bare `Bearer` rather than naming a location with no route.
+- **`resourceMetadataUrl`** — the URL a `401` advertises as `WWW-Authenticate: Bearer resource_metadata="<url>"` (RFC 9728) instead of a bare `Bearer`, pointing MCP clients at the protected-resource metadata document. **You normally do not set it**: when the document is served — i.e. both `resourceServerUrl` and `authorizationServerUrl` are configured — it defaults to the RFC 9728 location this router serves it at, so the header and the routes cannot drift apart. When the document is not served, the header stays a bare `Bearer` rather than naming a location with no route. The field exists for the one configuration where this router deliberately does not serve the document — an `oauthServer()` in the same deployment already answers that path, so this router is mounted without `resourceServerUrl`/`authorizationServerUrl` to avoid two routers on one path, and has nothing to derive from. Compute the value with `protectedResourceMetadataUrl` from [`@ttoss/auth-core`](https://ttoss.dev/docs/modules/packages/auth-core) rather than typing it, so both halves apply the same §3.1 rule.
 
 ```typescript
 createMcpRouter(mcpServer, {
@@ -503,7 +503,7 @@ Creates a Koa router configured to handle MCP protocol requests.
     - `auth.requiredScopes` — Router-level scope guard; returns 403 if any scope is missing
     - `auth.resourceServerUrl` + `auth.authorizationServerUrl` — Enable the protected-resource metadata document, served at both `/.well-known/oauth-protected-resource` and the RFC 9728 path-derived `/.well-known/oauth-protected-resource<path>`; the metadata `resource` is set to `resourceServerUrl + path` so clients following `resource` land on the actual MCP endpoint
     - `auth.publicMethods` — JSON-RPC methods that bypass verification (default `['initialize', 'tools/list']`)
-    - `auth.resourceMetadataUrl` — URL advertised in the RFC 9728 `WWW-Authenticate: Bearer resource_metadata="…"` header on a 401. Defaults to the location derived from `resourceServerUrl` + `path` (the one this router serves), so the header cannot drift from the routes; set it only to point at a document served elsewhere
+    - `auth.resourceMetadataUrl` — URL advertised in the RFC 9728 `WWW-Authenticate: Bearer resource_metadata="…"` header on a 401. Defaults to the location derived from `resourceServerUrl` + `path` (the one this router serves), so the header cannot drift from the routes; set it only when a separate `oauthServer()` serves the document and this router is mounted without `resourceServerUrl`/`authorizationServerUrl`
     - `auth.resourceIndicator` — Expected `aud` value(s) (RFC 8707); rejects tokens minted for a different resource. See [Resource indicator validation](#resource-indicator-validation-rfc-8707)
 
 **Returns:** `Router` — Koa router instance

package/dist/index.d.cts

@@ -909,9 +909,28 @@ interface McpAuthOptions {
    * drift from the routes. The default applies only when the document is
    * actually served (both `resourceServerUrl` and `authorizationServerUrl`
    * set); otherwise the header stays a bare `Bearer` rather than advertising a
-   * location with no route. Set it only to point at a document served
-   * elsewhere; a hand-written value that names a location nothing serves fails
-   * discovery silently.
+   * location with no route.
+   *
+   * **Leave it unset when this router serves the document.** It exists for the
+   * one configuration where that is deliberately not the case: an
+   * authorization server in the same deployment (`oauthServer({ resource })`)
+   * already answers `/.well-known/oauth-protected-resource`, so mounting this
+   * router with `resourceServerUrl` + `authorizationServerUrl` too would put
+   * two routers on one path. Omit both there and set this instead — without
+   * it the `401` is a bare `Bearer`, which never starts a client's discovery.
+   *
+   * Derive the value rather than typing it: `protectedResourceMetadataUrl`
+   * from `@ttoss/auth-core` applies the same RFC 9728 §3.1 rule the serving
+   * side does. A hand-written value that names a location nothing serves
+   * fails discovery silently.
+   *
+   * @example
+   * ```typescript
+   * // Only when oauthServer (not this router) serves the document.
+   * resourceMetadataUrl: protectedResourceMetadataUrl({
+   *   resource: 'https://mcp.example.com/mcp',
+   * }),
+   * ```
    */
   resourceMetadataUrl?: string;
   /**

package/dist/index.d.mts

@@ -910,9 +910,28 @@ interface McpAuthOptions {
    * drift from the routes. The default applies only when the document is
    * actually served (both `resourceServerUrl` and `authorizationServerUrl`
    * set); otherwise the header stays a bare `Bearer` rather than advertising a
-   * location with no route. Set it only to point at a document served
-   * elsewhere; a hand-written value that names a location nothing serves fails
-   * discovery silently.
+   * location with no route.
+   *
+   * **Leave it unset when this router serves the document.** It exists for the
+   * one configuration where that is deliberately not the case: an
+   * authorization server in the same deployment (`oauthServer({ resource })`)
+   * already answers `/.well-known/oauth-protected-resource`, so mounting this
+   * router with `resourceServerUrl` + `authorizationServerUrl` too would put
+   * two routers on one path. Omit both there and set this instead — without
+   * it the `401` is a bare `Bearer`, which never starts a client's discovery.
+   *
+   * Derive the value rather than typing it: `protectedResourceMetadataUrl`
+   * from `@ttoss/auth-core` applies the same RFC 9728 §3.1 rule the serving
+   * side does. A hand-written value that names a location nothing serves
+   * fails discovery silently.
+   *
+   * @example
+   * ```typescript
+   * // Only when oauthServer (not this router) serves the document.
+   * resourceMetadataUrl: protectedResourceMetadataUrl({
+   *   resource: 'https://mcp.example.com/mcp',
+   * }),
+   * ```
    */
   resourceMetadataUrl?: string;
   /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ttoss/http-server-mcp",
-  "version": "0.26.1",
+  "version": "0.26.2",
   "description": "Model Context Protocol (MCP) server integration for @ttoss/http-server",
   "keywords": [
     "ai",