fix: OAuth nits, run typecheck and linter in CI (#94)

* Replace expires_at with expires_in in OAuth tokens and fix TypeScript errors

- Replace non-standard expires_at with standard expires_in field for OAuth access tokens
- Update token validation logic to check expires_in as number instead of parsing timestamps
- Fix TypeScript compilation errors by adding any type annotations to catch blocks

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

* Apply Prettier formatting and code style improvements

- Update GitHub workflow quote style consistency
- Format README with consistent list markers and spacing
- Add lint-fix script to package.json
- Apply consistent formatting across TypeScript source files
- Standardize quote usage, indentation, and spacing

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

* Add GitHub workflow to run checks on PRs to main branch

- Run 'pnpm build' and 'pnpm run check' on every pull request to main
- Uses same pnpm setup as existing publish workflow for consistency
- Ensures code quality and type checking before merging

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

* remove npm package-lock, we use pnpm in this house

* fix lints again!

---------

Co-authored-by: Claude <[email protected]>

Author: max-stytch

.github/workflows/check.yml

@@ -0,0 +1,26 @@
+name: Check
+
+on:
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm & install
+        uses: wyvox/action-setup-pnpm@v3
+        with:
+          node-version: 22
+          pnpm-version: 10
+
+      - name: Build
+        run: pnpm build
+
+      - name: Run checks
+        run: pnpm run check

.github/workflows/publish.yml

@@ -3,9 +3,9 @@ on:
   pull_request:
   push:
     branches:
-      - "**"
+      - '**'
     tags:
-      - "!**"
+      - '!**'
 
 jobs:
   build:

README.md

@@ -23,10 +23,7 @@ All the most popular MCP clients (Claude Desktop, Cursor & Windsurf) use the fol
   "mcpServers": {
     "remote-example": {
       "command": "npx",
-      "args": [
-        "mcp-remote",
-        "https://remote.mcp.server/sse"
-      ]
+      "args": ["mcp-remote", "https://remote.mcp.server/sse"]
     }
   }
 }
@@ -41,16 +38,11 @@ To bypass authentication, or to emit custom headers on all requests to your remo
   "mcpServers": {
     "remote-example": {
       "command": "npx",
-      "args": [
-        "mcp-remote",
-        "https://remote.mcp.server/sse",
-        "--header",
-        "Authorization: Bearer ${AUTH_TOKEN}"
-      ],
+      "args": ["mcp-remote", "https://remote.mcp.server/sse", "--header", "Authorization: Bearer ${AUTH_TOKEN}"],
       "env": {
         "AUTH_TOKEN": "..."
       }
-    },
+    }
   }
 }
 ```
@@ -74,7 +66,7 @@ To bypass authentication, or to emit custom headers on all requests to your remo
 
 ### Flags
 
-* If `npx` is producing errors, consider adding `-y` as the first argument to auto-accept the installation of the `mcp-remote` package.
+- If `npx` is producing errors, consider adding `-y` as the first argument to auto-accept the installation of the `mcp-remote` package.
 
 ```json
       "command": "npx",
