@decocms/runtime 1.2.4 → 1.2.6

package/README.md

@@ -0,0 +1,770 @@
+# @decocms/runtime
+
+A TypeScript framework for building MCP (Model Context Protocol) servers with first-class support for tools, prompts, resources, OAuth authentication, and event-driven architectures.
+
+## Installation
+
+```bash
+bun add @decocms/runtime
+```
+
+Or with npm:
+
+```bash
+npm install @decocms/runtime
+```
+
+## Quick Start
+
+Create a simple MCP server with tools:
+
+```typescript
+import { withRuntime, createTool } from "@decocms/runtime";
+import { z } from "zod";
+
+// Define a tool
+const greetTool = createTool({
+  id: "greet",
+  description: "Greets a user by name",
+  inputSchema: z.object({
+    name: z.string().describe("Name of the person to greet"),
+  }),
+  outputSchema: z.object({
+    message: z.string(),
+  }),
+  execute: async ({ context }) => {
+    return { message: `Hello, ${context.name}!` };
+  },
+});
+
+// Create the MCP server
+export default withRuntime({
+  tools: [() => greetTool],
+});
+```
+
+The server automatically exposes an MCP endpoint at `/mcp` that handles all MCP protocol requests.
+
+## Core Concepts
+
+### withRuntime
+
+The `withRuntime` function is the main entry point for creating an MCP server. It accepts configuration options and returns a fetch handler compatible with Cloudflare Workers, Bun, and other web standard runtimes.
+
+```typescript
+import { withRuntime } from "@decocms/runtime";
+
+export default withRuntime({
+  // Tools exposed to LLMs
+  tools: [...],
+  
+  // Prompts for guided interactions
+  prompts: [...],
+  
+  // Resources for data access
+  resources: [...],
+  
+  // Optional: Custom fetch handler for non-MCP routes
+  fetch: async (req, env, ctx) => {
+    // Handle custom routes
+    return new Response("Custom response");
+  },
+  
+  // Optional: CORS configuration
+  cors: {
+    origin: "*",
+    credentials: true,
+  },
+  
+  // Optional: OAuth configuration
+  oauth: { ... },
+  
+  // Optional: Configuration state
+  configuration: { ... },
+  
+  // Optional: Event handlers
+  events: { ... },
+  
+  // Optional: Hook before request processing
+  before: async (env) => {
+    // Initialize resources
+  },
+});
+```
+
+## Tools
+
+Tools are functions that LLMs can invoke to perform actions or retrieve data.
+
+### Creating a Tool
+
+```typescript
+import { createTool } from "@decocms/runtime";
+import { z } from "zod";
+
+const calculateTool = createTool({
+  id: "calculate",
+  description: "Performs basic arithmetic operations",
+  inputSchema: z.object({
+    operation: z.enum(["add", "subtract", "multiply", "divide"]),
+    a: z.number(),
+    b: z.number(),
+  }),
+  outputSchema: z.object({
+    result: z.number(),
+  }),
+  execute: async ({ context }) => {
+    const { operation, a, b } = context;
+    let result: number;
+    
+    switch (operation) {
+      case "add": result = a + b; break;
+      case "subtract": result = a - b; break;
+      case "multiply": result = a * b; break;
+      case "divide": result = a / b; break;
+    }
+    
+    return { result };
+  },
+});
+```
+
+### Private Tools (Authentication Required)
+
+Use `createPrivateTool` for tools that require user authentication:
+
+```typescript
+import { createPrivateTool } from "@decocms/runtime";
+
+const getUserDataTool = createPrivateTool({
+  id: "getUserData",
+  description: "Retrieves the current user's data",
+  inputSchema: z.object({}),
+  outputSchema: z.object({
+    userId: z.string(),
+    email: z.string(),
+  }),
+  execute: async ({ runtimeContext }) => {
+    // ensureAuthenticated is called automatically
+    const user = runtimeContext.env.MESH_REQUEST_CONTEXT.ensureAuthenticated();
+    return { userId: user.id, email: user.email };
+  },
+});
+```
+
+### Streamable Tools
+
+For tools that return streaming responses:
+
+```typescript
+import { createStreamableTool } from "@decocms/runtime";
+
+const streamDataTool = createStreamableTool({
+  id: "streamData",
+  description: "Streams data as a response",
+  inputSchema: z.object({
+    query: z.string(),
+  }),
+  streamable: true,
+  execute: async ({ context }) => {
+    // Return a streaming Response
+    const stream = new ReadableStream({
+      async start(controller) {
+        controller.enqueue(new TextEncoder().encode("Chunk 1\n"));
+        controller.enqueue(new TextEncoder().encode("Chunk 2\n"));
+        controller.close();
+      },
+    });
+    
+    return new Response(stream, {
+      headers: { "Content-Type": "text/plain" },
+    });
+  },
+});
+```
+
+### Registering Tools
+
+Tools can be registered in multiple ways:
+
+```typescript
+export default withRuntime({
+  // Option 1: Array of tool factories
+  tools: [
+    () => greetTool,
+    () => calculateTool,
+    (env) => createDynamicTool(env),
+  ],
+  
+  // Option 2: Single function returning array
+  tools: async (env) => {
+    return [greetTool, calculateTool];
+  },
+});
+```
+
+## Prompts
+
+Prompts define guided interactions with predefined templates.
+
+### Creating a Prompt
+
+```typescript
+import { createPrompt, createPublicPrompt } from "@decocms/runtime";
+import { z } from "zod";
+
+const codeReviewPrompt = createPrompt({
+  name: "code-review",
+  title: "Code Review",
+  description: "Provides a structured code review",
+  argsSchema: {
+    code: z.string().describe("The code to review"),
+    language: z.string().optional().describe("Programming language"),
+  },
+  execute: async ({ args }) => {
+    return {
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: `Please review this ${args.language ?? "code"}:\n\n${args.code}`,
+          },
+        },
+      ],
+    };
+  },
+});
+
+// Public prompt (no auth required)
+const welcomePrompt = createPublicPrompt({
+  name: "welcome",
+  title: "Welcome Message",
+  description: "Generates a welcome message",
+  execute: async () => {
+    return {
+      messages: [
+        {
+          role: "user",
+          content: { type: "text", text: "Welcome to our MCP server!" },
+        },
+      ],
+    };
+  },
+});
+```
+
+## Resources
+
+Resources expose data that LLMs can read.
+
+### Creating a Resource
+
+```typescript
+import { createResource, createPublicResource } from "@decocms/runtime";
+
+const configResource = createResource({
+  uri: "config://app",
+  name: "App Configuration",
+  description: "Current application configuration",
+  mimeType: "application/json",
+  read: async ({ runtimeContext }) => {
+    const config = await loadConfig();
+    return {
+      uri: "config://app",
+      mimeType: "application/json",
+      text: JSON.stringify(config, null, 2),
+    };
+  },
+});
+
+// URI templates for dynamic resources
+const fileResource = createPublicResource({
+  uri: "file://{path}",
+  name: "File Reader",
+  description: "Reads file contents",
+  read: async ({ uri }) => {
+    const path = uri.pathname;
+    const content = await readFile(path);
+    return {
+      uri: uri.toString(),
+      mimeType: "text/plain",
+      text: content,
+    };
+  },
+});
+```
+
+## OAuth Authentication
+
+Enable OAuth for protected MCP endpoints:
+
+```typescript
+import { withRuntime, type OAuthConfig } from "@decocms/runtime";
+
+const oauthConfig: OAuthConfig = {
+  mode: "PKCE",
+  
+  // External OAuth provider URL
+  authorizationServer: "https://your-oauth-provider.com",
+  
+  // Generate authorization URL
+  authorizationUrl: (callbackUrl) => {
+    const url = new URL("https://your-oauth-provider.com/authorize");
+    url.searchParams.set("client_id", "your-client-id");
+    url.searchParams.set("redirect_uri", callbackUrl);
+    url.searchParams.set("response_type", "code");
+    url.searchParams.set("scope", "openid profile email");
+    return url.toString();
+  },
+  
+  // Exchange authorization code for tokens
+  exchangeCode: async ({ code, redirect_uri }) => {
+    const response = await fetch("https://your-oauth-provider.com/token", {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      body: new URLSearchParams({
+        grant_type: "authorization_code",
+        code,
+        redirect_uri: redirect_uri!,
+        client_id: "your-client-id",
+        client_secret: "your-client-secret",
+      }),
+    });
+    return response.json();
+  },
+  
+  // Optional: Refresh token support
+  refreshToken: async (refreshToken) => {
+    const response = await fetch("https://your-oauth-provider.com/token", {
+      method: "POST",
+      body: new URLSearchParams({
+        grant_type: "refresh_token",
+        refresh_token: refreshToken,
+      }),
+    });
+    return response.json();
+  },
+};
+
+export default withRuntime({
+  oauth: oauthConfig,
+  tools: [...],
+});
+```
+
+OAuth endpoints are automatically exposed:
+- `/.well-known/oauth-protected-resource` - Resource metadata
+- `/.well-known/oauth-authorization-server` - Server metadata
+- `/authorize` - Authorization endpoint
+- `/oauth/callback` - OAuth callback
+- `/token` - Token endpoint
+- `/register` - Dynamic client registration
+
+## Configuration State
+
+Define typed configuration state that persists across requests:
+
+```typescript
+import { withRuntime, BindingOf } from "@decocms/runtime";
+import { z } from "zod";
+
+// Define your state schema
+const stateSchema = z.object({
+  apiKey: z.string(),
+  maxTokens: z.number().default(1000),
+  // Bindings reference other MCP connections
+  database: BindingOf<MyRegistry, "@deco/database">("@deco/database"),
+});
+
+export default withRuntime({
+  configuration: {
+    state: stateSchema,
+    scopes: ["API_KEY::read", "DATABASE::query"],
+    
+    // Called when configuration changes
+    onChange: async (env, { state, scopes }) => {
+      console.log("Configuration updated:", state);
+    },
+  },
+  
+  tools: [
+    (env) => createTool({
+      id: "query",
+      inputSchema: z.object({ sql: z.string() }),
+      execute: async ({ runtimeContext }) => {
+        // Access resolved bindings from state
+        const { database } = runtimeContext.env.MESH_REQUEST_CONTEXT.state;
+        return database.QUERY({ sql: context.sql });
+      },
+    }),
+  ],
+});
+```
+
+## Event Handlers
+
+Subscribe to events from other MCP connections:
+
+```typescript
+import { withRuntime, SELF } from "@decocms/runtime";
+
+export default withRuntime({
+  configuration: {
+    state: z.object({
+      database: BindingOf<Registry, "@deco/database">("@deco/database"),
+    }),
+  },
+  
+  events: {
+    // Subscribe to events from the database binding
+    database: {
+      // Per-event handlers
+      "record.created": async ({ events }, env) => {
+        for (const event of events) {
+          console.log("New record:", event.data);
+        }
+        return { success: true };
+      },
+      "record.deleted": async ({ events }, env) => {
+        return { success: true };
+      },
+    },
+    
+    // Subscribe to events from self (this connection)
+    SELF: {
+      "order.completed": async ({ events }, env) => {
+        return { success: true };
+      },
+    },
+  },
+});
+
+// Or use batch handlers for multiple event types
+export default withRuntime({
+  events: {
+    handler: async ({ events }, env) => {
+      // Process all events in batch
+      return { success: true };
+    },
+    events: [
+      "SELF::order.created",
+      "database::record.updated",
+    ],
+  },
+});
+```
+
+## Bindings
+
+Bindings define standardized interfaces that MCP servers can implement.
+
+### Using Existing Bindings
+
+```typescript
+import { impl, WellKnownBindings } from "@decocms/runtime/bindings";
+
+// Implement a channel binding
+const channelTools = impl(WellKnownBindings.Channel, [
+  {
+    description: "Join a channel",
+    handler: async ({ workspace, channelId }) => {
+      // Implementation
+      return { success: true, channelId };
+    },
+  },
+  {
+    description: "Leave a channel",
+    handler: async ({ channelId }) => {
+      return { success: true };
+    },
+  },
+]);
+
+export default withRuntime({
+  tools: [() => channelTools].flat(),
+});
+```
+
+### Creating Custom Bindings
+
+```typescript
+import { z } from "zod";
+import type { Binder } from "@decocms/runtime/bindings";
+
+// Define your binding schema
+export const MY_BINDING = [
+  {
+    name: "MY_TOOL_ACTION" as const,
+    inputSchema: z.object({
+      param: z.string(),
+    }),
+    outputSchema: z.object({
+      result: z.string(),
+    }),
+  },
+  {
+    name: "MY_TOOL_QUERY" as const,
+    inputSchema: z.object({}),
+    outputSchema: z.object({
+      items: z.array(z.string()),
+    }),
+    opt: true, // Optional tool
+  },
+] as const satisfies Binder;
+```
+
+## Custom Fetch Handler
+
+Handle non-MCP routes alongside your MCP server:
+
+```typescript
+export default withRuntime({
+  tools: [...],
+  
+  fetch: async (req, env, ctx) => {
+    const url = new URL(req.url);
+    
+    if (url.pathname === "/api/health") {
+      return new Response(JSON.stringify({ status: "ok" }), {
+        headers: { "Content-Type": "application/json" },
+      });
+    }
+    
+    if (url.pathname.startsWith("/api/")) {
+      // Handle API routes
+      return handleApiRoutes(req, env);
+    }
+    
+    return new Response("Not Found", { status: 404 });
+  },
+});
+```
+
+## CORS Configuration
+
+Configure CORS for browser-based MCP clients:
+
+```typescript
+export default withRuntime({
+  cors: {
+    origin: ["https://example.com", "http://localhost:3000"],
+    credentials: true,
+    allowMethods: ["GET", "POST", "OPTIONS"],
+    allowHeaders: ["Content-Type", "Authorization", "mcp-protocol-version"],
+  },
+  
+  // Or disable CORS entirely
+  cors: false,
+});
+```
+
+## Accessing Request Context
+
+Access request context within tools:
+
+```typescript
+const myTool = createTool({
+  id: "contextDemo",
+  inputSchema: z.object({}),
+  execute: async ({ runtimeContext }) => {
+    const { env, req } = runtimeContext;
+    
+    // Access MESH_REQUEST_CONTEXT for auth and bindings
+    const ctx = env.MESH_REQUEST_CONTEXT;
+    
+    // Get authenticated user (throws if not authenticated)
+    const user = ctx.ensureAuthenticated();
+    
+    // Access resolved binding state
+    const state = ctx.state;
+    
+    // Get connection info
+    const { connectionId, organizationId, meshUrl } = ctx;
+    
+    // Access original request
+    const userAgent = req?.headers.get("user-agent");
+    
+    return { userId: user.id };
+  },
+});
+```
+
+## Complete Example
+
+Here's a complete example of an MCP server with tools, prompts, resources, and OAuth:
+
+```typescript
+import { 
+  withRuntime, 
+  createTool, 
+  createPrivateTool,
+  createPrompt,
+  createResource,
+} from "@decocms/runtime";
+import { z } from "zod";
+
+// Public tool - no auth required
+const echoTool = createTool({
+  id: "echo",
+  description: "Echoes the input message",
+  inputSchema: z.object({
+    message: z.string(),
+  }),
+  outputSchema: z.object({
+    echo: z.string(),
+  }),
+  execute: async ({ context }) => {
+    return { echo: context.message };
+  },
+});
+
+// Private tool - requires authentication
+const getProfileTool = createPrivateTool({
+  id: "getProfile",
+  description: "Gets the current user's profile",
+  inputSchema: z.object({}),
+  outputSchema: z.object({
+    id: z.string(),
+    email: z.string(),
+    name: z.string(),
+  }),
+  execute: async ({ runtimeContext }) => {
+    const user = runtimeContext.env.MESH_REQUEST_CONTEXT.ensureAuthenticated();
+    return {
+      id: user.id,
+      email: user.email,
+      name: user.user_metadata.full_name,
+    };
+  },
+});
+
+// Prompt template
+const analyzePrompt = createPrompt({
+  name: "analyze",
+  title: "Analyze Data",
+  description: "Analyzes provided data and returns insights",
+  argsSchema: {
+    data: z.string().describe("JSON data to analyze"),
+  },
+  execute: async ({ args }) => ({
+    messages: [
+      {
+        role: "user",
+        content: {
+          type: "text",
+          text: `Analyze this data and provide insights:\n\n${args.data}`,
+        },
+      },
+    ],
+  }),
+});
+
+// Resource
+const statusResource = createResource({
+  uri: "status://server",
+  name: "Server Status",
+  description: "Current server status and metrics",
+  mimeType: "application/json",
+  read: async () => ({
+    uri: "status://server",
+    mimeType: "application/json",
+    text: JSON.stringify({
+      status: "healthy",
+      uptime: process.uptime(),
+      timestamp: new Date().toISOString(),
+    }),
+  }),
+});
+
+// Export the MCP server
+export default withRuntime({
+  tools: [
+    () => echoTool,
+    () => getProfileTool,
+  ],
+  prompts: [
+    () => analyzePrompt,
+  ],
+  resources: [
+    () => statusResource,
+  ],
+  cors: {
+    origin: "*",
+    credentials: true,
+  },
+});
+```
+
+## API Reference
+
+### Types
+
+- `Tool<TSchemaIn, TSchemaOut>` - Tool definition with typed input/output
+- `StreamableTool<TSchemaIn>` - Tool that returns streaming Response
+- `Prompt<TArgs>` - Prompt definition with typed arguments
+- `Resource` - Resource definition
+- `OAuthConfig` - OAuth configuration
+- `CreateMCPServerOptions` - Full options for withRuntime
+- `RequestContext` - Request context with auth and bindings
+- `AppContext` - Runtime context passed to execute functions
+
+### Functions
+
+- `withRuntime(options)` - Create an MCP server
+- `createTool(opts)` - Create a public tool
+- `createPrivateTool(opts)` - Create an authenticated tool
+- `createStreamableTool(opts)` - Create a streaming tool
+- `createPrompt(opts)` - Create an authenticated prompt
+- `createPublicPrompt(opts)` - Create a public prompt
+- `createResource(opts)` - Create an authenticated resource
+- `createPublicResource(opts)` - Create a public resource
+- `BindingOf(name)` - Create a binding reference schema
+
+### Exports
+
+```typescript
+// Main entry
+import { withRuntime, createTool, ... } from "@decocms/runtime";
+
+// Bindings utilities
+import { impl, WellKnownBindings, ... } from "@decocms/runtime/bindings";
+
+// MCP client utilities
+import { createMCPFetchStub, MCPClient } from "@decocms/runtime/client";
+
+// Proxy utilities
+import { ... } from "@decocms/runtime/proxy";
+
+// Tool utilities
+import { ... } from "@decocms/runtime/tools";
+```
+
+## Deployment
+
+The server works with any Web Standard runtime:
+
+**Cloudflare Workers:**
+```typescript
+export default withRuntime({ tools: [...] });
+```
+
+**Bun:**
+```typescript
+const server = withRuntime({ tools: [...] });
+Bun.serve({
+  port: 3000,
+  fetch: server.fetch,
+});
+```
+
+**Node.js (with adapter):**
+```typescript
+import { serve } from "@hono/node-server";
+const server = withRuntime({ tools: [...] });
+serve({ fetch: server.fetch, port: 3000 });
+```
+
+## License
+
+See the root LICENSE.md file in the repository.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/runtime",
-  "version": "1.2.4",
+  "version": "1.2.6",
   "type": "module",
   "scripts": {
     "check": "tsc --noEmit",
@@ -8,8 +8,8 @@
   },
   "dependencies": {
     "@cloudflare/workers-types": "^4.20250617.0",
-    "@decocms/bindings": "^1.1.1",
-    "@modelcontextprotocol/sdk": "1.25.2",
+    "@decocms/bindings": "^1.0.7",
+    "@modelcontextprotocol/sdk": "1.25.3",
     "@ai-sdk/provider": "^3.0.0",
     "hono": "^4.10.7",
     "jose": "^6.0.11",

package/src/oauth.ts

@@ -56,11 +56,16 @@ interface PendingAuthState {
   clientState?: string;
   codeChallenge?: string;
   codeChallengeMethod?: string;
+  /** The clean callback URL used for OAuth (without state param) - used in token exchange */
+  oauthCallbackUri?: string;
 }
 
 interface CodePayload {
   accessToken: string;
   tokenType: string;
+  refreshToken?: string;
+  expiresIn?: number;
+  scope?: string;
   codeChallenge?: string;
   codeChallengeMethod?: string;
 }
@@ -154,17 +159,22 @@ export function createOAuthHandlers(oauth: OAuthConfig) {
       );
     }
 
