@thuyphuocthinh/mcp-auth-proxy 1.0.0 → 1.0.1

package/README.md

@@ -1,6 +1,6 @@
 # @thuyphuocthinh/mcp-auth-proxy 🔐
 
-> **Zero-config Stdio to Streamable HTTP MCP runtime proxy with automatic OAuth 2.0 PKCE discovery & silent token refresh.**
+> **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)
@@ -17,8 +17,9 @@
 - 🚀 **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.
-- 🌐 **Cross-Platform Auto Browser Launch**: Automatically opens default browser on Windows (`start`), macOS (`open`), and Linux (`xdg-open`).
-- 🔄 **Silent Background Refresh**: Automatically renews expiring tokens in the background via `grant_type=refresh_token` before the 5-minute expiry threshold.
+- 🧘 **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.
 
@@ -45,22 +46,36 @@ Add this entry to your `mcp_config.json` or `claude_desktop_config.json`:
 }
 ```
 
-*On first launch, your browser will automatically pop up to approve authorization. Subsequent launches will run silently forever with automatic token refresh!*
+### 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!
 
 ---
 
-### 2. CLI Options
+## 🛠️ 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` | Perform interactive OAuth authentication, save credentials, and exit |
+| `--login-only` | Alias for the `login` command |
 | `-h, --help` | Display help instructions |
 | `-v, --version` | Display version number |
 
