@thuyphuocthinh/mcp-auth-proxy 0.0.0-stage → 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thuy Phuoc Thinh
+
+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

@@ -1,3 +1,97 @@
-# Temporary Holding Version
+# @thuyphuocthinh/mcp-auth-proxy 🔐
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> **Zero-config Stdio to Streamable HTTP MCP runtime proxy with automatic OAuth 2.0 PKCE discovery & non-intrusive silent token refresh.**
+
+[![CI](https://github.com/thuyphuocthinh/mcp-auth-proxy/actions/workflows/ci.yml/badge.svg)](https://github.com/thuyphuocthinh/mcp-auth-proxy/actions/workflows/ci.yml)
+[![NPM Version](https://img.shields.io/npm/v/@thuyphuocthinh/mcp-auth-proxy.svg)](https://www.npmjs.com/package/@thuyphuocthinh/mcp-auth-proxy)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D20.0.0-green.svg)](https://nodejs.org/)
+[![Zero Dependencies](https://img.shields.io/badge/Dependencies-Zero-brightgreen.svg)]()
+
+`mcp-auth-proxy` acts as a zero-config bridge between your AI Client (Google Antigravity, Cursor, Windsurf, Claude Code, VS Code Copilot) and any remote Model Context Protocol (MCP) server protected by OAuth 2.0 (e.g., 200Lab AI Tutor, Notion, Linear, GitHub).
+
+---
+
+## 🌟 Highlights
+
+- 🚀 **Zero Runtime Dependencies**: Pure Node.js (`node:http`, `node:crypto`, `node:net`), lightweight, launches immediately via `npx`.
+- 🔍 **Automated OAuth Discovery**: Intercepts `401 Unauthorized`, parses `WWW-Authenticate: Bearer resource_metadata="..."` and resolves `.well-known` endpoints automatically.
+- 🔑 **Dynamic Client Registration (RFC 7591) & PKCE (RFC 7636)**: Automatically registers client IDs on the fly with S256 challenge, eliminating the need for hardcoded client secrets.
+- 🧘 **Non-Intrusive Stdio Mode**: Never interrupts your workflow by popping up a browser unexpectedly when running as a background proxy for AI IDEs.
+- 🔄 **Bound Silent Background Refresh**: Persists the registered `clientId` alongside your tokens and silently refreshes via `grant_type=refresh_token`, preventing `invalid_grant` client-mismatch errors.
+- 🚪 **Explicit `login` Command**: Authenticate upfront whenever you want using `mcp-auth-proxy login <url>`.
+- 🛡️ **Static Header Bypass**: Support for `--header` flag to pass static API keys or personal access tokens directly.
+- 🚦 **Dynamic Port Selection**: Automatically scans for free local ports starting from `8080` (8081, 8082...), eliminating `EADDRINUSE` port collision errors.
+
+---
+
+## 📦 Usage
+
+### 1. Antigravity / Cursor Configuration
+
+Add this entry to your `mcp_config.json` or `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "200lab-ai-tutor": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@thuyphuocthinh/mcp-auth-proxy",
+        "https://mcp.200lab.io/mcp/learner"
+      ]
+    }
+  }
+}
+```
+
+### 2. Explicit Login (Recommended Before First Use)
+
+Authenticate in advance so background sessions run smoothly:
+
+```bash
+npx @thuyphuocthinh/mcp-auth-proxy login https://mcp.200lab.io/mcp/learner
+```
+
+This opens your browser, receives the authorization code, securely stores the credentials in `~/.mcp-oauth-proxy/tokens.json`, and exits cleanly. All subsequent background proxy launches will run silently forever with automatic token refresh!
+
+---
+
+## 🛠️ CLI Reference
+
+```bash
+# Run as Stdio proxy
+npx @thuyphuocthinh/mcp-auth-proxy <remote-url> [options]
+
+# Explicit login command
+npx @thuyphuocthinh/mcp-auth-proxy login <remote-url> [options]
+```
+
+| Option | Description |
+| :--- | :--- |
+| `login <remote-url>` | Perform interactive OAuth authentication, save credentials, and exit |
+| `--client-id <id>` | Pre-configured Client ID (for servers without RFC 7591 dynamic registration) |
+| `--header "Key: Value"` | Custom request header (e.g. bypass OAuth with static API key) |
+| `--auto-browser` | Allow proxy to automatically launch browser when authentication is required |
+| `--no-browser` | Disable automatic browser launch; prints login URL to stderr (for headless/VPS environments) |
+| `--login-only` | Alias for the `login` command |
+| `-h, --help` | Display help instructions |
+| `-v, --version` | Display version number |
+
+---
+
+## 🧪 Testing
+
+```bash
+npm run build
+npm test
+```
+
+54 unit tests covering all core modules with 100% pass rate.
+
+---
+
+## 📄 License
+
+MIT © [Thuy Phuoc Thinh](https://github.com/thuyphuocthinh)

package/bin/cli.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../dist/src/index.js';

package/dist/src/index.d.ts

@@ -0,0 +1,24 @@
+import { TokenStore } from './store/token-store.js';
+export declare const VERSION = "1.0.1";
+export interface CliOptions {
+    command: 'proxy' | 'login';
+    remoteUrl?: string;
+    clientId?: string;
+    headers: Record<string, string>;
+    noBrowser: boolean;
+    autoBrowser: boolean;
+    loginOnly: boolean;
+    help: boolean;
+    version: boolean;
+}
+export declare function parseArgs(args: string[]): CliOptions;
+export declare function printHelp(): void;
+export declare function performLogin(options: {
+    remoteUrl: string;
+    clientId?: string;
+    noBrowser?: boolean;
+    store: TokenStore;
+    fetchFn?: typeof fetch;
+    log?: (msg: string) => void;
+}): Promise<string>;
+export declare function main(args?: string[]): Promise<void>;

package/dist/src/index.js

@@ -0,0 +1,231 @@
+import { discoverOAuth } from './oauth/discovery.js';
+import { generatePKCE } from './oauth/pkce.js';
+import { resolveClientId } from './oauth/client-registration.js';
+import { openBrowser } from './oauth/browser.js';
+import { startCallbackServer } from './oauth/server.js';
+import { TokenStore } from './store/token-store.js';
+import { startProxy } from './proxy.js';
+export const VERSION = '1.0.1';
+export function parseArgs(args) {
+    const options = {
+        command: 'proxy',
+        headers: {},
+        noBrowser: false,
+        autoBrowser: false,
+        loginOnly: false,
+        help: false,
+        version: false
+    };
+    const positional = [];
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === '--help' || arg === '-h') {
+            options.help = true;
+        }
+        else if (arg === '--version' || arg === '-v') {
+            options.version = true;
+        }
+        else if (arg === '--no-browser') {
+            options.noBrowser = true;
+        }
+        else if (arg === '--auto-browser') {
+            options.autoBrowser = true;
+        }
+        else if (arg === '--login-only') {
+            options.loginOnly = true;
+            options.command = 'login';
+        }
+        else if (arg === '--client-id' && i + 1 < args.length) {
+            options.clientId = args[++i];
+        }
+        else if (arg === '--header' && i + 1 < args.length) {
+            const headerStr = args[++i];
+            const colonIdx = headerStr.indexOf(':');
+            if (colonIdx > 0) {
+                const key = headerStr.substring(0, colonIdx).trim();
+                const value = headerStr.substring(colonIdx + 1).trim();
+                options.headers[key] = value;
+            }
+        }
+        else if (!arg.startsWith('-')) {
+            positional.push(arg);
+        }
+    }
+    if (positional.length > 0) {
+        if (positional[0] === 'login') {
+            options.command = 'login';
+            if (positional.length > 1) {
+                options.remoteUrl = positional[1];
+            }
+        }
+        else {
+            options.remoteUrl = positional[0];
+        }
+    }
+    return options;
+}
+export function printHelp() {
+    // All operational logging and help text MUST be printed to stderr
+    // so it does not interfere with the Stdio JSON-RPC stream on stdout!
+    console.error(`
+mcp-oauth-proxy v${VERSION}
+Zero-config Stdio to Streamable HTTP MCP runtime proxy with automatic OAuth PKCE & silent refresh.
+
+Usage:
+  mcp-oauth-proxy <remote-url> [options]
+  mcp-oauth-proxy login <remote-url> [options]
+
+Commands:
+  login <remote-url>     Perform interactive OAuth authentication, save credentials, and exit
+
+Options:
+  --client-id <id>       Pre-configured Client ID (for servers without RFC 7591 dynamic registration)
+  --header "K: V"        Custom request header (e.g. bypass OAuth using static API key)
+  --auto-browser         Automatically launch browser when re-authentication is required in proxy mode
+  --no-browser           Do not automatically open default browser; print authorization URL to stderr
+  --login-only           Alias for the login command
+  -h, --help             Display this help message
+  -v, --version          Display version number
+
+Examples:
+  mcp-oauth-proxy login https://mcp.200lab.io/mcp/learner
+  mcp-oauth-proxy https://mcp.200lab.io/mcp/learner
+  mcp-oauth-proxy https://api.example.com/mcp --header "Authorization: Bearer my_api_key"
+`);
+}
+export async function performLogin(options) {
+    const { remoteUrl, clientId, noBrowser = false, store, fetchFn = fetch, log = console.error } = options;
+    log(`[*] Discovering OAuth metadata for: ${remoteUrl}`);
+    const metadata = await discoverOAuth(remoteUrl, fetchFn);
+    log(`[*] Starting local callback server...`);
+    const callbackServer = await startCallbackServer();
+    const pkce = generatePKCE();
+    const effectiveClientId = await resolveClientId({
+        registrationEndpoint: metadata.registrationEndpoint,
+        redirectUri: callbackServer.redirectUri,
+        explicitClientId: clientId,
+        fetchFn,
+        log
+    });
+    const authUrl = new URL(metadata.authorizationEndpoint);
+    authUrl.searchParams.set('response_type', 'code');
+    authUrl.searchParams.set('client_id', effectiveClientId);
+    authUrl.searchParams.set('redirect_uri', callbackServer.redirectUri);
+    authUrl.searchParams.set('scope', metadata.scopes.join(' '));
+    authUrl.searchParams.set('code_challenge', pkce.challenge);
+    authUrl.searchParams.set('code_challenge_method', pkce.method);
+    authUrl.searchParams.set('resource', metadata.resource);
+    if (!noBrowser) {
+        await openBrowser(authUrl.toString(), log);
+    }
+    else {
+        log(`[*] Open this URL in your browser to complete authorization:\n${authUrl.toString()}\n`);
+    }
+    const code = await callbackServer.waitForCode();
+    log(`[*] Authorization code received. Exchanging for token...`);
+    const tokenRes = await fetchFn(metadata.tokenEndpoint, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+        body: new URLSearchParams({
+            grant_type: 'authorization_code',
+            client_id: effectiveClientId,
+            code,
+            redirect_uri: callbackServer.redirectUri,
+            code_verifier: pkce.verifier
+        })
+    });
+    if (!tokenRes.ok) {
+        const errText = await tokenRes.text();
+        await callbackServer.close();
+        throw new Error(`Token exchange failed (HTTP ${tokenRes.status}): ${errText}`);
+    }
+    const tokenData = (await tokenRes.json());
+    store.saveToken(metadata.resource, {
+        accessToken: tokenData.access_token,
+        refreshToken: tokenData.refresh_token,
+        expiresAt: Date.now() + tokenData.expires_in * 1000,
+        tokenType: tokenData.token_type,
+        scope: tokenData.scope,
+        clientId: effectiveClientId
+    });
+    log(`[+] Authentication successful! Credentials securely stored.`);
+    await callbackServer.close();
+    return tokenData.access_token;
+}
+export async function main(args = process.argv.slice(2)) {
+    const options = parseArgs(args);
+    if (options.help) {
+        printHelp();
+        process.exit(0);
+    }
+    if (options.version) {
+        console.error(`mcp-oauth-proxy v${VERSION}`);
+        process.exit(0);
+    }
+    if (!options.remoteUrl) {
+        console.error(`[-] Missing required <remote-url> parameter. Run with --help for instructions.`);
+        process.exit(1);
+    }
+    const remoteUrl = options.remoteUrl;
+    const store = new TokenStore();
+    if (options.command === 'login') {
+        await performLogin({
+            remoteUrl,
+            clientId: options.clientId,
+            noBrowser: options.noBrowser,
+            store
+        });
+        console.error(`[+] Authentication complete.`);
+        process.exit(0);
+    }
+    const getToken = async () => {
+        // If user provided a manual Authorization header via --header
+        if (options.headers['Authorization']) {
+            return '';
+        }
+        // 1. Discover OAuth Metadata from remote server
+        const metadata = await discoverOAuth(remoteUrl);
+        const storedToken = store.getToken(metadata.resource);
+        const existingClientId = storedToken?.clientId || options.clientId;
+        // 2. Try to get existing token or execute silent background refresh
+        const existingToken = await store.getOrRefreshToken({
+            resource: metadata.resource,
+            tokenEndpoint: metadata.tokenEndpoint,
+            clientId: existingClientId,
+            log: console.error
+        });
+        if (existingToken) {
+            return existingToken;
+        }
+        // 3. No valid token found or refresh failed:
+        if (options.autoBrowser) {
+            return await performLogin({
+                remoteUrl,
+                clientId: options.clientId,
+                noBrowser: options.noBrowser,
+                store
+            });
+        }
+        // Default Non-Intrusive mode: do not launch browser unsolicitedly
+        const loginCommand = `npx @thuyphuocthinh/mcp-auth-proxy login ${remoteUrl}`;
+        const message = `Authentication required for ${remoteUrl}. Please run: ${loginCommand}`;
+        console.error(`[-] ${message}`);
+        const authError = new Error(message);
+        authError.code = -32000;
+        throw authError;
+    };
+    // Launch Stdio runtime proxy loop
+    await startProxy({
+        remoteUrl,
+        getToken,
+        extraHeaders: options.headers,
+        logError: console.error
+    });
+}
+// When executed directly as a script
+if (process.argv[1]?.endsWith('cli.js') || process.argv[1]?.endsWith('index.js')) {
+    main().catch((err) => {
+        console.error(`[-] Fatal error: ${err.message}`);
+        process.exit(1);
+    });
+}

package/dist/src/oauth/browser.d.ts

@@ -0,0 +1,5 @@
+export declare function getOpenBrowserCommand(url: string, platform?: NodeJS.Platform): string;
+export declare function openBrowser(url: string, log?: {
+    (...data: any[]): void;
+    (message?: any, ...optionalParams: any[]): void;
+}): Promise<boolean>;

package/dist/src/oauth/browser.js

@@ -0,0 +1,27 @@
+import { exec } from 'node:child_process';
+import os from 'node:os';
+export function getOpenBrowserCommand(url, platform = os.platform()) {
+    if (platform === 'win32') {
+        return `start "" "${url}"`;
+    }
+    if (platform === 'darwin') {
+        return `open "${url}"`;
+    }
+    return `xdg-open "${url}"`;
+}
+export function openBrowser(url, log = console.log) {
+    return new Promise((resolve) => {
+        log(`[*] Automatically opening default browser for OAuth authentication...`);
+        log(`[*] If the browser does not open automatically, open this URL in your browser:\n${url}\n`);
+        const command = getOpenBrowserCommand(url);
+        exec(command, (error) => {
+            if (error) {
+                log(`[-] Failed to launch browser automatically: ${error.message}`);
+                resolve(false);
+            }
+            else {
+                resolve(true);
+            }
+        });
+    });
+}

package/dist/src/oauth/client-registration.d.ts

@@ -0,0 +1,13 @@
+export interface ClientRegistrationResponse {
+    client_id: string;
+    client_name?: string;
+    redirect_uris?: string[];
+}
+export declare function registerDynamicClient(registrationEndpoint: string, redirectUri: string, clientName?: string, fetchFn?: typeof fetch): Promise<string>;
+export declare function resolveClientId(options: {
+    registrationEndpoint?: string;
+    redirectUri: string;
+    explicitClientId?: string;
+    fetchFn?: typeof fetch;
+    log?: (msg: string) => void;
+}): Promise<string>;

package/dist/src/oauth/client-registration.js

@@ -0,0 +1,31 @@
+export async function registerDynamicClient(registrationEndpoint, redirectUri, clientName = 'mcp-oauth-proxy', fetchFn = fetch) {
+    const response = await fetchFn(registrationEndpoint, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+            client_name: clientName,
+            redirect_uris: [redirectUri]
+        })
+    });
+    if (!response.ok) {
+        const errorText = await response.text();
+        throw new Error(`Dynamic Client Registration failed (HTTP ${response.status}): ${errorText}`);
+    }
+    const data = (await response.json());
+    if (!data.client_id) {
+        throw new Error(`Registration response missing client_id`);
+    }
+    return data.client_id;
+}
+export async function resolveClientId(options) {
+    const { registrationEndpoint, redirectUri, explicitClientId, fetchFn = fetch, log = console.log } = options;
+    if (explicitClientId) {
+        log(`[*] Using configured Client ID: ${explicitClientId}`);
+        return explicitClientId;
+    }
+    if (registrationEndpoint) {
+        log(`[*] Registering dynamic Client ID with: ${registrationEndpoint}`);
+        return await registerDynamicClient(registrationEndpoint, redirectUri, 'mcp-oauth-proxy', fetchFn);
+    }
+    throw new Error(`Server does not support Dynamic Client Registration (RFC 7591). Please provide an explicit --client-id <id>`);
+}

package/dist/src/oauth/discovery.d.ts

@@ -0,0 +1,9 @@
+export interface OAuthMetadata {
+    resource: string;
+    authorizationEndpoint: string;
+    tokenEndpoint: string;
+    registrationEndpoint?: string;
+    scopes: string[];
+}
+export declare function extractResourceMetadataUrl(authHeader: string | null): string | null;
+export declare function discoverOAuth(remoteUrl: string, fetchFn?: typeof fetch): Promise<OAuthMetadata>;

package/dist/src/oauth/discovery.js

@@ -0,0 +1,42 @@
+export function extractResourceMetadataUrl(authHeader) {
+    if (!authHeader)
+        return null;
+    const match = authHeader.match(/resource_metadata="([^"]+)"/i);
+    return match ? match[1] : null;
+}
+export async function discoverOAuth(remoteUrl, fetchFn = fetch) {
+    // Step 1: Probe remote endpoint for 401 and WWW-Authenticate header
+    const probeResponse = await fetchFn(remoteUrl, { method: 'GET' });
+    const authHeader = probeResponse.headers.get('www-authenticate');
+    const metadataUrl = extractResourceMetadataUrl(authHeader);
+    if (!metadataUrl) {
+        throw new Error(`Missing 'WWW-Authenticate: Bearer resource_metadata="..."' header from ${remoteUrl}`);
+    }
+    // Step 2: Retrieve Protected Resource Metadata (RFC 8707)
+    const resourceRes = await fetchFn(metadataUrl);
+    if (!resourceRes.ok) {
+        throw new Error(`Failed to fetch Resource Metadata from ${metadataUrl}: HTTP ${resourceRes.status}`);
+    }
+    const resourceData = (await resourceRes.json());
+    const authServer = resourceData.authorization_servers?.[0];
+    if (!authServer) {
+        throw new Error(`Resource Metadata does not contain valid authorization_servers`);
+    }
+    // Step 3: Retrieve Authorization Server Metadata (RFC 8414)
+    const serverMetaUrl = `${authServer.replace(/\/$/, '')}/.well-known/oauth-authorization-server`;
+    const serverRes = await fetchFn(serverMetaUrl);
+    if (!serverRes.ok) {
+        throw new Error(`Failed to fetch Auth Server Metadata from ${serverMetaUrl}: HTTP ${serverRes.status}`);
+    }
+    const serverData = (await serverRes.json());
+    if (!serverData.authorization_endpoint || !serverData.token_endpoint) {
+        throw new Error(`Auth Server Metadata is missing authorization_endpoint or token_endpoint`);
+    }
+    return {
+        resource: resourceData.resource || remoteUrl,
+        authorizationEndpoint: serverData.authorization_endpoint,
+        tokenEndpoint: serverData.token_endpoint,
+        registrationEndpoint: serverData.registration_endpoint,
+        scopes: resourceData.scopes_supported || ['learner']
+    };
+}

