refactor(cloudflare): improve McpAgent constraint abstraction (#517)

- Rename mcp-transport.ts to mcp-agent.ts for better semantic clarity
- Remove custom wrapper functions from index.ts
- Integrate URLPattern-based constraint extraction directly into
SentryMCP class
- Add helper functions for flexible routing: /mcp, /mcp/:org,
/mcp/:org/:project
- Maintain backward compatibility with existing constraint handling

Author: dcramer

packages/mcp-cloudflare/package.json

@@ -37,6 +37,7 @@
     "@types/react-scroll-to-bottom": "^4.2.5",
     "@vitejs/plugin-react": "catalog:",
     "tailwindcss": "catalog:",
+    "urlpattern-polyfill": "^10.1.0",
     "vite": "catalog:",
     "vitest": "catalog:",
     "wrangler": "catalog:"

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

@@ -1,116 +1,24 @@
 import * as Sentry from "@sentry/cloudflare";
 import OAuthProvider from "@cloudflare/workers-oauth-provider";
-import SentryMCP from "./lib/mcp-transport";
+import SentryMCP from "./lib/mcp-agent";
 import app from "./app";
 import { SCOPES } from "../constants";
 import type { Env } from "./types";
 import getSentryConfig from "./sentry.config";
-import { isValidSlug } from "./lib/slug-validation";
 
 // required for Durable Objects
 export { SentryMCP };
 
-// Custom wrapper to preserve path parameters via headers.
-//
-// ARCHITECTURAL LIMITATION:
-// We must pass constraints via headers because the agents library rewrites URLs
-// from /mcp/org/project to /streamable-http, losing path information.
-//
-// IDEAL SOLUTION (not possible with current libraries):
-// Each URL path (/mcp/org1/project1) would map to a separate DO instance,
-// providing immutable configuration per context.
-//
-// CURRENT SOLUTION:
-// 1. Extract org/project from URL path here
-// 2. Pass as headers (X-Sentry-Org-Slug, X-Sentry-Project-Slug)
-// 3. DO extracts headers and reconfigures when constraints change
-//
-// This wrapper ensures:
-// - Security: External clients cannot bypass URL-based constraints
-// - Validation: Slugs are validated before being passed to DO
-// - Compatibility: Works with both SSE and streamable-http transports
-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);
-
-      // Always create new headers to prevent external manipulation
-      const headers = new Headers(request.headers);
-
-      // Remove any externally-set constraint headers for security
-      // This prevents clients from bypassing URL-based constraints
-      headers.delete("X-Sentry-Org-Slug");
-      headers.delete("X-Sentry-Project-Slug");
-
-      // Extract org/project from URL path
-      // NOTE: Extra path segments after project (e.g., /mcp/org/project/extra) are
-      // intentionally ignored - the MCP handler manages any additional routing
-      // IMPORTANT: /sse/message and /mcp/message are reserved SSE protocol endpoints
-      // and must not be interpreted as organization slugs
-      const pathMatch = url.pathname.match(
-        /^\/(mcp|sse)(?:\/([a-zA-Z0-9._-]{1,100}))?(?:\/([a-zA-Z0-9._-]{1,100}))?/,
-      );
-
-      // Check if this is a reserved protocol endpoint
-      const isReservedEndpoint =
-        url.pathname === "/sse/message" ||
-        url.pathname.startsWith("/sse/message?") ||
-        url.pathname === "/mcp/message" ||
-        url.pathname.startsWith("/mcp/message?");
-
-      // Validate and set headers based on URL path (unless it's a reserved endpoint)
-      if (!isReservedEndpoint && pathMatch?.[2]) {
-        // Organization slug is present - validate it
-        if (!isValidSlug(pathMatch[2])) {
-          return new Response(
-            JSON.stringify({
-              error: "invalid_request",
-              error_description: "Invalid organization slug format",
-            }),
-            {
-              status: 400,
-              headers: { "Content-Type": "application/json" },
-            },
-          );
-        }
-        headers.set("X-Sentry-Org-Slug", pathMatch[2]);
-
-        // Project slug is optional but must be valid if present
-        if (pathMatch[3]) {
-          if (!isValidSlug(pathMatch[3])) {
-            return new Response(
-              JSON.stringify({
-                error: "invalid_request",
-                error_description: "Invalid project slug format",
-              }),
-              {
-                status: 400,
-                headers: { "Content-Type": "application/json" },
-              },
-            );
-          }
-          headers.set("X-Sentry-Project-Slug", pathMatch[3]);
-        }
-      }
-      // If no path params, headers remain deleted (cleared above)
-
-      // Create a new request with the sanitized headers
-      const modifiedRequest = new Request(request, { headers });
-      return handler.fetch(modifiedRequest, env, ctx);
-    },
-  };
-};
+// SentryMCP handles URLPattern-based constraint extraction from request URLs
+// and passes context to Durable Objects via headers for org/project scoping.
 
 const oAuthProvider = new OAuthProvider({
   apiHandlers: {
-    // NOTE: OAuthProvider only does prefix matching, not parameterized routes.
-    // So "/mcp" will match "/mcp", "/mcp/org", "/mcp/org/project" etc.
-    // We use a custom wrapper to extract path params for /mcp endpoints only.
+    // OAuthProvider uses prefix matching, so "/mcp" matches all MCP routes.
+    // SentryMCP.serve() uses URLPattern to extract org/project constraints from URLs.
     // SSE endpoints don't support subpath constraints due to protocol limitations.
     "/sse": SentryMCP.serveSSE("/sse"),
-    "/mcp": createMcpHandler("/mcp", false),
+    "/mcp": SentryMCP.serve("/mcp/:org?/:project?"),
   },
   // @ts-ignore
   defaultHandler: app,

packages/mcp-cloudflare/src/server/lib/constraint-utils.test.ts

@@ -0,0 +1,185 @@
+import { describe, it, expect } from "vitest";
+import "urlpattern-polyfill";
+import {
+  isReservedEndpoint,
+  extractConstraintsWithURLPattern,
+} from "./constraint-utils";
+
+describe("isReservedEndpoint", () => {
+  it("should identify reserved SSE and MCP endpoints", () => {
+    expect(isReservedEndpoint("/sse/message")).toBe(true);
+    expect(isReservedEndpoint("/mcp/message")).toBe(true);
+  });
+
+  it("should identify reserved endpoints with query parameters", () => {
+    expect(isReservedEndpoint("/sse/message?param=value")).toBe(true);
+    expect(isReservedEndpoint("/mcp/message?foo=bar&baz=qux")).toBe(true);
+  });
+
+  it("should not identify non-reserved endpoints", () => {
+    expect(isReservedEndpoint("/mcp")).toBe(false);
+    expect(isReservedEndpoint("/mcp/org")).toBe(false);
+    expect(isReservedEndpoint("/mcp/org/project")).toBe(false);
+    expect(isReservedEndpoint("/api/something")).toBe(false);
+    expect(isReservedEndpoint("/")).toBe(false);
+  });
+});
+
+describe("extractConstraintsWithURLPattern", () => {
+  describe("reserved endpoints", () => {
+    it("should return null constraints for reserved SSE endpoints", () => {
+      const result = extractConstraintsWithURLPattern(
+        "https://example.com/sse/message",
+        "/mcp/:org?/:project?",
+      );
+      expect(result).toEqual({
+        organizationSlug: null,
+        projectSlug: null,
+      });
+    });
+
+    it("should return null constraints for reserved MCP endpoints", () => {
+      const result = extractConstraintsWithURLPattern(
+        "https://example.com/mcp/message",
+        "/mcp/:org?/:project?",
+      );
+      expect(result).toEqual({
+        organizationSlug: null,
+        projectSlug: null,
+      });
+    });
+  });
+
+  describe("pattern matching", () => {
+    it("should extract no constraints for base /mcp path", () => {
+      const result = extractConstraintsWithURLPattern(
+        "https://example.com/mcp",
+        "/mcp/:org?/:project?",
+      );
+      expect(result).toEqual({
+        organizationSlug: null,
+        projectSlug: null,
+      });
+    });
+
+    it("should extract organization slug for /mcp/:org pattern", () => {
+      const result = extractConstraintsWithURLPattern(
+        "https://example.com/mcp/sentry",
+        "/mcp/:org?/:project?",
+      );
+      expect(result).toEqual({
+        organizationSlug: "sentry",
+        projectSlug: null,
+      });
+    });
+
+    it("should extract both organization and project slugs for /mcp/:org/:project pattern", () => {
+      const result = extractConstraintsWithURLPattern(
+        "https://example.com/mcp/sentry/my-app",
+        "/mcp/:org?/:project?",
+      );
+      expect(result).toEqual({
+        organizationSlug: "sentry",
+        projectSlug: "my-app",
+      });
+    });
+
+    it("should handle URLs that don't match the pattern", () => {
+      const result = extractConstraintsWithURLPattern(
+        "https://example.com/api/something",
+        "/mcp/:org?/:project?",
+      );
+      expect(result).toEqual({
+        organizationSlug: null,
+        projectSlug: null,
+      });
+    });
+  });
+
+  describe("slug validation", () => {
+    it("should return error for invalid organization slug", () => {
+      const result = extractConstraintsWithURLPattern(
+        "https://example.com/mcp/invalid..slug",
+        "/mcp/:org?/:project?",
+      );
+      expect(result).toEqual({
+        organizationSlug: null,
+        projectSlug: null,
+        error: "Invalid organization slug format",
+      });
+    });
+
+    it("should return error for invalid project slug", () => {
+      const result = extractConstraintsWithURLPattern(
+        "https://example.com/mcp/valid-org/invalid..project",
+        "/mcp/:org?/:project?",
+      );
+      expect(result).toEqual({
+        organizationSlug: null,
+        projectSlug: null,
+        error: "Invalid project slug format",
+      });
+    });
+
+    it("should accept valid slugs with allowed characters", () => {
+      const result = extractConstraintsWithURLPattern(
+        "https://example.com/mcp/my-org_v2.1/test-project_123",
+        "/mcp/:org?/:project?",
+      );
+      expect(result).toEqual({
+        organizationSlug: "my-org_v2.1",
+        projectSlug: "test-project_123",
+      });
+    });
+  });
+
+  describe("error handling", () => {
+    it("should handle invalid URLPattern gracefully", () => {
+      const result = extractConstraintsWithURLPattern(
+        "https://example.com/mcp/org",
+        "*{invalid",
+      );
+      expect(result).toEqual({
+        organizationSlug: null,
+        projectSlug: null,
+        error: "Invalid URL pattern",
+      });
+    });
+
+    it("should handle malformed URLs gracefully", () => {
+      const result = extractConstraintsWithURLPattern(
+        "not-a-valid-url",
+        "/mcp/:org?/:project?",
+      );
+      expect(result).toEqual({
+        organizationSlug: null,
+        projectSlug: null,
+        error: "Invalid URL pattern",
+      });
+    });
+  });
+
+  describe("query parameters and fragments", () => {
+    it("should extract constraints from URLs with query parameters", () => {
+      const result = extractConstraintsWithURLPattern(
+        "https://example.com/mcp/sentry/my-project?param=value&foo=bar",
+        "/mcp/:org?/:project?",
+      );
+      expect(result).toEqual({
+        organizationSlug: "sentry",
+        projectSlug: "my-project",
+      });
+    });
+
+    it("should extract constraints from URLs with fragments", () => {
+      const result = extractConstraintsWithURLPattern(
+        "https://example.com/mcp/sentry#section",
+        "/mcp/:org?/:project?",
+      );
+      expect(result).toEqual({
+        organizationSlug: "sentry",
+        projectSlug: null,
+      });
+    });
+  });
+});

packages/mcp-cloudflare/src/server/lib/constraint-utils.ts

@@ -0,0 +1,76 @@
+import type { UrlConstraints } from "@sentry/mcp-server/types";
+import { isValidSlug } from "./slug-validation";
+
+/**
+ * Check if a pathname is a reserved MCP protocol endpoint
+ */
+export function isReservedEndpoint(pathname: string): boolean {
+  const reservedEndpoints = ["/sse/message", "/mcp/message"];
+
+  return reservedEndpoints.some(
+    (endpoint) => pathname === endpoint || pathname.startsWith(`${endpoint}?`),
+  );
+}
+
+/**
+ * Extract constraints using URLPattern for flexible routing
+ * Supports: /mcp, /mcp/:org, /mcp/:org/:project
+ */
+export function extractConstraintsWithURLPattern(
+  url: string,
+  patternString: string,
+): UrlConstraints & { error?: string } {
+  try {
+    // Handle reserved SSE protocol endpoints first
+    const urlObj = new URL(url);
+    if (isReservedEndpoint(urlObj.pathname)) {
+      return { organizationSlug: null, projectSlug: null };
+    }
+
+    // Create URLPattern for flexible matching
+    // Support multiple patterns: /mcp, /mcp/:org, /mcp/:org/:project
+    const pattern = new URLPattern({ pathname: patternString });
+
+    // Try to match and extract parameters
+    const result = pattern.exec(url);
+
+    if (!result) {
+      // URL doesn't match pattern - could be valid for some endpoints
+      return { organizationSlug: null, projectSlug: null };
+    }
+
+    // Extract named parameters from URLPattern groups
+    const { groups } = result.pathname;
+    const org = groups?.org || null;
+    const project = groups?.project || null;
+
+    // Validate slugs if present
+    if (org && !isValidSlug(org)) {
+      return {
+        organizationSlug: null,
+        projectSlug: null,
+        error: "Invalid organization slug format",
+      };
+    }
+
+    if (project && !isValidSlug(project)) {
+      return {
+        organizationSlug: null,
+        projectSlug: null,
+        error: "Invalid project slug format",
+      };
+    }
+
+    return {
+      organizationSlug: org,
+      projectSlug: project,
+    };
+  } catch (error) {
+    console.error("[MCP Agent] URLPattern error:", error);
+    return {
+      organizationSlug: null,
+      projectSlug: null,
+      error: "Invalid URL pattern",
+    };
+  }
+}