Skip to content

Comments

0.6.3#488

Merged
valebearzotti merged 9 commits intomainfrom
canary
Feb 4, 2026
Merged

0.6.3#488
valebearzotti merged 9 commits intomainfrom
canary

Conversation

@valebearzotti
Copy link
Collaborator

No description provided.

valebearzotti and others added 9 commits January 29, 2026 10:56
* CF

* Create pnpm-lock.yaml

* checkpoint

* Update README.md

* OAuth working and monolith split

* ditch cache - jose as dev dependency - migrate to .jsonc

* fix build runtime

* rmv stats gen

* rmv extra comments

* single import code generation

* replace auth validation with zod parse

* revert to multiple code gen

* add new plugins folder and split type definitions

* remove auth, leave only middlewares

* no destructuring objects!!!

* extract cors building into single util

* rmv cloudflare as adapter - handle build output natively

* shared deps for cors

* rmv jose dep

* standard cf workflow

* fix zod resolution compatible with workers

* fix simpler injected_client_bundles check

* server and transport resources correct cleanup

* djb2 in uint32 fix

* fix cors origin

* validate for jsonrpc batch

* iscloudflare defined var

* fix lock

* rmv unused ts directive

* rollback generate-stats to fix ci

* fix

* rmv workers workos example

---------

Co-authored-by: valebearzotti <valebearzotti1@gmail.com>
Co-authored-by: Valentina Bearzotti <64658886+valebearzotti@users.noreply.github.com>
* compatible middlewares for cloudflare + custom module

* disallow RegExp in cf config and pass strings straight through to JOSE
* upd cf dev to rebuild dev server

* rmv extra log

* concurrently run processes

* upd lock
@vercel
Copy link
Contributor

vercel bot commented Feb 4, 2026

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
xmcp-website Ready Ready Preview, Comment Feb 4, 2026 2:21pm

@valebearzotti valebearzotti merged commit 44058b0 into main Feb 4, 2026
6 checks passed
@github-actions
Copy link

github-actions bot commented Feb 4, 2026

Rspack Bundle Analysis

Build Assets Total Size (MB) Build Time
Main Compiler 4 6.31 5.16s
Runtime Compiler 6 5.34 5.60s

Main Compiler

Source: stats-main.json

Asset Chunk Size (KB) Size (MB)
cli.js cli 5991.34 5.85
index.js index 368.22 0.36
cloudflare.js cloudflare 81.70 0.08
detached-flush.js detached-flush 15.18 0.01

Total emitted JS: 6.31 MB

Runtime Compiler

Source: stats-runtime.json

Asset Chunk Size (KB) Size (MB)
http.js http 1302.49 1.27
adapter-nestjs.js adapter-nestjs 1278.76 1.25
adapter-nextjs.js adapter-nextjs 1272.80 1.24
adapter-express.js adapter-express 1271.07 1.24
stdio.js stdio 342.65 0.33
headers.js headers 1.33 0.00

Total emitted JS: 5.34 MB

Package Footprint (npm pack + npm install)

Item Size (KB) Size (MB)
Tarball (.tgz) 4608.10 4.50
dist/ 11979.36 11.70
node_modules/ 100887.47 98.52
dist + node_modules 112866.83 110.22

@gemini-code-assist
Copy link

Summary of Changes

Hello @valebearzotti, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly expands the xmcp framework's deployment capabilities by integrating full support for Cloudflare Workers. It provides developers with the tools to build, develop, and deploy xmcp applications directly to the Cloudflare edge, leveraging a new example, dedicated CLI commands, and a refactored internal architecture optimized for the Workers environment. This enhancement broadens the reach and flexibility of xmcp applications.

Highlights

  • Cloudflare Workers Support: Introduced comprehensive support for deploying xmcp applications to Cloudflare Workers, including a new example, CLI flags, and runtime adaptations.
  • New CLI Options: Added --cf flag to the xmcp dev and xmcp build commands for Cloudflare Workers development and production builds, respectively.
  • Project Scaffolding: The create-xmcp-app utility now includes a --cloudflare option to initialize new projects with Cloudflare Workers specific configurations.
  • Bundler and Runtime Enhancements: Modified the xmcp bundler to target webworker environments, handle Node.js built-in fallbacks, and inject client bundles for Cloudflare. The runtime now includes a Web API-based stateless HTTP transport and Cloudflare-specific authentication middlewares (API Key and JWT).
  • Dependency Updates: Updated the Auth0 plugin version and its xmcp peer dependency, and added jose as a new dependency for JWT handling.
