@vinkius-core/mcp-fusion-cloudflare 1.0.0

package/dist/adapter.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Cloudflare Workers ExecutionContext.
+ *
+ * Provides `waitUntil()` for background tasks and `passThroughOnException()`.
+ * Defined inline to avoid requiring `@cloudflare/workers-types`.
+ *
+ * If `@cloudflare/workers-types` is installed, the user's types will
+ * merge with this via declaration merging.
+ */
+export interface ExecutionContext {
+    waitUntil(promise: Promise<unknown>): void;
+    passThroughOnException(): void;
+}
+/**
+ * Duck-typed interface for MCP Fusion's ToolRegistry.
+ *
+ * Accepts any object with `attachToServer()` — decoupled from the
+ * concrete class to avoid importing the core package at type level.
+ */
+export interface RegistryLike {
+    attachToServer(server: unknown, options?: Record<string, unknown>): Promise<unknown>;
+}
+/**
+ * Configuration for the Cloudflare Workers adapter.
+ *
+ * @typeParam TEnv - Cloudflare environment bindings (D1, KV, R2, secrets)
+ * @typeParam TContext - Application context type for Fusion handlers
+ */
+export interface CloudflareAdapterOptions<TEnv, TContext> {
+    /**
+     * A pre-built `ToolRegistry` populated during Cold Start.
+     *
+     * The registry contains all tools with their Zod schemas,
+     * Presenters, and middleware already compiled. This avoids
+     * re-running reflection on every request.
+     */
+    readonly registry: RegistryLike;
+    /** MCP server name (visible in capabilities). Default: `'mcp-fusion-edge'` */
+    readonly serverName?: string;
+    /** MCP server version string. Default: `'1.0.0'` */
+    readonly serverVersion?: string;
+    /**
+     * Context factory — creates the application context per request.
+     *
+     * Receives the Cloudflare `Request`, `env` bindings, and `ExecutionContext`,
+     * allowing full access to D1 databases, KV namespaces, R2 buckets, and secrets.
+     *
+     * @example
+     * ```typescript
+     * contextFactory: async (req, env) => ({
+     *     db: env.DB,           // D1 binding
+     *     tenantId: req.headers.get('x-tenant-id') || 'public',
+     * })
+     * ```
+     */
+    readonly contextFactory?: (req: Request, env: TEnv, ctx: ExecutionContext) => TContext | Promise<TContext>;
+    /**
+     * Additional options forwarded to `registry.attachToServer()`.
+     *
+     * Supports `filter`, `stateSync`, `observability`, etc.
+     */
+    readonly attachOptions?: Record<string, unknown>;
+}
+/**
+ * The object returned by `cloudflareWorkersAdapter()`.
+ *
+ * Implements the Cloudflare Workers ES Modules `fetch` handler signature.
+ *
+ * @typeParam TEnv - Cloudflare environment bindings
+ */
+export interface CloudflareWorkerHandler<TEnv> {
+    fetch(request: Request, env: TEnv, ctx: ExecutionContext): Promise<Response>;
+}
+/**
+ * Create a Cloudflare Workers adapter for MCP Fusion.
+ *
+ * Returns an object with a `fetch()` method matching the Workers
+ * ES Modules export default interface. Each request creates an
+ * ephemeral `McpServer` + `WebStandardStreamableHTTPServerTransport`,
+ * wires the pre-compiled registry, and returns the MCP JSON-RPC response.
+ *
+ * @typeParam TEnv - Cloudflare environment bindings (typed by the developer)
+ * @typeParam TContext - Application context type for Fusion handlers
+ *
+ * @example
+ * ```typescript
+ * // worker.ts
+ * import { ToolRegistry } from '@vinkius-core/mcp-fusion';
+ * import { cloudflareWorkersAdapter } from '@vinkius-core/mcp-fusion-cloudflare';
+ * import { billing, projects } from './tools.js';
+ *
+ * // COLD START: Zod reflection + compilation (once)
+ * const registry = new ToolRegistry<MyContext>();
+ * registry.registerAll(billing, projects);
+ *
+ * export interface Env { DB: D1Database; KV: KVNamespace; }
+ *
+ * // WARM REQUEST: Only McpServer + Transport per invocation
+ * export default cloudflareWorkersAdapter<Env, MyContext>({
+ *     registry,
+ *     contextFactory: async (req, env) => ({
+ *         db: env.DB,
+ *         tenantId: req.headers.get('x-tenant-id') || 'public',
+ *     }),
+ * });
+ * ```
+ */
+export declare function cloudflareWorkersAdapter<TEnv = unknown, TContext = void>(options: CloudflareAdapterOptions<TEnv, TContext>): CloudflareWorkerHandler<TEnv>;
+//# sourceMappingURL=adapter.d.ts.map

