@xsreality/mcp-gateway 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Abhinav Sonkar
+
+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,128 @@
+# mcp-gateway
+
+![CI](https://github.com/xsreality/mcp-gateway/actions/workflows/ci.yml/badge.svg)
+
+A small CLI that exposes a **local STDIO MCP endpoint** and proxies it to a **remote Streamable-HTTP MCP
+server** — handling **OAuth 2.1** (including **Dynamic Client Registration**) on your behalf.
+
+Use it to connect stdio-only MCP clients (Claude Desktop, IDE MCP integrations, anything that launches an
+MCP server as a subprocess) to remote, OAuth-protected MCP servers that those clients can't reach directly.
+
+```
+┌──────────────┐   stdio    ┌──────────────┐   Streamable HTTP + OAuth   ┌──────────────┐
+│ MCP client   │ ─────────▶ │ mcp-gateway  │ ─────────────────────────▶ │ Remote MCP   │
+│ (Claude etc.)│ ◀───────── │              │ ◀───────────────────────── │ server       │
+└──────────────┘            └──────────────┘                            └──────────────┘
+```
+
+The gateway is transparent: it forwards raw MCP messages both ways, so every tool, resource, prompt, and
+notification the remote server offers passes straight through.
+
+## Requirements
+
+- Node.js ≥ 20
+
+## Install
+
+```bash
+npm install -g @xsreality/mcp-gateway
+```
+
+Or run without installing:
+
+```bash
+npx @xsreality/mcp-gateway --url https://mcp.example.com/mcp
+```
+
+### From source
+
+```bash
+git clone https://github.com/xsreality/mcp-gateway.git && cd mcp-gateway
+npm install
+npm run build
+npm link          # puts `mcp-gateway` on your PATH
+```
+
+To remove the global link: `npm rm -g @xsreality/mcp-gateway`.
+
+## Usage
+
+```bash
+mcp-gateway --url https://mcp.example.com/mcp
+```
+
+On first connection to a protected server, the gateway opens your browser to authorize. After you approve,
+tokens are cached locally and reused on subsequent runs (and refreshed automatically when they expire).
+Servers that don't require auth work with no extra flags.
+
+### Use from an MCP client
+
+Point your client at the `mcp-gateway` command:
+
+```json
+{
+  "mcpServers": {
+    "remote": {
+      "command": "npx",
+      "args": ["-y", "@xsreality/mcp-gateway", "--url", "https://mcp.example.com/mcp", "--scope", "read write"]
+    }
+  }
+}
+```
+
+## Options
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--url <url>` | **(required)** Remote Streamable-HTTP MCP server endpoint | `$MCP_GATEWAY_URL` |
+| `--header <k:v>` | Static header forwarded upstream, `"Key: value"` (repeatable) | — |
+| `--scope <scopes>` | OAuth scopes to request | `$MCP_GATEWAY_SCOPE` |
+| `--client-name <name>` | `client_name` used during Dynamic Client Registration | `mcp-gateway` |
+| `--client-id <id>` | Pre-registered OAuth client id (skips DCR) | `$MCP_GATEWAY_CLIENT_ID` |
+| `--client-secret <secret>` | Pre-registered OAuth client secret (confidential client) | `$MCP_GATEWAY_CLIENT_SECRET` |
+| `--no-dcr` | Disable Dynamic Client Registration (requires `--client-id`) | DCR enabled |
+| `--callback-port <port>` | Fixed loopback port for the OAuth redirect | auto (persisted) |
+| `--auth-timeout <seconds>` | How long to wait for you to finish authorizing in the browser | `300` |
+| `--token-store <dir>` | Where tokens + client registration are stored | `~/.mcp-gateway` |
+| `--no-browser` | Print the authorization URL instead of opening a browser (headless) | opens browser |
+| `--log-level <level>` | `trace` `debug` `info` `warn` `error` `silent` (stderr/file only) | `info` |
+| `--log-file <path>` | Write logs to a file instead of stderr | stderr |
+
+Every flag has a `MCP_GATEWAY_*` environment-variable fallback where shown, so it drops cleanly into client
+config blocks.
+
+## Authentication
+
+- **Standards:** OAuth 2.1 authorization-code flow with mandatory PKCE, RFC 9728 protected-resource metadata
+  discovery, RFC 8414 authorization-server metadata, RFC 7591 Dynamic Client Registration, and the RFC 8707
+  `resource` indicator.
+- **No setup needed for DCR servers:** the gateway registers itself automatically and caches the client id.
+- **Servers without DCR:** pass `--client-id` (and `--client-secret` if it's a confidential client) and
+  `--no-dcr`.
+- **Headless / remote machines:** use `--no-browser`; the gateway prints the URL to open, and listens on a
+  loopback port for the redirect. (You'll need to be able to reach that loopback port — e.g. over an SSH
+  tunnel — to complete the flow.)
+
+### Where credentials live
+
+Tokens, the registered client, and the chosen callback port are stored as one JSON file per server (keyed by
+the server's canonical URL) under `--token-store` (default `~/.mcp-gateway`), written with `0600` permissions.
+Delete that directory to force re-authorization.
+
+## Logging
+
+The stdio channel (stdout) carries the MCP protocol, so **all logs go to stderr** (or `--log-file`). If your
+client shows the gateway's diagnostics mixed into its logs, lower `--log-level` (e.g. `warn`) or redirect to
+a file.
+
+## Troubleshooting
+
+- **Browser didn't open** — copy the URL printed on stderr, or run with `--no-browser`.
+- **`authorization timed out`** — you didn't finish within `--auth-timeout`; just reconnect to retry.
+- **Re-authorize from scratch** — delete the server's file under `~/.mcp-gateway` (or the whole directory).
+- **Corporate proxy / extra auth** — forward static headers with repeated `--header "Key: value"`.
+- **Stuck after the server changed its auth** — clear the token store; cached discovery/registration may be stale.
+
+## License
+
+[MIT](LICENSE) © Abhinav Sonkar

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+import { Command, InvalidArgumentError, Option } from "commander";
+import { ConfigError, defaultTokenStoreDir, parseHeaders, parseUrl, } from "./config.js";
+import { createLogger } from "./log.js";
+import { Gateway } from "./gateway.js";
+const LOG_LEVELS = ["trace", "debug", "info", "warn", "error", "silent"];
+function collect(value, previous) {
+    return [...previous, value];
+}
+function intArg(name) {
+    return (value) => {
+        const n = Number(value);
+        if (!Number.isInteger(n) || n < 0) {
+            throw new InvalidArgumentError(`${name} must be a non-negative integer`);
+        }
+        return n;
+    };
+}
+function buildProgram() {
+    return new Command()
+        .name("mcp-gateway")
+        .description("Expose a local STDIO MCP endpoint that proxies a remote Streamable-HTTP MCP server (OAuth 2.1 + DCR).")
+        .requiredOption("--url <url>", "Remote Streamable-HTTP MCP server endpoint", process.env.MCP_GATEWAY_URL)
+        .option("--header <k:v>", 'Static header forwarded upstream, "Key: value" (repeatable)', collect, [])
+        .option("--scope <scopes>", "OAuth scopes to request", process.env.MCP_GATEWAY_SCOPE)
+        .option("--client-name <name>", "client_name used in Dynamic Client Registration", "mcp-gateway")
+        .option("--client-id <id>", "Pre-registered OAuth client id (skips DCR)", process.env.MCP_GATEWAY_CLIENT_ID)
+        .option("--client-secret <secret>", "Pre-registered OAuth client secret", process.env.MCP_GATEWAY_CLIENT_SECRET)
+        .option("--no-dcr", "Disable Dynamic Client Registration")
+        .option("--callback-port <port>", "Fixed loopback OAuth callback port", intArg("--callback-port"))
+        .option("--auth-timeout <seconds>", "Max wait for browser authorization", intArg("--auth-timeout"), 300)
+        .option("--token-store <dir>", "Directory for tokens + client registration", defaultTokenStoreDir())
+        .option("--no-browser", "Print the authorization URL instead of opening a browser")
+        .addOption(new Option("--log-level <level>", "Log verbosity (stderr/file only)")
+        .choices(LOG_LEVELS)
+        .default(process.env.MCP_GATEWAY_LOG_LEVEL ?? "info"))
+        .option("--log-file <path>", "Write logs to a file instead of stderr", process.env.MCP_GATEWAY_LOG_FILE);
+}
+function resolveConfig(opts) {
+    if (!opts.url) {
+        throw new ConfigError("--url is required (or set MCP_GATEWAY_URL)");
+    }
+    if (!LOG_LEVELS.includes(opts.logLevel)) {
+        throw new InvalidArgumentError(`invalid --log-level "${opts.logLevel}"`);
+    }
+    if (!opts.dcr && !opts.clientId) {
+        throw new ConfigError("--no-dcr requires --client-id to be provided");
+    }
+    return {
+        url: parseUrl(opts.url),
+        headers: parseHeaders(opts.header),
+        scope: opts.scope,
+        clientName: opts.clientName,
+        clientId: opts.clientId,
+        clientSecret: opts.clientSecret,
+        dcr: opts.dcr,
+        callbackPort: opts.callbackPort,
+        authTimeoutSec: opts.authTimeout,
+        tokenStoreDir: opts.tokenStore,
+        openBrowser: opts.browser,
+        logLevel: opts.logLevel,
+        logFile: opts.logFile,
+    };
+}
+async function main() {
+    const program = buildProgram();
+    program.parse(process.argv);
+    const opts = program.opts();
+    const config = resolveConfig(opts);
+    const log = createLogger({ level: config.logLevel, file: config.logFile });
+    const gateway = await Gateway.create(config, log);
+    const shutdown = (signal) => {
+        log.info({ signal }, "received signal, shutting down");
+        void gateway.close().finally(() => process.exit(0));
+    };
+    process.on("SIGINT", () => shutdown("SIGINT"));
+    process.on("SIGTERM", () => shutdown("SIGTERM"));
+    try {
+        await gateway.run();
+        process.exit(0);
+    }
+    catch (err) {
+        log.error({ err }, "gateway failed");
+        process.exit(1);
+    }
+}
+main().catch((err) => {
+    // Last-resort handler; logger may not exist yet. stderr only.
+    process.stderr.write(`fatal: ${err instanceof Error ? err.stack : String(err)}\n`);
+    process.exit(1);
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,OAAO,EAAE,oBAAoB,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAClE,OAAO,EAEL,WAAW,EACX,oBAAoB,EACpB,YAAY,EACZ,QAAQ,GACT,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,YAAY,EAAiB,MAAM,UAAU,CAAC;AACvD,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAkBvC,MAAM,UAAU,GAAe,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC;AAErF,SAAS,OAAO,CAAC,KAAa,EAAE,QAAkB;IAChD,OAAO,CAAC,GAAG,QAAQ,EAAE,KAAK,CAAC,CAAC;AAC9B,CAAC;AAED,SAAS,MAAM,CAAC,IAAY;IAC1B,OAAO,CAAC,KAAa,EAAU,EAAE;QAC/B,MAAM,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;QACxB,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;YAClC,MAAM,IAAI,oBAAoB,CAAC,GAAG,IAAI,iCAAiC,CAAC,CAAC;QAC3E,CAAC;QACD,OAAO,CAAC,CAAC;IACX,CAAC,CAAC;AACJ,CAAC;AAED,SAAS,YAAY;IACnB,OAAO,IAAI,OAAO,EAAE;SACjB,IAAI,CAAC,aAAa,CAAC;SACnB,WAAW,CACV,uGAAuG,CACxG;SACA,cAAc,CACb,aAAa,EACb,4CAA4C,EAC5C,OAAO,CAAC,GAAG,CAAC,eAAe,CAC5B;SACA,MAAM,CAAC,gBAAgB,EAAE,6DAA6D,EAAE,OAAO,EAAE,EAAE,CAAC;SACpG,MAAM,CAAC,kBAAkB,EAAE,yBAAyB,EAAE,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC;SACpF,MAAM,CAAC,sBAAsB,EAAE,iDAAiD,EAAE,aAAa,CAAC;SAChG,MAAM,CAAC,kBAAkB,EAAE,4CAA4C,EAAE,OAAO,CAAC,GAAG,CAAC,qBAAqB,CAAC;SAC3G,MAAM,CAAC,0BAA0B,EAAE,oCAAoC,EAAE,OAAO,CAAC,GAAG,CAAC,yBAAyB,CAAC;SAC/G,MAAM,CAAC,UAAU,EAAE,qCAAqC,CAAC;SACzD,MAAM,CAAC,wBAAwB,EAAE,oCAAoC,EAAE,MAAM,CAAC,iBAAiB,CAAC,CAAC;SACjG,MAAM,CAAC,0BAA0B,EAAE,oCAAoC,EAAE,MAAM,CAAC,gBAAgB,CAAC,EAAE,GAAG,CAAC;SACvG,MAAM,CAAC,qBAAqB,EAAE,4CAA4C,EAAE,oBAAoB,EAAE,CAAC;SACnG,MAAM,CAAC,cAAc,EAAE,0DAA0D,CAAC;SAClF,SAAS,CACR,IAAI,MAAM,CAAC,qBAAqB,EAAE,kCAAkC,CAAC;SAClE,OAAO,CAAC,UAAU,CAAC;SACnB,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,qBAAqB,IAAI,MAAM,CAAC,CACxD;SACA,MAAM,CAAC,mBAAmB,EAAE,wCAAwC,EAAE,OAAO,CAAC,GAAG,CAAC,oBAAoB,CAAC,CAAC;AAC7G,CAAC;AAED,SAAS,aAAa,CAAC,IAAgB;IACrC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC;QACd,MAAM,IAAI,WAAW,CAAC,4CAA4C,CAAC,CAAC;IACtE,CAAC;IACD,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAoB,CAAC,EAAE,CAAC;QACpD,MAAM,IAAI,oBAAoB,CAAC,wBAAwB,IAAI,CAAC,QAAQ,GAAG,CAAC,CAAC;IAC3E,CAAC;IACD,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC;QAChC,MAAM,IAAI,WAAW,CAAC,8CAA8C,CAAC,CAAC;IACxE,CAAC;IACD,OAAO;QACL,GAAG,EAAE,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC;QACvB,OAAO,EAAE,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC;QAClC,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,UAAU,EAAE,IAAI,CAAC,UAAU;QAC3B,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,YAAY,EAAE,IAAI,CAAC,YAAY;QAC/B,GAAG,EAAE,IAAI,CAAC,GAAG;QACb,YAAY,EAAE,IAAI,CAAC,YAAY;QAC/B,cAAc,EAAE,IAAI,CAAC,WAAW;QAChC,aAAa,EAAE,IAAI,CAAC,UAAU;QAC9B,WAAW,EAAE,IAAI,CAAC,OAAO;QACzB,QAAQ,EAAE,IAAI,CAAC,QAAoB;QACnC,OAAO,EAAE,IAAI,CAAC,OAAO;KACtB,CAAC;AACJ,CAAC;AAED,KAAK,UAAU,IAAI;IACjB,MAAM,OAAO,GAAG,YAAY,EAAE,CAAC;IAC/B,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,EAAc,CAAC;IAExC,MAAM,MAAM,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;IACnC,MAAM,GAAG,GAAG,YAAY,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,QAAQ,EAAE,IAAI,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC;IAC3E,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAElD,MAAM,QAAQ,GAAG,CAAC,MAAc,EAAE,EAAE;QAClC,GAAG,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,EAAE,gCAAgC,CAAC,CAAC;QACvD,KAAK,OAAO,CAAC,KAAK,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;IACtD,CAAC,CAAC;IACF,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC;IAC/C,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC;IAEjD,IAAI,CAAC;QACH,MAAM,OAAO,CAAC,GAAG,EAAE,CAAC;QACpB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,GAAG,CAAC,KAAK,CAAC,EAAE,GAAG,EAAE,EAAE,gBAAgB,CAAC,CAAC;QACrC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;AACH,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;IAC5B,8DAA8D;IAC9D,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,UAAU,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACnF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/config.d.ts

@@ -0,0 +1,36 @@
+import type { LogLevel } from "./log.js";
+/**
+ * Resolved gateway configuration.
+ */
+export interface Config {
+    /** Remote Streamable-HTTP MCP server endpoint. */
+    url: URL;
+    /** Static headers forwarded on every upstream request (e.g. routing, non-OAuth auth). */
+    headers: Record<string, string>;
+    logLevel: LogLevel;
+    logFile?: string;
+    /** OAuth scopes to request. */
+    scope?: string;
+    /** client_name used in Dynamic Client Registration. */
+    clientName: string;
+    /** Pre-registered client id (skips DCR for the id). */
+    clientId?: string;
+    /** Pre-registered client secret (confidential client). */
+    clientSecret?: string;
+    /** Whether Dynamic Client Registration is permitted. */
+    dcr: boolean;
+    /** Fixed loopback callback port; when undefined a free port is chosen and persisted. */
+    callbackPort?: number;
+    /** Max seconds to wait for the user to complete browser authorization. */
+    authTimeoutSec: number;
+    /** Directory holding per-server tokens + registration. */
+    tokenStoreDir: string;
+    /** Open the system browser automatically (false => print the URL). */
+    openBrowser: boolean;
+}
+export declare class ConfigError extends Error {
+}
+/** Parse repeated `--header "Key: value"` flags into a header map. */
+export declare function parseHeaders(raw: string[]): Record<string, string>;
+export declare function parseUrl(raw: string): URL;
+export declare function defaultTokenStoreDir(): string;

package/dist/config.js

@@ -0,0 +1,38 @@
+import os from "node:os";
+import path from "node:path";
+export class ConfigError extends Error {
+}
+/** Parse repeated `--header "Key: value"` flags into a header map. */
+export function parseHeaders(raw) {
+    const headers = {};
+    for (const entry of raw) {
+        const idx = entry.indexOf(":");
+        if (idx === -1) {
+            throw new ConfigError(`Invalid --header "${entry}", expected "Key: value"`);
+        }
+        const key = entry.slice(0, idx).trim();
+        const value = entry.slice(idx + 1).trim();
+        if (!key) {
+            throw new ConfigError(`Invalid --header "${entry}", empty header name`);
+        }
+        headers[key] = value;
+    }
+    return headers;
+}
+export function parseUrl(raw) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new ConfigError(`Invalid --url "${raw}"`);
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+        throw new ConfigError(`--url must be http(s), got "${url.protocol}"`);
+    }
+    return url;
+}
+export function defaultTokenStoreDir() {
+    return path.join(os.homedir(), ".mcp-gateway");
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAmC7B,MAAM,OAAO,WAAY,SAAQ,KAAK;CAAG;AAEzC,sEAAsE;AACtE,MAAM,UAAU,YAAY,CAAC,GAAa;IACxC,MAAM,OAAO,GAA2B,EAAE,CAAC;IAC3C,KAAK,MAAM,KAAK,IAAI,GAAG,EAAE,CAAC;QACxB,MAAM,GAAG,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAC/B,IAAI,GAAG,KAAK,CAAC,CAAC,EAAE,CAAC;YACf,MAAM,IAAI,WAAW,CAAC,qBAAqB,KAAK,0BAA0B,CAAC,CAAC;QAC9E,CAAC;QACD,MAAM,GAAG,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;QACvC,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QAC1C,IAAI,CAAC,GAAG,EAAE,CAAC;YACT,MAAM,IAAI,WAAW,CAAC,qBAAqB,KAAK,sBAAsB,CAAC,CAAC;QAC1E,CAAC;QACD,OAAO,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;IACvB,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,GAAW;IAClC,IAAI,GAAQ,CAAC;IACb,IAAI,CAAC;QACH,GAAG,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;IACrB,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,WAAW,CAAC,kBAAkB,GAAG,GAAG,CAAC,CAAC;IAClD,CAAC;IACD,IAAI,GAAG,CAAC,QAAQ,KAAK,OAAO,IAAI,GAAG,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;QAC1D,MAAM,IAAI,WAAW,CAAC,+BAA+B,GAAG,CAAC,QAAQ,GAAG,CAAC,CAAC;IACxE,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,MAAM,UAAU,oBAAoB;IAClC,OAAO,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,cAAc,CAAC,CAAC;AACjD,CAAC"}

package/dist/gateway.d.ts

@@ -0,0 +1,38 @@
+import type { Config } from "./config.js";
+import type { Logger } from "./log.js";
+/**
+ * The gateway transparently relays raw JSON-RPC messages between a local stdio
+ * MCP client (downstream) and a remote Streamable-HTTP MCP server (upstream).
+ *
+ * It deliberately does NOT re-declare tools/resources/prompts: by forwarding
+ * messages verbatim it passes through every current and future MCP capability.
+ *
+ * OAuth is lazy and transport-driven: the SDK transport attempts each upstream
+ * request with whatever token it has; on a 401 it runs discovery/DCR and invokes
+ * the provider's `redirectToAuthorization`. The first forwarded send then rejects
+ * with `UnauthorizedError`, at which point the gateway waits for the browser
+ * redirect, finishes the token exchange, and retries the send. Servers that need
+ * no auth never trigger any of this.
+ */
+export declare class Gateway {
+    private readonly config;
+    private readonly log;
+    private readonly provider;
+    private readonly downstream;
+    private readonly upstream;
+    private closing;
+    private onClosed?;
+    private authInFlight?;
+    private constructor();
+    static create(config: Config, log: Logger): Promise<Gateway>;
+    /** Resolves when either side closes the connection. */
+    run(): Promise<void>;
+    private wire;
+    /** Send to upstream, completing the OAuth flow on a 401 and retrying once. */
+    private sendUpstream;
+    /** Wait for the browser redirect and finish token exchange; shared + reusable. */
+    private completeAuthorization;
+    private forward;
+    /** Tears down both transports; idempotent. */
+    close(): Promise<void>;
+}

package/dist/gateway.js

@@ -0,0 +1,134 @@
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { UnauthorizedError } from "@modelcontextprotocol/sdk/client/auth.js";
+import { createUpstreamTransport } from "./upstream.js";
+import { GatewayOAuthProvider } from "./oauth/provider.js";
+/**
+ * The gateway transparently relays raw JSON-RPC messages between a local stdio
+ * MCP client (downstream) and a remote Streamable-HTTP MCP server (upstream).
+ *
+ * It deliberately does NOT re-declare tools/resources/prompts: by forwarding
+ * messages verbatim it passes through every current and future MCP capability.
+ *
+ * OAuth is lazy and transport-driven: the SDK transport attempts each upstream
+ * request with whatever token it has; on a 401 it runs discovery/DCR and invokes
+ * the provider's `redirectToAuthorization`. The first forwarded send then rejects
+ * with `UnauthorizedError`, at which point the gateway waits for the browser
+ * redirect, finishes the token exchange, and retries the send. Servers that need
+ * no auth never trigger any of this.
+ */
+export class Gateway {
+    config;
+    log;
+    provider;
+    downstream;
+    upstream;
+    closing = false;
+    onClosed;
+    authInFlight;
+    constructor(config, log, provider) {
+        this.config = config;
+        this.log = log;
+        this.provider = provider;
+        this.downstream = new StdioServerTransport();
+        this.upstream = createUpstreamTransport(config, provider);
+    }
+    static async create(config, log) {
+        const provider = await GatewayOAuthProvider.create(config, log);
+        return new Gateway(config, log, provider);
+    }
+    /** Resolves when either side closes the connection. */
+    async run() {
+        this.wire();
+        // Bind the loopback callback up front: the SDK reads redirect_uri (needing the
+        // bound port) during DCR, before redirectToAuthorization runs. Kept open for
+        // the session so token-expiry re-auth works without rebinding.
+        await this.provider.callback.listen();
+        await this.upstream.start(); // no network call yet; auth happens on first send
+        await this.downstream.start();
+        this.log.info({ url: this.config.url.href }, "gateway ready (stdio <-> streamable-http)");
+        await new Promise((resolve) => {
+            this.onClosed = resolve;
+        });
+    }
+    wire() {
+        // downstream (local client) -> upstream (remote server): may need auth.
+        this.downstream.onmessage = (msg) => {
+            if (this.closing)
+                return;
+            this.log.debug({ dir: "client→remote", msg }, "relay");
+            void this.sendUpstream(msg).catch((err) => {
+                this.log.error({ err }, "upstream relay failed");
+                void this.close();
+            });
+        };
+        // upstream (remote server) -> downstream (local client).
+        this.upstream.onmessage = (msg) => {
+            this.forward(this.downstream, msg, "remote→client");
+        };
+        this.downstream.onerror = (err) => this.log.error({ err }, "downstream error");
+        this.upstream.onerror = (err) => {
+            // 401s are reported out-of-band here too, but sendUpstream handles them.
+            if (err instanceof UnauthorizedError)
+                this.log.debug({ err }, "upstream auth challenge");
+            else
+                this.log.error({ err }, "upstream error");
+        };
+        this.downstream.onclose = () => {
+            this.log.info("downstream closed");
+            void this.close();
+        };
+        this.upstream.onclose = () => {
+            this.log.info("upstream closed");
+            void this.close();
+        };
+    }
+    /** Send to upstream, completing the OAuth flow on a 401 and retrying once. */
+    async sendUpstream(msg) {
+        try {
+            await this.upstream.send(msg);
+        }
+        catch (err) {
+            if (!(err instanceof UnauthorizedError))
+                throw err;
+            await this.completeAuthorization();
+            await this.upstream.send(msg);
+        }
+    }
+    /** Wait for the browser redirect and finish token exchange; shared + reusable. */
+    completeAuthorization() {
+        if (!this.authInFlight) {
+            this.authInFlight = (async () => {
+                this.log.info("authorization required; waiting for browser approval");
+                const code = await this.provider.callback.waitForCode(this.config.authTimeoutSec * 1000);
+                await this.upstream.finishAuth(code);
+                this.log.info("authorization complete");
+            })().finally(() => {
+                this.authInFlight = undefined; // allow re-auth on later token expiry
+            });
+        }
+        return this.authInFlight;
+    }
+    forward(to, msg, dir) {
+        if (this.closing)
+            return;
+        this.log.debug({ dir, msg }, "relay");
+        void to.send(msg).catch((err) => {
+            this.log.error({ err, dir }, "relay send failed");
+            void this.close();
+        });
+    }
+    /** Tears down both transports; idempotent. */
+    async close() {
+        if (this.closing)
+            return;
+        this.closing = true;
+        this.log.info("shutting down gateway");
+        await Promise.allSettled([
+            this.downstream.close(),
+            this.upstream.close(),
+            this.provider.callback.close(),
+        ]);
+        this.onClosed?.();
+    }
+}
+//# sourceMappingURL=gateway.js.map

package/dist/gateway.js.map

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

package/dist/log.d.ts

@@ -0,0 +1,14 @@
+import pino from "pino";
+/**
+ * Logger writes to **stderr only**. stdout is reserved for the MCP JSON-RPC
+ * stream on the stdio transport — writing anything else there corrupts the
+ * protocol. Never use console.log in this project.
+ */
+export type LogLevel = "trace" | "debug" | "info" | "warn" | "error" | "silent";
+export interface LogOptions {
+    level?: LogLevel;
+    /** Optional file path. When set, logs go to the file instead of stderr. */
+    file?: string;
+}
+export declare function createLogger(opts?: LogOptions): pino.Logger;
+export type Logger = pino.Logger;

package/dist/log.js

@@ -0,0 +1,9 @@
+import pino from "pino";
+export function createLogger(opts = {}) {
+    const level = opts.level ?? "info";
+    const destination = opts.file
+        ? pino.destination({ dest: opts.file, sync: false })
+        : pino.destination(2); // fd 2 = stderr
+    return pino({ level }, destination);
+}
+//# sourceMappingURL=log.js.map

package/dist/log.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"log.js","sourceRoot":"","sources":["../src/log.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,MAAM,CAAC;AAexB,MAAM,UAAU,YAAY,CAAC,OAAmB,EAAE;IAChD,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,MAAM,CAAC;IACnC,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI;QAC3B,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;QACpD,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,gBAAgB;IACzC,OAAO,IAAI,CAAC,EAAE,KAAK,EAAE,EAAE,WAAW,CAAC,CAAC;AACtC,CAAC"}

package/dist/oauth/callback.d.ts

@@ -0,0 +1,28 @@
+import type { Logger } from "../log.js";
+/**
+ * Loopback HTTP server (127.0.0.1 only) that captures the OAuth authorization
+ * code redirect. Bound to a fixed port so the registered redirect_uri stays
+ * byte-identical across runs.
+ */
+export declare class CallbackServer {
+    private readonly preferredPort;
+    private readonly expectedState;
+    private readonly log;
+    private server?;
+    private pending?;
+    private boundPort?;
+    constructor(preferredPort: number | undefined, expectedState: () => string | undefined, log: Logger);
+    /** Begin listening. Resolves to the actual bound port. */
+    listen(): Promise<number>;
+    get port(): number;
+    get redirectUrl(): string;
+    /** Resolves with the authorization code once the browser redirect arrives. */
+    waitForCode(timeoutMs: number): Promise<string>;
+    /** Settle the pending waitForCode exactly once, clearing its timeout. */
+    private settle;
+    private handle;
+    private fail;
+    close(): Promise<void>;
+}
+/** Open a URL in the system browser without an extra dependency. */
+export declare function openBrowser(url: string, log: Logger): void;

package/dist/oauth/callback.js

@@ -0,0 +1,131 @@
+import http from "node:http";
+import { spawn } from "node:child_process";
+const CALLBACK_PATH = "/callback";
+const SUCCESS_HTML = "<!doctype html><meta charset=utf-8><title>Authorized</title>" +
+    "<body style='font-family:system-ui;padding:3rem;text-align:center'>" +
+    "<h2>Authorization complete</h2><p>You can close this tab and return to the terminal.</p>";
+/**
+ * Loopback HTTP server (127.0.0.1 only) that captures the OAuth authorization
+ * code redirect. Bound to a fixed port so the registered redirect_uri stays
+ * byte-identical across runs.
+ */
+export class CallbackServer {
+    preferredPort;
+    expectedState;
+    log;
+    server;
+    pending;
+    boundPort;
+    constructor(preferredPort, expectedState, log) {
+        this.preferredPort = preferredPort;
+        this.expectedState = expectedState;
+        this.log = log;
+    }
+    /** Begin listening. Resolves to the actual bound port. */
+    async listen() {
+        if (this.server)
+            return this.boundPort;
+        const server = http.createServer((req, res) => this.handle(req, res));
+        // Prefer an explicit/stored port; otherwise reuse the port from a previous
+        // bind in this process so the registered redirect_uri stays stable.
+        const target = this.preferredPort ?? this.boundPort ?? 0;
+        await new Promise((resolve, reject) => {
+            server.once("error", reject);
+            server.listen(target, "127.0.0.1", resolve);
+        });
+        this.server = server;
+        this.boundPort = server.address().port;
+        this.log.debug({ port: this.boundPort }, "callback server listening");
+        return this.boundPort;
+    }
+    get port() {
+        if (this.boundPort === undefined)
+            throw new Error("callback server not listening");
+        return this.boundPort;
+    }
+    get redirectUrl() {
+        return `http://127.0.0.1:${this.port}${CALLBACK_PATH}`;
+    }
+    /** Resolves with the authorization code once the browser redirect arrives. */
+    waitForCode(timeoutMs) {
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.settle(new Error(`timed out after ${Math.round(timeoutMs / 1000)}s waiting for authorization`));
+            }, timeoutMs);
+            timer.unref();
+            this.pending = { resolve, reject, timer };
+        });
+    }
+    /** Settle the pending waitForCode exactly once, clearing its timeout. */
+    settle(result) {
+        const p = this.pending;
+        if (!p)
+            return;
+        this.pending = undefined;
+        clearTimeout(p.timer);
+        if (result instanceof Error)
+            p.reject(result);
+        else
+            p.resolve(result.code);
+    }
+    handle(req, res) {
+        const url = new URL(req.url ?? "/", `http://127.0.0.1:${this.boundPort}`);
+        if (url.pathname !== CALLBACK_PATH) {
+            res.writeHead(404).end();
+            return;
+        }
+        const error = url.searchParams.get("error");
+        const code = url.searchParams.get("code");
+        const state = url.searchParams.get("state");
+        const expected = this.expectedState();
+        if (error) {
+            const desc = url.searchParams.get("error_description") ?? "";
+            this.fail(res, 400, `Authorization failed: ${error} ${desc}`.trim());
+            return;
+        }
+        if (expected !== undefined && state !== expected) {
+            this.fail(res, 400, "State mismatch — possible CSRF, request rejected.");
+            return;
+        }
+        if (!code) {
+            this.fail(res, 400, "Missing authorization code.");
+            return;
+        }
+        res.writeHead(200, { "content-type": "text/html" }).end(SUCCESS_HTML);
+        this.settle({ code });
+    }
+    fail(res, status, message) {
+        res.writeHead(status, { "content-type": "text/plain" }).end(message);
+        this.settle(new Error(message));
+    }
+    async close() {
+        // Don't leave a waitForCode() awaiter hanging if we shut down mid-flow.
+        this.settle(new Error("callback server closed before authorization completed"));
+        if (!this.server)
+            return;
+        await new Promise((resolve) => this.server.close(() => resolve()));
+        this.server = undefined;
+    }
+}
+/** Open a URL in the system browser without an extra dependency. */
+export function openBrowser(url, log) {
+    const platform = process.platform;
+    const isWin = platform === "win32";
+    const cmd = platform === "darwin" ? "open" : isWin ? "cmd" : "xdg-open";
+    // On Windows the URL must be quoted: cmd.exe treats `&` (always present in
+    // OAuth query strings) as a command separator, which would truncate the URL.
+    const args = isWin ? ["/c", "start", '""', `"${url}"`] : [url];
+    try {
+        const child = spawn(cmd, args, {
+            stdio: "ignore",
+            detached: true,
+            windowsVerbatimArguments: isWin,
+        });
+        child.on("error", (err) => log.warn({ err }, "failed to launch browser"));
+        child.unref();
+    }
+    catch (err) {
+        log.warn({ err }, "failed to launch browser");
+    }
+}
+//# sourceMappingURL=callback.js.map

