@opensaas/stack-auth 0.1.2 → 0.1.4

package/.turbo/turbo-build.log

@@ -1,4 +1,4 @@
 
-> @opensaas/stack-auth@0.1.2 build /home/runner/work/stack/stack/packages/auth
+> @opensaas/stack-auth@0.1.4 build /home/runner/work/stack/stack/packages/auth
 > tsc
 

package/CHANGELOG.md

@@ -1,5 +1,53 @@
 # @opensaas/stack-auth
 
+## 0.1.4
+
+### Patch Changes
+
+- d013859: **BREAKING CHANGE**: Migrate MCP functionality into core and auth packages
+
+  The `@opensaas/stack-mcp` package has been deprecated and its functionality has been split into:
+  - `@opensaas/stack-core/mcp` - Auth-agnostic MCP runtime and handlers
+  - `@opensaas/stack-auth/mcp` - Better Auth OAuth adapter
+
+  **Migration required:**
+
+  ```typescript
+  // Before
+  import { createMcpHandlers } from '@opensaas/stack-mcp'
+  const { GET, POST, DELETE } = createMcpHandlers({ config, auth, getContext })
+
+  // After
+  import { createMcpHandlers } from '@opensaas/stack-core/mcp'
+  import { createBetterAuthMcpAdapter } from '@opensaas/stack-auth/mcp'
+  const { GET, POST, DELETE } = createMcpHandlers({
+    config,
+    getSession: createBetterAuthMcpAdapter(auth),
+    getContext,
+  })
+  ```
+
+  **Why this change?**
+  - Reduces package count in the monorepo
+  - Core package handles auth-agnostic MCP protocol
+  - Auth package provides Better Auth specific adapter
+  - Better-auth is no longer a dependency of core
+  - Enables support for custom auth providers beyond Better Auth
+
+  **New features:**
+  - `McpSessionProvider` type for custom auth integration
+  - More generic `McpAuthConfig` type supporting custom auth providers
+  - Core MCP functionality available without auth dependencies
+
+- Updated dependencies [d013859]
+  - @opensaas/stack-core@0.1.4
+
+## 0.1.3
+
+### Patch Changes
+
+- @opensaas/stack-core@0.1.3
+
 ## 0.1.2
 
 ### Patch Changes

package/CLAUDE.md