@@ -85,7 +77,7 @@ To bypass authentication, or to emit custom headers on all requests to your remo
       ]
 ```
 
-* To force `npx` to always check for an updated version of `mcp-remote`, add the `@latest` flag:
+- To force `npx` to always check for an updated version of `mcp-remote`, add the `@latest` flag:
 
 ```json
       "args": [
@@ -94,7 +86,7 @@ To bypass authentication, or to emit custom headers on all requests to your remo
       ]
 ```
 
-* To change which port `mcp-remote` listens for an OAuth redirect (by default `3334`), add an additional argument after the server URL. Note that whatever port you specify, if it is unavailable an open port will be chosen at random.
+- To change which port `mcp-remote` listens for an OAuth redirect (by default `3334`), add an additional argument after the server URL. Note that whatever port you specify, if it is unavailable an open port will be chosen at random.
 
 ```json
       "args": [
@@ -104,7 +96,7 @@ To bypass authentication, or to emit custom headers on all requests to your remo
       ]
 ```
 
-* To change which host `mcp-remote` registers as the OAuth callback URL (by default `localhost`), add the `--host` flag.
+- To change which host `mcp-remote` registers as the OAuth callback URL (by default `localhost`), add the `--host` flag.
 
 ```json
       "args": [
@@ -115,7 +107,7 @@ To bypass authentication, or to emit custom headers on all requests to your remo
       ]
 ```
 
-* To allow HTTP connections in trusted private networks, add the `--allow-http` flag. Note: This should only be used in secure private networks where traffic cannot be intercepted.
+- To allow HTTP connections in trusted private networks, add the `--allow-http` flag. Note: This should only be used in secure private networks where traffic cannot be intercepted.
 
 ```json
       "args": [
@@ -125,7 +117,7 @@ To bypass authentication, or to emit custom headers on all requests to your remo
       ]
 ```
 
-* To enable detailed debugging logs, add the `--debug` flag. This will write verbose logs to `~/.mcp-auth/{server_hash}_debug.log` with timestamps and detailed information about the auth process, connections, and token refreshing.
+- To enable detailed debugging logs, add the `--debug` flag. This will write verbose logs to `~/.mcp-auth/{server_hash}_debug.log` with timestamps and detailed information about the auth process, connections, and token refreshing.
 
 ```json
       "args": [
@@ -189,8 +181,8 @@ npx mcp-remote https://example.remote/server --static-oauth-client-info '@/Users
 
 In order to add an MCP server to Claude Desktop you need to edit the configuration file located at:
 
-* macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
-* Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
 
 If it does not exist yet, [you may need to enable it under Settings > Developer](https://modelcontextprotocol.io/quickstart/user#2-add-the-filesystem-mcp-server).
 
@@ -212,16 +204,16 @@ As of version `0.48.0`, Cursor supports unauthed SSE servers directly. If your M
 
 For instructions on building & deploying remote MCP servers, including acting as a valid OAuth client, see the following resources:
 
-* https://developers.cloudflare.com/agents/guides/remote-mcp-server/
+- https://developers.cloudflare.com/agents/guides/remote-mcp-server/
 
 In particular, see:
 
-* https://github.com/cloudflare/workers-oauth-provider for defining an MCP-comlpiant OAuth server in Cloudflare Workers
-* https://github.com/cloudflare/agents/tree/main/examples/mcp for defining an `McpAgent` using the [`agents`](https://npmjs.com/package/agents) framework.
+- https://github.com/cloudflare/workers-oauth-provider for defining an MCP-comlpiant OAuth server in Cloudflare Workers
+- https://github.com/cloudflare/agents/tree/main/examples/mcp for defining an `McpAgent` using the [`agents`](https://npmjs.com/package/agents) framework.
 
 For more information about testing these servers, see also:
 
-* https://developers.cloudflare.com/agents/guides/test-remote-mcp-server/
+- https://developers.cloudflare.com/agents/guides/test-remote-mcp-server/
 
 Know of more resources you'd like to share? Please add them to this Readme and send a PR!
 
@@ -256,13 +248,10 @@ this might look like:
 
 ```json
 {
- "mcpServers": {
+  "mcpServers": {
     "remote-example": {
       "command": "npx",
-      "args": [
-        "mcp-remote",
-        "https://remote.mcp.server/sse"
-      ],
+      "args": ["mcp-remote", "https://remote.mcp.server/sse"],
       "env": {
         "NODE_EXTRA_CA_CERTS": "{your CA certificate file path}.pem"
       }
@@ -273,10 +262,10 @@ this might look like:
 
 ### Check the logs
 
-* [Follow Claude Desktop logs in real-time](https://modelcontextprotocol.io/docs/tools/debugging#debugging-in-claude-desktop)
-* MacOS / Linux:<br/>`tail -n 20 -F ~/Library/Logs/Claude/mcp*.log`
-* For bash on WSL:<br/>`tail -n 20 -f "C:\Users\YourUsername\AppData\Local\Claude\Logs\mcp.log"`
-* Powershell: <br/>`Get-Content "C:\Users\YourUsername\AppData\Local\Claude\Logs\mcp.log" -Wait -Tail 20`
+- [Follow Claude Desktop logs in real-time](https://modelcontextprotocol.io/docs/tools/debugging#debugging-in-claude-desktop)
+- MacOS / Linux:<br/>`tail -n 20 -F ~/Library/Logs/Claude/mcp*.log`
+- For bash on WSL:<br/>`tail -n 20 -f "C:\Users\YourUsername\AppData\Local\Claude\Logs\mcp.log"`
+- Powershell: <br/>`Get-Content "C:\Users\YourUsername\AppData\Local\Claude\Logs\mcp.log" -Wait -Tail 20`
 
 ## Debugging
 

package.json

@@ -25,7 +25,8 @@
   "scripts": {
     "build": "tsup",
     "build:watch": "tsup --watch",
-    "check": "prettier --check . && tsc"
+    "check": "prettier --check . && tsc",
+    "lint-fix": "prettier --check . --write"
   },
   "dependencies": {
     "express": "^4.21.2",

src/lib/coordination.ts

@@ -32,15 +32,16 @@ export async function isPidRunning(pid: number): Promise<boolean> {
  */
 export async function isLockValid(lockData: LockfileData): Promise<boolean> {
   if (DEBUG) await debugLog(global.currentServerUrlHash!, 'Checking if lockfile is valid', lockData)
-  
+
   // Check if the lockfile is too old (over 30 minutes)
   const MAX_LOCK_AGE = 30 * 60 * 1000 // 30 minutes
   if (Date.now() - lockData.timestamp > MAX_LOCK_AGE) {
     log('Lockfile is too old')
-    if (DEBUG) await debugLog(global.currentServerUrlHash!, 'Lockfile is too old', {
-      age: Date.now() - lockData.timestamp,
-      maxAge: MAX_LOCK_AGE
-    })
+    if (DEBUG)
+      await debugLog(global.currentServerUrlHash!, 'Lockfile is too old', {
+        age: Date.now() - lockData.timestamp,
+        maxAge: MAX_LOCK_AGE,
+      })
     return false
   }
 
@@ -54,7 +55,7 @@ export async function isLockValid(lockData: LockfileData): Promise<boolean> {
   // Check if the endpoint is accessible
   try {
     if (DEBUG) await debugLog(global.currentServerUrlHash!, 'Checking if endpoint is accessible', { port: lockData.port })
-    
+
     const controller = new AbortController()
     const timeout = setTimeout(() => controller.abort(), 1000)
 
@@ -63,9 +64,10 @@ export async function isLockValid(lockData: LockfileData): Promise<boolean> {
     })
 
     clearTimeout(timeout)
-    
+
     const isValid = response.status === 200 || response.status === 202
-    if (DEBUG) await debugLog(global.currentServerUrlHash!, `Endpoint check result: ${isValid ? 'valid' : 'invalid'}`, { status: response.status })
+    if (DEBUG)
+      await debugLog(global.currentServerUrlHash!, `Endpoint check result: ${isValid ? 'valid' : 'invalid'}`, { status: response.status })
     return isValid
   } catch (error) {
     log(`Error connecting to auth server: ${(error as Error).message}`)
@@ -84,13 +86,13 @@ export async function waitForAuthentication(port: number): Promise<boolean> {
   if (DEBUG) await debugLog(global.currentServerUrlHash!, `Waiting for authentication from server on port ${port}`)
 
   try {
-    let attempts = 0;
+    let attempts = 0
     while (true) {
-      attempts++;
+      attempts++
       const url = `http://127.0.0.1:${port}/wait-for-auth`
       log(`Querying: ${url}`)
       if (DEBUG) await debugLog(global.currentServerUrlHash!, `Poll attempt ${attempts}: ${url}`)
-      
+
       try {
         const response = await fetch(url)
         if (DEBUG) await debugLog(global.currentServerUrlHash!, `Poll response status: ${response.status}`)
@@ -130,11 +132,7 @@ export async function waitForAuthentication(port: number): Promise<boolean> {
  * @param events The event emitter to use for signaling
  * @returns An AuthCoordinator object with an initializeAuth method
  */
-export function createLazyAuthCoordinator(
-  serverUrlHash: string,
-  callbackPort: number,
-  events: EventEmitter
-): AuthCoordinator {
+export function createLazyAuthCoordinator(serverUrlHash: string, callbackPort: number, events: EventEmitter): AuthCoordinator {
   let authState: { server: Server; waitForAuthCode: () => Promise<string>; skipBrowserAuth: boolean } | null = null
 
   return {
@@ -147,12 +145,12 @@ export function createLazyAuthCoordinator(
 
       log('Initializing auth coordination on-demand')
       if (DEBUG) await debugLog(serverUrlHash, 'Initializing auth coordination on-demand', { serverUrlHash, callbackPort })
-      
+
       // Initialize auth using the existing coordinateAuth logic
       authState = await coordinateAuth(serverUrlHash, callbackPort, events)
       if (DEBUG) await debugLog(serverUrlHash, 'Auth coordination completed', { skipBrowserAuth: authState.skipBrowserAuth })
       return authState
-    }
+    },
   }
 }
 
@@ -169,10 +167,10 @@ export async function coordinateAuth(
   events: EventEmitter,
 ): Promise<{ server: Server; waitForAuthCode: () => Promise<string>; skipBrowserAuth: boolean }> {
   if (DEBUG) await debugLog(serverUrlHash, 'Coordinating authentication', { serverUrlHash, callbackPort })
-  
+
   // Check for a lockfile (disabled on Windows for the time being)
   const lockData = process.platform === 'win32' ? null : await checkLockfile(serverUrlHash)
-  
+
   if (DEBUG) {
     if (process.platform === 'win32') {
       await debugLog(serverUrlHash, 'Skipping lockfile check on Windows')
@@ -190,7 +188,7 @@ export async function coordinateAuth(
       // Try to wait for the authentication to complete
       if (DEBUG) await debugLog(serverUrlHash, 'Waiting for authentication from other instance')
       const authCompleted = await waitForAuthentication(lockData.port)
-      
+
       if (authCompleted) {
         log('Authentication completed by another instance')
         if (DEBUG) await debugLog(serverUrlHash, 'Authentication completed by another instance, will use tokens from disk')

src/lib/node-oauth-client-provider.ts

@@ -41,7 +41,7 @@ export class NodeOAuthClientProvider implements OAuthClientProvider {
   }
 
   get redirectUrl(): string {
-    return `http://${this.options.host}:${this.options.callbackPort}${this.callbackPath}`;
+    return `http://${this.options.host}:${this.options.callbackPort}${this.callbackPath}`
   }
 
   get clientMetadata() {
@@ -68,7 +68,11 @@ export class NodeOAuthClientProvider implements OAuthClientProvider {
       if (DEBUG) await debugLog(this.serverUrlHash, 'Returning static client info')
       return this.staticOAuthClientInfo
     }
-    const clientInfo = await readJsonFile<OAuthClientInformationFull>(this.serverUrlHash, 'client_info.json', OAuthClientInformationFullSchema)
+    const clientInfo = await readJsonFile<OAuthClientInformationFull>(
+      this.serverUrlHash,
+      'client_info.json',
+      OAuthClientInformationFullSchema,
+    )
     if (DEBUG) await debugLog(this.serverUrlHash, 'Client info result:', clientInfo ? 'Found' : 'Not found')
     return clientInfo
   }
@@ -96,17 +100,14 @@ export class NodeOAuthClientProvider implements OAuthClientProvider {
 
     if (DEBUG) {
       if (tokens) {
-        const expiresAt = new Date(tokens.expires_at)
-        const now = new Date()
-        const expiresAtTime = expiresAt.getTime()
-        const timeLeft = !isNaN(expiresAtTime) ? Math.round((expiresAtTime - now.getTime()) / 1000) : 0
-
-        // Alert if expires_at produces an invalid date
-        if (isNaN(expiresAtTime)) {
-          await debugLog(this.serverUrlHash, '⚠️ WARNING: Invalid expires_at detected while reading tokens ⚠️', {
-            expiresAt: tokens.expires_at,
+        const timeLeft = tokens.expires_in || 0
+
+        // Alert if expires_in is invalid
+        if (typeof tokens.expires_in !== 'number' || tokens.expires_in < 0) {
+          await debugLog(this.serverUrlHash, '⚠️ WARNING: Invalid expires_in detected while reading tokens ⚠️', {
+            expiresIn: tokens.expires_in,
             tokenObject: JSON.stringify(tokens),
-            stack: new Error('Invalid expires_at timestamp').stack
+            stack: new Error('Invalid expires_in value').stack,
           })
         }
 
@@ -116,7 +117,7 @@ export class NodeOAuthClientProvider implements OAuthClientProvider {
           hasRefreshToken: !!tokens.refresh_token,
           expiresIn: `${timeLeft} seconds`,
           isExpired: timeLeft <= 0,
-          expiresAt: tokens.expires_at
+          expiresInValue: tokens.expires_in,
         })
       } else {
         await debugLog(this.serverUrlHash, 'Token result: Not found')
@@ -132,25 +133,22 @@ export class NodeOAuthClientProvider implements OAuthClientProvider {
    */
   async saveTokens(tokens: OAuthTokens): Promise<void> {
     if (DEBUG) {
-      const expiresAt = new Date(tokens.expires_at)
-      const now = new Date()
-      const expiresAtTime = expiresAt.getTime()
-      const timeLeft = !isNaN(expiresAtTime) ? Math.round((expiresAtTime - now.getTime()) / 1000) : 0
-
-      // Alert if expires_at produces an invalid date
-      if (isNaN(expiresAtTime)) {
-        await debugLog(this.serverUrlHash, '⚠️ WARNING: Invalid expires_at detected in tokens ⚠️', {
-          expiresAt: tokens.expires_at,
+      const timeLeft = tokens.expires_in || 0
+
+      // Alert if expires_in is invalid
+      if (typeof tokens.expires_in !== 'number' || tokens.expires_in < 0) {
+        await debugLog(this.serverUrlHash, '⚠️ WARNING: Invalid expires_in detected in tokens ⚠️', {
+          expiresIn: tokens.expires_in,
           tokenObject: JSON.stringify(tokens),
-          stack: new Error('Invalid expires_at timestamp').stack
+          stack: new Error('Invalid expires_in value').stack,
         })
       }
 
       await debugLog(this.serverUrlHash, 'Saving tokens', {
         hasAccessToken: !!tokens.access_token,
         hasRefreshToken: !!tokens.refresh_token,
         expiresIn: `${timeLeft} seconds`,
-        expiresAt: tokens.expires_at
+        expiresInValue: tokens.expires_in,
       })
     }