package/dist/oauth/callback.js.map

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

package/dist/oauth/canonical.d.ts

@@ -0,0 +1,8 @@
+/**
+ * RFC 8707 canonical resource URI for an MCP server.
+ *
+ * Lowercase scheme + host, no fragment, default ports dropped, and no trailing
+ * slash on the root path. Used both as the `resource` indicator value and as the
+ * key for per-server credential storage.
+ */
+export declare function canonicalResourceUri(url: URL): string;

package/dist/oauth/canonical.js

@@ -0,0 +1,27 @@
+/**
+ * RFC 8707 canonical resource URI for an MCP server.
+ *
+ * Lowercase scheme + host, no fragment, default ports dropped, and no trailing
+ * slash on the root path. Used both as the `resource` indicator value and as the
+ * key for per-server credential storage.
+ */
+export function canonicalResourceUri(url) {
+    const u = new URL(url.href);
+    u.hash = "";
+    u.username = "";
+    u.password = "";
+    u.protocol = u.protocol.toLowerCase();
+    u.hostname = u.hostname.toLowerCase();
+    // Drop default ports.
+    if ((u.protocol === "http:" && u.port === "80") ||
+        (u.protocol === "https:" && u.port === "443")) {
+        u.port = "";
+    }
+    let out = u.toString();
+    // Drop a lone trailing slash on the root (but keep meaningful paths intact).
+    if (u.pathname === "/" && !u.search) {
+        out = out.replace(/\/$/, "");
+    }
+    return out;
+}
+//# sourceMappingURL=canonical.js.map

