feat: streamable http

felixnorden · felixnorden · commit 4cfc2e0bd9bd · 2025-11-01T19:34:41.000Z
diff --git a/examples/browser-mcp/test/browser-mcp-client.test.ts b/examples/browser-mcp/test/browser-mcp-client.test.ts
@@ -5,7 +5,7 @@ import {
 } from "cloudflare:test";
 import { describe, it, expect, beforeEach, afterEach } from "vitest";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
-import { WorkerSSEClientTransport } from "@nullshot/test-utils/mcp/WorkerSSEClientTransport";
+import { WorkerStreamableHTTPClientTransport } from "@nullshot/test-utils/mcp/WorkerStreamableHTTPClientTransport";
 
 // Define response types for clarity
 interface ToolResponse {
@@ -84,8 +84,8 @@ describe("Browser MCP Client Integration Tests", () => {
 
   // Helper function to create the transport
   function createTransport(ctx: ExecutionContext) {
-    const url = new URL(`${baseUrl}/sse`);
-    return new WorkerSSEClientTransport(url, ctx);
+    const url = new URL(`${baseUrl}/mcp`);
+    return new WorkerStreamableHTTPClientTransport(url, ctx);
   }
 
   // Helper function to check if a tool call involves browser rendering
@@ -124,7 +124,7 @@ describe("Browser MCP Client Integration Tests", () => {
   });
 
   it("should successfully connect to the browser MCP server", async () => {
-    console.log(`Testing SSE transport connection`);
+    console.log(`Testing StreamableHTTP transport connection`);
 
     const transport = createTransport(ctx);
     await client.connect(transport);
diff --git a/examples/crud-mcp/test/todo-mcp-client.test.ts b/examples/crud-mcp/test/todo-mcp-client.test.ts
@@ -5,7 +5,7 @@ import {
 } from "cloudflare:test";
 import { describe, it, expect, beforeEach, afterEach } from "vitest";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
-import { WorkerSSEClientTransport } from "@nullshot/test-utils/mcp/WorkerSSEClientTransport";
+import { WorkerStreamableHTTPClientTransport } from "@nullshot/test-utils/mcp/WorkerStreamableHTTPClientTransport";
 import { TodoStatus, Todo } from "../src/schema";
 
 // Define response type for clarity
@@ -62,8 +62,8 @@ describe("Todo MCP Client Integration Tests", () => {
 
   // Helper function to create the transport
   function createTransport(ctx: ExecutionContext) {
-    const url = new URL(`${baseUrl}/sse`);
-    return new WorkerSSEClientTransport(url, ctx);
+    const url = new URL(`${baseUrl}/mcp`);
+    return new WorkerStreamableHTTPClientTransport(url, ctx);
   }
 
   // Test for basic functionality
@@ -77,7 +77,7 @@ describe("Todo MCP Client Integration Tests", () => {
   });
 
   it("should successfully connect to the todo MCP server", async () => {
-    console.log(`Testing SSE transport connection`);
+    console.log(`Testing StreamableHTTP transport connection`);
 
     const transport = createTransport(ctx);
     await client.connect(transport);
diff --git a/examples/email-mcp/test/email-mcp-client.test.ts b/examples/email-mcp/test/email-mcp-client.test.ts
@@ -5,7 +5,7 @@ import {
 } from "cloudflare:test";
 import { describe, it, expect, beforeEach, afterEach } from "vitest";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
-import { WorkerSSEClientTransport } from "@nullshot/test-utils/mcp/WorkerSSEClientTransport";
+import { WorkerStreamableHTTPClientTransport } from "@nullshot/test-utils/mcp/WorkerStreamableHTTPClientTransport";
 
 // Define response type for clarity
 interface ToolResponse {
@@ -60,12 +60,12 @@ describe("Email MCP Client Integration Tests", () => {
   });
 
   function createTransport(ctx: ExecutionContext) {
-    const url = new URL(`${baseUrl}/sse`);
-    return new WorkerSSEClientTransport(url, ctx);
+    const url = new URL(`${baseUrl}/mcp`);
+    return new WorkerStreamableHTTPClientTransport(url, ctx);
   }
 
   it("should successfully connect to the email MCP server", async () => {
-    console.log(`Testing SSE transport connection`);
+    console.log(`Testing StreamableHTTP transport connection`);
 
     const transport = createTransport(ctx);
     await client.connect(transport);
diff --git a/examples/expense-mcp/test/expense-mcp-client.test.ts b/examples/expense-mcp/test/expense-mcp-client.test.ts
@@ -5,7 +5,7 @@ import {
 } from "cloudflare:test";
 import { describe, it, expect, beforeEach, afterEach } from "vitest";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
-import { WorkerSSEClientTransport } from "@nullshot/test-utils/mcp/WorkerSSEClientTransport";
+import { WorkerStreamableHTTPClientTransport } from "@nullshot/test-utils/mcp/WorkerStreamableHTTPClientTransport";
 import { Expense } from "../src/repository";
 
 // Define response type for clarity
@@ -51,8 +51,8 @@ describe("Expense MCP Client Integration Tests", () => {
   });
 
   function createTransport(ctx: ExecutionContext) {
-    const url = new URL(`${baseUrl}/sse`);
-    return new WorkerSSEClientTransport(url, ctx);
+    const url = new URL(`${baseUrl}/mcp`);
+    return new WorkerStreamableHTTPClientTransport(url, ctx);
   }
 
   it("should initialize the client properly", () => {
@@ -62,7 +62,7 @@ describe("Expense MCP Client Integration Tests", () => {
   });
 
   it("should successfully connect to the expense MCP server", async () => {
-    console.log(`Testing SSE transport connection`);
+    console.log(`Testing StreamableHTTP transport connection`);
 
     const transport = createTransport(ctx);
     await client.connect(transport);
diff --git a/examples/vectorize-mcp/test/vectorize-mcp-client.test.ts b/examples/vectorize-mcp/test/vectorize-mcp-client.test.ts
@@ -5,7 +5,7 @@ import {
 } from "cloudflare:test";
 import { describe, it, expect, beforeEach, afterEach } from "vitest";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
-import { WorkerSSEClientTransport } from "@nullshot/test-utils/mcp/WorkerSSEClientTransport";
+import { WorkerStreamableHTTPClientTransport } from "@nullshot/test-utils/mcp/WorkerStreamableHTTPClientTransport";
 import { VectorDocument } from "../src/schema";
 
 // Define response type for clarity
@@ -51,8 +51,8 @@ describe("Vectorize MCP Client Integration Tests", () => {
   });
 
   function createTransport(ctx: ExecutionContext) {
-    const url = new URL(`${baseUrl}/sse`);
-    return new WorkerSSEClientTransport(url, ctx);
+    const url = new URL(`${baseUrl}/mcp`);
+    return new WorkerStreamableHTTPClientTransport(url, ctx);
   }
 
   it("should initialize the client properly", () => {
@@ -62,7 +62,7 @@ describe("Vectorize MCP Client Integration Tests", () => {
   });
 
   it("should successfully connect to the vectorize MCP server", async () => {
-    console.log(`Testing SSE transport connection`);
+    console.log(`Testing StreamableHTTP transport connection`);
 
     const transport = createTransport(ctx);
     await client.connect(transport);
diff --git a/packages/cli/AGENTS.md b/packages/cli/AGENTS.md
@@ -0,0 +1,46 @@
+# AGENTS.md
+
+## Build/Run Commands
+- Build: `pnpm run build` (uses tsc)
+- Dev mode: `pnpm run dev` (tsx watch)
+- Run tests: `pnpm run test` (vitest)
+- Run single test: `pnpm run test <test-file-pattern>`
+- Test watch mode: `pnpm run test:watch`
+- Lint: `pnpm run lint` (eslint)
+- Lint fix: `pnpm run lint:fix`
+- Typecheck: `pnpm run typecheck` (tsc --noEmit)
+- Format: `pnpm run format` (prettier)
+- Format check: `pnpm run format:check`
+
+## Code Style Guidelines
+- Use double quotes for strings
+- No semicolons
+- Use tabs for indentation (TSConfig sets this)
+- Strict TypeScript with all strict flags enabled
+- No unused locals/parameters
+- Exact optional property types
+- No implicit returns/fallthrough cases
+- No unchecked indexed access
+- Use ESNext target and modules
+- Import paths use `@/*` alias for src/
+- Declaration files and source maps generated
+- Resolve JSON modules enabled
+
+## Naming Conventions
+- Files: kebab-case
+- Types: PascalCase
+- Functions/variables: camelCase
+- Constants: UPPER_SNAKE_CASE
+- Test files: *.test.ts
+
+## Error Handling
+- Use custom error classes from utils/errors.ts
+- Always provide meaningful error messages
+- Use logger.ts for consistent logging
+- Handle dry-run mode in all mutating operations
+
+## Testing
+- Use vitest with globals
+- Place tests alongside source files
+- Use .test.ts extension
+- Mock filesystem with memfs where needed
diff --git a/packages/mcp/test/mcp-client.test.ts b/packages/mcp/test/mcp-client.test.ts
@@ -1,7 +1,7 @@
 import { env, createExecutionContext, waitOnExecutionContext } from 'cloudflare:test';
 import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
-import { WorkerSSEClientTransport } from '../../test-utils/src/mcp/WorkerSSEClientTransport';
+import { WorkerStreamableHTTPClientTransport } from '../../test-utils/src/mcp/WorkerStreamableHTTPClientTransport';
 import { WorkerWebSocketClientTransport } from '../../test-utils/src/mcp/WorkerWebSocketClientTransport';
 
 // Define response type for clarity
@@ -25,6 +25,13 @@ describe('MCP Client Connection Tests', () => {
         return new WorkerSSEClientTransport(url, ctx);
       }
     },
+    {
+      name: 'StreamableHTTP',
+      createTransport: (ctx: ExecutionContext) => {
+        const url = new URL(`${baseUrl}/mcp`);
+        return new WorkerStreamableHTTPClientTransport(url, ctx);
+      }
+    },
     {
       name: 'WebSocket',
       createTransport: (ctx: ExecutionContext) => {
diff --git a/packages/test-utils/README.md b/packages/test-utils/README.md
@@ -14,17 +14,18 @@ This package provides utilities for testing MCP applications, particularly in Cl
 
 ### Available Utilities
 
-- `WorkerSSEClientTransport`: A client transport for Server-Sent Events (SSE) in Worker environments
+- `WorkerSSEClientTransport`: A client transport for Server-Sent Events (SSE) in Worker environments (deprecated)
+- `WorkerStreamableHTTPClientTransport`: A client transport for Streamable HTTP in Worker environments (recommended)
 - `WorkerWebSocketClientTransport`: A client transport for WebSocket connections in Worker environments
 
 ### Example
 
 ```typescript
-import { WorkerSSEClientTransport } from "@nullshot/test-utils";
+import { WorkerStreamableHTTPClientTransport } from "@nullshot/test-utils";
 
 // Set up test client
-const transport = new WorkerSSEClientTransport({
-  endpoint: "https://your-worker.example.com/sse",
+const transport = new WorkerStreamableHTTPClientTransport({
+  endpoint: "https://your-worker.example.com/mcp",
 });
 
 // Use in tests
diff --git a/packages/test-utils/package.json b/packages/test-utils/package.json
@@ -17,6 +17,11 @@
       "import": "./dist/mcp/WorkerSSEClientTransport.js",
       "default": "./dist/mcp/WorkerSSEClientTransport.js"
     },
+    "./mcp/WorkerStreamableHTTPClientTransport": {
+      "types": "./dist/mcp/WorkerStreamableHTTPClientTransport.d.ts",
+      "import": "./dist/mcp/WorkerStreamableHTTPClientTransport.js",
+      "default": "./dist/mcp/WorkerStreamableHTTPClientTransport.js"
+    },
     "./mcp/WorkerWebSocketClientTransport": {
       "types": "./dist/mcp/WorkerWebSocketClientTransport.d.ts",
       "import": "./dist/mcp/WorkerWebSocketClientTransport.js",
diff --git a/packages/test-utils/src/index.ts b/packages/test-utils/src/index.ts
@@ -4,6 +4,7 @@
 // This is a substantial change to force a version bump
 // This comment should make the diff large enough to be recognized
 export * from "./mcp/WorkerSSEClientTransport.js";
+export * from "./mcp/WorkerStreamableHTTPClientTransport.js";
 export * from "./mcp/WorkerWebSocketClientTransport.js"; // Force version bump comment
 
 // Export vitest utilities
diff --git a/packages/test-utils/src/mcp/WorkerStreamableHTTPClientTransport.ts b/packages/test-utils/src/mcp/WorkerStreamableHTTPClientTransport.ts
@@ -0,0 +1,41 @@
+import { JSONRPCMessage } from '@modelcontextprotocol/sdk/types.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { env, SELF } from 'cloudflare:test';
+
+/**
+ * WorkerStreamableHTTPClientTransport is a wrapper around the official StreamableHTTPClientTransport
+ * that intercepts network requests and routes them to our Cloudflare Worker for testing.
+ * 
+ * This allows us to use the actual MCP client implementation against our worker
+ * for realistic integration testing with the modern Streamable HTTP transport.
+ */
+export class WorkerStreamableHTTPClientTransport extends StreamableHTTPClientTransport {
+  ctx: ExecutionContext;
+  constructor(url: URL, ctx: ExecutionContext) {
+    const fetchOverride: typeof fetch = async (
+      fetchUrl: RequestInfo | URL,
+      fetchInit: RequestInit = {}
+    ) => {
+      console.log(`[Debug] Fetching from: ${fetchUrl}`);
+      // add auth headers
+      const workerOptions = {
+        ...fetchInit,
+        headers: {
+          ...fetchInit?.headers,
+        },
+      };
+
+      // Call the original fetch with fixed options
+      // Create a proper Request object with the worker options
+      const request = new Request(fetchUrl.toString(), workerOptions);
+      
+      // Pass the Request object to the worker.fetch method
+      return await SELF.fetch(request);
+    };
+
+    
+    // Initialize the parent StreamableHTTPClientTransport with our custom fetch
+    super(url, { fetch: fetchOverride } as any);
+    this.ctx = ctx;
+  }
+}