Changelog
  • examples/cloudflare-workers/.gitignore
    • Added a new .gitignore file tailored for Cloudflare Workers projects.
  • examples/cloudflare-workers/README.md
    • Added a comprehensive README file detailing how to get started, build, develop, test, and deploy xmcp MCP servers to Cloudflare Workers.
  • examples/cloudflare-workers/package.json
    • Added a new package.json file for the Cloudflare Workers example, including necessary scripts and dependencies like wrangler and @cloudflare/workers-types.
  • examples/cloudflare-workers/src/tools/get-weather.ts
    • Added a mock 'get-weather' tool as an example for Cloudflare Workers.
  • examples/cloudflare-workers/src/tools/hello.ts
    • Added a 'hello' tool example for Cloudflare Workers, demonstrating authentication information usage.
  • examples/cloudflare-workers/tsconfig.json
    • Added a new tsconfig.json file configured for Cloudflare Workers development.
  • examples/cloudflare-workers/xmcp.config.ts
    • Added a new xmcp.config.ts file for the Cloudflare Workers example, setting up HTTP debug and tool paths.
  • examples/with-nestjs/tsconfig.json
    • Applied minor formatting changes by adding a trailing comma to the paths object.
  • packages/create-xmcp-app/src/helpers/cloudflare.ts
    • Added a new helper function applyCloudflareSettings to configure package.json scripts, wrangler.jsonc, and tsconfig.json for Cloudflare Workers projects.
  • packages/create-xmcp-app/src/helpers/create.ts
    • Integrated applyCloudflareSettings into the project creation process when the cloudflare option is enabled.
    • Added a cloudflare option to the ProjectOptions interface.
  • packages/create-xmcp-app/src/index.ts
    • Imported applyCloudflareSettings to be used during project creation.
    • Added --cloudflare (or --cf) CLI option to initialize projects for Cloudflare Workers.
    • Applied Cloudflare settings when creating a project from an example if the --cloudflare option is used.
  • packages/plugins/auth0/package.json
    • Bumped the package version from 0.0.2 to 0.1.0.
    • Updated the xmcp peer dependency and dev dependency from ^0.5.8 to ^0.6.2.
  • packages/xmcp/bundler/build-main.ts
    • Added cloudflare.ts as a new entry point for the main bundler build.
  • packages/xmcp/bundler/build-runtime.ts
    • Updated the script description comment.
    • Renamed the Rspack config name from runtime to runtime-node.
    • Improved error logging for runtime build errors.
  • packages/xmcp/package.json
    • Added cloudflare export mapping to dist/cloudflare.d.ts and dist/cloudflare.js.
    • Added typesVersions entry for cloudflare.
    • Included src directory in the files array for better source mapping and debugging.
    • Added jose library as a dependency for JWT handling in Cloudflare Workers.
  • packages/xmcp/src/cli.ts
    • Imported buildCloudflareOutput for Cloudflare Workers deployment.
    • Added --cf option to the dev command to enable Cloudflare Workers output in development mode.
    • Added --cf option to the build command to build for Cloudflare Workers deployment.
    • Integrated buildCloudflareOutput into the build process when isCloudflareBuild is true, with error handling.
  • packages/xmcp/src/cloudflare.ts
    • New file: Exports Cloudflare-specific API key and JWT authentication middlewares, and WebMiddleware type.
  • packages/xmcp/src/compiler/compiler-context.ts
    • Added a cloudflare boolean flag to the platforms object in CompilerContext to indicate Cloudflare Workers build target.
  • packages/xmcp/src/compiler/config/tests/config.test.ts
    • Updated the default description for the xmcp server to be more concise.
  • packages/xmcp/src/compiler/config/index.ts
    • Changed RspackOptions import to a type-only import.
  • packages/xmcp/src/compiler/generate-import-code.ts
    • Implemented conditional import generation: static imports for Cloudflare Workers (to avoid code splitting) and dynamic imports for Node.js environments.
    • Added pathToIdentifier utility to create valid variable names from file paths.
  • packages/xmcp/src/compiler/get-bundler-config/get-entries.ts
    • Added a Cloudflare-specific entry point (worker.ts) when targeting Cloudflare Workers.
  • packages/xmcp/src/compiler/get-bundler-config/index.ts
    • Modified output path and filename to be Cloudflare-specific (.xmcp/cloudflare/worker.js) when isCloudflare is true.
    • Set bundler target to webworker and enabled outputModule experiment for Cloudflare builds.
    • Configured externals to handle async_hooks for Cloudflare and Node.js built-in fallbacks.
    • Added aliases for zod and xmcp/plugins/x402 to ensure correct resolution in Cloudflare builds.
    • Introduced IgnorePlugin and NormalModuleReplacementPlugin to handle Node.js built-in modules for Cloudflare.
    • Added runtimeChunk: false to optimization for Cloudflare builds.
    • Injected IS_CLOUDFLARE and INJECTED_CLIENT_BUNDLES as defined variables for Cloudflare builds.
  • packages/xmcp/src/compiler/get-bundler-config/plugins.ts
    • File removed; its content was refactored and moved to a new plugins directory structure.
  • packages/xmcp/src/compiler/get-bundler-config/plugins/index.ts
    • New file: Contains readClientBundlesFromDisk for Cloudflare injection, runtimeFiles export, getNeededRuntimeFiles logic, InjectRuntimePlugin, and CreateTypeDefinitionPlugin.
  • packages/xmcp/src/compiler/get-bundler-config/plugins/types/express.ts
    • New file: Defines the expressTypeDefinition string for Express adapter types.
  • packages/xmcp/src/compiler/get-bundler-config/plugins/types/index.ts
    • New file: Re-exports type definitions for Next.js, Express, and NestJS.
  • packages/xmcp/src/compiler/get-bundler-config/plugins/types/nest.ts
    • New file: Defines the nestJsTypeDefinition string for NestJS adapter types.
  • packages/xmcp/src/compiler/get-bundler-config/plugins/types/next.ts
    • New file: Defines the nextJsTypeDefinition string for Next.js adapter types.
  • packages/xmcp/src/compiler/index.ts
    • Imported buildCloudflareOutput for use in the compiler.
    • Passed platforms context to the compiler.
    • Integrated buildCloudflareOutput into the development mode when platforms.cloudflare is enabled, ensuring Cloudflare output is synced during dev.
  • packages/xmcp/src/compiler/parse-xmcp-config.ts
    • Added logic to remove stdio and ensure http is enabled when building for Cloudflare Workers.
  • packages/xmcp/src/compiler/utils/path-utils.ts
    • Modified pathToToolName to dynamically select between pathToToolNameDjb2 (for Cloudflare) and pathToToolNameMd5 (for Node.js) based on the compiler context.
  • packages/xmcp/src/index.ts
    • Exported new types: WebMiddleware and WebMiddlewareContext.
  • packages/xmcp/src/platforms/build-cloudflare-output.ts
    • New file: Contains buildCloudflareOutput function to copy the bundled worker and generate wrangler.jsonc if not present, along with helper functions for project naming and config generation.
  • packages/xmcp/src/runtime/contexts/http-request-context.ts
    • Replaced IncomingHttpHeaders with a more generic HttpHeaders type to support both Node.js and Web API headers.
  • packages/xmcp/src/runtime/platforms/cloudflare/cors.ts
    • New file: Provides addCorsHeaders and handleCorsPreflightRequest functions for CORS handling in Cloudflare Workers.
  • packages/xmcp/src/runtime/platforms/cloudflare/middlewares/api-key.ts
    • New file: Implements cloudflareApiKeyAuthMiddleware for API key authentication in Cloudflare Workers, supporting static keys or custom validation functions.
  • packages/xmcp/src/runtime/platforms/cloudflare/middlewares/jwt.ts
    • New file: Implements cloudflareJwtAuthMiddleware for JWT authentication in Cloudflare Workers, leveraging the jose library.
  • packages/xmcp/src/runtime/platforms/cloudflare/types.ts
    • New file: Defines Env and ExecutionContext interfaces for Cloudflare Workers.
  • packages/xmcp/src/runtime/platforms/cloudflare/worker.ts
    • New file: The main Cloudflare Workers entry point, handling HTTP requests, CORS, health checks, home page rendering, and MCP request processing through a WebStatelessHttpTransport.
  • packages/xmcp/src/runtime/transports/http/cors/headers.ts
    • New file: Provides buildCorsHeaders utility function to construct CORS headers based on a given configuration.
  • packages/xmcp/src/runtime/transports/http/cors/index.ts
    • Refactored setHeaders to utilize the new buildCorsHeaders utility.
  • packages/xmcp/src/runtime/transports/http/web-stateless-http.ts
    • New file: Implements WebStatelessHttpTransport, a Web API-based transport for Cloudflare Workers, handling JSON-RPC messages and HTTP requests.
  • packages/xmcp/src/runtime/utils/path-to-tool-name.ts
    • New file: Provides pathToToolNameDjb2 (Web-compatible hash) and pathToToolNameMd5 (Node.js-compatible hash) for generating tool names, with pathToToolName as a default export.
  • packages/xmcp/src/runtime/utils/resources.ts
    • Modified pathToToolName to be dynamically chosen based on whether the environment is Cloudflare or Node.js.
    • Updated getClientBundle to read injected client bundles for Cloudflare Workers or dynamically from the filesystem for Node.js.
  • packages/xmcp/src/runtime/utils/tools.ts
    • Used z.object(toolSchema) for inputSchema to ensure compatibility and avoid Zod v3 cross-instance issues during JSON schema generation.
  • packages/xmcp/src/types/declarations.ts
    • Added module declarations for xmcp/cloudflare, exposing apiKeyAuthMiddleware, jwtAuthMiddleware, and related types.
  • packages/xmcp/src/types/middleware.ts
    • Added WebMiddlewareContext and WebMiddleware types to support middleware functions compatible with Web API environments like Cloudflare Workers.
  • packages/xmcp/src/utils/constants.ts
    • Imported createRequire for resolving xmcp source path.
    • Added cloudflareOutputPath constant.
    • Added resolveXmcpSrcPath function to dynamically determine the absolute path to the xmcp src folder.
  • packages/xmcp/xmcp.tsconfig.json
    • Added src/cloudflare.ts to the include array.
  • pnpm-lock.yaml
    • Updated various package versions and added new dependencies related to Cloudflare Workers support, including @cloudflare/workers-types, concurrently, wrangler, jose, and several @esbuild platform-specific packages.