package/dist/src/oauth/pkce.d.ts

@@ -0,0 +1,7 @@
+export interface PKCEPair {
+    verifier: string;
+    challenge: string;
+    method: 'S256';
+}
+export declare function base64url(buffer: Buffer): string;
+export declare function generatePKCE(): PKCEPair;

package/dist/src/oauth/pkce.js

@@ -0,0 +1,17 @@
+import crypto from 'node:crypto';
+export function base64url(buffer) {
+    return buffer.toString('base64')
+        .replace(/=/g, '')
+        .replace(/\+/g, '-')
+        .replace(/\//g, '_');
+}
+export function generatePKCE() {
+    // RFC 7636: verifier must have minimum 43 characters and maximum 128 characters
+    const verifier = base64url(crypto.randomBytes(32));
+    const challenge = base64url(crypto.createHash('sha256').update(verifier).digest());
+    return {
+        verifier,
+        challenge,
+        method: 'S256'
+    };
+}

package/dist/src/oauth/server.d.ts

@@ -0,0 +1,10 @@
+import http from 'node:http';
+export declare function getAvailablePort(startPort?: number): Promise<number>;
+export interface CallbackServerInstance {
+    server: http.Server;
+    port: number;
+    redirectUri: string;
+    waitForCode: () => Promise<string>;
+    close: () => Promise<void>;
+}
+export declare function startCallbackServer(port?: number): Promise<CallbackServerInstance>;

package/dist/src/oauth/server.js

@@ -0,0 +1,84 @@
+import http from 'node:http';
+import net from 'node:net';
+export function getAvailablePort(startPort = 8080) {
+    return new Promise((resolve) => {
+        const tester = net.createServer();
+        tester.listen(startPort, () => {
+            const port = tester.address().port;
+            tester.close(() => resolve(port));
+        });
+        tester.on('error', () => {
+            resolve(getAvailablePort(startPort + 1));
+        });
+    });
+}
+export async function startCallbackServer(port) {
+    const selectedPort = port ?? (await getAvailablePort(8080));
+    const redirectUri = `http://localhost:${selectedPort}/callback`;
+    let resolveCode;
+    let rejectCode;
+    const codePromise = new Promise((res, rej) => {
+        resolveCode = res;
+        rejectCode = rej;
+    });
+    // Prevent unhandledRejection if consumer awaits slightly after callback resolves/rejects
+    codePromise.catch(() => { });
+    const server = http.createServer((req, res) => {
+        const url = new URL(req.url || '/', `http://localhost:${selectedPort}`);
+        if (url.pathname === '/callback') {
+            const code = url.searchParams.get('code');
+            const error = url.searchParams.get('error');
+            const errorDesc = url.searchParams.get('error_description') || error;
+            if (error) {
+                res.writeHead(400, { 'Content-Type': 'text/html; charset=utf-8' });
+                res.end(`
+          <div style="font-family: sans-serif; text-align: center; padding: 40px;">
+            <h1 style="color: #ef4444;">&#10008; Authentication Failed</h1>
+            <p>${errorDesc}</p>
+          </div>
+        `);
+                rejectCode(new Error(`OAuth authentication failed: ${errorDesc}`));
+                return;
+            }
+            if (!code) {
+                res.writeHead(400, { 'Content-Type': 'text/html; charset=utf-8' });
+                res.end(`
+          <div style="font-family: sans-serif; text-align: center; padding: 40px;">
+            <h1 style="color: #ef4444;">&#10008; Authorization Code Missing</h1>
+            <p>The authorization server did not return a valid code.</p>
+          </div>
+        `);
+                rejectCode(new Error('Missing authorization code in callback'));
+                return;
+            }
+            res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+            res.end(`
+        <div style="font-family: sans-serif; text-align: center; padding: 40px;">
+          <h1 style="color: #10b981;">&#10004; Authentication Successful!</h1>
+          <p>Credentials have been securely saved to your local environment.</p>
+          <p>You may now close this tab and return to your application.</p>
+        </div>
+      `);
+            resolveCode(code);
+        }
+        else {
+            res.writeHead(404, { 'Content-Type': 'text/plain' });
+            res.end('Not Found');
+        }
+    });
+    await new Promise((resolve) => {
+        server.listen(selectedPort, () => resolve());
+    });
+    const close = () => {
+        return new Promise((resolve) => {
+            server.close(() => resolve());
+        });
+    };
+    return {
+        server,
+        port: selectedPort,
+        redirectUri,
+        waitForCode: () => codePromise,
+        close
+    };
+}

package/dist/src/proxy.d.ts

@@ -0,0 +1,30 @@
+export interface ProxyOptions {
+    remoteUrl: string;
+    getToken: () => Promise<string>;
+    extraHeaders?: Record<string, string>;
+    input?: NodeJS.ReadableStream;
+    output?: NodeJS.WritableStream;
+    fetchFn?: typeof fetch;
+    logError?: (msg: string) => void;
+}
+/**
+ * Extracts JSON-RPC message payloads from SSE (text/event-stream) response chunks.
+ * Conforms to standard Model Context Protocol (MCP) Streamable HTTP specification:
+ * event: message
+ * data: {"jsonrpc":"2.0", ...}
+ */
+export declare function extractJsonRpcFromSse(responseText: string): string[];
+/**
+ * Forwards a single JSON-RPC line from Stdio to the Remote HTTP MCP Server.
+ */
+export declare function forwardJsonRpc(options: {
+    line: string;
+    remoteUrl: string;
+    headers: Record<string, string>;
+    fetchFn?: typeof fetch;
+}): Promise<string[]>;
+/**
+ * Starts Stdio bidirectional proxy loop.
+ * Reads newline-delimited JSON-RPC from stdin, attaches valid token, and writes to stdout.
+ */
+export declare function startProxy(options: ProxyOptions): Promise<void>;