oauth-callback 0.1.2 → 1.1.0

package/README.md

@@ -5,17 +5,23 @@
 [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/kriasoft/oauth-callback/blob/main/LICENSE)
 [![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
 
-A lightweight local HTTP server for handling OAuth 2.0 authorization callbacks in Node.js, Deno, and Bun applications. Perfect for CLI tools, desktop applications, and development environments that need to capture OAuth authorization codes.
+A lightweight OAuth 2.0 callback handler for Node.js, Deno, and Bun with built-in browser flow and MCP SDK integration. Perfect for CLI tools, desktop applications, and development environments that need to capture OAuth authorization codes.
+
+<div align="center">
+  <img src="https://raw.githubusercontent.com/kriasoft/oauth-callback/main/examples/notion.gif" alt="OAuth Callback Demo" width="100%" style="max-width: 800px; height: auto;">
+</div>
 
 ## Features
 
 - 🚀 **Multi-runtime support** - Works with Node.js 18+, Deno, and Bun
 - 🔒 **Secure localhost-only server** for OAuth callbacks
+- 🤖 **MCP SDK integration** - Built-in OAuth provider for Model Context Protocol
 - ⚡ **Minimal dependencies** - Only requires `open` package
 - 🎯 **TypeScript support** out of the box
 - 🛡️ **Comprehensive OAuth error handling** with detailed error classes
 - 🔄 **Automatic server cleanup** after callback
-- 🎪 **Auto-closing success pages** with countdown timer
+- 💾 **Flexible token storage** - In-memory and file-based options
+- 🎪 **Clean success pages** with animated checkmark
 - 🎨 **Customizable HTML templates** with placeholder support
 - 🚦 **AbortSignal support** for programmatic cancellation
 - 📝 **Request logging and debugging** callbacks
@@ -36,13 +42,21 @@ npm install oauth-callback
 ## Quick Start
 
 ```typescript
-import { getAuthCode, OAuthError } from "oauth-callback";
+import {
+  getAuthCode,
+  OAuthError,
+  browserAuth,
+  fileStore,
+} 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
+const authProvider = browserAuth({ store: fileStore() });
 ```
 
 ## Usage Examples
@@ -120,6 +134,71 @@ const microsoftAuth = await getAuthCode(
 );
 ```
 
+### MCP SDK Integration
+
+The `browserAuth()` function provides a drop-in OAuth provider for the Model Context Protocol SDK:
+
+```typescript
+import { browserAuth, inMemoryStore } from "oauth-callback";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+
+// Create MCP-compatible OAuth provider
+const authProvider = browserAuth({
+  port: 3000,
+  scope: "read write",
+  store: inMemoryStore(), // Or fileStore() for persistence
+});
+
+// Use with MCP SDK transport
+const transport = new StreamableHTTPClientTransport(
+  new URL("https://mcp.notion.com/mcp"),
+  { authProvider },
+);
+
+const client = new Client(
+  { name: "my-app", version: "1.0.0" },
+  { capabilities: {} },
+);
+
+await client.connect(transport);
+```
+
+#### Token Storage Options
+
+```typescript
+import { browserAuth, inMemoryStore, fileStore } from "oauth-callback";
+
+// Ephemeral storage (tokens lost on restart)
+const ephemeralAuth = browserAuth({
+  store: inMemoryStore(),
+});
+
+// Persistent file storage (default: ~/.mcp/tokens.json)
+const persistentAuth = browserAuth({
+  store: fileStore(),
+  storeKey: "my-app-tokens", // Namespace for multiple apps
+});
+
+// Custom file location
+const customAuth = browserAuth({
+  store: fileStore("/path/to/tokens.json"),
+});
+```
+
+#### Pre-configured Client Credentials
+
+If you have pre-registered OAuth client credentials:
+
+```typescript
+const authProvider = browserAuth({
+  clientId: "your-client-id",
+  clientSecret: "your-client-secret",
+  scope: "read write",
+  store: fileStore(), // Persist tokens across sessions
+});
+```
+
 ### Advanced Usage
 
 ```typescript
@@ -202,6 +281,50 @@ class OAuthError extends Error {
 }
 ```
 
+### `browserAuth(options)`
+
+Creates an MCP SDK-compatible OAuth provider for browser-based flows. Handles Dynamic Client Registration (DCR), token storage, and automatic refresh.
+
+#### Parameters
+
+- `options` (BrowserAuthOptions): Configuration object with:
+  - `port` (number): Port for callback server (default: 3000)
+  - `hostname` (string): Hostname to bind to (default: "localhost")
+  - `callbackPath` (string): URL path for OAuth callback (default: "/callback")
+  - `scope` (string): OAuth scopes to request
+  - `clientId` (string): Pre-registered client ID (optional)
+  - `clientSecret` (string): Pre-registered client secret (optional)
+  - `store` (TokenStore): Token storage implementation (default: inMemoryStore())
+  - `storeKey` (string): Storage key for tokens (default: "mcp-tokens")
+  - `authTimeout` (number): Authorization timeout in ms (default: 300000)
+  - `successHtml` (string): Custom success page HTML
+  - `errorHtml` (string): Custom error page HTML
+  - `onRequest` (function): Request logging callback
+
+#### Returns
+
+OAuthClientProvider compatible with MCP SDK transports.
+
+### `inMemoryStore()`
+
+Creates an ephemeral in-memory token store. Tokens are lost when the process exits.
+
+#### Returns
+
+TokenStore implementation for temporary token storage.
+
+### `fileStore(filepath?)`
+
+Creates a persistent file-based token store.
+
+#### Parameters
+
+- `filepath` (string): Optional custom file path (default: `~/.mcp/tokens.json`)
+
+#### Returns
+
+TokenStore implementation for persistent token storage.
+
 ## How It Works
 
 1. **Server Creation**: Creates a temporary HTTP server on the specified port
@@ -239,9 +362,11 @@ The demo showcases:
 - Custom HTML templates for success/error pages
 - Token exchange and API usage simulation
 
-### Real OAuth Example (GitHub)
+### Real OAuth Examples
 
-For testing with a real OAuth provider:
+#### GitHub OAuth
+
+For testing with GitHub OAuth:
 
 ```bash
 # Set up GitHub OAuth App credentials
@@ -259,6 +384,23 @@ This example demonstrates:
 - Exchanging the code for an access token
 - Using the token to fetch user information
 
+#### Notion MCP with Dynamic Client Registration
+
+For testing with Notion's Model Context Protocol server:
+
+```bash
+# No credentials needed - uses Dynamic Client Registration!
+bun run example:notion
+```
+
+This example demonstrates:
+
+- Dynamic Client Registration (OAuth 2.0 DCR) - no pre-configured client ID/secret needed
+- Integration with Model Context Protocol (MCP) servers
+- Automatic client registration with the authorization server
+- Using `browserAuth()` provider with MCP SDK's `StreamableHTTPClientTransport`
+- Token persistence with `inMemoryStore()` for ephemeral sessions
+
 ## Development
 
 ```bash
@@ -274,6 +416,7 @@ bun run build
 # Run examples
 bun run example:demo    # Interactive demo
 bun run example:github  # GitHub OAuth example
+bun run example:notion  # Notion MCP example with Dynamic Client Registration
 ```
 
 ## Requirements
@@ -314,6 +457,17 @@ Contributions are welcome! Please feel free to submit a Pull Request.
 
 This project is released under the MIT License. Feel free to use it in your projects, modify it to suit your needs, and share it with others. We believe in open source and hope this tool makes OAuth integration easier for everyone!
 
+## Related Projects
+
+- [**MCP Client Generator**](https://github.com/kriasoft/mcp-client-gen) - Generate TypeScript clients from MCP server specifications. Perfect companion for building MCP-enabled applications with OAuth support ([npm](https://www.npmjs.com/package/mcp-client-gen)).
+- [**React Starter Kit**](https://github.com/kriasoft/react-starter-kit) - Full-stack React application template with authentication, including OAuth integration examples.
+
+## Backers
+
+Support this project by becoming a backer. Your logo will show up here with a link to your website.
+
+<a href="https://reactstarter.com/b/1"><img src="https://reactstarter.com/b/1.png" height="60" /></a>&nbsp;&nbsp;<a href="https://reactstarter.com/b/2"><img src="https://reactstarter.com/b/2.png" height="60" /></a>&nbsp;&nbsp;<a href="https://reactstarter.com/b/3"><img src="https://reactstarter.com/b/3.png" height="60" /></a>&nbsp;&nbsp;<a href="https://reactstarter.com/b/4"><img src="https://reactstarter.com/b/4.png" height="60" /></a>&nbsp;&nbsp;<a href="https://reactstarter.com/b/5"><img src="https://reactstarter.com/b/5.png" height="60" /></a>&nbsp;&nbsp;<a href="https://reactstarter.com/b/6"><img src="https://reactstarter.com/b/6.png" height="60" /></a>&nbsp;&nbsp;<a href="https://reactstarter.com/b/7"><img src="https://reactstarter.com/b/7.png" height="60" /></a>&nbsp;&nbsp;<a href="https://reactstarter.com/b/8"><img src="https://reactstarter.com/b/8.png" height="60" /></a>
+
 ## Support
 
 Found a bug or have a question? Please open an issue on the [GitHub issue tracker](https://github.com/kriasoft/oauth-callback/issues) and we'll be happy to help. If this project saves you time and you'd like to support its continued development, consider [becoming a sponsor](https://github.com/sponsors/koistya). Every bit of support helps maintain and improve this tool for the community. Thank you!

package/dist/auth/browser-auth.d.ts

@@ -0,0 +1,18 @@
+import type { BrowserAuthOptions } from "../mcp-types";
+import type { OAuthClientProvider } from "@modelcontextprotocol/sdk/client/auth.js";
+/**
+ * Factory for MCP SDK-compatible OAuth provider using browser flow.
+ *
+ * @param options Configuration for OAuth flow behavior
+ * @returns OAuthClientProvider for MCP SDK transport
+ *
+ * @example
+ * ```typescript
+ * const transport = new StreamableHTTPClientTransport(
+ *   new URL("https://mcp.notion.com/mcp"),
+ *   { authProvider: browserAuth() }
+ * );
+ * ```
+ */
+export declare function browserAuth(options?: BrowserAuthOptions): OAuthClientProvider;
+//# sourceMappingURL=browser-auth.d.ts.map

package/dist/auth/browser-auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-auth.d.ts","sourceRoot":"","sources":["../../src/auth/browser-auth.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,kBAAkB,EAMnB,MAAM,cAAc,CAAC;AAKtB,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0CAA0C,CAAC;AAQpF;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CACzB,OAAO,GAAE,kBAAuB,GAC/B,mBAAmB,CAErB"}

package/dist/auth/browser-auth.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=browser-auth.test.d.ts.map

package/dist/auth/browser-auth.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-auth.test.d.ts","sourceRoot":"","sources":["../../src/auth/browser-auth.test.ts"],"names":[],"mappings":""}

package/dist/index.d.ts

@@ -3,27 +3,26 @@ import type { GetAuthCodeOptions } from "./types";
 export type { CallbackResult, CallbackServer, ServerOptions } from "./server";
 export { OAuthError } from "./errors";
 export type { GetAuthCodeOptions } from "./types";
+export { browserAuth } from "./auth/browser-auth";
+export { inMemoryStore } from "./storage/memory";
+export { fileStore } from "./storage/file";
+export type { BrowserAuthOptions, Tokens, TokenStore } from "./mcp-types";
 /**
- * Get the OAuth authorization code from the authorization URL.
+ * Captures OAuth authorization code via localhost callback.
+ * Opens browser to auth URL, waits for provider redirect to localhost.
  *
- * Creates a temporary local HTTP server to handle the OAuth callback,
- * opens the authorization URL in the user's browser, and waits for the
- * OAuth provider to redirect back with an authorization code.
- *
- * @param input - Either a string containing the OAuth authorization URL,
- *                or a GetAuthCodeOptions object with detailed configuration
- * @returns Promise that resolves to CallbackResult containing the authorization code
- *          and other parameters, or rejects with OAuthError if authorization fails
- * @throws {OAuthError} When OAuth provider returns an error (e.g., access_denied)
- * @throws {Error} For timeout, network errors, or other unexpected failures
+ * @param input - Auth URL string or GetAuthCodeOptions with config
+ * @returns Promise<CallbackResult> with code and params
+ * @throws {OAuthError} Provider errors (access_denied, invalid_scope)
+ * @throws {Error} Timeout, network failures, port conflicts
  *
  * @example
  * ```typescript
- * // Simple usage with URL string
+ * // Simple
  * const result = await getAuthCode('https://oauth.example.com/authorize?...');
  * console.log('Code:', result.code);
  *
- * // Advanced usage with options
+ * // Custom port/timeout
  * const result = await getAuthCode({
  *   authorizationUrl: 'https://oauth.example.com/authorize?...',
  *   port: 8080,

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAaA,OAAO,EAAwB,KAAK,cAAc,EAAE,MAAM,UAAU,CAAC;AACrE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAGlD,YAAY,EAAE,cAAc,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAC9E,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACtC,YAAY,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAsB,WAAW,CAC/B,KAAK,EAAE,kBAAkB,GAAG,MAAM,GACjC,OAAO,CAAC,cAAc,CAAC,CAqEzB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAUA,OAAO,EAAwB,KAAK,cAAc,EAAE,MAAM,UAAU,CAAC;AACrE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAElD,YAAY,EAAE,cAAc,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAC9E,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACtC,YAAY,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAGlD,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAGlD,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAG3C,YAAY,EAAE,kBAAkB,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE1E;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,WAAW,CAC/B,KAAK,EAAE,kBAAkB,GAAG,MAAM,GACjC,OAAO,CAAC,cAAc,CAAC,CA8DzB"}