Activity
  • The pull request introduces a significant new feature (Cloudflare Workers support) and associated infrastructure changes.
  • New example project for Cloudflare Workers has been added.
  • CLI commands have been extended to support Cloudflare-specific build and development workflows.
  • Core bundler and runtime logic have been adapted for the Cloudflare Workers environment.
  • New authentication middlewares tailored for Cloudflare Workers have been implemented.
Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature Command Description
Code Review /gemini review Performs a code review for the current pull request in its current state.
Pull Request Summary /gemini summary Provides a summary of the current pull request in its current state.
Comment @gemini-code-assist Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help /gemini help Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

  1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution.

Copy link

@gemini-code-assist gemini-code-assist bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request introduces comprehensive support for deploying xmcp servers to Cloudflare Workers. The changes are well-architected, with a clear separation between the Node.js and Cloudflare runtimes. The bundler configuration has been cleverly adapted to produce a single, optimized worker file, and the new stateless HTTP transport is a solid implementation for the edge environment. The addition of a Cloudflare example and updates to create-xmcp-app make it easy for developers to get started.

I've added a couple of review comments with suggestions for minor improvements, including a bug fix in the project scaffolding logic. Overall, this is an excellent feature addition that significantly expands the deployment options for xmcp.

Comment on lines +68 to +70
if (!Array.isArray(tsconfig.compilerOptions.types)) {
return;
}

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