package/dist/oauth/canonical.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical.js","sourceRoot":"","sources":["../../src/oauth/canonical.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAAC,GAAQ;IAC3C,MAAM,CAAC,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC,CAAC,IAAI,GAAG,EAAE,CAAC;IACZ,CAAC,CAAC,QAAQ,GAAG,EAAE,CAAC;IAChB,CAAC,CAAC,QAAQ,GAAG,EAAE,CAAC;IAChB,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAC;IACtC,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAC;IACtC,sBAAsB;IACtB,IACE,CAAC,CAAC,CAAC,QAAQ,KAAK,OAAO,IAAI,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC;QAC3C,CAAC,CAAC,CAAC,QAAQ,KAAK,QAAQ,IAAI,CAAC,CAAC,IAAI,KAAK,KAAK,CAAC,EAC7C,CAAC;QACD,CAAC,CAAC,IAAI,GAAG,EAAE,CAAC;IACd,CAAC;IACD,IAAI,GAAG,GAAG,CAAC,CAAC,QAAQ,EAAE,CAAC;IACvB,6EAA6E;IAC7E,IAAI,CAAC,CAAC,QAAQ,KAAK,GAAG,IAAI,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;QACpC,GAAG,GAAG,GAAG,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IAC/B,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/oauth/provider.d.ts