@@ -110,9 +110,12 @@ authConfig({
 - Session flows through context to all access control functions
 - Generator creates Prisma schema with auth tables
 
-### With @opensaas/stack-mcp
+### With MCP (Model Context Protocol)
 
+- Auth provides Better Auth MCP adapter via `@opensaas/stack-auth/mcp`
 - MCP plugin enables OAuth for AI assistants
+- `createBetterAuthMcpAdapter()` converts Better Auth instance to session provider
+- Works with core MCP runtime from `@opensaas/stack-core/mcp`
 - Requires `rawOpensaasContext` from `.opensaas/context.ts`:
 
 ```typescript

package/dist/mcp/better-auth.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Better Auth integration for MCP OAuth authentication
+ * Provides session handling and authentication utilities
+ */
+import type { McpSession, McpSessionProvider } from '@opensaas/stack-core/mcp';
+/**
+ * Better Auth instance type (flexible)
+ * Uses minimal typing to avoid tight coupling with better-auth package
+ */
+export type BetterAuthInstance = {
+    api: any;
+    [key: string]: any;
+};
+/**
+ * Create Better Auth MCP session adapter
+ * Converts Better Auth instance into MCP session provider
+ *
+ * @example
+ * ```typescript
+ * import { createMcpHandlers } from '@opensaas/stack-core/mcp'
+ * import { createBetterAuthMcpAdapter } from '@opensaas/stack-auth/mcp'
+ * import config from '@/opensaas.config'
+ * import { auth } from '@/lib/auth'
+ * import { getContext } from '@/.opensaas/context'
+ *
+ * const { GET, POST, DELETE } = createMcpHandlers({
+ *   config,
+ *   getSession: createBetterAuthMcpAdapter(auth),
+ *   getContext
+ * })
+ *
+ * export { GET, POST, DELETE }
+ * ```
+ */
+export declare function createBetterAuthMcpAdapter(auth: BetterAuthInstance): McpSessionProvider;
+/**
+ * Create MCP request handler with Better Auth OAuth authentication
+ * Wraps an MCP handler to automatically authenticate and inject session
+ *
+ * @example
+ * ```typescript
+ * import { withMcpAuth } from '@opensaas/stack-auth/mcp'
+ * import { auth } from '@/lib/auth'
+ * import { createMcpServer } from '@/.opensaas/mcp/server'
+ *
+ * const handler = withMcpAuth(auth, async (req, session) => {
+ *   const server = createMcpServer(session)
+ *   return server.handleRequest(req)
+ * })
+ *
+ * export { handler as GET, handler as POST, handler as DELETE }
+ * ```
+ */
+export declare function withMcpAuth(auth: BetterAuthInstance, handler: (req: Request, session: McpSession) => Promise<Response> | Response): (req: Request) => Promise<Response>;
+/**
+ * Convert MCP session to OpenSaaS context session
+ * Allows using MCP session with OpenSaaS access control
+ *
+ * @example
+ * ```typescript
+ * const mcpSession = await auth.api.getMcpSession({ headers: req.headers })
+ * const context = getContext(mcpSessionToContextSession(mcpSession))
+ * const posts = await context.db.post.findMany()
+ * ```
+ */
+export declare function mcpSessionToContextSession(mcpSession: McpSession): {
+    userId: string;
+};
+/**
+ * Validate MCP session scopes
+ * Check if session has required OAuth scopes
+ *
+ * @example
+ * ```typescript
+ * if (!hasScopes(session, ['read:posts', 'write:posts'])) {
+ *   return new Response('Insufficient scopes', { status: 403 })
+ * }
+ * ```
+ */
+export declare function hasScopes(session: McpSession, requiredScopes: string[]): boolean;
+/**
+ * Check if MCP session is expired
+ */
+export declare function isSessionExpired(session: McpSession): boolean;
+/**
+ * Create OAuth discovery metadata handler
+ * Exposes OAuth authorization server metadata for MCP clients
+ *
+ * This should be placed at `/.well-known/oauth-authorization-server/route.ts`
+ * Better Auth already handles `/api/auth/.well-known/oauth-authorization-server`
+ * but some clients may fail to parse WWW-Authenticate headers
+ */
+export declare function createOAuthDiscoveryHandler(_auth: BetterAuthInstance): (req: Request) => Promise<Response>;
+/**
+ * Create OAuth protected resource metadata handler
+ * Exposes OAuth protected resource metadata for MCP clients
+ *
+ * This should be placed at `/.well-known/oauth-protected-resource/route.ts`
+ */
+export declare function createOAuthProtectedResourceHandler(_auth: BetterAuthInstance): (req: Request) => Promise<Response>;
+//# sourceMappingURL=better-auth.d.ts.map

package/dist/mcp/better-auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"better-auth.d.ts","sourceRoot":"","sources":["../../src/mcp/better-auth.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAA;AAE9E;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAE/B,GAAG,EAAE,GAAG,CAAA;IAER,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAA;CACnB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,kBAAkB,GAAG,kBAAkB,CAIvF;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,kBAAkB,EACxB,OAAO,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,UAAU,KAAK,OAAO,CAAC,QAAQ,CAAC,GAAG,QAAQ,GAC3E,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAoBrC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,0BAA0B,CAAC,UAAU,EAAE,UAAU,GAAG;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,CAIrF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,EAAE,GAAG,OAAO,CAGhF;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAG7D;AAED;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,kBAAkB,IACrD,KAAK,OAAO,uBAS3B;AAED;;;;;GAKG;AACH,wBAAgB,mCAAmC,CAAC,KAAK,EAAE,kBAAkB,IAC7D,KAAK,OAAO,uBAS3B"}

package/dist/mcp/better-auth.js

@@ -0,0 +1,142 @@
+/**
+ * Better Auth integration for MCP OAuth authentication
+ * Provides session handling and authentication utilities
+ */
+/**
+ * Create Better Auth MCP session adapter
+ * Converts Better Auth instance into MCP session provider
+ *
+ * @example
+ * ```typescript
+ * import { createMcpHandlers } from '@opensaas/stack-core/mcp'
+ * import { createBetterAuthMcpAdapter } from '@opensaas/stack-auth/mcp'
+ * import config from '@/opensaas.config'
+ * import { auth } from '@/lib/auth'
+ * import { getContext } from '@/.opensaas/context'
+ *
+ * const { GET, POST, DELETE } = createMcpHandlers({
+ *   config,
+ *   getSession: createBetterAuthMcpAdapter(auth),
+ *   getContext
+ * })
+ *
+ * export { GET, POST, DELETE }
+ * ```
+ */
+export function createBetterAuthMcpAdapter(auth) {
+    return async (headers) => {
+        return await auth.api.getMcpSession({ headers });
+    };
+}
+/**
+ * Create MCP request handler with Better Auth OAuth authentication
+ * Wraps an MCP handler to automatically authenticate and inject session
+ *
+ * @example
+ * ```typescript
+ * import { withMcpAuth } from '@opensaas/stack-auth/mcp'
+ * import { auth } from '@/lib/auth'
+ * import { createMcpServer } from '@/.opensaas/mcp/server'
+ *
+ * const handler = withMcpAuth(auth, async (req, session) => {
+ *   const server = createMcpServer(session)
+ *   return server.handleRequest(req)
+ * })
+ *
+ * export { handler as GET, handler as POST, handler as DELETE }
+ * ```
+ */
+export function withMcpAuth(auth, handler) {
+    return async (req) => {
+        // Extract MCP session from Better Auth
+        const session = await auth.api.getMcpSession({
+            headers: req.headers,
+        });
+        if (!session) {
+            // Return 401 with WWW-Authenticate header for OAuth clients
+            return new Response(null, {
+                status: 401,
+                headers: {
+                    'WWW-Authenticate': 'Bearer realm="MCP", error="invalid_token"',
+                },
+            });
+        }
+        // Call handler with authenticated session
+        return handler(req, session);
+    };
+}
+/**
+ * Convert MCP session to OpenSaaS context session
+ * Allows using MCP session with OpenSaaS access control
+ *
+ * @example
+ * ```typescript
+ * const mcpSession = await auth.api.getMcpSession({ headers: req.headers })
+ * const context = getContext(mcpSessionToContextSession(mcpSession))
+ * const posts = await context.db.post.findMany()
+ * ```
+ */
+export function mcpSessionToContextSession(mcpSession) {
+    return {
+        userId: mcpSession.userId,
+    };
+}
+/**
+ * Validate MCP session scopes
+ * Check if session has required OAuth scopes
+ *
+ * @example
+ * ```typescript
+ * if (!hasScopes(session, ['read:posts', 'write:posts'])) {
+ *   return new Response('Insufficient scopes', { status: 403 })
+ * }
+ * ```
+ */
+export function hasScopes(session, requiredScopes) {
+    if (!session.scopes)
+        return false;
+    return requiredScopes.every((scope) => session.scopes.includes(scope));
+}
+/**
+ * Check if MCP session is expired
+ */
+export function isSessionExpired(session) {
+    if (!session.expiresAt)
+        return false;
+    return new Date() > session.expiresAt;
+}
+/**
+ * Create OAuth discovery metadata handler
+ * Exposes OAuth authorization server metadata for MCP clients
+ *
+ * This should be placed at `/.well-known/oauth-authorization-server/route.ts`
+ * Better Auth already handles `/api/auth/.well-known/oauth-authorization-server`
+ * but some clients may fail to parse WWW-Authenticate headers
+ */
+export function createOAuthDiscoveryHandler(_auth) {
+    return async (req) => {
+        // Delegate to Better Auth's built-in handler
+        const authPath = '/api/auth/.well-known/oauth-authorization-server';
+        const authUrl = new URL(authPath, req.url);
+        return fetch(authUrl.toString(), {
+            headers: req.headers,
+        });
+    };
+}
+/**
+ * Create OAuth protected resource metadata handler
+ * Exposes OAuth protected resource metadata for MCP clients
+ *
+ * This should be placed at `/.well-known/oauth-protected-resource/route.ts`
+ */
+export function createOAuthProtectedResourceHandler(_auth) {
+    return async (req) => {
+        // Delegate to Better Auth's built-in handler
+        const authPath = '/api/auth/.well-known/oauth-protected-resource';
+        const authUrl = new URL(authPath, req.url);
+        return fetch(authUrl.toString(), {
+            headers: req.headers,
+        });
+    };
+}
+//# sourceMappingURL=better-auth.js.map

package/dist/mcp/better-auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"better-auth.js","sourceRoot":"","sources":["../../src/mcp/better-auth.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAeH;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,0BAA0B,CAAC,IAAwB;IACjE,OAAO,KAAK,EAAE,OAAgB,EAA8B,EAAE;QAC5D,OAAO,MAAM,IAAI,CAAC,GAAG,CAAC,aAAa,CAAC,EAAE,OAAO,EAAE,CAAC,CAAA;IAClD,CAAC,CAAA;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,WAAW,CACzB,IAAwB,EACxB,OAA4E;IAE5E,OAAO,KAAK,EAAE,GAAY,EAAE,EAAE;QAC5B,uCAAuC;QACvC,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,aAAa,CAAC;YAC3C,OAAO,EAAE,GAAG,CAAC,OAAO;SACrB,CAAC,CAAA;QAEF,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,4DAA4D;YAC5D,OAAO,IAAI,QAAQ,CAAC,IAAI,EAAE;gBACxB,MAAM,EAAE,GAAG;gBACX,OAAO,EAAE;oBACP,kBAAkB,EAAE,2CAA2C;iBAChE;aACF,CAAC,CAAA;QACJ,CAAC;QAED,0CAA0C;QAC1C,OAAO,OAAO,CAAC,GAAG,EAAE,OAAO,CAAC,CAAA;IAC9B,CAAC,CAAA;AACH,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,0BAA0B,CAAC,UAAsB;IAC/D,OAAO;QACL,MAAM,EAAE,UAAU,CAAC,MAAM;KAC1B,CAAA;AACH,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,SAAS,CAAC,OAAmB,EAAE,cAAwB;IACrE,IAAI,CAAC,OAAO,CAAC,MAAM;QAAE,OAAO,KAAK,CAAA;IACjC,OAAO,cAAc,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,MAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAA;AACzE,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAmB;IAClD,IAAI,CAAC,OAAO,CAAC,SAAS;QAAE,OAAO,KAAK,CAAA;IACpC,OAAO,IAAI,IAAI,EAAE,GAAG,OAAO,CAAC,SAAS,CAAA;AACvC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,2BAA2B,CAAC,KAAyB;IACnE,OAAO,KAAK,EAAE,GAAY,EAAE,EAAE;QAC5B,6CAA6C;QAC7C,MAAM,QAAQ,GAAG,kDAAkD,CAAA;QACnE,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,QAAQ,EAAE,GAAG,CAAC,GAAG,CAAC,CAAA;QAE1C,OAAO,KAAK,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE;YAC/B,OAAO,EAAE,GAAG,CAAC,OAAO;SACrB,CAAC,CAAA;IACJ,CAAC,CAAA;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,mCAAmC,CAAC,KAAyB;IAC3E,OAAO,KAAK,EAAE,GAAY,EAAE,EAAE;QAC5B,6CAA6C;QAC7C,MAAM,QAAQ,GAAG,gDAAgD,CAAA;QACjE,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,QAAQ,EAAE,GAAG,CAAC,GAAG,CAAC,CAAA;QAE1C,OAAO,KAAK,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE;YAC/B,OAAO,EAAE,GAAG,CAAC,OAAO;SACrB,CAAC,CAAA;IACJ,CAAC,CAAA;AACH,CAAC"}

package/dist/mcp/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Better Auth MCP integration
+ * OAuth authentication adapter for MCP servers
+ */
+export { createBetterAuthMcpAdapter, withMcpAuth, mcpSessionToContextSession, hasScopes, isSessionExpired, createOAuthDiscoveryHandler, createOAuthProtectedResourceHandler, } from './better-auth.js';
+export type { BetterAuthInstance } from './better-auth.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/mcp/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/mcp/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACL,0BAA0B,EAC1B,WAAW,EACX,0BAA0B,EAC1B,SAAS,EACT,gBAAgB,EAChB,2BAA2B,EAC3B,mCAAmC,GACpC,MAAM,kBAAkB,CAAA;AAEzB,YAAY,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA"}

package/dist/mcp/index.js

@@ -0,0 +1,6 @@
+/**
+ * Better Auth MCP integration
+ * OAuth authentication adapter for MCP servers
+ */
+export { createBetterAuthMcpAdapter, withMcpAuth, mcpSessionToContextSession, hasScopes, isSessionExpired, createOAuthDiscoveryHandler, createOAuthProtectedResourceHandler, } from './better-auth.js';
+//# sourceMappingURL=index.js.map

package/dist/mcp/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/mcp/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACL,0BAA0B,EAC1B,WAAW,EACX,0BAA0B,EAC1B,SAAS,EACT,gBAAgB,EAChB,2BAA2B,EAC3B,mCAAmC,GACpC,MAAM,kBAAkB,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opensaas/stack-auth",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Better-auth integration for OpenSaas Stack",
   "type": "module",
   "main": "./dist/index.js",
@@ -25,6 +25,10 @@
     "./plugins": {
       "types": "./dist/plugins/index.d.ts",
       "default": "./dist/plugins/index.js"
+    },
+    "./mcp": {
+      "types": "./dist/mcp/index.d.ts",
+      "default": "./dist/mcp/index.js"
     }
   },
   "keywords": [
@@ -39,7 +43,7 @@
     "better-auth": "^1.3.29",
     "react": "^18.0.0 || ^19.0.0",
     "next": "^15.0.0 || ^16.0.0",
-    "@opensaas/stack-core": "0.1.2"
+    "@opensaas/stack-core": "0.1.4"
   },
   "dependencies": {},
   "devDependencies": {
@@ -52,7 +56,7 @@
     "react": "^19.2.0",
     "typescript": "^5.9.3",
     "vitest": "^4.0.0",
-    "@opensaas/stack-core": "0.1.2"
+    "@opensaas/stack-core": "0.1.4"
   },
   "scripts": {
     "build": "tsc",

package/src/mcp/better-auth.ts

@@ -0,0 +1,166 @@
+/**
+ * Better Auth integration for MCP OAuth authentication
+ * Provides session handling and authentication utilities
+ */
+
+import type { McpSession, McpSessionProvider } from '@opensaas/stack-core/mcp'
+
+/**
+ * Better Auth instance type (flexible)
+ * Uses minimal typing to avoid tight coupling with better-auth package
+ */
+export type BetterAuthInstance = {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Better Auth API types vary by plugins, must use any
+  api: any
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Allows additional Better Auth instance properties
+  [key: string]: any
+}
+
+/**
+ * Create Better Auth MCP session adapter
+ * Converts Better Auth instance into MCP session provider
+ *
+ * @example
+ * ```typescript
+ * import { createMcpHandlers } from '@opensaas/stack-core/mcp'
+ * import { createBetterAuthMcpAdapter } from '@opensaas/stack-auth/mcp'
+ * import config from '@/opensaas.config'
+ * import { auth } from '@/lib/auth'
+ * import { getContext } from '@/.opensaas/context'
+ *
+ * const { GET, POST, DELETE } = createMcpHandlers({
+ *   config,
+ *   getSession: createBetterAuthMcpAdapter(auth),
+ *   getContext
+ * })
+ *
+ * export { GET, POST, DELETE }
+ * ```
+ */
+export function createBetterAuthMcpAdapter(auth: BetterAuthInstance): McpSessionProvider {
+  return async (headers: Headers): Promise<McpSession | null> => {
+    return await auth.api.getMcpSession({ headers })
+  }
+}
+
+/**
+ * Create MCP request handler with Better Auth OAuth authentication
+ * Wraps an MCP handler to automatically authenticate and inject session
+ *
+ * @example
+ * ```typescript
+ * import { withMcpAuth } from '@opensaas/stack-auth/mcp'
+ * import { auth } from '@/lib/auth'
+ * import { createMcpServer } from '@/.opensaas/mcp/server'
+ *
+ * const handler = withMcpAuth(auth, async (req, session) => {
+ *   const server = createMcpServer(session)
+ *   return server.handleRequest(req)
+ * })
+ *
+ * export { handler as GET, handler as POST, handler as DELETE }
+ * ```
+ */
+export function withMcpAuth(
+  auth: BetterAuthInstance,
+  handler: (req: Request, session: McpSession) => Promise<Response> | Response,
+): (req: Request) => Promise<Response> {
+  return async (req: Request) => {
+    // Extract MCP session from Better Auth
+    const session = await auth.api.getMcpSession({
+      headers: req.headers,
+    })
+
+    if (!session) {
+      // Return 401 with WWW-Authenticate header for OAuth clients
+      return new Response(null, {
+        status: 401,
+        headers: {
+          'WWW-Authenticate': 'Bearer realm="MCP", error="invalid_token"',
+        },
+      })
+    }
+
+    // Call handler with authenticated session
+    return handler(req, session)
+  }
+}
+
+/**
+ * Convert MCP session to OpenSaaS context session
+ * Allows using MCP session with OpenSaaS access control
+ *
+ * @example
+ * ```typescript
+ * const mcpSession = await auth.api.getMcpSession({ headers: req.headers })
+ * const context = getContext(mcpSessionToContextSession(mcpSession))
+ * const posts = await context.db.post.findMany()
+ * ```
+ */
+export function mcpSessionToContextSession(mcpSession: McpSession): { userId: string } {
+  return {
+    userId: mcpSession.userId,
+  }
+}
+
+/**
+ * Validate MCP session scopes
+ * Check if session has required OAuth scopes
+ *
+ * @example
+ * ```typescript
+ * if (!hasScopes(session, ['read:posts', 'write:posts'])) {
+ *   return new Response('Insufficient scopes', { status: 403 })
+ * }
+ * ```
+ */
+export function hasScopes(session: McpSession, requiredScopes: string[]): boolean {
+  if (!session.scopes) return false
+  return requiredScopes.every((scope) => session.scopes!.includes(scope))
+}
+
+/**
+ * Check if MCP session is expired
+ */
+export function isSessionExpired(session: McpSession): boolean {
+  if (!session.expiresAt) return false
+  return new Date() > session.expiresAt
+}
+
+/**
+ * Create OAuth discovery metadata handler
+ * Exposes OAuth authorization server metadata for MCP clients
+ *
+ * This should be placed at `/.well-known/oauth-authorization-server/route.ts`
+ * Better Auth already handles `/api/auth/.well-known/oauth-authorization-server`
+ * but some clients may fail to parse WWW-Authenticate headers
+ */
+export function createOAuthDiscoveryHandler(_auth: BetterAuthInstance) {
+  return async (req: Request) => {
+    // Delegate to Better Auth's built-in handler
+    const authPath = '/api/auth/.well-known/oauth-authorization-server'
+    const authUrl = new URL(authPath, req.url)
+
+    return fetch(authUrl.toString(), {
+      headers: req.headers,
+    })
+  }
+}
+
+/**
+ * Create OAuth protected resource metadata handler
+ * Exposes OAuth protected resource metadata for MCP clients
+ *
+ * This should be placed at `/.well-known/oauth-protected-resource/route.ts`
+ */
+export function createOAuthProtectedResourceHandler(_auth: BetterAuthInstance) {
+  return async (req: Request) => {
+    // Delegate to Better Auth's built-in handler
+    const authPath = '/api/auth/.well-known/oauth-protected-resource'
+    const authUrl = new URL(authPath, req.url)
+
+    return fetch(authUrl.toString(), {
+      headers: req.headers,
+    })
+  }
+}

package/src/mcp/index.ts

@@ -0,0 +1,16 @@
+/**
+ * Better Auth MCP integration
+ * OAuth authentication adapter for MCP servers
+ */
+
+export {
+  createBetterAuthMcpAdapter,
+  withMcpAuth,
+  mcpSessionToContextSession,
+  hasScopes,
+  isSessionExpired,
+  createOAuthDiscoveryHandler,
+  createOAuthProtectedResourceHandler,
+} from './better-auth.js'
+
+export type { BetterAuthInstance } from './better-auth.js'