high

The current logic in ensureTsConfig will not add @cloudflare/workers-types to tsconfig.json if the compilerOptions.types array does not already exist. The function returns early if tsconfig.compilerOptions.types is not an array, which includes the case where it is undefined. This can lead to an incomplete setup for users who don't have a types array in their tsconfig.json.

The logic should be adjusted to handle cases where types is missing and create it, or when it exists, to add the new type if it's not already present.

Suggested change
if (!Array.isArray(tsconfig.compilerOptions.types)) {
return;
}
if (tsconfig.compilerOptions.types === undefined) {
tsconfig.compilerOptions.types = [];
} else if (!Array.isArray(tsconfig.compilerOptions.types)) {
// If `types` exists but is not an array, we can't safely modify it.
return;
}

Comment on lines +23 to +28
return (
`Weather in ${mockWeather.location}:\n` +
`Temperature: ${mockWeather.temperature}°C\n` +
`Conditions: ${mockWeather.conditions}\n` +
`Humidity: ${mockWeather.humidity}%`
);

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

For improved readability and maintainability, consider using an array of strings joined by a newline character instead of string concatenation with +. This pattern is often cleaner when building multi-line strings.

Suggested change
return (
`Weather in ${mockWeather.location}:\n` +
`Temperature: ${mockWeather.temperature}°C\n` +
`Conditions: ${mockWeather.conditions}\n` +
`Humidity: ${mockWeather.humidity}%`
);
return [
`Weather in ${mockWeather.location}:`,
`Temperature: ${mockWeather.temperature}°C`,
`Conditions: ${mockWeather.conditions}`,
`Humidity: ${mockWeather.humidity}%`,
].join("\n");