@@ -0,0 +1,32 @@
+import type { OAuthClientProvider } from "@modelcontextprotocol/sdk/client/auth.js";
+import type { OAuthClientInformationFull, OAuthClientMetadata, OAuthTokens } from "@modelcontextprotocol/sdk/shared/auth.js";
+import type { Config } from "../config.js";
+import type { Logger } from "../log.js";
+import { CallbackServer } from "./callback.js";
+/**
+ * OAuth 2.1 client provider for one remote MCP server. The SDK's `auth()` helper
+ * drives discovery (RFC 9728 → RFC 8414), Dynamic Client Registration (RFC 7591),
+ * PKCE, and token exchange; this class supplies persistence, the redirect URL,
+ * and the browser hand-off. RFC 8707 `resource` binding is handled by the SDK.
+ */
+export declare class GatewayOAuthProvider implements OAuthClientProvider {
+    private readonly config;
+    private readonly store;
+    readonly callback: CallbackServer;
+    private readonly log;
+    private currentState?;
+    private constructor();
+    /** Async factory: loads persisted state and binds the loopback callback port. */
+    static create(config: Config, log: Logger): Promise<GatewayOAuthProvider>;
+    get redirectUrl(): string;
+    get clientMetadata(): OAuthClientMetadata;
+    state(): string;
+    clientInformation(): Promise<OAuthClientInformationFull | undefined>;
+    saveClientInformation(info: OAuthClientInformationFull): Promise<void>;
+    tokens(): Promise<OAuthTokens | undefined>;
+    saveTokens(tokens: OAuthTokens): Promise<void>;
+    saveCodeVerifier(codeVerifier: string): Promise<void>;
+    codeVerifier(): Promise<string>;
+    redirectToAuthorization(authorizationUrl: URL): Promise<void>;
+    invalidateCredentials(scope: "all" | "client" | "tokens" | "verifier" | "discovery"): Promise<void>;
+}