-    // Encode pending auth state
+    // Build callback URL pointing to our internal callback (without state yet)
+    const callbackUrl = forceHttps(new URL(`${url.origin}/oauth/callback`));
+    // Store the clean callback URL for token exchange
+    const oauthCallbackUri = callbackUrl.toString();
+
+    // Encode pending auth state (including the clean callback URL)
     const pendingState: PendingAuthState = {
       redirectUri,
       clientState: clientState ?? undefined,
       codeChallenge: codeChallenge ?? undefined,
       codeChallengeMethod: codeChallengeMethod ?? undefined,
+      oauthCallbackUri,
     };
     const encodedState = encodeState(pendingState);
 
-    // Build callback URL pointing to our internal callback
-    const callbackUrl = forceHttps(new URL(`${url.origin}/oauth/callback`));
+    // Add state to callback URL
     callbackUrl.searchParams.set("state", encodedState);
 
     // Get the external authorization URL from the config
@@ -217,14 +227,26 @@ export function createOAuthHandlers(oauth: OAuthConfig) {
     }
 
     try {
+      // Use the clean redirect_uri from the state (same URL used in authorization request)
+      // This ensures the exact same URL is used for token exchange
+      const cleanRedirectUri =
+        pending.oauthCallbackUri ??
+        forceHttps(new URL(`${url.origin}/oauth/callback`)).toString();
+
       // Exchange code with external provider
-      const oauthParams: OAuthParams = { code };
+      const oauthParams: OAuthParams = {
+        code,
+        redirect_uri: cleanRedirectUri,
+      };
       const tokenResponse = await oauth.exchangeCode(oauthParams);
 
       // Encode the token in our own code (stateless)
       const codePayload: CodePayload = {
         accessToken: tokenResponse.access_token,
         tokenType: tokenResponse.token_type,
+        refreshToken: tokenResponse.refresh_token,
+        expiresIn: tokenResponse.expires_in,
+        scope: tokenResponse.scope,
         codeChallenge: pending.codeChallenge,
         codeChallengeMethod: pending.codeChallengeMethod,
       };
@@ -257,6 +279,7 @@ export function createOAuthHandlers(oauth: OAuthConfig) {
 
   /**
    * Handle token exchange - decodes our code to get the actual token
+   * Supports both authorization_code and refresh_token grant types
    * Stateless: token is encoded in the code
    */
   const handleToken = async (req: Request): Promise<Response> => {
@@ -271,13 +294,63 @@ export function createOAuthHandlers(oauth: OAuthConfig) {
         body = await req.json();
       }
 
-      const { code, code_verifier, grant_type } = body;
+      const { code, code_verifier, grant_type, refresh_token } = body;
+
+      // Handle refresh_token grant type
+      if (grant_type === "refresh_token") {
+        if (!refresh_token) {
+          return Response.json(
+            {
+              error: "invalid_request",
+              error_description: "refresh_token is required",
+            },
+            { status: 400 },
+          );
+        }
+
+        if (!oauth.refreshToken) {
+          return Response.json(
+            {
+              error: "unsupported_grant_type",
+              error_description: "refresh_token grant not supported",
+            },
+            { status: 400 },
+          );
+        }
+
+        // Call the external provider to refresh the token
+        const newTokenResponse = await oauth.refreshToken(refresh_token);
+
+        const tokenResponse: Record<string, unknown> = {
+          access_token: newTokenResponse.access_token,
+          token_type: newTokenResponse.token_type,
+        };
+
+        if (newTokenResponse.refresh_token) {
+          tokenResponse.refresh_token = newTokenResponse.refresh_token;
+        }
+        if (newTokenResponse.expires_in !== undefined) {
+          tokenResponse.expires_in = newTokenResponse.expires_in;
+        }
+        if (newTokenResponse.scope) {
+          tokenResponse.scope = newTokenResponse.scope;
+        }
+
+        return Response.json(tokenResponse, {
+          headers: {
+            "Cache-Control": "no-store",
+            Pragma: "no-cache",
+          },
+        });
+      }
 
+      // Handle authorization_code grant type
       if (grant_type !== "authorization_code") {
         return Response.json(
           {
             error: "unsupported_grant_type",
-            error_description: "Only authorization_code supported",
+            error_description:
+              "Only authorization_code and refresh_token supported",
           },
           { status: 400 },
         );
@@ -339,19 +412,29 @@ export function createOAuthHandlers(oauth: OAuthConfig) {
         }
       }
 
-      // Return the actual token
-      return Response.json(
-        {
-          access_token: payload.accessToken,
-          token_type: payload.tokenType,
-        },
-        {
-          headers: {
-            "Cache-Control": "no-store",
-            Pragma: "no-cache",
-          },
+      // Return the actual token with all fields
+      const tokenResponse: Record<string, unknown> = {
+        access_token: payload.accessToken,
+        token_type: payload.tokenType,
+      };
+
+      // Include optional fields if present
+      if (payload.refreshToken) {
+        tokenResponse.refresh_token = payload.refreshToken;
+      }
+      if (payload.expiresIn !== undefined) {
+        tokenResponse.expires_in = payload.expiresIn;
+      }
+      if (payload.scope) {
+        tokenResponse.scope = payload.scope;
+      }
+
+      return Response.json(tokenResponse, {
+        headers: {
+          "Cache-Control": "no-store",
+          Pragma: "no-cache",
         },
-      );
+      });
     } catch (err) {
       console.error("Token exchange error:", err);
       return Response.json(

package/src/tools.ts

@@ -349,6 +349,11 @@ export interface OAuthParams {
   code: string;
   code_verifier?: string;
   code_challenge_method?: "S256" | "plain";
+  /**
+   * The redirect_uri used in the authorization request (without state/extra params).
+   * This is the clean callback URL that should be used for token exchange.
+   */
+  redirect_uri?: string;
 }
 
 export interface OAuthTokenResponse {
@@ -398,6 +403,11 @@ export interface OAuthConfig {
    * Called when the OAuth callback is received with a code
    */
   exchangeCode: (oauthParams: OAuthParams) => Promise<OAuthTokenResponse>;
+  /**
+   * Refreshes the access token using a refresh token
+   * Called when the client requests a new access token with grant_type=refresh_token
+   */
+  refreshToken?: (refreshToken: string) => Promise<OAuthTokenResponse>;
   /**
    * Optional: persistence for dynamic client registration (RFC7591)
    * If not provided, clients are accepted without validation
@@ -850,16 +860,46 @@ export const createMCPServer = <
     await server.connect(transport);
 
     try {
-      return await transport.handleRequest(req);
-    } finally {
-      // CRITICAL: Close transport to prevent memory leaks
-      // Without this, ReadableStream/WritableStream controllers accumulate
-      // causing thousands of stream objects to be retained in memory
+      const response = await transport.handleRequest(req);
+
+      // Check if this is a streaming response (SSE or streamable tool)
+      // SSE responses have text/event-stream content-type
+      // Note: response.body is always non-null for all HTTP responses, so we can't use it to detect streaming
+      const contentType = response.headers.get("content-type");
+      const isStreaming =
+        contentType?.includes("text/event-stream") ||
+        contentType?.includes("application/json-rpc");
+
+      // Only close transport for non-streaming responses
+      if (!isStreaming) {
+        console.debug(
+          "[MCP Transport] Closing transport for non-streaming response",
+        );
+        try {
+          await transport.close?.();
+        } catch {
+          // Ignore close errors
+        }
+      } else {
+        console.debug(
+          "[MCP Transport] Keeping transport open for streaming response (Content-Type: %s)",
+          contentType,
+        );
+      }
+
+      return response;
+    } catch (error) {
+      // On error, always try to close transport to prevent leaks
+      console.debug(
+        "[MCP Transport] Closing transport due to error:",
+        error instanceof Error ? error.message : error,
+      );
       try {
         await transport.close?.();
       } catch {
-        // Ignore close errors - transport may already be closed
+        // Ignore close errors
       }
+      throw error;
     }
   };