@@ -73,7 +88,7 @@ npm run build
 npm test
 ```
 
-49 unit tests covering all core modules with 100% pass rate.
+54 unit tests covering all core modules with 100% pass rate.
 
 ---
 

package/dist/src/index.d.ts

@@ -1,13 +1,24 @@
-export declare const VERSION = "1.0.0";
+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

@@ -5,15 +5,18 @@ 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.0';
+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') {
@@ -25,8 +28,12 @@ export function parseArgs(args) {
         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];
@@ -40,8 +47,19 @@ export function parseArgs(args) {
                 options.headers[key] = value;
             }
         }
-        else if (!arg.startsWith('-') && !options.remoteUrl) {
-            options.remoteUrl = arg;
+        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;
@@ -55,20 +73,85 @@ Zero-config Stdio to Streamable HTTP MCP runtime proxy with automatic OAuth PKCE
 
 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           Perform interactive OAuth authentication, save credentials, and exit
+  --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) {
@@ -85,6 +168,16 @@ export async function main(args = process.argv.slice(2)) {
     }
     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']) {
@@ -92,80 +185,35 @@ export async function main(args = process.argv.slice(2)) {
         }
         // 1. Discover OAuth Metadata from remote server
         const metadata = await discoverOAuth(remoteUrl);
-        const clientId = await resolveClientId({
-            registrationEndpoint: metadata.registrationEndpoint,
-            redirectUri: 'http://localhost:8080/callback',
-            explicitClientId: options.clientId,
-            log: console.error
-        });
+        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,
+            clientId: existingClientId,
             log: console.error
         });
         if (existingToken) {
             return existingToken;
         }
-        // 3. No valid token: start interactive OAuth PKCE flow
-        console.error(`[*] Initiating OAuth authentication flow for: ${metadata.resource}`);
-        const callbackServer = await startCallbackServer();
-        const pkce = generatePKCE();
-        // Re-resolve client with exact dynamic callback port
-        const effectiveClientId = await resolveClientId({
-            registrationEndpoint: metadata.registrationEndpoint,
-            redirectUri: callbackServer.redirectUri,
-            explicitClientId: options.clientId,
-            log: console.error
-        });
-        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 (!options.noBrowser) {
-            await openBrowser(authUrl.toString(), console.error);
+        // 3. No valid token found or refresh failed:
+        if (options.autoBrowser) {
+            return await performLogin({
+                remoteUrl,
+                clientId: options.clientId,
+                noBrowser: options.noBrowser,
+                store
+            });
         }
-        else {
-            console.error(`[*] Open this URL in your browser to complete authorization:\n${authUrl.toString()}\n`);
-        }
-        const code = await callbackServer.waitForCode();
-        console.error(`[*] Authorization code received. Exchanging for token...`);
-        const tokenRes = await fetch(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
-        });
-        console.error(`[+] Authentication successful! Credentials securely stored.`);
-        await callbackServer.close();
-        return tokenData.access_token;
+        // 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;
     };
-    if (options.loginOnly) {
-        await getToken();
-        console.error(`[+] Pre-authentication complete (--login-only).`);
-        process.exit(0);
-    }
     // Launch Stdio runtime proxy loop
     await startProxy({
         remoteUrl,

package/dist/src/proxy.js

@@ -116,10 +116,11 @@ export async function startProxy(options) {
                 requestId = parsed.id ?? null;
             }
             catch { }
+            const errorCode = err && typeof err.code === 'number' ? err.code : -32603;
             output.write(JSON.stringify({
                 jsonrpc: '2.0',
                 id: requestId,
-                error: { code: -32603, message: err.message }
+                error: { code: errorCode, message: err.message }
             }) + '\n');
         }
     }

package/dist/src/store/token-store.d.ts

@@ -4,6 +4,7 @@ export interface StoredToken {
     expiresAt: number;
     tokenType?: string;
     scope?: string;
+    clientId?: string;
 }
 export declare class TokenStore {
     private storePath;
@@ -14,14 +15,14 @@ export declare class TokenStore {
     refreshToken(options: {
         resource: string;
         tokenEndpoint: string;
-        clientId: string;
+        clientId?: string;
         fetchFn?: typeof fetch;
         log?: (msg: string) => void;
     }): Promise<string | null>;
     getOrRefreshToken(options: {
         resource: string;
         tokenEndpoint: string;
-        clientId: string;
+        clientId?: string;
         fetchFn?: typeof fetch;
         log?: (msg: string) => void;
     }): Promise<string | null>;

package/dist/src/store/token-store.js

@@ -22,12 +22,17 @@ export class TokenStore {
         return Date.now() >= token.expiresAt - bufferMs;
     }
     async refreshToken(options) {
-        const { resource, tokenEndpoint, clientId, fetchFn = fetch, log = console.log } = options;
+        const { resource, tokenEndpoint, fetchFn = fetch, log = console.log } = options;
         const current = this.getToken(resource);
         if (!current?.refreshToken) {
             log(`[-] No refresh_token available for resource: ${resource}`);
             return null;
         }
+        const effectiveClientId = current.clientId || options.clientId;
+        if (!effectiveClientId) {
+            log(`[-] No client_id available for silent token refresh for resource: ${resource}`);
+            return null;
+        }
         try {
             log(`[*] Performing silent background token refresh...`);
             const response = await fetchFn(tokenEndpoint, {
@@ -35,7 +40,7 @@ export class TokenStore {
                 headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
                 body: new URLSearchParams({
                     grant_type: 'refresh_token',
-                    client_id: clientId,
+                    client_id: effectiveClientId,
                     refresh_token: current.refreshToken
                 })
             });
@@ -50,7 +55,8 @@ export class TokenStore {
                 refreshToken: data.refresh_token || current.refreshToken,
                 expiresAt: Date.now() + data.expires_in * 1000,
                 tokenType: data.token_type || current.tokenType,
-                scope: data.scope || current.scope
+                scope: data.scope || current.scope,
+                clientId: effectiveClientId
             };
             this.saveToken(resource, updatedToken);
             log(`[+] Token refreshed successfully! Valid for ${data.expires_in}s.`);
@@ -73,7 +79,10 @@ export class TokenStore {
         }
         // Expiring soon: silently refresh if refresh_token exists
         if (current.refreshToken) {
-            const refreshed = await this.refreshToken(options);
+            const refreshed = await this.refreshToken({
+                ...options,
+                clientId: current.clientId || options.clientId
+            });
             if (refreshed) {
                 return refreshed;
             }

package/dist/tests/cli.test.js

@@ -47,4 +47,19 @@ describe('CLI Argument Parser', () => {
         assert.strictEqual(options.clientId, 'test_id');
         assert.strictEqual(options.noBrowser, true);
     });
+    it('should parse login subcommand and set command to login', () => {
+        const options = parseArgs(['login', 'https://mcp.200lab.io/mcp/learner']);
+        assert.strictEqual(options.command, 'login');
+        assert.strictEqual(options.remoteUrl, 'https://mcp.200lab.io/mcp/learner');
+    });
+    it('should parse --auto-browser flag', () => {
+        const options = parseArgs(['https://mcp.example.com', '--auto-browser']);
+        assert.strictEqual(options.command, 'proxy');
+        assert.strictEqual(options.autoBrowser, true);
+    });
+    it('should treat --login-only as command login', () => {
+        const options = parseArgs(['https://mcp.example.com', '--login-only']);
+        assert.strictEqual(options.command, 'login');
+        assert.strictEqual(options.loginOnly, true);
+    });
 });

package/dist/tests/smoke.test.js

@@ -2,7 +2,7 @@ import { describe, it } from 'node:test';
 import assert from 'node:assert';
 import { VERSION } from '../src/index.js';
 describe('Boilerplate Smoke Test', () => {
-    it('phải export đúng version', () => {
-        assert.strictEqual(VERSION, '1.0.0');
+    it('should export correct version', () => {
+        assert.strictEqual(VERSION, '1.0.1');
     });
 });

package/dist/tests/store/token-store.test.js

@@ -157,4 +157,62 @@ describe('TokenStore & Silent Refresh Logic', () => {
         });
         assert.strictEqual(token, 'still_working_for_2_minutes', 'Should fallback to remaining validity');
     });
+    it('refreshToken should prioritize persisted clientId over options.clientId and preserve it in storage', async () => {
+        const resource = 'https://mcp.bound-client.com';
+        const tokenEndpoint = 'https://api.bound-client.com/oauth/token';
+        store.saveToken(resource, {
+            accessToken: 'old_token',
+            refreshToken: 'bound_refresh_token',
+            expiresAt: Date.now() + 60_000,
+            clientId: 'original_persisted_client_id'
+        });
+        let sentClientId = null;
+        const mockFetch = async (_input, init) => {
+            const params = new URLSearchParams(init?.body);
+            sentClientId = params.get('client_id');
+            return new Response(JSON.stringify({
+                access_token: 'new_token_refreshed',
+                expires_in: 3600
+            }), { status: 200, headers: { 'Content-Type': 'application/json' } });
+        };
+        // Even if options passes a different clientId, stored clientId MUST take precedence!
+        const result = await store.refreshToken({
+            resource,
+            tokenEndpoint,
+            clientId: 'different_new_client_id',
+            fetchFn: mockFetch,
+            log: () => { }
+        });
+        assert.strictEqual(result, 'new_token_refreshed');
+        assert.strictEqual(sentClientId, 'original_persisted_client_id', 'Must use persisted clientId tied to refresh token');
+        const updated = store.getToken(resource);
+        assert.strictEqual(updated?.clientId, 'original_persisted_client_id', 'Must preserve persisted clientId after refresh');
+    });
+    it('getOrRefreshToken should use stored clientId during silent refresh when clientId option is omitted', async () => {
+        const resource = 'https://mcp.silent.com';
+        const tokenEndpoint = 'https://api.silent.com/oauth/token';
+        store.saveToken(resource, {
+            accessToken: 'expiring_token',
+            refreshToken: 'my_refresh_token',
+            expiresAt: Date.now() + 60_000, // < 5m buffer
+            clientId: 'stored_pkce_client_id'
+        });
+        let sentClientId = null;
+        const mockFetch = async (_input, init) => {
+            const params = new URLSearchParams(init?.body);
+            sentClientId = params.get('client_id');
+            return new Response(JSON.stringify({
+                access_token: 'refreshed_access_token',
+                expires_in: 7200
+            }), { status: 200, headers: { 'Content-Type': 'application/json' } });
+        };
+        const token = await store.getOrRefreshToken({
+            resource,
+            tokenEndpoint,
+            fetchFn: mockFetch,
+            log: () => { }
+        });
+        assert.strictEqual(token, 'refreshed_access_token');
+        assert.strictEqual(sentClientId, 'stored_pkce_client_id');
+    });
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thuyphuocthinh/mcp-auth-proxy",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Zero-config Stdio to Streamable HTTP MCP runtime proxy with automatic OAuth PKCE & silent refresh",
   "type": "module",
   "main": "./dist/src/index.js",