package/dist/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAsCA;;;;;;;;GAQG;AACH,MAAM,WAAW,gBAAgB;IAC7B,SAAS,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC;IAC3C,sBAAsB,IAAI,IAAI,CAAC;CAClC;AAMD;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IACzB,cAAc,CACV,MAAM,EAAE,OAAO,EACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAClC,OAAO,CAAC,OAAO,CAAC,CAAC;CACvB;AAED;;;;;GAKG;AACH,MAAM,WAAW,wBAAwB,CAAC,IAAI,EAAE,QAAQ;IACpD;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;IAEhC,8EAA8E;IAC9E,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAE7B,oDAAoD;IACpD,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAEhC;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,CACtB,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,IAAI,EACT,GAAG,EAAE,gBAAgB,KACpB,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAElC;;;;OAIG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpD;AAED;;;;;;GAMG;AACH,MAAM,WAAW,uBAAuB,CAAC,IAAI;IACzC,KAAK,CACD,OAAO,EAAE,OAAO,EAChB,GAAG,EAAE,IAAI,EACT,GAAG,EAAE,gBAAgB,GACtB,OAAO,CAAC,QAAQ,CAAC,CAAC;CACxB;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,GAAG,OAAO,EAAE,QAAQ,GAAG,IAAI,EACpE,OAAO,EAAE,wBAAwB,CAAC,IAAI,EAAE,QAAQ,CAAC,GAClD,uBAAuB,CAAC,IAAI,CAAC,CAwE/B"}

package/dist/adapter.js