package/dist/oauth/provider.js

@@ -0,0 +1,105 @@
+import { randomUUID } from "node:crypto";
+import { canonicalResourceUri } from "./canonical.js";
+import { CallbackServer, openBrowser } from "./callback.js";
+import { AuthStore } from "./store.js";
+/**
+ * OAuth 2.1 client provider for one remote MCP server. The SDK's `auth()` helper
+ * drives discovery (RFC 9728 → RFC 8414), Dynamic Client Registration (RFC 7591),
+ * PKCE, and token exchange; this class supplies persistence, the redirect URL,
+ * and the browser hand-off. RFC 8707 `resource` binding is handled by the SDK.
+ */
+export class GatewayOAuthProvider {
+    config;
+    store;
+    callback;
+    log;
+    currentState;
+    constructor(config, store, callback, log) {
+        this.config = config;
+        this.store = store;
+        this.callback = callback;
+        this.log = log;
+    }
+    /** Async factory: loads persisted state and binds the loopback callback port. */
+    static async create(config, log) {
+        const canonical = canonicalResourceUri(config.url);
+        const store = new AuthStore(config.tokenStoreDir, canonical, log);
+        const stored = await store.load();
+        const port = config.callbackPort ?? stored.redirectPort;
+        let provider;
+        const callback = new CallbackServer(port, () => provider.currentState, log);
+        provider = new GatewayOAuthProvider(config, store, callback, log);
+        return provider;
+    }
+    get redirectUrl() {
+        return this.callback.redirectUrl;
+    }
+    get clientMetadata() {
+        return {
+            redirect_uris: [this.callback.redirectUrl],
+            token_endpoint_auth_method: this.config.clientSecret ? "client_secret_post" : "none",
+            grant_types: ["authorization_code", "refresh_token"],
+            response_types: ["code"],
+            client_name: this.config.clientName,
+            ...(this.config.scope ? { scope: this.config.scope } : {}),
+        };
+    }
+    state() {
+        this.currentState = randomUUID();
+        return this.currentState;
+    }
+    async clientInformation() {
+        // Statically configured client takes precedence over any DCR result.
+        if (this.config.clientId) {
+            return {
+                client_id: this.config.clientId,
+                ...(this.config.clientSecret ? { client_secret: this.config.clientSecret } : {}),
+                ...this.clientMetadata,
+            };
+        }
+        return (await this.store.load()).clientInformation;
+    }
+    async saveClientInformation(info) {
+        if (!this.config.dcr) {
+            throw new Error("Dynamic Client Registration is disabled (--no-dcr) and no --client-id was provided");
+        }
+        this.log.info({ clientId: info.client_id }, "registered OAuth client via DCR");
+        await this.store.patch({ clientInformation: info, redirectPort: this.callback.port });
+    }
+    async tokens() {
+        return (await this.store.load()).tokens;
+    }
+    async saveTokens(tokens) {
+        this.log.info("stored OAuth tokens");
+        await this.store.patch({ tokens });
+    }
+    async saveCodeVerifier(codeVerifier) {
+        await this.store.patch({ codeVerifier });
+    }
+    async codeVerifier() {
+        const verifier = (await this.store.load()).codeVerifier;
+        if (!verifier)
+            throw new Error("missing PKCE code verifier");
+        return verifier;
+    }
+    async redirectToAuthorization(authorizationUrl) {
+        // Start the loopback listener before launching the browser so the redirect
+        // can never arrive before we are listening.
+        await this.callback.listen();
+        if (this.config.openBrowser) {
+            this.log.info("opening browser for authorization");
+            openBrowser(authorizationUrl.href, this.log);
+            // stderr so the local client's stdout protocol stream stays clean.
+            process.stderr.write(`\nIf your browser did not open, visit:\n${authorizationUrl.href}\n\n`);
+        }
+        else {
+            process.stderr.write(`\nAuthorize this gateway by visiting:\n${authorizationUrl.href}\n\n`);
+        }
+    }
+    async invalidateCredentials(scope) {
+        if (scope === "discovery")
+            return; // discovery state isn't persisted here
+        await this.store.clear(scope);
+    }
+}
+//# sourceMappingURL=provider.js.map

