Separate MCP SDK exports into dedicated submodule

Author: koistya

README.md

@@ -42,21 +42,21 @@ npm install oauth-callback
 ## Quick Start
 
 ```typescript
-import {
-  getAuthCode,
-  OAuthError,
-  browserAuth,
-  fileStore,
-} from "oauth-callback";
+import { getAuthCode, OAuthError } from "oauth-callback";
 
 // Simple usage
 const result = await getAuthCode(
   "https://example.com/oauth/authorize?client_id=xxx&redirect_uri=http://localhost:3000/callback",
 );
 console.log("Authorization code:", result.code);
 
-// MCP SDK integration
+// MCP SDK integration - use specific import
+import { browserAuth, fileStore } from "oauth-callback/mcp";
 const authProvider = browserAuth({ store: fileStore() });
+
+// Or via namespace import
+import { mcp } from "oauth-callback";
+const authProvider = mcp.browserAuth({ store: mcp.fileStore() });
 ```
 
 ## Usage Examples
@@ -139,7 +139,7 @@ const microsoftAuth = await getAuthCode(
 The `browserAuth()` function provides a drop-in OAuth provider for the Model Context Protocol SDK:
 
 ```typescript
-import { browserAuth, inMemoryStore } from "oauth-callback";
+import { browserAuth, inMemoryStore } from "oauth-callback/mcp";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 
@@ -167,7 +167,7 @@ await client.connect(transport);
 #### Token Storage Options
 
 ```typescript
-import { browserAuth, inMemoryStore, fileStore } from "oauth-callback";
+import { browserAuth, inMemoryStore, fileStore } from "oauth-callback/mcp";
 
 // Ephemeral storage (tokens lost on restart)
 const ephemeralAuth = browserAuth({

examples/notion.ts

@@ -14,7 +14,7 @@
 
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
-import { browserAuth, inMemoryStore } from "../src/index";
+import { browserAuth, inMemoryStore } from "../src/mcp";
 
 async function main() {
   console.log("🚀 Starting OAuth flow example with Notion MCP Server\n");

package.json

@@ -1,6 +1,6 @@
 {
   "name": "oauth-callback",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Lightweight OAuth 2.0 callback handler for Node.js, Deno, and Bun with built-in browser flow, MCP support, and zero dependencies",
   "keywords": [
     "oauth",
@@ -57,6 +57,10 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./mcp": {
+      "types": "./dist/mcp.d.ts",
+      "default": "./dist/mcp.js"
+    },
     "./package.json": "./package.json"
   },
   "dependencies": {
@@ -90,7 +94,7 @@
   },
   "scripts": {
     "build:templates": "bun run templates/build.ts",
-    "build": "bun run build:templates && bun build ./src/index.ts --outdir=./dist --target=node && tsc --declaration --emitDeclarationOnly --outDir ./dist",
+    "build": "bun run build:templates && bun build ./src/index.ts --outdir=./dist --target=node && bun build ./src/mcp.ts --outdir=./dist --target=node && tsc --declaration --emitDeclarationOnly --outDir ./dist",
     "clean": "rm -rf dist",
     "test": "bun test",
     "typecheck": "bun tsc -p tsconfig.json --noEmit",

review.md

@@ -0,0 +1,107 @@
+# Pull Request #1 Review: Refactor Server with Base Class and Modern Patterns
+
+Hey @7heMech! 👋
+
+First off, thank you so much for taking the time to contribute to this project! I really appreciate your thoughtful improvements to the codebase. Your PR shows a deep understanding of the code structure and brings some excellent modernization ideas. Let me share my detailed review of the changes.
+
+## ✅ What I Love About This PR
+
+### 1. **Base Class Architecture** 🏗️
+
+The introduction of `BaseCallbackServer` is brilliant! This dramatically reduces code duplication across the three runtime implementations (Bun, Deno, Node.js). The shared logic for request handling, timeout management, and cleanup is now centralized, making the codebase much more maintainable.
+
+### 2. **Modern Promise Patterns with Promise.race()** ⚡
+
+Your replacement of the manual timeout handling with `Promise.race()` is exactly the kind of modernization this project needed. The old approach with `isResolved` flags and manual `clearTimeout` calls was indeed verbose and error-prone. Your solution is:
+
+- More declarative and readable
+- Less prone to race conditions
+- Following modern JavaScript best practices
+
+### 3. **Improved Resource Management** 🧹
+
+The `try...finally` block in `waitForCallback` is a significant improvement! This guarantees that listeners are always cleaned up, preventing potential memory leaks. The use of a `Map` for tracking multiple path listeners is also more robust than the single property approach.
+
+### 4. **Better Error Handling for Multiple Listeners** 🛡️
+
+The check for existing listeners on the same path prevents potential conflicts and provides clear error messages. This is a thoughtful addition that improves the developer experience.
+
+## 🔍 Areas That Need Attention
+
+### 1. **TypeScript Type Definitions Issue**
+
+While adding type packages (`@types/deno`, `@types/node`) was a good intention, there's a compilation issue. The TypeScript compiler can't find the Deno global even with the types installed. The PR still requires `@ts-ignore` comments for Deno globals, which somewhat defeats the purpose of adding the type packages.
+
+**Critical issue with Node.js type imports:**
+The PR adds `import type { Server as HttpServer } from "node:http"` at the top level, which is problematic for a cross-runtime library:
+
+- These imports will fail in Bun and Deno environments
+- Goes against the cross-runtime design principle
+- The `any` type for runtime-specific servers is actually the correct pattern here
+
+**Current state:**
+
+- Build fails without `@ts-ignore` for Deno globals
+- The added type packages aren't fully utilized
+- Node-specific type imports break cross-runtime compatibility
+
+### 2. **Type Safety Could Be Stronger**
+
+While the base class reduces duplication, we're still using `any` for runtime-specific server types (e.g., `Bun.Server`). With the type packages added, we could potentially use the proper types:
+
+```typescript
+private server?: Bun.Server;  // Instead of any
+```
+
+### 3. **Minor Implementation Details**
+
+- The `generateCallbackHTML` function refactor is cleaner but changes the logic flow slightly (early return vs. nested if)
+- The Node.js implementation now uses `req.headers.host` which is good, but might need validation for security
+
+## 📊 Test Results
+
+✅ All tests pass successfully (9/9 tests, 22 assertions)
+✅ Examples run without issues
+✅ Server functionality remains intact
+
+## 🎯 Suggestions for Improvement
+
+1. **Consider conditional type imports** instead of adding all type packages:
+
+   ```typescript
+   /// <reference types="bun-types" />
+   ```
+
+   Only in files where needed, keeping the package lighter.
+
+2. **Type the server properties properly** if keeping the type packages:
+
+   ```typescript
+   private server?: Bun.Server;  // For BunCallbackServer
+   private server?: HttpServer;  // For NodeCallbackServer
+   ```
+
+3. **Document the breaking changes** if any - the refactoring might affect error messages or timing slightly.
+
+## 🚀 Overall Assessment
+
+This is a **high-quality PR** that brings meaningful improvements to the codebase! The architectural changes with the base class pattern and modernized Promise handling are exactly what this project needed. While there are some minor issues with the TypeScript types that need resolution, the core improvements are solid and valuable.
+
+The code is cleaner, more maintainable, and follows modern JavaScript/TypeScript best practices. Your attention to detail in areas like resource cleanup and error handling shows careful consideration of edge cases.
+
+## 📝 Recommendation
+
+I recommend **accepting this PR with modifications**:
+
+1. **Remove the Node.js type imports** (`import type { Server as HttpServer } from "node:http"`) - these break cross-runtime compatibility
+2. Either remove the unused type packages or keep `any` types for runtime-specific code
+3. Ensure TypeScript compilation works without errors
+4. Consider adding a comment about the Map-based listener approach for future maintainers
+
+Thank you again for this excellent contribution! Your efforts to modernize the codebase while maintaining backward compatibility are truly appreciated. The improvements you've made will benefit all users of this library. 🙏
+
+Keep up the great work, and I look forward to any future contributions you might have!
+
+---
+
+_Review by @koistya_

src/index.ts

@@ -15,15 +15,13 @@ export type { CallbackResult, CallbackServer, ServerOptions } from "./server";
 export { OAuthError } from "./errors";
 export type { GetAuthCodeOptions } from "./types";
 
-// MCP auth providers
-export { browserAuth } from "./auth/browser-auth";
-
-// Storage implementations
+// Storage implementations (backward compatibility)
 export { inMemoryStore } from "./storage/memory";
 export { fileStore } from "./storage/file";
 
-// MCP types
-export type { BrowserAuthOptions, Tokens, TokenStore } from "./mcp-types";
+// MCP namespace export
+import * as mcp from "./mcp";
+export { mcp };
 
 /**
  * Captures OAuth authorization code via localhost callback.

src/mcp.ts

@@ -0,0 +1,23 @@
+/* SPDX-FileCopyrightText: 2025-present Kriasoft */
+/* SPDX-License-Identifier: MIT */
+
+/**
+ * MCP SDK-specific OAuth providers and utilities.
+ * For Model Context Protocol integration.
+ *
+ * @module oauth-callback/mcp
+ */
+
+export { browserAuth } from "./auth/browser-auth";
+
+export { inMemoryStore } from "./storage/memory";
+export { fileStore } from "./storage/file";
+
+export type {
+  BrowserAuthOptions,
+  Tokens,
+  TokenStore,
+  ClientInfo,
+  OAuthSession,
+  OAuthStore,
+} from "./mcp-types";