@@ -0,0 +1,122 @@
+/**
+ * MCP Fusion — Cloudflare Workers Adapter
+ *
+ * Deploys an MCP Fusion ToolRegistry to Cloudflare Workers edge
+ * with zero configuration. Uses the MCP SDK's native WinterCG
+ * transport (`WebStandardStreamableHTTPServerTransport`).
+ *
+ * **Architecture**:
+ *
+ * - **Cold Start** (once): The developer builds and populates a
+ *   `ToolRegistry` in the module's top-level scope. Zod reflection,
+ *   Presenter compilation, and schema generation happen here —
+ *   zero CPU cost on warm requests.
+ *
+ * - **Warm Request** (per invocation): Only `McpServer` + `Transport`
+ *   are instantiated per request. `attachToServer()` is a trivial
+ *   handler-routing layer — no reflection, no compilation.
+ *
+ * **Stateless JSON-RPC**: Cloudflare Workers are ephemeral. This
+ * adapter forces `enableJsonResponse: true` — no SSE, no sessions,
+ * no streaming notifications. Pure request/response. Compatible with
+ * backend orchestrators (LangChain, Vercel AI SDK, custom agents).
+ *
+ * **Cloudflare `env` Injection**: The `env` object (D1, KV, R2,
+ * secrets) is injected per-request via the Worker's `fetch()`
+ * signature. The adapter exposes it to the user's `contextFactory`.
+ *
+ * @module
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { WebStandardStreamableHTTPServerTransport, } from '@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js';
+// ============================================================================
+// Adapter
+// ============================================================================
+/**
+ * Create a Cloudflare Workers adapter for MCP Fusion.
+ *
+ * Returns an object with a `fetch()` method matching the Workers
+ * ES Modules export default interface. Each request creates an
+ * ephemeral `McpServer` + `WebStandardStreamableHTTPServerTransport`,
+ * wires the pre-compiled registry, and returns the MCP JSON-RPC response.
+ *
+ * @typeParam TEnv - Cloudflare environment bindings (typed by the developer)
+ * @typeParam TContext - Application context type for Fusion handlers
+ *
+ * @example
+ * ```typescript
+ * // worker.ts
+ * import { ToolRegistry } from '@vinkius-core/mcp-fusion';
+ * import { cloudflareWorkersAdapter } from '@vinkius-core/mcp-fusion-cloudflare';
+ * import { billing, projects } from './tools.js';
+ *
+ * // COLD START: Zod reflection + compilation (once)
+ * const registry = new ToolRegistry<MyContext>();
+ * registry.registerAll(billing, projects);
+ *
+ * export interface Env { DB: D1Database; KV: KVNamespace; }
+ *
+ * // WARM REQUEST: Only McpServer + Transport per invocation
+ * export default cloudflareWorkersAdapter<Env, MyContext>({
+ *     registry,
+ *     contextFactory: async (req, env) => ({
+ *         db: env.DB,
+ *         tenantId: req.headers.get('x-tenant-id') || 'public',
+ *     }),
+ * });
+ * ```
+ */
+export function cloudflareWorkersAdapter(options) {
+    const { registry, serverName = 'mcp-fusion-edge', serverVersion = '1.0.0', contextFactory, attachOptions = {}, } = options;
+    return {
+        async fetch(request, env, ctx) {
+            // Only POST is valid for stateless MCP JSON-RPC
+            if (request.method !== 'POST') {
+                return new Response(JSON.stringify({
+                    jsonrpc: '2.0',
+                    error: {
+                        code: -32600,
+                        message: 'Only POST requests are accepted. This is a stateless MCP endpoint.',
+                    },
+                }), {
+                    status: 405,
+                    headers: {
+                        'Content-Type': 'application/json',
+                        'Allow': 'POST',
+                    },
+                });
+            }
+            // 1. Ephemeral McpServer (isolates concurrent requests)
+            const server = new McpServer({
+                name: serverName,
+                version: serverVersion,
+            });
+            // 2. Stateless WinterCG transport — JSON-RPC only, no SSE
+            const transport = new WebStandardStreamableHTTPServerTransport({
+                enableJsonResponse: true,
+            });
+            // 3. Build context from Cloudflare env (per-request)
+            const requestContext = contextFactory
+                ? await contextFactory(request, env, ctx)
+                : undefined;
+            // 4. Wire the pre-compiled registry to the ephemeral server
+            const mergedOptions = {
+                ...attachOptions,
+            };
+            if (requestContext !== undefined) {
+                mergedOptions['contextFactory'] = () => requestContext;
+            }
+            await registry.attachToServer(server, mergedOptions);
+            // 5. Connect transport and handle the request
+            await server.connect(transport);
+            try {
+                return await transport.handleRequest(request);
+            }
+            finally {
+                // Cleanup — release resources
+                await server.close();
+            }
+        },
+    };
+}
+//# sourceMappingURL=adapter.js.map