package/dist/oauth/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../../src/oauth/provider.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AASzC,OAAO,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AACtD,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5D,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEvC;;;;;GAKG;AACH,MAAM,OAAO,oBAAoB;IAIZ;IACA;IACR;IACQ;IANX,YAAY,CAAU;IAE9B,YACmB,MAAc,EACd,KAAgB,EACxB,QAAwB,EAChB,GAAW;QAHX,WAAM,GAAN,MAAM,CAAQ;QACd,UAAK,GAAL,KAAK,CAAW;QACxB,aAAQ,GAAR,QAAQ,CAAgB;QAChB,QAAG,GAAH,GAAG,CAAQ;IAC3B,CAAC;IAEJ,iFAAiF;IACjF,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,MAAc,EAAE,GAAW;QAC7C,MAAM,SAAS,GAAG,oBAAoB,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACnD,MAAM,KAAK,GAAG,IAAI,SAAS,CAAC,MAAM,CAAC,aAAa,EAAE,SAAS,EAAE,GAAG,CAAC,CAAC;QAClE,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,IAAI,EAAE,CAAC;QAClC,MAAM,IAAI,GAAG,MAAM,CAAC,YAAY,IAAI,MAAM,CAAC,YAAY,CAAC;QACxD,IAAI,QAA8B,CAAC;QACnC,MAAM,QAAQ,GAAG,IAAI,cAAc,CAAC,IAAI,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,YAAY,EAAE,GAAG,CAAC,CAAC;QAC5E,QAAQ,GAAG,IAAI,oBAAoB,CAAC,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,CAAC,CAAC;QAClE,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,IAAI,WAAW;QACb,OAAO,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC;IACnC,CAAC;IAED,IAAI,cAAc;QAChB,OAAO;YACL,aAAa,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC;YAC1C,0BAA0B,EAAE,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC,oBAAoB,CAAC,CAAC,CAAC,MAAM;YACpF,WAAW,EAAE,CAAC,oBAAoB,EAAE,eAAe,CAAC;YACpD,cAAc,EAAE,CAAC,MAAM,CAAC;YACxB,WAAW,EAAE,IAAI,CAAC,MAAM,CAAC,UAAU;YACnC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC3D,CAAC;IACJ,CAAC;IAED,KAAK;QACH,IAAI,CAAC,YAAY,GAAG,UAAU,EAAE,CAAC;QACjC,OAAO,IAAI,CAAC,YAAY,CAAC;IAC3B,CAAC;IAED,KAAK,CAAC,iBAAiB;QACrB,qEAAqE;QACrE,IAAI,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC;YACzB,OAAO;gBACL,SAAS,EAAE,IAAI,CAAC,MAAM,CAAC,QAAQ;gBAC/B,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,IAAI,CAAC,MAAM,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAChF,GAAG,IAAI,CAAC,cAAc;aACvB,CAAC;QACJ,CAAC;QACD,OAAO,CAAC,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,iBAAiB,CAAC;IACrD,CAAC;IAED,KAAK,CAAC,qBAAqB,CAAC,IAAgC;QAC1D,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC;YACrB,MAAM,IAAI,KAAK,CAAC,oFAAoF,CAAC,CAAC;QACxG,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,SAAS,EAAE,EAAE,iCAAiC,CAAC,CAAC;QAC/E,MAAM,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,iBAAiB,EAAE,IAAI,EAAE,YAAY,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IACxF,CAAC;IAED,KAAK,CAAC,MAAM;QACV,OAAO,CAAC,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC;IAC1C,CAAC;IAED,KAAK,CAAC,UAAU,CAAC,MAAmB;QAClC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,qBAAqB,CAAC,CAAC;QACrC,MAAM,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC;IACrC,CAAC;IAED,KAAK,CAAC,gBAAgB,CAAC,YAAoB;QACzC,MAAM,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,YAAY,EAAE,CAAC,CAAC;IAC3C,CAAC;IAED,KAAK,CAAC,YAAY;QAChB,MAAM,QAAQ,GAAG,CAAC,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,YAAY,CAAC;QACxD,IAAI,CAAC,QAAQ;YAAE,MAAM,IAAI,KAAK,CAAC,4BAA4B,CAAC,CAAC;QAC7D,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,KAAK,CAAC,uBAAuB,CAAC,gBAAqB;QACjD,2EAA2E;QAC3E,4CAA4C;QAC5C,MAAM,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC;QAC7B,IAAI,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC;YAC5B,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,mCAAmC,CAAC,CAAC;YACnD,WAAW,CAAC,gBAAgB,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC;YAC7C,mEAAmE;YACnE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,2CAA2C,gBAAgB,CAAC,IAAI,MAAM,CAAC,CAAC;QAC/F,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,0CAA0C,gBAAgB,CAAC,IAAI,MAAM,CAAC,CAAC;QAC9F,CAAC;IACH,CAAC;IAED,KAAK,CAAC,qBAAqB,CAAC,KAA6D;QACvF,IAAI,KAAK,KAAK,WAAW;YAAE,OAAO,CAAC,uCAAuC;QAC1E,MAAM,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAChC,CAAC;CACF"}