@greptile-apps
Copy link

greptile-apps bot commented Feb 4, 2026

Greptile Overview

Greptile Summary

This PR adds comprehensive Cloudflare Workers support to xmcp, enabling deployment of MCP servers to Cloudflare's edge platform. The implementation includes:

  • New Cloudflare Workers runtime: Stateless HTTP transport using Web APIs instead of Node.js APIs (web-stateless-http.ts, worker.ts)
  • Authentication middlewares: JWT and API key authentication for Cloudflare Workers
  • Platform-specific bundling: Static imports for Cloudflare (avoiding code splitting) vs dynamic imports for Node.js
  • CLI enhancements: Added --cf flag for build and dev commands with CF_PAGES environment detection
  • Hashing compatibility: djb2 hash for Cloudflare (no crypto module) vs MD5 for Node.js
  • Example project: Complete Cloudflare Workers starter in examples/cloudflare-workers/
  • Build tooling: Automatic wrangler.jsonc generation and worker.js output

The code is well-structured and follows good patterns for platform abstraction. The changes maintain backward compatibility for existing Node.js deployments.

Confidence Score: 5/5

  • This PR is safe to merge with minimal risk
  • The implementation is comprehensive, well-tested through example projects, and maintains backward compatibility. The platform abstraction is clean, and the code follows established patterns. Only minor style improvement suggested for error logging.
  • No files require special attention

Important Files Changed

Filename Overview
packages/xmcp/src/runtime/platforms/cloudflare/middlewares/jwt.ts Added JWT authentication middleware for Cloudflare Workers with support for multiple key formats
packages/xmcp/src/runtime/platforms/cloudflare/worker.ts Implemented stateless Cloudflare Workers fetch handler with middleware support, CORS, and MCP request handling
packages/xmcp/src/runtime/transports/http/web-stateless-http.ts Created Web API-based stateless HTTP transport for Cloudflare Workers with JSON-RPC batching support
packages/xmcp/src/compiler/generate-import-code.ts Implemented platform-specific import generation (static for Cloudflare, dynamic for Node.js)
packages/xmcp/src/cli.ts Added --cf flag for Cloudflare Workers build and dev commands with CF_PAGES environment detection
packages/xmcp/package.json Added cloudflare export, typesVersions, jose dependency, and included src in files array

Copy link

@greptile-apps greptile-apps bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

6 files reviewed, 1 comment

Edit Code Review Agent Settings | Greptile

Comment on lines +28 to +32
await verifyJwt(token, config);
return;
} catch {
return jsonUnauthorized("Unauthorized: Invalid or expired token");
}
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

error details are silently swallowed, making debugging difficult

Suggested change
await verifyJwt(token, config);
return;
} catch {
return jsonUnauthorized("Unauthorized: Invalid or expired token");
}
} catch (error) {
console.error("[JWT Auth] Token verification failed:", error);
return jsonUnauthorized("Unauthorized: Invalid or expired token");
}
Prompt To Fix With AI
This is a comment left during a code review.
Path: packages/xmcp/src/runtime/platforms/cloudflare/middlewares/jwt.ts
Line: 28:32

Comment:
error details are silently swallowed, making debugging difficult

```suggestion
    } catch (error) {
      console.error("[JWT Auth] Token verification failed:", error);
      return jsonUnauthorized("Unauthorized: Invalid or expired token");
    }
```

How can I resolve this? If you propose a fix, please make it concise.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants