@koduhai/mcp-kit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Koduhai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,141 @@
+# @koduhai/mcp-kit
+
+[![CI](https://github.com/koduhai/mcp-kit/actions/workflows/ci.yml/badge.svg)](https://github.com/koduhai/mcp-kit/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/@koduhai/mcp-kit.svg)](https://www.npmjs.com/package/@koduhai/mcp-kit)
+[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/koduhai/mcp-kit/badge)](https://scorecard.dev/viewer/?uri=github.com/koduhai/mcp-kit)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
+[![Node](https://img.shields.io/node/v/@koduhai/mcp-kit.svg)](https://nodejs.org)
+
+The two things people get wrong building [MCP](https://modelcontextprotocol.io) servers, solved: **auth** and **versioning**.
+
+It does three things, on three import paths so the lightweight parts pull no heavy deps:
+
+- **Upstream auth** (`/upstream`) — how your server authenticates to the API it wraps: API key, bearer, or OAuth client-credentials with automatic token caching/refresh.
+- **Versioning** (`/versioning`) — pin the upstream API version, send it on every call, expose a `get_version` tool, and detect drift.
+- **Server OAuth** (`/auth`) — turn a remote (Streamable HTTP) MCP server into a spec-compliant **OAuth 2.1 Resource Server** in one call. Ships the JWKS + introspection token verifiers the MCP SDK needs but does not include.
+
+Built on top of `@modelcontextprotocol/sdk`. Aligned to the **2025-06-18** authorization spec (MCP servers are Resource Servers; they verify tokens and serve RFC 9728 metadata, they do not act as an Authorization Server).
+
+```bash
+npm install @koduhai/mcp-kit
+```
+
+---
+
+## 1. Upstream auth — `@koduhai/mcp-kit/upstream`
+
+Most MCP servers wrap an API and need to authenticate to it. Stop hand-rolling this.
+
+```ts
+import {
+  apiKeyAuth,
+  bearerAuth,
+  clientCredentialsAuth,
+  createUpstreamFetch,
+} from '@koduhai/mcp-kit/upstream';
+
+// Static API key (defaults to `Authorization: Bearer <key>`; pass a header for raw keys)
+const auth = apiKeyAuth({ key: process.env.API_KEY! });
+const auth2 = apiKeyAuth({ key: process.env.API_KEY!, header: 'X-Api-Key' });
+
+// OAuth 2.0 machine-to-machine — fetches, caches, and refreshes the token for you
+const m2m = clientCredentialsAuth({
+  tokenUrl: 'https://issuer/oauth/token',
+  clientId: process.env.CLIENT_ID!,
+  clientSecret: process.env.CLIENT_SECRET!,
+  audience: 'https://api.example.com', // if your IdP needs it (e.g. Auth0)
+});
+
+// A fetch that carries your auth (+ any standing headers) on every request
+const api = createUpstreamFetch({ baseUrl: 'https://api.example.com', auth });
+const res = await api('/things/123'); // -> GET https://api.example.com/things/123, authorized
+```
+
+`clientCredentialsAuth` caches the access token and refreshes it shortly before expiry; concurrent callers during a refresh share a single in-flight request.
+
+## 2. Versioning — `@koduhai/mcp-kit/versioning`
+
+APIs evolve; agents get confused when response shapes shift under them. Pin a version, send it everywhere, and surface it.
+
+```ts
+import { apiVersioning, versionTool } from '@koduhai/mcp-kit/versioning';
+
+const versioning = apiVersioning({
+  header: 'Api-Version',
+  version: '2026-01-01',
+  current: '2026-03-01', // optional: flags drift
+  supported: ['2026-01-01', '2026-03-01'], // optional: refuses an unknown pin at startup
+});
+
+// Feed it into createUpstreamFetch so every request carries the header:
+const api = createUpstreamFetch({ baseUrl, auth, headers: () => versioning.headers() });
+
+// Register this descriptor as a tool so the agent can ask which version it's talking to:
+const tool = versionTool(versioning); // { name: 'get_version', inputSchema, handler }
+```
+
+## 3. Server-side OAuth — `@koduhai/mcp-kit/auth`
+
+This is the part everyone gets stuck on. Per the current spec, a remote MCP server is an **OAuth 2.1 Resource Server**: it must verify access tokens and serve Protected Resource Metadata (RFC 9728) so clients can discover where to log in. The MCP SDK gives you `requireBearerAuth` and the metadata router, **but not a token verifier** — you have to write JWT/JWKS or introspection validation yourself. mcp-kit ships both, plus a one-call assembly.
+
+```ts
+import express from 'express';
+import { jwtVerifier, protectMcpServer } from '@koduhai/mcp-kit/auth';
+
+const app = express();
+const issuer = 'https://your-tenant.auth0.com';
+const resourceServerUrl = 'https://mcp.example.com';
+
+const { requireAuth } = await protectMcpServer({
+  app,
+  resourceServerUrl,
+  issuer, // AS metadata + JWKS auto-discovered
+  verifier: jwtVerifier({ issuer, audience: resourceServerUrl }),
+  scopesSupported: ['mcp:tools'],
+  requiredScopes: ['mcp:tools'],
+});
+
+app.post('/mcp', requireAuth, mcpHttpHandler); // req.auth is now populated
+```
+
+That gives you, for free:
+
+- `GET /.well-known/oauth-protected-resource` → RFC 9728 metadata pointing at your IdP.
+- `401` on missing/invalid tokens with a `WWW-Authenticate: Bearer ... resource_metadata="..."` header, so compliant MCP clients can discover the auth server and start the flow.
+- JWT validation of signature (via the issuer's JWKS), `iss`, `aud` (this is what stops token-passthrough/confused-deputy attacks), `exp`/`nbf`, and scope enforcement.
+
+Opaque tokens instead of JWTs? Swap the verifier:
+
+```ts
+import { introspectionVerifier } from '@koduhai/mcp-kit/auth';
+
+const verifier = introspectionVerifier({
+  introspectionUrl: 'https://your-tenant.auth0.com/oauth/introspect',
+  clientId: process.env.RS_CLIENT_ID!,
+  clientSecret: process.env.RS_CLIENT_SECRET!,
+  cacheTtlSeconds: 60, // cache active results (default 60); set 0 to introspect every request
+});
+```
+
+Introspection results are cached for a short TTL (capped by the token's own `exp`) and deduplicated while a call is in flight, so a busy server doesn't introspect the same token on every request. Caching delays revocation visibility by at most the TTL; set `cacheTtlSeconds: 0` if every request must hit the AS.
+
+Works with any standards-compliant IdP: Auth0, Logto, Clerk, Keycloak, Okta, Cognito, WorkOS, and friends. mcp-kit verifies tokens; it does not try to be your Authorization Server (the spec says don't, and you shouldn't).
+
+See [`examples/`](./examples) for a full stdio server and a full remote OAuth server.
+
+---
+
+## Design
+
+- **Layered, optional peers.** `/upstream` and `/versioning` have zero dependencies. `/auth` declares `@modelcontextprotocol/sdk`, `express`, and `jose` as _optional_ peers, so you only install them if you build a remote server.
+- **Injectable everything.** Every network call and clock is injectable, so the whole thing is tested offline (46 tests, including a real Express + token-verification integration).
+- **Resilient outbound calls.** Every control-plane request the library makes (token, introspection, JWKS, discovery) carries a timeout (default 10s, configurable via `timeoutMs`) so an unresponsive IdP can't hang your server.
+- **ESM, Node ≥ 20, TypeScript-first.**
+
+## Compatibility
+
+Targets `@modelcontextprotocol/sdk` ≥ 1.20 and the 2025-06-18 MCP authorization spec. The SDK's auth helpers are Express-based, so `/auth` integrates with Express; `/upstream` and `/versioning` are transport-agnostic.
+
+## License
+
+MIT © [Koduhai](https://github.com/koduhai). Built alongside [KoduhMail](https://koduhmail.com), generalizing the auth + versioning patterns from its MCP server.

package/dist/auth/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @koduhai/mcp-kit/auth — make a remote (Streamable HTTP) MCP server a spec-compliant
+ * OAuth 2.1 Resource Server. Supplies the token verifiers the MCP SDK needs but does not
+ * ship (JWKS + introspection) and a one-call `protectMcpServer` assembly.
+ *
+ * Peers: `@modelcontextprotocol/sdk`, `express`, `jose`.
+ */
+export { discoverOAuthMetadata } from './metadata.js';
+export type { DiscoverOptions } from './metadata.js';
+export { jwtVerifier } from './jwt-verifier.js';
+export type { JwtVerifierOptions } from './jwt-verifier.js';
+export { introspectionVerifier } from './introspection-verifier.js';
+export type { IntrospectionVerifierOptions } from './introspection-verifier.js';
+export { protectMcpServer } from './protect.js';
+export type { ProtectMcpServerOptions, ProtectMcpServerResult } from './protect.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/auth/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/auth/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AACtD,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,YAAY,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAC5D,OAAO,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AACpE,YAAY,EAAE,4BAA4B,EAAE,MAAM,6BAA6B,CAAC;AAChF,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChD,YAAY,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC"}

package/dist/auth/index.js

@@ -0,0 +1,12 @@
+/**
+ * @koduhai/mcp-kit/auth — make a remote (Streamable HTTP) MCP server a spec-compliant
+ * OAuth 2.1 Resource Server. Supplies the token verifiers the MCP SDK needs but does not
+ * ship (JWKS + introspection) and a one-call `protectMcpServer` assembly.
+ *
+ * Peers: `@modelcontextprotocol/sdk`, `express`, `jose`.
+ */
+export { discoverOAuthMetadata } from './metadata.js';
+export { jwtVerifier } from './jwt-verifier.js';
+export { introspectionVerifier } from './introspection-verifier.js';
+export { protectMcpServer } from './protect.js';
+//# sourceMappingURL=index.js.map

package/dist/auth/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/auth/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAEtD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhD,OAAO,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AAEpE,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC"}

package/dist/auth/introspection-verifier.d.ts

@@ -0,0 +1,37 @@
+import type { OAuthTokenVerifier } from '@modelcontextprotocol/sdk/server/auth/provider.js';
+export interface IntrospectionVerifierOptions {
+    /** The OAuth 2.0 token introspection endpoint (RFC 7662). */
+    introspectionUrl: string;
+    /** Client credentials this Resource Server uses to authenticate to the introspection endpoint. */
+    clientId: string;
+    clientSecret: string;
+    /** How to present the client credentials. Default `basic` (HTTP Basic). */
+    authMethod?: 'basic' | 'post';
+    /**
+     * Cache successful introspection results for this many seconds, so a burst of
+     * requests bearing the same token does not introspect on every call. The cached
+     * entry never outlives the token's own `exp`. Default 60. Set 0 to introspect on
+     * every request (instant revocation visibility, at the cost of more AS load).
+     */
+    cacheTtlSeconds?: number;
+    /** Maximum number of cached tokens; oldest entries are evicted first. Default 1000. */
+    maxCacheEntries?: number;
+    /** Timeout (ms) for the introspection request. Default 10000. Pass 0 to disable. */
+    timeoutMs?: number;
+    /** Injectable clock (ms). */
+    now?: () => number;
+    /** Injectable for tests. */
+    fetch?: typeof globalThis.fetch;
+}
+/**
+ * An {@link OAuthTokenVerifier} that validates opaque (or any) access tokens by calling the
+ * Authorization Server's introspection endpoint (RFC 7662). Use this when your IdP issues
+ * opaque tokens, or when you want the AS to be the single source of truth on revocation.
+ *
+ * Successful results are cached for a short, configurable TTL (and deduplicated while a
+ * call is in flight) so high-traffic servers don't introspect the same token on every
+ * request. Caching delays revocation visibility by at most the TTL; set `cacheTtlSeconds: 0`
+ * if you need every request to hit the AS.
+ */
+export declare function introspectionVerifier(opts: IntrospectionVerifierOptions): OAuthTokenVerifier;
+//# sourceMappingURL=introspection-verifier.d.ts.map

package/dist/auth/introspection-verifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"introspection-verifier.d.ts","sourceRoot":"","sources":["../../src/auth/introspection-verifier.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mDAAmD,CAAC;AAI5F,MAAM,WAAW,4BAA4B;IAC3C,6DAA6D;IAC7D,gBAAgB,EAAE,MAAM,CAAC;IACzB,kGAAkG;IAClG,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,2EAA2E;IAC3E,UAAU,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IAC9B;;;;;OAKG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,uFAAuF;IACvF,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,oFAAoF;IACpF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6BAA6B;IAC7B,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,4BAA4B;IAC5B,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CACjC;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,4BAA4B,GAAG,kBAAkB,CA8F5F"}

package/dist/auth/introspection-verifier.js

@@ -0,0 +1,103 @@
+import { createHash } from 'node:crypto';
+import { InvalidTokenError } from '@modelcontextprotocol/sdk/server/auth/errors.js';
+import { DEFAULT_TIMEOUT_MS, fetchWithTimeout } from '../internal/http.js';
+/**
+ * An {@link OAuthTokenVerifier} that validates opaque (or any) access tokens by calling the
+ * Authorization Server's introspection endpoint (RFC 7662). Use this when your IdP issues
+ * opaque tokens, or when you want the AS to be the single source of truth on revocation.
+ *
+ * Successful results are cached for a short, configurable TTL (and deduplicated while a
+ * call is in flight) so high-traffic servers don't introspect the same token on every
+ * request. Caching delays revocation visibility by at most the TTL; set `cacheTtlSeconds: 0`
+ * if you need every request to hit the AS.
+ */
+export function introspectionVerifier(opts) {
+    if (!opts.introspectionUrl)
+        throw new Error('introspectionVerifier: `introspectionUrl` is required');
+    if (!opts.clientId || !opts.clientSecret) {
+        throw new Error('introspectionVerifier: `clientId` and `clientSecret` are required');
+    }
+    const fetchImpl = opts.fetch ?? globalThis.fetch;
+    const method = opts.authMethod ?? 'basic';
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const ttlMs = (opts.cacheTtlSeconds ?? 60) * 1000;
+    const maxEntries = opts.maxCacheEntries ?? 1000;
+    const now = opts.now ?? (() => Date.now());
+    const cache = new Map();
+    const inflight = new Map();
+    // Hash so raw bearer tokens are not retained as cache keys.
+    const keyOf = (token) => createHash('sha256').update(token).digest('hex');
+    async function introspect(token) {
+        const headers = {
+            'Content-Type': 'application/x-www-form-urlencoded',
+            Accept: 'application/json',
+        };
+        const body = new URLSearchParams({ token, token_type_hint: 'access_token' });
+        if (method === 'basic') {
+            headers.Authorization = `Basic ${Buffer.from(`${opts.clientId}:${opts.clientSecret}`).toString('base64')}`;
+        }
+        else {
+            body.set('client_id', opts.clientId);
+            body.set('client_secret', opts.clientSecret);
+        }
+        let res;
+        try {
+            res = await fetchWithTimeout(fetchImpl, opts.introspectionUrl, { method: 'POST', headers, body }, timeoutMs);
+        }
+        catch (e) {
+            throw new InvalidTokenError(`introspection request failed: ${e instanceof Error ? e.message : String(e)}`);
+        }
+        if (!res.ok)
+            throw new InvalidTokenError(`introspection endpoint returned HTTP ${res.status}`);
+        const data = (await res.json());
+        if (data.active !== true)
+            throw new InvalidTokenError('token is inactive or revoked');
+        const scopes = typeof data.scope === 'string' ? data.scope.split(' ').filter(Boolean) : [];
+        return {
+            token,
+            clientId: String(data.client_id ?? ''),
+            scopes,
+            expiresAt: typeof data.exp === 'number' ? data.exp : undefined,
+            extra: data,
+        };
+    }
+    function remember(key, info) {
+        // Cap the cached lifetime by both the TTL and the token's own expiry.
+        const tokenExpiryMs = info.expiresAt != null ? info.expiresAt * 1000 : Infinity;
+        const expiresAtMs = Math.min(now() + ttlMs, tokenExpiryMs);
+        if (expiresAtMs <= now())
+            return;
+        if (cache.size >= maxEntries) {
+            const oldest = cache.keys().next().value;
+            if (oldest !== undefined)
+                cache.delete(oldest);
+        }
+        cache.set(key, { info, expiresAtMs });
+    }
+    return {
+        async verifyAccessToken(token) {
+            if (ttlMs <= 0)
+                return introspect(token);
+            const key = keyOf(token);
+            const hit = cache.get(key);
+            if (hit && now() < hit.expiresAtMs)
+                return hit.info;
+            if (hit)
+                cache.delete(key);
+            const pending = inflight.get(key);
+            if (pending)
+                return pending;
+            const p = introspect(token)
+                .then((info) => {
+                remember(key, info);
+                return info;
+            })
+                .finally(() => {
+                inflight.delete(key);
+            });
+            inflight.set(key, p);
+            return p;
+        },
+    };
+}
+//# sourceMappingURL=introspection-verifier.js.map

package/dist/auth/introspection-verifier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"introspection-verifier.js","sourceRoot":"","sources":["../../src/auth/introspection-verifier.ts"],"names":[],"mappings":"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"}

package/dist/auth/jwt-verifier.d.ts

@@ -0,0 +1,35 @@
+import { jwtVerify } from 'jose';
+import type { OAuthTokenVerifier } from '@modelcontextprotocol/sdk/server/auth/provider.js';
+/** The accepted forms for the verification key (a key, a JWKS, or a key-resolving function). */
+type JwtKeyInput = Parameters<typeof jwtVerify>[1];
+export interface JwtVerifierOptions {
+    /** Expected token issuer (`iss`). Also used to auto-discover the JWKS if `jwksUri` is omitted. */
+    issuer: string;
+    /**
+     * Expected audience (`aud`): your MCP server's resource identifier (RFC 8707). A token minted
+     * for a different resource is rejected, which is what stops token-passthrough attacks.
+     */
+    audience: string | string[];
+    /** JWKS URI. If omitted it is discovered from the issuer's AS metadata (`jwks_uri`). */
+    jwksUri?: string;
+    /** Allowed signing algorithms. Default `['RS256', 'ES256']`. Never allow `none`. */
+    algorithms?: string[];
+    /** Clock skew tolerance in seconds for `exp`/`nbf`. Default 5. */
+    clockToleranceSeconds?: number;
+    /** Timeout (ms) for JWKS fetch and issuer discovery. Default 10000. */
+    timeoutMs?: number;
+    /** Claim to read scopes from. By default tries `scope` (space-delimited) then `scp` (array). */
+    scopeClaim?: string;
+    /** Provide the key directly (a `KeyLike`/JWKS/resolver) instead of discovering it. Mainly for tests. */
+    key?: JwtKeyInput;
+    /** Injectable fetch for discovery. */
+    fetch?: typeof globalThis.fetch;
+}
+/**
+ * An {@link OAuthTokenVerifier} that validates JWT access tokens against an IdP's JWKS:
+ * signature, `iss`, `aud`, and `exp`/`nbf`. This is the verifier the MCP SDK's
+ * `requireBearerAuth` needs but does not ship. Drop it into {@link protectMcpServer}.
+ */
+export declare function jwtVerifier(opts: JwtVerifierOptions): OAuthTokenVerifier;
+export {};
+//# sourceMappingURL=jwt-verifier.d.ts.map

package/dist/auth/jwt-verifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jwt-verifier.d.ts","sourceRoot":"","sources":["../../src/auth/jwt-verifier.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,SAAS,EAAE,MAAM,MAAM,CAAC;AAErD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mDAAmD,CAAC;AAK5F,gGAAgG;AAChG,KAAK,WAAW,GAAG,UAAU,CAAC,OAAO,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;AAEnD,MAAM,WAAW,kBAAkB;IACjC,kGAAkG;IAClG,MAAM,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC5B,wFAAwF;IACxF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oFAAoF;IACpF,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,kEAAkE;IAClE,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,uEAAuE;IACvE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gGAAgG;IAChG,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,wGAAwG;IACxG,GAAG,CAAC,EAAE,WAAW,CAAC;IAClB,sCAAsC;IACtC,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CACjC;AAcD;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,kBAAkB,GAAG,kBAAkB,CAyDxE"}

package/dist/auth/jwt-verifier.js

@@ -0,0 +1,86 @@
+import { createRemoteJWKSet, jwtVerify } from 'jose';
+import { InvalidTokenError } from '@modelcontextprotocol/sdk/server/auth/errors.js';
+import { DEFAULT_TIMEOUT_MS } from '../internal/http.js';
+import { discoverOAuthMetadata } from './metadata.js';
+function extractScopes(payload, scopeClaim) {
+    const toScopes = (v) => {
+        if (typeof v === 'string')
+            return v.split(' ').filter(Boolean);
+        if (Array.isArray(v))
+            return v.map(String);
+        return [];
+    };
+    if (scopeClaim)
+        return toScopes(payload[scopeClaim]);
+    if (payload.scope != null)
+        return toScopes(payload.scope);
+    if (payload.scp != null)
+        return toScopes(payload.scp);
+    return [];
+}
+/**
+ * An {@link OAuthTokenVerifier} that validates JWT access tokens against an IdP's JWKS:
+ * signature, `iss`, `aud`, and `exp`/`nbf`. This is the verifier the MCP SDK's
+ * `requireBearerAuth` needs but does not ship. Drop it into {@link protectMcpServer}.
+ */
+export function jwtVerifier(opts) {
+    if (!opts.issuer)
+        throw new Error('jwtVerifier: `issuer` is required');
+    if (!opts.audience)
+        throw new Error('jwtVerifier: `audience` is required');
+    let keyInput = opts.key;
+    let resolving = null;
+    async function resolveKey() {
+        if (keyInput)
+            return keyInput;
+        if (resolving)
+            return resolving;
+        resolving = (async () => {
+            let jwksUri = opts.jwksUri;
+            if (!jwksUri) {
+                const meta = (await discoverOAuthMetadata(opts.issuer, {
+                    fetch: opts.fetch,
+                    timeoutMs: opts.timeoutMs,
+                }));
+                jwksUri = meta.jwks_uri;
+                if (!jwksUri)
+                    throw new Error('jwtVerifier: issuer metadata has no jwks_uri; pass `jwksUri` or `key`');
+            }
+            const jwksTimeout = opts.timeoutMs && opts.timeoutMs > 0 ? opts.timeoutMs : DEFAULT_TIMEOUT_MS;
+            keyInput = createRemoteJWKSet(new URL(jwksUri), { timeoutDuration: jwksTimeout });
+            return keyInput;
+        })();
+        try {
+            return await resolving;
+        }
+        finally {
+            resolving = null;
+        }
+    }
+    return {
+        async verifyAccessToken(token) {
+            try {
+                const key = await resolveKey();
+                const { payload } = await jwtVerify(token, key, {
+                    issuer: opts.issuer,
+                    audience: opts.audience,
+                    algorithms: opts.algorithms ?? ['RS256', 'ES256'],
+                    clockTolerance: opts.clockToleranceSeconds ?? 5,
+                });
+                return {
+                    token,
+                    clientId: String(payload.client_id ?? payload.azp ?? payload.sub ?? ''),
+                    scopes: extractScopes(payload, opts.scopeClaim),
+                    expiresAt: typeof payload.exp === 'number' ? payload.exp : undefined,
+                    extra: payload,
+                };
+            }
+            catch (e) {
+                if (e instanceof InvalidTokenError)
+                    throw e;
+                throw new InvalidTokenError(e instanceof Error ? e.message : 'invalid token');
+            }
+        },
+    };
+}
+//# sourceMappingURL=jwt-verifier.js.map

package/dist/auth/jwt-verifier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jwt-verifier.js","sourceRoot":"","sources":["../../src/auth/jwt-verifier.ts"],"names":[],"mappings":"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"}

package/dist/auth/metadata.d.ts

@@ -0,0 +1,16 @@
+import type { OAuthMetadata } from '@modelcontextprotocol/sdk/shared/auth.js';
+export interface DiscoverOptions {
+    /** Timeout (ms) per discovery request. Default 10000. Pass 0 to disable. */
+    timeoutMs?: number;
+    /** Injectable for tests. */
+    fetch?: typeof globalThis.fetch;
+}
+/**
+ * Discover an Authorization Server's metadata (RFC 8414) from its issuer URL. Tries the
+ * OAuth well-known path first, then OIDC discovery. The result feeds `protectMcpServer`
+ * (and supplies `jwks_uri` for {@link jwtVerifier}).
+ *
+ * @throws when neither well-known document can be fetched.
+ */
+export declare function discoverOAuthMetadata(issuer: string, opts?: DiscoverOptions): Promise<OAuthMetadata>;
+//# sourceMappingURL=metadata.d.ts.map

package/dist/auth/metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata.d.ts","sourceRoot":"","sources":["../../src/auth/metadata.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0CAA0C,CAAC;AAG9E,MAAM,WAAW,eAAe;IAC9B,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4BAA4B;IAC5B,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CACjC;AAED;;;;;;GAMG;AACH,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,MAAM,EACd,IAAI,GAAE,eAAoB,GACzB,OAAO,CAAC,aAAa,CAAC,CA4BxB"}

package/dist/auth/metadata.js

@@ -0,0 +1,32 @@
+import { DEFAULT_TIMEOUT_MS, fetchWithTimeout } from '../internal/http.js';
+/**
+ * Discover an Authorization Server's metadata (RFC 8414) from its issuer URL. Tries the
+ * OAuth well-known path first, then OIDC discovery. The result feeds `protectMcpServer`
+ * (and supplies `jwks_uri` for {@link jwtVerifier}).
+ *
+ * @throws when neither well-known document can be fetched.
+ */
+export async function discoverOAuthMetadata(issuer, opts = {}) {
+    const fetchImpl = opts.fetch ?? globalThis.fetch;
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const base = issuer.replace(/\/+$/, '');
+    const candidates = [
+        `${base}/.well-known/oauth-authorization-server`,
+        `${base}/.well-known/openid-configuration`,
+    ];
+    let lastErr;
+    for (const url of candidates) {
+        try {
+            const res = await fetchWithTimeout(fetchImpl, url, { headers: { Accept: 'application/json' } }, timeoutMs);
+            if (res.ok)
+                return (await res.json());
+            lastErr = new Error(`HTTP ${res.status} from ${url}`);
+        }
+        catch (e) {
+            lastErr = e;
+        }
+    }
+    throw new Error(`discoverOAuthMetadata: could not load AS metadata for issuer "${issuer}" ` +
+        `(${lastErr instanceof Error ? lastErr.message : String(lastErr)})`);
+}
+//# sourceMappingURL=metadata.js.map

package/dist/auth/metadata.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata.js","sourceRoot":"","sources":["../../src/auth/metadata.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAS3E;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,MAAc,EACd,OAAwB,EAAE;IAE1B,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,IAAI,UAAU,CAAC,KAAK,CAAC;IACjD,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,kBAAkB,CAAC;IACvD,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IACxC,MAAM,UAAU,GAAG;QACjB,GAAG,IAAI,yCAAyC;QAChD,GAAG,IAAI,mCAAmC;KAC3C,CAAC;IAEF,IAAI,OAAgB,CAAC;IACrB,KAAK,MAAM,GAAG,IAAI,UAAU,EAAE,CAAC;QAC7B,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,MAAM,gBAAgB,CAChC,SAAS,EACT,GAAG,EACH,EAAE,OAAO,EAAE,EAAE,MAAM,EAAE,kBAAkB,EAAE,EAAE,EAC3C,SAAS,CACV,CAAC;YACF,IAAI,GAAG,CAAC,EAAE;gBAAE,OAAO,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAkB,CAAC;YACvD,OAAO,GAAG,IAAI,KAAK,CAAC,QAAQ,GAAG,CAAC,MAAM,SAAS,GAAG,EAAE,CAAC,CAAC;QACxD,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,OAAO,GAAG,CAAC,CAAC;QACd,CAAC;IACH,CAAC;IACD,MAAM,IAAI,KAAK,CACb,iEAAiE,MAAM,IAAI;QACzE,IAAI,OAAO,YAAY,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,CACtE,CAAC;AACJ,CAAC"}

package/dist/auth/protect.d.ts

@@ -0,0 +1,50 @@
+import type { Express, RequestHandler } from 'express';
+import type { OAuthTokenVerifier } from '@modelcontextprotocol/sdk/server/auth/provider.js';
+import type { OAuthMetadata } from '@modelcontextprotocol/sdk/shared/auth.js';
+export interface ProtectMcpServerOptions {
+    /** Your Express app. The RFC 9728 metadata endpoints are mounted on it. */
+    app: Express;
+    /** The public URL of this MCP server (its OAuth resource identifier). */
+    resourceServerUrl: string | URL;
+    /** A token verifier — e.g. {@link jwtVerifier} or {@link introspectionVerifier}. */
+    verifier: OAuthTokenVerifier;
+    /** The Authorization Server metadata. Provide this OR `issuer` to discover it. */
+    oauthMetadata?: OAuthMetadata;
+    /** Issuer URL to discover AS metadata from when `oauthMetadata` is not given. */
+    issuer?: string;
+    /** Scopes advertised in Protected Resource Metadata. */
+    scopesSupported?: string[];
+    /** Scopes a token must carry to be allowed through (enforced on each request). */
+    requiredScopes?: string[];
+    /** Human-readable resource name for the metadata document. */
+    resourceName?: string;
+    /** Docs URL advertised in the metadata document. */
+    serviceDocumentationUrl?: string | URL;
+    /** Injectable fetch for issuer discovery. */
+    fetch?: typeof globalThis.fetch;
+}
+export interface ProtectMcpServerResult {
+    /** Express middleware that guards your MCP endpoint(s): validates the bearer token and sets `req.auth`. */
+    requireAuth: RequestHandler;
+    /** The RFC 9728 protected-resource-metadata URL clients discover via the 401 `WWW-Authenticate` header. */
+    resourceMetadataUrl: string;
+    /** The resolved Authorization Server metadata. */
+    metadata: OAuthMetadata;
+}
+/**
+ * Turn an Express app into a spec-compliant MCP OAuth 2.1 **Resource Server** in one call:
+ * serve Protected Resource Metadata (RFC 9728), and return a `requireAuth` middleware that
+ * validates bearer tokens with your verifier and emits a discovery-pointing `WWW-Authenticate`
+ * header on 401. You wire `requireAuth` onto your Streamable-HTTP MCP route.
+ *
+ * @example
+ * const { requireAuth } = await protectMcpServer({
+ *   app, resourceServerUrl: 'https://mcp.example.com',
+ *   issuer: 'https://auth.example.com',
+ *   verifier: jwtVerifier({ issuer: 'https://auth.example.com', audience: 'https://mcp.example.com' }),
+ *   scopesSupported: ['mcp:tools'],
+ * });
+ * app.post('/mcp', requireAuth, mcpHttpHandler);
+ */
+export declare function protectMcpServer(opts: ProtectMcpServerOptions): Promise<ProtectMcpServerResult>;
+//# sourceMappingURL=protect.d.ts.map

package/dist/auth/protect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protect.d.ts","sourceRoot":"","sources":["../../src/auth/protect.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAMvD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mDAAmD,CAAC;AAC5F,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0CAA0C,CAAC;AAG9E,MAAM,WAAW,uBAAuB;IACtC,2EAA2E;IAC3E,GAAG,EAAE,OAAO,CAAC;IACb,yEAAyE;IACzE,iBAAiB,EAAE,MAAM,GAAG,GAAG,CAAC;IAChC,oFAAoF;IACpF,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,kFAAkF;IAClF,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,iFAAiF;IACjF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wDAAwD;IACxD,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,kFAAkF;IAClF,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,8DAA8D;IAC9D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,oDAAoD;IACpD,uBAAuB,CAAC,EAAE,MAAM,GAAG,GAAG,CAAC;IACvC,6CAA6C;IAC7C,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CACjC;AAED,MAAM,WAAW,sBAAsB;IACrC,2GAA2G;IAC3G,WAAW,EAAE,cAAc,CAAC;IAC5B,2GAA2G;IAC3G,mBAAmB,EAAE,MAAM,CAAC;IAC5B,kDAAkD;IAClD,QAAQ,EAAE,aAAa,CAAC;CACzB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,uBAAuB,GAAG,OAAO,CAAC,sBAAsB,CAAC,CA2BrG"}

package/dist/auth/protect.js

@@ -0,0 +1,42 @@
+import { requireBearerAuth } from '@modelcontextprotocol/sdk/server/auth/middleware/bearerAuth.js';
+import { mcpAuthMetadataRouter, getOAuthProtectedResourceMetadataUrl, } from '@modelcontextprotocol/sdk/server/auth/router.js';
+import { discoverOAuthMetadata } from './metadata.js';
+/**
+ * Turn an Express app into a spec-compliant MCP OAuth 2.1 **Resource Server** in one call:
+ * serve Protected Resource Metadata (RFC 9728), and return a `requireAuth` middleware that
+ * validates bearer tokens with your verifier and emits a discovery-pointing `WWW-Authenticate`
+ * header on 401. You wire `requireAuth` onto your Streamable-HTTP MCP route.
+ *
+ * @example
+ * const { requireAuth } = await protectMcpServer({
+ *   app, resourceServerUrl: 'https://mcp.example.com',
+ *   issuer: 'https://auth.example.com',
+ *   verifier: jwtVerifier({ issuer: 'https://auth.example.com', audience: 'https://mcp.example.com' }),
+ *   scopesSupported: ['mcp:tools'],
+ * });
+ * app.post('/mcp', requireAuth, mcpHttpHandler);
+ */
+export async function protectMcpServer(opts) {
+    const resourceServerUrl = new URL(opts.resourceServerUrl.toString());
+    const metadata = opts.oauthMetadata ??
+        (opts.issuer ? await discoverOAuthMetadata(opts.issuer, { fetch: opts.fetch }) : undefined);
+    if (!metadata)
+        throw new Error('protectMcpServer: provide either `oauthMetadata` or `issuer`');
+    opts.app.use(mcpAuthMetadataRouter({
+        oauthMetadata: metadata,
+        resourceServerUrl,
+        scopesSupported: opts.scopesSupported,
+        resourceName: opts.resourceName,
+        serviceDocumentationUrl: opts.serviceDocumentationUrl
+            ? new URL(opts.serviceDocumentationUrl.toString())
+            : undefined,
+    }));
+    const resourceMetadataUrl = getOAuthProtectedResourceMetadataUrl(resourceServerUrl);
+    const requireAuth = requireBearerAuth({
+        verifier: opts.verifier,
+        requiredScopes: opts.requiredScopes,
+        resourceMetadataUrl,
+    });
+    return { requireAuth, resourceMetadataUrl, metadata };
+}
+//# sourceMappingURL=protect.js.map

package/dist/auth/protect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protect.js","sourceRoot":"","sources":["../../src/auth/protect.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAE,MAAM,gEAAgE,CAAC;AACnG,OAAO,EACL,qBAAqB,EACrB,oCAAoC,GACrC,MAAM,iDAAiD,CAAC;AAGzD,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAkCtD;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,IAA6B;IAClE,MAAM,iBAAiB,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,iBAAiB,CAAC,QAAQ,EAAE,CAAC,CAAC;IACrE,MAAM,QAAQ,GACZ,IAAI,CAAC,aAAa;QAClB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,qBAAqB,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IAC9F,IAAI,CAAC,QAAQ;QAAE,MAAM,IAAI,KAAK,CAAC,8DAA8D,CAAC,CAAC;IAE/F,IAAI,CAAC,GAAG,CAAC,GAAG,CACV,qBAAqB,CAAC;QACpB,aAAa,EAAE,QAAQ;QACvB,iBAAiB;QACjB,eAAe,EAAE,IAAI,CAAC,eAAe;QACrC,YAAY,EAAE,IAAI,CAAC,YAAY;QAC/B,uBAAuB,EAAE,IAAI,CAAC,uBAAuB;YACnD,CAAC,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,uBAAuB,CAAC,QAAQ,EAAE,CAAC;YAClD,CAAC,CAAC,SAAS;KACd,CAAC,CACH,CAAC;IAEF,MAAM,mBAAmB,GAAG,oCAAoC,CAAC,iBAAiB,CAAC,CAAC;IACpF,MAAM,WAAW,GAAG,iBAAiB,CAAC;QACpC,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,cAAc,EAAE,IAAI,CAAC,cAAc;QACnC,mBAAmB;KACpB,CAAC,CAAC;IAEH,OAAO,EAAE,WAAW,EAAE,mBAAmB,EAAE,QAAQ,EAAE,CAAC;AACxD,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @koduhai/mcp-kit — the two things people get wrong building MCP servers: auth and
+ * versioning, solved.
+ *
+ * This root entry re-exports the dependency-free modules (`upstream`, `versioning`).
+ * The server-side OAuth resource-server helpers live at `@koduhai/mcp-kit/auth` so that
+ * their optional peers (`@modelcontextprotocol/sdk`, `express`, `jose`) are only loaded
+ * when you actually build a remote/HTTP server.
+ */
+export * from './upstream/index.js';
+export * from './versioning/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC"}

package/dist/index.js

@@ -0,0 +1,12 @@
+/**
+ * @koduhai/mcp-kit — the two things people get wrong building MCP servers: auth and
+ * versioning, solved.
+ *
+ * This root entry re-exports the dependency-free modules (`upstream`, `versioning`).
+ * The server-side OAuth resource-server helpers live at `@koduhai/mcp-kit/auth` so that
+ * their optional peers (`@modelcontextprotocol/sdk`, `express`, `jose`) are only loaded
+ * when you actually build a remote/HTTP server.
+ */
+export * from './upstream/index.js';
+export * from './versioning/index.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC"}

package/dist/internal/http.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Shared helpers for the library's own outbound (control-plane) requests:
+ * token endpoints, introspection, and AS metadata discovery. Zero dependencies.
+ */
+/** Default timeout (ms) applied to the library's own outbound requests. */
+export declare const DEFAULT_TIMEOUT_MS = 10000;
+type FetchInput = Parameters<typeof globalThis.fetch>[0];
+/**
+ * `fetch` with a timeout. Aborts the request after `timeoutMs` and reports a
+ * clear error rather than hanging on an unresponsive endpoint. A caller-supplied
+ * `init.signal` is honored too: whichever aborts first wins. Pass a non-positive
+ * or non-finite `timeoutMs` to disable the timeout entirely.
+ */
+export declare function fetchWithTimeout(fetchImpl: typeof globalThis.fetch, input: FetchInput, init?: RequestInit, timeoutMs?: number): Promise<Response>;
+export {};
+//# sourceMappingURL=http.d.ts.map

package/dist/internal/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/internal/http.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,2EAA2E;AAC3E,eAAO,MAAM,kBAAkB,QAAS,CAAC;AAEzC,KAAK,UAAU,GAAG,UAAU,CAAC,OAAO,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;AAEzD;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,SAAS,EAAE,OAAO,UAAU,CAAC,KAAK,EAClC,KAAK,EAAE,UAAU,EACjB,IAAI,GAAE,WAAgB,EACtB,SAAS,GAAE,MAA2B,GACrC,OAAO,CAAC,QAAQ,CAAC,CAWnB"}

package/dist/internal/http.js

@@ -0,0 +1,28 @@
+/**
+ * Shared helpers for the library's own outbound (control-plane) requests:
+ * token endpoints, introspection, and AS metadata discovery. Zero dependencies.
+ */
+/** Default timeout (ms) applied to the library's own outbound requests. */
+export const DEFAULT_TIMEOUT_MS = 10_000;
+/**
+ * `fetch` with a timeout. Aborts the request after `timeoutMs` and reports a
+ * clear error rather than hanging on an unresponsive endpoint. A caller-supplied
+ * `init.signal` is honored too: whichever aborts first wins. Pass a non-positive
+ * or non-finite `timeoutMs` to disable the timeout entirely.
+ */
+export async function fetchWithTimeout(fetchImpl, input, init = {}, timeoutMs = DEFAULT_TIMEOUT_MS) {
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0)
+        return fetchImpl(input, init);
+    const timeout = AbortSignal.timeout(timeoutMs);
+    const signal = init.signal ? AbortSignal.any([init.signal, timeout]) : timeout;
+    try {
+        return await fetchImpl(input, { ...init, signal });
+    }
+    catch (e) {
+        // Distinguish our timeout from a caller-initiated abort or a network error.
+        if (timeout.aborted)
+            throw new Error(`request timed out after ${timeoutMs}ms`, { cause: e });
+        throw e;
+    }
+}
+//# sourceMappingURL=http.js.map

package/dist/internal/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../../src/internal/http.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,2EAA2E;AAC3E,MAAM,CAAC,MAAM,kBAAkB,GAAG,MAAM,CAAC;AAIzC;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,SAAkC,EAClC,KAAiB,EACjB,OAAoB,EAAE,EACtB,YAAoB,kBAAkB;IAEtC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,SAAS,IAAI,CAAC;QAAE,OAAO,SAAS,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IACjF,MAAM,OAAO,GAAG,WAAW,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAC/C,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;IAC/E,IAAI,CAAC;QACH,OAAO,MAAM,SAAS,CAAC,KAAK,EAAE,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;IACrD,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,4EAA4E;QAC5E,IAAI,OAAO,CAAC,OAAO;YAAE,MAAM,IAAI,KAAK,CAAC,2BAA2B,SAAS,IAAI,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC;QAC7F,MAAM,CAAC,CAAC;IACV,CAAC;AACH,CAAC"}

package/dist/upstream/index.d.ts

@@ -0,0 +1,70 @@
+/** A strategy that produces the headers to attach to each upstream request. */
+export interface UpstreamAuth {
+    /** Returns headers to merge into every upstream request. May refresh tokens internally. */
+    headers(): Promise<Record<string, string>>;
+}
+export interface ApiKeyAuthOptions {
+    /** The API key / token value. */
+    key: string;
+    /** Header to send it in. Default `Authorization`. */
+    header?: string;
+    /**
+     * Scheme prefix for the value, e.g. `Bearer` -> `Authorization: Bearer <key>`.
+     * Defaults to `Bearer` when the header is `Authorization`, otherwise no prefix
+     * (e.g. `X-Api-Key: <key>`). Pass `null` to force a raw value.
+     */
+    scheme?: string | null;
+}
+/** Static API-key auth. The most common MCP-server-to-API pattern. */
+export declare function apiKeyAuth(opts: ApiKeyAuthOptions): UpstreamAuth;
+/** A bearer token, or a (possibly async) function that resolves one per call. */
+export type TokenSource = string | (() => string | Promise<string>);
+/** Bearer-token auth. Pass a function when the token rotates or is fetched lazily. */
+export declare function bearerAuth(token: TokenSource, header?: string): UpstreamAuth;
+export interface ClientCredentialsOptions {
+    /** The OAuth token endpoint (e.g. `https://issuer/oauth/token`). */
+    tokenUrl: string;
+    clientId: string;
+    clientSecret: string;
+    /** Space-delimited scopes to request. */
+    scope?: string;
+    /** RFC 8707 audience / resource indicator, if your IdP needs it (e.g. Auth0). */
+    audience?: string;
+    /** Refresh this many seconds before the token actually expires. Default 60. */
+    refreshSkewSeconds?: number;
+    /** Timeout (ms) for the token request. Default 10000. Pass 0 to disable. */
+    timeoutMs?: number;
+    /** Injectable for tests. */
+    fetch?: typeof globalThis.fetch;
+    /** Injectable clock (ms). */
+    now?: () => number;
+}
+/**
+ * OAuth 2.0 client-credentials auth (machine-to-machine). Fetches an access token,
+ * caches it, and transparently refreshes before expiry. Concurrent callers during a
+ * refresh share one in-flight request.
+ */
+export declare function clientCredentialsAuth(opts: ClientCredentialsOptions): UpstreamAuth;
+/** A source of static-ish headers: an object, or a (possibly async) function returning one. */
+export type HeaderSource = Record<string, string> | (() => Record<string, string> | Promise<Record<string, string>>);
+export interface UpstreamFetchOptions {
+    /** Base URL prepended to relative request paths. */
+    baseUrl?: string;
+    /** Auth strategy; its headers are merged into every request. */
+    auth?: UpstreamAuth;
+    /** Extra headers merged into every request (e.g. a versioning header source). */
+    headers?: HeaderSource;
+    /**
+     * Per-request timeout (ms). Off by default so long-running upstream calls are
+     * never cut short unexpectedly; set it to opt in. Pass 0 to disable explicitly.
+     */
+    timeoutMs?: number;
+    /** Injectable for tests. */
+    fetch?: typeof globalThis.fetch;
+}
+/**
+ * Wrap `fetch` so every request carries your auth + standing headers. Returns a
+ * drop-in `fetch` your tool handlers can call with relative paths.
+ */
+export declare function createUpstreamFetch(opts: UpstreamFetchOptions): typeof globalThis.fetch;
+//# sourceMappingURL=index.d.ts.map

package/dist/upstream/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/upstream/index.ts"],"names":[],"mappings":"AAMA,+EAA+E;AAC/E,MAAM,WAAW,YAAY;IAC3B,2FAA2F;IAC3F,OAAO,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CAC5C;AAED,MAAM,WAAW,iBAAiB;IAChC,iCAAiC;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,qDAAqD;IACrD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED,sEAAsE;AACtE,wBAAgB,UAAU,CAAC,IAAI,EAAE,iBAAiB,GAAG,YAAY,CAQhE;AAED,iFAAiF;AACjF,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,CAAC,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;AAEpE,sFAAsF;AACtF,wBAAgB,UAAU,CAAC,KAAK,EAAE,WAAW,EAAE,MAAM,SAAkB,GAAG,YAAY,CAQrF;AAED,MAAM,WAAW,wBAAwB;IACvC,oEAAoE;IACpE,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,yCAAyC;IACzC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iFAAiF;IACjF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,+EAA+E;IAC/E,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4BAA4B;IAC5B,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IAChC,6BAA6B;IAC7B,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,wBAAwB,GAAG,YAAY,CAiElF;AAED,+FAA+F;AAC/F,MAAM,MAAM,YAAY,GACpB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACtB,CAAC,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;AAMrE,MAAM,WAAW,oBAAoB;IACnC,oDAAoD;IACpD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gEAAgE;IAChE,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB,iFAAiF;IACjF,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4BAA4B;IAC5B,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CACjC;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,oBAAoB,GAAG,OAAO,UAAU,CAAC,KAAK,CAmBvF"}

package/dist/upstream/index.js

@@ -0,0 +1,116 @@
+/**
+ * Upstream auth: how your MCP server authenticates to the API/service it wraps.
+ * Zero dependencies, zero transport assumptions. Works with stdio or HTTP servers.
+ */
+import { DEFAULT_TIMEOUT_MS, fetchWithTimeout } from '../internal/http.js';
+/** Static API-key auth. The most common MCP-server-to-API pattern. */
+export function apiKeyAuth(opts) {
+    if (!opts.key)
+        throw new Error('apiKeyAuth: `key` is required');
+    const header = opts.header ?? 'Authorization';
+    const scheme = opts.scheme === undefined ? (header.toLowerCase() === 'authorization' ? 'Bearer' : null) : opts.scheme;
+    const value = scheme ? `${scheme} ${opts.key}` : opts.key;
+    const headers = { [header]: value };
+    return { headers: async () => ({ ...headers }) };
+}
+/** Bearer-token auth. Pass a function when the token rotates or is fetched lazily. */
+export function bearerAuth(token, header = 'Authorization') {
+    return {
+        async headers() {
+            const t = typeof token === 'function' ? await token() : token;
+            if (!t)
+                throw new Error('bearerAuth: token resolved empty');
+            return { [header]: `Bearer ${t}` };
+        },
+    };
+}
+/**
+ * OAuth 2.0 client-credentials auth (machine-to-machine). Fetches an access token,
+ * caches it, and transparently refreshes before expiry. Concurrent callers during a
+ * refresh share one in-flight request.
+ */
+export function clientCredentialsAuth(opts) {
+    if (!opts.tokenUrl || !opts.clientId || !opts.clientSecret) {
+        throw new Error('clientCredentialsAuth: tokenUrl, clientId and clientSecret are required');
+    }
+    const fetchImpl = opts.fetch ?? globalThis.fetch;
+    const now = opts.now ?? (() => Date.now());
+    const skewMs = (opts.refreshSkewSeconds ?? 60) * 1000;
+    let cached = null;
+    let inflight = null;
+    async function fetchToken() {
+        const body = new URLSearchParams({
+            grant_type: 'client_credentials',
+            client_id: opts.clientId,
+            client_secret: opts.clientSecret,
+        });
+        if (opts.scope)
+            body.set('scope', opts.scope);
+        if (opts.audience)
+            body.set('audience', opts.audience);
+        const res = await fetchWithTimeout(fetchImpl, opts.tokenUrl, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/x-www-form-urlencoded', Accept: 'application/json' },
+            body,
+        }, opts.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+        const text = await res.text();
+        let json;
+        try {
+            json = text ? JSON.parse(text) : {};
+        }
+        catch {
+            json = {};
+        }
+        if (!res.ok) {
+            throw new Error(`clientCredentialsAuth: token request failed (${res.status}): ${String(json.error ?? text)}`);
+        }
+        const token = json.access_token;
+        if (typeof token !== 'string' || !token) {
+            throw new Error('clientCredentialsAuth: response missing access_token');
+        }
+        const expiresIn = typeof json.expires_in === 'number' ? json.expires_in : 3600;
+        cached = { token, expiresAtMs: now() + expiresIn * 1000 };
+        return token;
+    }
+    async function getToken() {
+        if (cached && now() < cached.expiresAtMs - skewMs)
+            return cached.token;
+        if (inflight)
+            return inflight;
+        inflight = fetchToken().finally(() => {
+            inflight = null;
+        });
+        return inflight;
+    }
+    return {
+        async headers() {
+            return { Authorization: `Bearer ${await getToken()}` };
+        },
+    };
+}
+async function resolveHeaderSource(src) {
+    return typeof src === 'function' ? src() : src;
+}
+/**
+ * Wrap `fetch` so every request carries your auth + standing headers. Returns a
+ * drop-in `fetch` your tool handlers can call with relative paths.
+ */
+export function createUpstreamFetch(opts) {
+    const fetchImpl = opts.fetch ?? globalThis.fetch;
+    const base = opts.baseUrl?.replace(/\/+$/, '');
+    return (async (input, init = {}) => {
+        const authHeaders = opts.auth ? await opts.auth.headers() : {};
+        const standing = opts.headers ? await resolveHeaderSource(opts.headers) : {};
+        const merged = new Headers(init.headers);
+        for (const [k, v] of Object.entries({ ...standing, ...authHeaders }))
+            merged.set(k, v);
+        let target = input;
+        if (base && typeof input === 'string' && input.startsWith('/'))
+            target = base + input;
+        const req = { ...init, headers: merged };
+        return opts.timeoutMs != null
+            ? fetchWithTimeout(fetchImpl, target, req, opts.timeoutMs)
+            : fetchImpl(target, req);
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/upstream/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/upstream/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAqB3E,sEAAsE;AACtE,MAAM,UAAU,UAAU,CAAC,IAAuB;IAChD,IAAI,CAAC,IAAI,CAAC,GAAG;QAAE,MAAM,IAAI,KAAK,CAAC,+BAA+B,CAAC,CAAC;IAChE,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,eAAe,CAAC;IAC9C,MAAM,MAAM,GACV,IAAI,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,WAAW,EAAE,KAAK,eAAe,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC;IACzG,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC;IAC1D,MAAM,OAAO,GAAG,EAAE,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,CAAC;IACpC,OAAO,EAAE,OAAO,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC,EAAE,GAAG,OAAO,EAAE,CAAC,EAAE,CAAC;AACnD,CAAC;AAKD,sFAAsF;AACtF,MAAM,UAAU,UAAU,CAAC,KAAkB,EAAE,MAAM,GAAG,eAAe;IACrE,OAAO;QACL,KAAK,CAAC,OAAO;YACX,MAAM,CAAC,GAAG,OAAO,KAAK,KAAK,UAAU,CAAC,CAAC,CAAC,MAAM,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC;YAC9D,IAAI,CAAC,CAAC;gBAAE,MAAM,IAAI,KAAK,CAAC,kCAAkC,CAAC,CAAC;YAC5D,OAAO,EAAE,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC,EAAE,EAAE,CAAC;QACrC,CAAC;KACF,CAAC;AACJ,CAAC;AAqBD;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CAAC,IAA8B;IAClE,IAAI,CAAC,IAAI,CAAC,QAAQ,IAAI,CAAC,IAAI,CAAC,QAAQ,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC;QAC3D,MAAM,IAAI,KAAK,CAAC,yEAAyE,CAAC,CAAC;IAC7F,CAAC;IACD,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,IAAI,UAAU,CAAC,KAAK,CAAC;IACjD,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;IAC3C,MAAM,MAAM,GAAG,CAAC,IAAI,CAAC,kBAAkB,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC;IAEtD,IAAI,MAAM,GAAkD,IAAI,CAAC;IACjE,IAAI,QAAQ,GAA2B,IAAI,CAAC;IAE5C,KAAK,UAAU,UAAU;QACvB,MAAM,IAAI,GAAG,IAAI,eAAe,CAAC;YAC/B,UAAU,EAAE,oBAAoB;YAChC,SAAS,EAAE,IAAI,CAAC,QAAQ;YACxB,aAAa,EAAE,IAAI,CAAC,YAAY;SACjC,CAAC,CAAC;QACH,IAAI,IAAI,CAAC,KAAK;YAAE,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;QAC9C,IAAI,IAAI,CAAC,QAAQ;YAAE,IAAI,CAAC,GAAG,CAAC,UAAU,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;QAEvD,MAAM,GAAG,GAAG,MAAM,gBAAgB,CAChC,SAAS,EACT,IAAI,CAAC,QAAQ,EACb;YACE,MAAM,EAAE,MAAM;YACd,OAAO,EAAE,EAAE,cAAc,EAAE,mCAAmC,EAAE,MAAM,EAAE,kBAAkB,EAAE;YAC5F,IAAI;SACL,EACD,IAAI,CAAC,SAAS,IAAI,kBAAkB,CACrC,CAAC;QACF,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;QAC9B,IAAI,IAA6B,CAAC;QAClC,IAAI,CAAC;YACH,IAAI,GAAG,IAAI,CAAC,CAAC,CAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAA6B,CAAC,CAAC,CAAC,EAAE,CAAC;QACnE,CAAC;QAAC,MAAM,CAAC;YACP,IAAI,GAAG,EAAE,CAAC;QACZ,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CACb,gDAAgD,GAAG,CAAC,MAAM,MAAM,MAAM,CAAC,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,EAAE,CAC7F,CAAC;QACJ,CAAC;QACD,MAAM,KAAK,GAAG,IAAI,CAAC,YAAY,CAAC;QAChC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,EAAE,CAAC;YACxC,MAAM,IAAI,KAAK,CAAC,sDAAsD,CAAC,CAAC;QAC1E,CAAC;QACD,MAAM,SAAS,GAAG,OAAO,IAAI,CAAC,UAAU,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC;QAC/E,MAAM,GAAG,EAAE,KAAK,EAAE,WAAW,EAAE,GAAG,EAAE,GAAG,SAAS,GAAG,IAAI,EAAE,CAAC;QAC1D,OAAO,KAAK,CAAC;IACf,CAAC;IAED,KAAK,UAAU,QAAQ;QACrB,IAAI,MAAM,IAAI,GAAG,EAAE,GAAG,MAAM,CAAC,WAAW,GAAG,MAAM;YAAE,OAAO,MAAM,CAAC,KAAK,CAAC;QACvE,IAAI,QAAQ;YAAE,OAAO,QAAQ,CAAC;QAC9B,QAAQ,GAAG,UAAU,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE;YACnC,QAAQ,GAAG,IAAI,CAAC;QAClB,CAAC,CAAC,CAAC;QACH,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,OAAO;QACL,KAAK,CAAC,OAAO;YACX,OAAO,EAAE,aAAa,EAAE,UAAU,MAAM,QAAQ,EAAE,EAAE,EAAE,CAAC;QACzD,CAAC;KACF,CAAC;AACJ,CAAC;AAOD,KAAK,UAAU,mBAAmB,CAAC,GAAiB;IAClD,OAAO,OAAO,GAAG,KAAK,UAAU,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC;AACjD,CAAC;AAkBD;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAA0B;IAC5D,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,IAAI,UAAU,CAAC,KAAK,CAAC;IACjD,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAG/C,OAAO,CAAC,KAAK,EAAE,KAAiB,EAAE,OAAoB,EAAE,EAAE,EAAE;QAC1D,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/D,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,mBAAmB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7E,MAAM,MAAM,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACzC,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,EAAE,GAAG,QAAQ,EAAE,GAAG,WAAW,EAAE,CAAC;YAAE,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QAEvF,IAAI,MAAM,GAAe,KAAK,CAAC;QAC/B,IAAI,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC;YAAE,MAAM,GAAG,IAAI,GAAG,KAAK,CAAC;QAEtF,MAAM,GAAG,GAAG,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;QACzC,OAAO,IAAI,CAAC,SAAS,IAAI,IAAI;YAC3B,CAAC,CAAC,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC;YAC1D,CAAC,CAAC,SAAS,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC7B,CAAC,CAA4B,CAAC;AAChC,CAAC"}

package/dist/versioning/index.d.ts

@@ -0,0 +1,50 @@
+/**
+ * API versioning for MCP servers: pin the upstream API version, send it on every
+ * request, expose it to the agent via a `get_version` tool, and detect drift between
+ * the version your server speaks and the API's current version.
+ */
+export interface VersioningOptions {
+    /** Header used to send the pinned version upstream, e.g. `Api-Version` or `Koduh-Version`. */
+    header: string;
+    /** The version this server pins and sends. */
+    version: string;
+    /** The API's current/latest version, if known. Used to flag drift. */
+    current?: string;
+    /** Versions this server is known-compatible with. If set, `version` must be one of them. */
+    supported?: string[];
+}
+export interface DriftInfo {
+    /** True when the pinned version differs from the API's current version. */
+    behind: boolean;
+    /** True when `supported` is set and the pinned version is not in it. */
+    unsupported: boolean;
+    /** A human-readable warning, or null when everything lines up. */
+    message: string | null;
+}
+export interface Versioning {
+    readonly header: string;
+    readonly version: string;
+    readonly current?: string;
+    readonly supported?: readonly string[];
+    /** Headers to merge into upstream requests (a `HeaderSource` for `createUpstreamFetch`). */
+    headers(): Record<string, string>;
+    /** Evaluate drift between the pinned version and the API's current version. */
+    drift(): DriftInfo;
+}
+/** Build a {@link Versioning} from options. Throws if the pinned version is unsupported. */
+export declare function apiVersioning(opts: VersioningOptions): Versioning;
+/** A transport-agnostic tool definition you can register on any MCP server. */
+export interface ToolDescriptor {
+    name: string;
+    description: string;
+    /** JSON Schema for the tool input. */
+    inputSchema: Record<string, unknown>;
+    handler: (args: Record<string, unknown>) => Promise<unknown> | unknown;
+}
+/**
+ * A `get_version` tool that reports which API version the server speaks. Agents
+ * (and humans debugging) constantly need this; surfacing it removes a class of
+ * "why is the response shaped differently" confusion.
+ */
+export declare function versionTool(v: Versioning, name?: string): ToolDescriptor;
+//# sourceMappingURL=index.d.ts.map

package/dist/versioning/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/versioning/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,WAAW,iBAAiB;IAChC,8FAA8F;IAC9F,MAAM,EAAE,MAAM,CAAC;IACf,8CAA8C;IAC9C,OAAO,EAAE,MAAM,CAAC;IAChB,sEAAsE;IACtE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4FAA4F;IAC5F,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,MAAM,WAAW,SAAS;IACxB,2EAA2E;IAC3E,MAAM,EAAE,OAAO,CAAC;IAChB,wEAAwE;IACxE,WAAW,EAAE,OAAO,CAAC;IACrB,kEAAkE;IAClE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,4FAA4F;IAC5F,OAAO,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,+EAA+E;IAC/E,KAAK,IAAI,SAAS,CAAC;CACpB;AAED,4FAA4F;AAC5F,wBAAgB,aAAa,CAAC,IAAI,EAAE,iBAAiB,GAAG,UAAU,CA6BjE;AAED,+EAA+E;AAC/E,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,sCAAsC;IACtC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;CACxE;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,UAAU,EAAE,IAAI,SAAgB,GAAG,cAAc,CAkB/E"}

package/dist/versioning/index.js

@@ -0,0 +1,60 @@
+/**
+ * API versioning for MCP servers: pin the upstream API version, send it on every
+ * request, expose it to the agent via a `get_version` tool, and detect drift between
+ * the version your server speaks and the API's current version.
+ */
+/** Build a {@link Versioning} from options. Throws if the pinned version is unsupported. */
+export function apiVersioning(opts) {
+    if (!opts.header)
+        throw new Error('apiVersioning: `header` is required');
+    if (!opts.version)
+        throw new Error('apiVersioning: `version` is required');
+    if (opts.supported && !opts.supported.includes(opts.version)) {
+        throw new Error(`apiVersioning: pinned version "${opts.version}" is not in supported [${opts.supported.join(', ')}]`);
+    }
+    const header = opts.header;
+    const value = opts.version;
+    return {
+        header,
+        version: opts.version,
+        current: opts.current,
+        supported: opts.supported,
+        headers: () => ({ [header]: value }),
+        drift() {
+            const behind = opts.current != null && opts.current !== opts.version;
+            const unsupported = opts.supported != null && !opts.supported.includes(opts.version);
+            let message = null;
+            if (unsupported) {
+                message = `pinned API version ${opts.version} is not in the supported set [${(opts.supported ?? []).join(', ')}]`;
+            }
+            else if (behind) {
+                message = `pinned API version ${opts.version} is behind the current API version ${opts.current}`;
+            }
+            return { behind, unsupported, message };
+        },
+    };
+}
+/**
+ * A `get_version` tool that reports which API version the server speaks. Agents
+ * (and humans debugging) constantly need this; surfacing it removes a class of
+ * "why is the response shaped differently" confusion.
+ */
+export function versionTool(v, name = 'get_version') {
+    return {
+        name,
+        description: 'Report the upstream API version this MCP server is pinned to, the header it is sent in, ' +
+            'the current API version (if known), and whether the two have drifted.',
+        inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+        handler: () => {
+            const drift = v.drift();
+            return {
+                version: v.version,
+                header: v.header,
+                current: v.current ?? null,
+                supported: v.supported ?? null,
+                drift: drift.message,
+            };
+        },
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/versioning/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/versioning/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAiCH,4FAA4F;AAC5F,MAAM,UAAU,aAAa,CAAC,IAAuB;IACnD,IAAI,CAAC,IAAI,CAAC,MAAM;QAAE,MAAM,IAAI,KAAK,CAAC,qCAAqC,CAAC,CAAC;IACzE,IAAI,CAAC,IAAI,CAAC,OAAO;QAAE,MAAM,IAAI,KAAK,CAAC,sCAAsC,CAAC,CAAC;IAC3E,IAAI,IAAI,CAAC,SAAS,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QAC7D,MAAM,IAAI,KAAK,CACb,kCAAkC,IAAI,CAAC,OAAO,0BAA0B,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CACrG,CAAC;IACJ,CAAC;IACD,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;IAC3B,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC;IAE3B,OAAO;QACL,MAAM;QACN,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,SAAS,EAAE,IAAI,CAAC,SAAS;QACzB,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,CAAC;QACpC,KAAK;YACH,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,IAAI,IAAI,IAAI,IAAI,CAAC,OAAO,KAAK,IAAI,CAAC,OAAO,CAAC;YACrE,MAAM,WAAW,GAAG,IAAI,CAAC,SAAS,IAAI,IAAI,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YACrF,IAAI,OAAO,GAAkB,IAAI,CAAC;YAClC,IAAI,WAAW,EAAE,CAAC;gBAChB,OAAO,GAAG,sBAAsB,IAAI,CAAC,OAAO,iCAAiC,CAAC,IAAI,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC;YACpH,CAAC;iBAAM,IAAI,MAAM,EAAE,CAAC;gBAClB,OAAO,GAAG,sBAAsB,IAAI,CAAC,OAAO,sCAAsC,IAAI,CAAC,OAAO,EAAE,CAAC;YACnG,CAAC;YACD,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,CAAC;QAC1C,CAAC;KACF,CAAC;AACJ,CAAC;AAWD;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,CAAa,EAAE,IAAI,GAAG,aAAa;IAC7D,OAAO;QACL,IAAI;QACJ,WAAW,EACT,0FAA0F;YAC1F,uEAAuE;QACzE,WAAW,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,EAAE,EAAE,oBAAoB,EAAE,KAAK,EAAE;QAC5E,OAAO,EAAE,GAAG,EAAE;YACZ,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,EAAE,CAAC;YACxB,OAAO;gBACL,OAAO,EAAE,CAAC,CAAC,OAAO;gBAClB,MAAM,EAAE,CAAC,CAAC,MAAM;gBAChB,OAAO,EAAE,CAAC,CAAC,OAAO,IAAI,IAAI;gBAC1B,SAAS,EAAE,CAAC,CAAC,SAAS,IAAI,IAAI;gBAC9B,KAAK,EAAE,KAAK,CAAC,OAAO;aACrB,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC"}

package/package.json

@@ -0,0 +1,97 @@
+{
+  "name": "@koduhai/mcp-kit",
+  "version": "0.1.0",
+  "description": "Auth and versioning for MCP servers, solved. Upstream API auth (API key / bearer / OAuth client-credentials), API versioning with a get_version tool, and a one-call OAuth 2.1 Resource Server (JWKS + introspection verifiers, RFC 9728 metadata) on top of the MCP SDK.",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "mcp-server",
+    "oauth",
+    "oauth2",
+    "authorization",
+    "jwt",
+    "jwks",
+    "token-introspection",
+    "ai-agents",
+    "llm",
+    "versioning"
+  ],
+  "license": "MIT",
+  "author": "Koduhai",
+  "homepage": "https://github.com/koduhai/mcp-kit#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/koduhai/mcp-kit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/koduhai/mcp-kit/issues"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./upstream": {
+      "types": "./dist/upstream/index.d.ts",
+      "import": "./dist/upstream/index.js"
+    },
+    "./versioning": {
+      "types": "./dist/versioning/index.d.ts",
+      "import": "./dist/versioning/index.js"
+    },
+    "./auth": {
+      "types": "./dist/auth/index.d.ts",
+      "import": "./dist/auth/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "@modelcontextprotocol/sdk": ">=1.20.0",
+    "express": "^4.19.0 || ^5.0.0",
+    "jose": "^5.9.0 || ^6.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@modelcontextprotocol/sdk": {
+      "optional": true
+    },
+    "express": {
+      "optional": true
+    },
+    "jose": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@types/express": "^5.0.0",
+    "@types/node": "^25.9.3",
+    "@types/supertest": "^7.2.0",
+    "eslint": "^10.4.1",
+    "eslint-config-prettier": "^10.1.8",
+    "express": "^5.0.0",
+    "jose": "^6.0.0",
+    "prettier": "^3.8.4",
+    "supertest": "^7.0.0",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.61.0",
+    "vitest": "^4.1.8"
+  }
+}