package/dist/adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.js","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EACH,wCAAwC,GAC3C,MAAM,+DAA+D,CAAC;AAsGvE,+EAA+E;AAC/E,UAAU;AACV,+EAA+E;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,MAAM,UAAU,wBAAwB,CACpC,OAAiD;IAEjD,MAAM,EACF,QAAQ,EACR,UAAU,GAAG,iBAAiB,EAC9B,aAAa,GAAG,OAAO,EACvB,cAAc,EACd,aAAa,GAAG,EAAE,GACrB,GAAG,OAAO,CAAC;IAEZ,OAAO;QACH,KAAK,CAAC,KAAK,CACP,OAAgB,EAChB,GAAS,EACT,GAAqB;YAErB,gDAAgD;YAChD,IAAI,OAAO,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;gBAC5B,OAAO,IAAI,QAAQ,CACf,IAAI,CAAC,SAAS,CAAC;oBACX,OAAO,EAAE,KAAK;oBACd,KAAK,EAAE;wBACH,IAAI,EAAE,CAAC,KAAK;wBACZ,OAAO,EAAE,oEAAoE;qBAChF;iBACJ,CAAC,EACF;oBACI,MAAM,EAAE,GAAG;oBACX,OAAO,EAAE;wBACL,cAAc,EAAE,kBAAkB;wBAClC,OAAO,EAAE,MAAM;qBAClB;iBACJ,CACJ,CAAC;YACN,CAAC;YAED,wDAAwD;YACxD,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;gBACzB,IAAI,EAAE,UAAU;gBAChB,OAAO,EAAE,aAAa;aACzB,CAAC,CAAC;YAEH,0DAA0D;YAC1D,MAAM,SAAS,GAAG,IAAI,wCAAwC,CAAC;gBAC3D,kBAAkB,EAAE,IAAI;aAC3B,CAAC,CAAC;YAEH,qDAAqD;YACrD,MAAM,cAAc,GAAG,cAAc;gBACjC,CAAC,CAAC,MAAM,cAAc,CAAC,OAAO,EAAE,GAAG,EAAE,GAAG,CAAC;gBACzC,CAAC,CAAC,SAAS,CAAC;YAEhB,4DAA4D;YAC5D,MAAM,aAAa,GAA4B;gBAC3C,GAAG,aAAa;aACnB,CAAC;YACF,IAAI,cAAc,KAAK,SAAS,EAAE,CAAC;gBAC/B,aAAa,CAAC,gBAAgB,CAAC,GAAG,GAAG,EAAE,CAAC,cAAc,CAAC;YAC3D,CAAC;YAED,MAAM,QAAQ,CAAC,cAAc,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;YAErD,8CAA8C;YAC9C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;YAEhC,IAAI,CAAC;gBACD,OAAO,MAAM,SAAS,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;YAClD,CAAC;oBAAS,CAAC;gBACP,8BAA8B;gBAC9B,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;YACzB,CAAC;QACL,CAAC;KACJ,CAAC;AACN,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @vinkius-core/mcp-fusion-cloudflare
+ *
+ * Cloudflare Workers adapter for MCP Fusion.
+ *
+ * @module
+ */
+export { cloudflareWorkersAdapter, type CloudflareAdapterOptions, type CloudflareWorkerHandler, type RegistryLike, } from './adapter.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EACH,wBAAwB,EACxB,KAAK,wBAAwB,EAC7B,KAAK,uBAAuB,EAC5B,KAAK,YAAY,GACpB,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1,9 @@
+/**
+ * @vinkius-core/mcp-fusion-cloudflare
+ *
+ * Cloudflare Workers adapter for MCP Fusion.
+ *
+ * @module
+ */
+export { cloudflareWorkersAdapter, } from './adapter.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EACH,wBAAwB,GAI3B,MAAM,cAAc,CAAC"}

package/package.json

@@ -0,0 +1,54 @@
+{
+    "name": "@vinkius-core/mcp-fusion-cloudflare",
+    "version": "1.0.0",
+    "description": "Cloudflare Workers adapter for MCP Fusion. Deploys your MCP server to the edge with zero config — stateless JSON-RPC, cold-start caching, and native env injection.",
+    "type": "module",
+    "main": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "exports": {
+        ".": {
+            "import": "./dist/index.js",
+            "types": "./dist/index.d.ts"
+        }
+    },
+    "scripts": {
+        "build": "tsc",
+        "prepublishOnly": "npm run build"
+    },
+    "keywords": [
+        "mcp",
+        "mcp-fusion",
+        "cloudflare",
+        "workers",
+        "edge",
+        "serverless",
+        "wintercg",
+        "ai",
+        "llm"
+    ],
+    "author": "Vinkius Labs",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/vinkius-labs/mcp-fusion.git",
+        "directory": "packages/cloudflare"
+    },
+    "bugs": {
+        "url": "https://github.com/vinkius-labs/mcp-fusion/issues"
+    },
+    "homepage": "https://mcp-fusion.vinkius.com/",
+    "files": [
+        "dist",
+        "README.md"
+    ],
+    "engines": {
+        "node": ">=18.0.0"
+    },
+    "publishConfig": {
+        "access": "public"
+    },
+    "peerDependencies": {
+        "@vinkius-core/mcp-fusion": "^2.0.0",
+        "@modelcontextprotocol/sdk": "^1.12.0"
+    },
+    "license": "Apache-2.0"
+}