package/dist/oauth/store.d.ts

@@ -0,0 +1,35 @@
+import type { OAuthClientInformationFull, OAuthTokens } from "@modelcontextprotocol/sdk/shared/auth.js";
+import type { Logger } from "../log.js";
+/** Everything persisted for one remote MCP server, keyed by its canonical URI. */
+export interface StoredAuth {
+    /** DCR result (or full info for a statically configured client). */
+    clientInformation?: OAuthClientInformationFull;
+    tokens?: OAuthTokens;
+    /** PKCE verifier persisted between redirect and token exchange. */
+    codeVerifier?: string;
+    /**
+     * Loopback callback port used for the registered redirect_uri. Persisted so
+     * the redirect_uri stays byte-identical across runs (exact-match requirement).
+     */
+    redirectPort?: number;
+}
+/**
+ * File-backed credential store. One JSON file per server under a 0700 directory,
+ * each written 0600. Tolerates a missing/corrupt file by treating it as empty.
+ */
+export declare class AuthStore {
+    private readonly dir;
+    private readonly log;
+    private readonly file;
+    private cache;
+    /** Serializes read-modify-write cycles so concurrent patches don't lose updates. */
+    private writeChain;
+    constructor(dir: string, canonicalUri: string, log: Logger);
+    load(): Promise<StoredAuth>;
+    private save;
+    /** Run a read-modify-write cycle serialized against all other mutations. */
+    private mutate;
+    patch(update: Partial<StoredAuth>): Promise<void>;
+    /** Remove credentials by scope; used by invalidateCredentials. */
+    clear(scope: "all" | "client" | "tokens" | "verifier"): Promise<void>;
+}

