refactor(cloudflare): remove Durable Object migration artifacts (#592)

Completes the Durable Objects to stateless MCP handler migration by
removing temporary migration code and unnecessary URL rewriting logic.
The MCP handler now uses the original URL path directly instead of
rewriting to /mcp, simplifying the request flow.

Changes:
- Remove temporary SentryMCP stub class used for DO migration
- Remove URL rewriting logic in mcp-handler (passes original path to
createMcpHandler)
- Update documentation to reflect stateless architecture
- Simplify tests to remove URL rewriting assertions

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

Co-authored-by: Claude <noreply@anthropic.com>

Author: dcramer

docs/cloudflare/architecture.md

@@ -137,8 +137,8 @@ const result = streamText({
 
 - **Workers**: Serverless compute for API routes
 - **Pages**: Static asset hosting for React app
-- **KV Namespace**: Token storage
-- **Durable Objects**: State management (future)
+- **KV Namespace**: OAuth token storage
+- **AI Binding**: Access to Cloudflare AI models (AutoRAG for docs search)
 - **R2**: File storage (future)
 
 ### Environment Variables

docs/cloudflare/deployment.md

@@ -5,8 +5,7 @@ Cloudflare Workers deployment configuration and patterns.
 ## Architecture Overview
 
 The deployment consists of:
-- **Worker**: Main HTTP server with OAuth flow
-- **Durable Object**: MCP transport handling WebSocket connections
+- **Worker**: Stateless HTTP server with OAuth flow and MCP handler
 - **KV Storage**: OAuth token storage
 - **Static Assets**: React UI for setup instructions
 
@@ -16,30 +15,30 @@ The deployment consists of:
 
 ```jsonc
 {
-  "name": "sentry-mcp-oauth",
+  "name": "sentry-mcp",
   "main": "./src/server/index.ts",
   "compatibility_date": "2025-03-21",
   "compatibility_flags": [
     "nodejs_compat",
-    "nodejs_compat_populate_process_env"
+    "nodejs_compat_populate_process_env",
+    "global_fetch_strictly_public"
   ],
   "keep_vars": true,
-  
+
   // Bindings
-  "durable_objects": {
-    "bindings": [{
-      "name": "SENTRY_MCP",
-      "class_name": "SentryMCP"
-    }]
-  },
   "kv_namespaces": [{
-    "binding": "KV",
-    "id": "your-kv-namespace-id"
+    "binding": "OAUTH_KV",
+    "id": "8dd5e9bafe1945298e2d5ca3b408a553"
   }],
-  
-  // SPA configuration
-  "site": {
-    "bucket": "./dist/client"
+  "ai": {
+    "binding": "AI"
+  },
+
+  // Static assets configuration
+  "assets": {
+    "directory": "./public",
+    "binding": "ASSETS",
+    "not_found_handling": "single-page-application"
   }
 }
 ```
@@ -51,7 +50,12 @@ Required in production:
 SENTRY_CLIENT_ID=your_oauth_app_id
 SENTRY_CLIENT_SECRET=your_oauth_app_secret
 COOKIE_SECRET=32_char_random_string
-SENTRY_HOST=sentry.io  # Optional for self-hosted
+```
+
+Optional overrides for self-hosted deployments:
+```bash
+# Leave unset to target the SaaS host
+SENTRY_HOST=sentry.example.com     # Hostname only (self-hosted only)
 ```
 
 Development (.dev.vars):
@@ -61,27 +65,36 @@ SENTRY_CLIENT_SECRET=dev_secret
 COOKIE_SECRET=dev-cookie-secret
 ```
 
-## Durable Object Setup
+## MCP Handler Setup
 
-The MCP transport runs as a Durable Object:
+The MCP handler uses a stateless architecture with AsyncLocalStorage:
 
 ```typescript
-export class SentryMCP extends DurableObject {
-  async fetch(request: Request): Promise<Response> {
-    // Handle WebSocket upgrade
-    if (request.headers.get("Upgrade") === "websocket") {
-      const [client, server] = Object.values(new WebSocketPair());
-      
-      await this.handleWebSocket(server);
-      return new Response(null, { 
-        status: 101, 
-        webSocket: client 
-      });
-    }
-    
-    return new Response("Not found", { status: 404 });
-  }
-}
+import { experimental_createMcpHandler as createMcpHandler } from "agents/mcp";
+import { serverContextStorage } from "@sentry/mcp-server/internal/context-storage";
+
+const mcpHandler: ExportedHandler<Env> = {
+  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
+    // Extract auth props from ExecutionContext (set by OAuth provider)
+    const oauthCtx = ctx as OAuthExecutionContext;
+
+    // Build complete ServerContext from OAuth props + constraints
+    const serverContext: ServerContext = {
+      userId: oauthCtx.props.userId,
+      clientId: oauthCtx.props.clientId,
+      accessToken: oauthCtx.props.accessToken,
+      grantedScopes: expandedScopes,
+      constraints: verification.constraints,
+      sentryHost,
+      mcpUrl: oauthCtx.props.mcpUrl,
+    };
+
+    // Run MCP handler within ServerContext (AsyncLocalStorage)
+    return serverContextStorage.run(serverContext, () => {
+      return createMcpHandler(server, { route: "/mcp" })(request, env, ctx);
+    });
+  },
+};
 ```
 
 ## OAuth Provider Setup
@@ -212,19 +225,16 @@ Tests validate (using Vitest):
 
 First-time setup:
 ```bash
-# Create KV namespace
-npx wrangler kv:namespace create KV
-
-# Create Durable Object namespace
-npx wrangler durable-objects namespace create SENTRY_MCP
+# Create KV namespace for OAuth token storage
+npx wrangler kv:namespace create OAUTH_KV
 
-# Update wrangler.jsonc with IDs
+# Update wrangler.jsonc with the namespace ID
 ```
 
 ## Multi-Region Considerations
 
 Cloudflare Workers run globally, but consider:
-- Durable Objects have a home region
+- Workers are stateless and edge-deployed
 - KV is eventually consistent globally
 - Use regional hints for performance
 
@@ -275,7 +285,7 @@ export default {
 Monitor via Cloudflare dashboard:
 - Request rates
 - Error rates
-- Durable Object usage
+- CPU time and memory usage
 - KV operations
 
 ## Troubleshooting
@@ -286,9 +296,9 @@ Monitor via Cloudflare dashboard:
    - Ensure callback URL matches Sentry app config
    - Check protocol (http vs https)
 
-2. **Durable Object not found**
-   - Verify namespace binding in wrangler.jsonc
-   - Check class export in main file
+2. **AsyncLocalStorage context missing**
+   - Verify serverContextStorage.run() wraps MCP handler
+   - Check ExecutionContext.props contains OAuth data
 
 3. **Environment variables missing**
    - Use `wrangler secret put` for production

docs/cloudflare/oauth-architecture.md

@@ -32,7 +32,7 @@ The system uses a dual-token approach:
 sequenceDiagram
     participant Client as MCP Client (Cursor)
     participant MCPOAuth as MCP OAuth Provider<br/>(Our Server)
-    participant MCP as MCP Server<br/>(Durable Object)
+    participant MCP as MCP Server<br/>(Stateless Handler)
     participant SentryOAuth as Sentry OAuth Provider<br/>(sentry.io)
     participant SentryAPI as Sentry API
     participant User as User
@@ -167,14 +167,13 @@ const oAuthProvider = new OAuthProvider({
 });
 ```
 
-### 2. API Handlers
+### 2. API Handler
 
-The `apiHandlers` are protected endpoints that require valid OAuth tokens:
+The `apiHandler` is a protected endpoint that requires valid OAuth tokens:
 
-- `/mcp/*` - MCP protocol endpoints
-- `/sse/*` - Server-sent events for MCP
+- `/mcp` - MCP protocol endpoint (HTTP transport)
 
-These handlers receive:
+The handler receives:
 - `request`: The incoming request
 - `env`: Cloudflare environment bindings
 - `ctx`: Execution context with `ctx.props` containing decrypted user data
@@ -202,39 +201,44 @@ interface WorkerProps {
 The MCP server needs to support URL-based constraints like `/mcp/sentry/javascript` to limit agent access to specific organizations/projects. However:
 
 1. OAuth Provider only does prefix matching (`/mcp` matches `/mcp/*`)
-2. The agents library rewrites URLs to `/streamable-http` before reaching the Durable Object
-3. URL path parameters are lost in this rewrite
+2. The MCP handler needs to extract constraints from URL paths
+3. URL path parameters must be preserved through the OAuth middleware
 
 #### The Solution
 
 We use HTTP headers to preserve constraints through the URL rewriting:
 
 ```typescript
-const createMcpHandler = (basePath: string, isSSE = false) => {
-  const handler = isSSE ? SentryMCP.serveSSE("/*") : SentryMCP.serve("/*");
-
-  return {
-    fetch: (request: Request, env: unknown, ctx: ExecutionContext) => {
-      const url = new URL(request.url);
-      
-      // Extract constraints from URL
-      const pathMatch = url.pathname.match(
-        /^\/(mcp|sse)(?:\/([a-z0-9._-]+))?(?:\/([a-z0-9._-]+))?/i
-      );
-      
-      // Pass constraints via headers (preserved through URL rewriting)
-      const headers = new Headers(request.headers);
-      if (pathMatch?.[2]) {
-        headers.set("X-Sentry-Org-Slug", pathMatch[2]);
-      }
-      if (pathMatch?.[3]) {
-        headers.set("X-Sentry-Project-Slug", pathMatch[3]);
-      }
-      
-      const modifiedRequest = new Request(request, { headers });
-      return handler.fetch(modifiedRequest, env, ctx);
-    },
-  };
+// The MCP handler extracts constraints from URL path segments
+// Example URLs:
+//   /mcp - No constraints
+//   /mcp/sentry - Organization constraint
+//   /mcp/sentry/javascript - Organization + project constraints
+
+const mcpHandler: ExportedHandler<Env> = {
+  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
+    // Extract auth props from ExecutionContext (set by OAuth provider)
+    const oauthCtx = ctx as OAuthExecutionContext;
+
+    // Parse constraints from URL path
+    const url = new URL(request.url);
+    const pathSegments = url.pathname.split('/').filter(Boolean);
+    const constraints = {
+      organizationSlug: pathSegments[1] || null,
+      projectSlug: pathSegments[2] || null,
+    };
+
+    // Build complete ServerContext
+    const serverContext: ServerContext = {
+      ...oauthCtx.props,
+      constraints,
+    };
+
+    // Run MCP handler within ServerContext (AsyncLocalStorage)
+    return serverContextStorage.run(serverContext, () => {
+      return createMcpHandler(server, { route: "/mcp" })(request, env, ctx);
+    });
+  },
 };
 ```
 
@@ -375,19 +379,19 @@ Note: These describe the MCP OAuth server, not Sentry's OAuth endpoints.
 
 ## Integration Between MCP OAuth and MCP Server
 
-The MCP Server (Durable Object `SentryMCP`) receives:
+The MCP Server (stateless handler) receives context via AsyncLocalStorage:
 
-1. **Props via constructor**: Decrypted data from MCP token (includes Sentry tokens)
-2. **Constraints via headers**: Organization/project limits from URL path
-3. **Both stored**: In Durable Object storage for session persistence
+1. **Props via ExecutionContext**: Decrypted data from MCP token (includes Sentry tokens)
+2. **Constraints from URL**: Organization/project limits parsed from URL path
+3. **Context storage**: AsyncLocalStorage provides per-request isolation
 
-The MCP Server then uses the Sentry access token from props to make Sentry API calls.
+The MCP Server then uses the Sentry access token from context to make Sentry API calls.
 
 ## Limitations
 
 1. **No direct Hono integration**: OAuth Provider expects specific handler signatures
-2. **URL rewriting**: Requires header-based constraint passing
-3. **Props architecture mismatch**: OAuth passes props per-request, agents library expects them in constructor
+2. **Constraint extraction**: Must parse URL segments to extract organization/project constraints
+3. **AsyncLocalStorage dependency**: Requires Node.js compatibility mode in Cloudflare Workers
 
 ## Why Use Two OAuth Systems?
 

docs/llms/document-scopes.mdc

@@ -110,7 +110,7 @@ Defines the specific purpose and content for each documentation file.
 **Must Include**:
 - Wrangler configuration
 - Environment variables
-- Durable Objects setup
+- MCP handler setup
 - OAuth flow
 - Deployment commands
 

packages/mcp-cloudflare/src/server/index.ts

@@ -6,10 +6,6 @@ import type { Env } from "./types";
 import getSentryConfig from "./sentry.config";
 import { tokenExchangeCallback } from "./oauth";
 import sentryMcpHandler from "./lib/mcp-handler";
-import { SentryMCP as SentryMCPStub } from "./lib/mcp-agent-stub";
-
-// SentryMCP stub exported ONLY for Durable Object migration purposes.
-// This will be removed after the deleted_classes migration completes.
 
 // Public metadata endpoints that should be accessible from any origin
 const PUBLIC_METADATA_PATHS = [
@@ -75,8 +71,3 @@ export default Sentry.withSentry(
   getSentryConfig,
   corsWrappedOAuthProvider,
 ) satisfies ExportedHandler<Env>;
-
-// Export SentryMCP Durable Object class for migration
-// TEMPORARY: This export is required for Cloudflare to apply the deleted_classes migration.
-// Once all Durable Object instances are deleted, this export should be removed.
-export { SentryMCPStub as SentryMCP };