Implement R2 artifact storage middleware

[dangayle]

This pull request adds support for storing Playwright MCP artifacts (such as screenshots and PDFs) in Cloudflare R2 when running in Cloudflare Workers. It introduces middleware to intercept MCP responses, upload artifacts to R2, and return accessible URLs instead of inline base64 data. The documentation is updated to explain how to configure and use this feature.

Artifact Storage with R2 Integration:

• Added a new interceptMcpResponse middleware in cloudflare/src/r2-middleware.ts that intercepts MCP responses, uploads image artifacts to R2, and modifies the response to return URLs, inline data, or both, depending on configuration.
• Updated cloudflare/src/index.ts to support artifact storage configuration, including R2 bucket binding, key prefix, public URL base, and return mode.

Documentation:

• Updated README.md with detailed instructions on configuring R2 storage for artifacts, including example wrangler.toml, Worker middleware usage, return modes, and serving artifacts from R2.

Related to #40

[dangayle]

Implementation Approach

We explored several approaches before settling on the HTTP response interception middleware:

Approaches Tried

1. Direct tool modification - Modifying core src/tools/screenshot.ts and src/tools/pdf.ts to upload to R2 directly.

• Required changes to core src/ directory
• Breaks the architectural isolation Cloudflare maintains (all Cloudflare-specific code in cloudflare/ directory)
• Would diverge from upstream microsoft/playwright-mcp and make syncing difficult

2. MCP server handler wrapping - Wrapping the MCP server's CallToolRequestSchema handler after server creation to intercept tool results.

• Server handlers are set during createConnection() in the core package
• Trying to wrap server._requestHandlers after the fact didn't work reliably
• Timing issues with Agent/Durable Object initialization

3. HTTP response interception (final approach) - Intercept the SSE response stream at the Worker's fetch() handler level, parse and transform on-the-fly.

• Works at the HTTP boundary, before responses reach the client
• All code isolated to cloudflare/ directory (matches Cloudflare's pattern)
• Zero changes to core src/ package
• Prevents base64 image blobs from filling LLM context (replaces ~500KB base64 with ~100 byte URLs)

Why HTTP Interception is Correct

The middleware intercepts SSE responses, parses data: lines containing JSON-RPC results, uploads image content to R2, and replaces/augments with URLs. This approach:

• Preserves SSE protocol compliance (proper message termination, UTF-8 handling)
• Allows users to control behavior via returnMode (url, url+inline, inline)
• Keeps implementation fully isolated in the Cloudflare package

The ~140 lines of SSE parsing code are necessary for streaming transformation without buffering entire responses.

[ruifigueira]

This is really nice, thanks! I really like the idea, but this is a very generic and low level implementation (R2 middleware does not depend on playwright-mcp) that I wonder if we shouldn't integrate this into agents library instead.

[dangayle]

@ruifigueira I'm not sure what you mean. What does this have to do with agents? Are you saying that this entire MCP should be moved over to agents instead? Otherwise, this is all self-contained. Adding in a basic middleware wasn't the only option, it just ended up being the cleanest option that still maintained upstream compatibility with the playwright mcp.

I'm happy to chat about the options here.