package/dist/oauth/store.js

@@ -0,0 +1,68 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+/**
+ * File-backed credential store. One JSON file per server under a 0700 directory,
+ * each written 0600. Tolerates a missing/corrupt file by treating it as empty.
+ */
+export class AuthStore {
+    dir;
+    log;
+    file;
+    cache;
+    /** Serializes read-modify-write cycles so concurrent patches don't lose updates. */
+    writeChain = Promise.resolve();
+    constructor(dir, canonicalUri, log) {
+        this.dir = dir;
+        this.log = log;
+        const key = createHash("sha256").update(canonicalUri).digest("hex").slice(0, 32);
+        this.file = path.join(dir, `${key}.json`);
+    }
+    async load() {
+        if (this.cache)
+            return this.cache;
+        try {
+            const raw = await fs.readFile(this.file, "utf8");
+            this.cache = JSON.parse(raw);
+        }
+        catch (err) {
+            if (err.code !== "ENOENT") {
+                this.log.warn({ err, file: this.file }, "ignoring unreadable auth store file");
+            }
+            this.cache = {};
+        }
+        return this.cache;
+    }
+    async save() {
+        await fs.mkdir(this.dir, { recursive: true, mode: 0o700 });
+        const tmp = `${this.file}.tmp`;
+        await fs.writeFile(tmp, JSON.stringify(this.cache ?? {}, null, 2), { mode: 0o600 });
+        await fs.rename(tmp, this.file);
+    }
+    /** Run a read-modify-write cycle serialized against all other mutations. */
+    mutate(fn) {
+        const next = this.writeChain.then(async () => {
+            this.cache = fn(await this.load());
+            await this.save();
+        });
+        // Keep the chain alive even if one mutation rejects.
+        this.writeChain = next.catch(() => { });
+        return next;
+    }
+    async patch(update) {
+        return this.mutate((current) => ({ ...current, ...update }));
+    }
+    /** Remove credentials by scope; used by invalidateCredentials. */
+    async clear(scope) {
+        return this.mutate((current) => {
+            if (scope === "all")
+                return {};
+            if (scope === "client")
+                return { ...current, clientInformation: undefined };
+            if (scope === "tokens")
+                return { ...current, tokens: undefined };
+            return { ...current, codeVerifier: undefined };
+        });
+    }
+}
+//# sourceMappingURL=store.js.map

package/dist/oauth/store.js.map

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

package/dist/upstream.d.ts

@@ -0,0 +1,9 @@
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import type { OAuthClientProvider } from "@modelcontextprotocol/sdk/client/auth.js";
+import type { Config } from "./config.js";
+/**
+ * Builds the upstream Streamable-HTTP client transport that talks to the remote
+ * MCP server. When an `authProvider` is supplied, the SDK drives OAuth discovery,
+ * DCR, token refresh, and the RFC 8707 resource parameter automatically.
+ */
+export declare function createUpstreamTransport(config: Config, authProvider?: OAuthClientProvider): StreamableHTTPClientTransport;

package/dist/upstream.js

@@ -0,0 +1,15 @@
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+/**
+ * Builds the upstream Streamable-HTTP client transport that talks to the remote
+ * MCP server. When an `authProvider` is supplied, the SDK drives OAuth discovery,
+ * DCR, token refresh, and the RFC 8707 resource parameter automatically.
+ */
+export function createUpstreamTransport(config, authProvider) {
+    return new StreamableHTTPClientTransport(config.url, {
+        authProvider,
+        requestInit: {
+            headers: config.headers,
+        },
+    });
+}
+//# sourceMappingURL=upstream.js.map

package/dist/upstream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"upstream.js","sourceRoot":"","sources":["../src/upstream.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,6BAA6B,EAAE,MAAM,oDAAoD,CAAC;AAInG;;;;GAIG;AACH,MAAM,UAAU,uBAAuB,CACrC,MAAc,EACd,YAAkC;IAElC,OAAO,IAAI,6BAA6B,CAAC,MAAM,CAAC,GAAG,EAAE;QACnD,YAAY;QACZ,WAAW,EAAE;YACX,OAAO,EAAE,MAAM,CAAC,OAAO;SACxB;KACF,CAAC,CAAC;AACL,CAAC"}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@xsreality/mcp-gateway",
+  "version": "0.1.0",
+  "description": "CLI gateway that exposes a local STDIO MCP endpoint and proxies a remote Streamable-HTTP MCP server (OAuth 2.1 + DCR).",
+  "type": "module",
+  "license": "MIT",
+  "author": "Abhinav Sonkar",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xsreality/mcp-gateway.git"
+  },
+  "homepage": "https://github.com/xsreality/mcp-gateway#readme",
+  "bugs": {
+    "url": "https://github.com/xsreality/mcp-gateway/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "gateway",
+    "proxy",
+    "stdio",
+    "streamable-http",
+    "oauth",
+    "oauth2",
+    "dynamic-client-registration",
+    "cli"
+  ],
+  "bin": {
+    "mcp-gateway": "dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "prepare": "npm run build",
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsc -p tsconfig.json --watch",
+    "start": "node dist/cli.js",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "npm run build && node test/manual-relay.mjs && node test/manual-oauth.mjs"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "commander": "^13.0.0",
+    "pino": "^9.6.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.0"
+  }
+}