@frontmcp/edge 0.0.1

package/kv-cache.d.ts

@@ -0,0 +1,82 @@
+/**
+ * KV-backed last-good bundle cache for managed edge mode.
+ *
+ * A Cloudflare Worker has no filesystem, so the SaaS bundle source's default
+ * on-disk cache (the boot fallback when a fresh pull fails) can't be used.
+ * `createKvBundleCache` adapts a Cloudflare **KV namespace** to the generic
+ * `BundleCacheStore` contract (`@frontmcp/adapters/skills`) so the last-good
+ * bundle survives across isolate restarts and cold starts.
+ *
+ * ```ts
+ * import { createEdgeMcp, createKvBundleCache } from '@frontmcp/edge';
+ *
+ * export default createEdgeMcp({
+ *   info: { name: 'my-worker', version: '1.0.0' },
+ *   apps: [],
+ *   tasks: { enabled: false },
+ *   managed: {
+ *     endpoint: env.BUNDLE_ENDPOINT,
+ *     authToken: env.PULL_TOKEN,
+ *     // ...
+ *     cache: createKvBundleCache(env.BUNDLE_CACHE), // KV namespace binding
+ *   },
+ * });
+ * ```
+ */
+/**
+ * Minimal structural subset of the Cloudflare `KVNamespace` binding this cache
+ * needs. Declared locally so `@frontmcp/edge` stays free of a hard dependency
+ * on `@cloudflare/workers-types` (any runtime exposing this shape works).
+ */
+export interface EdgeKvNamespace {
+    get(key: string, type?: 'text'): Promise<string | null>;
+    put(key: string, value: string, options?: {
+        expirationTtl?: number;
+    }): Promise<void>;
+}
+/**
+ * A last-good bundle cache. Structurally compatible with the adapters'
+ * `BundleCacheStore` — kept local (bundle typed as `unknown`) so the edge
+ * package doesn't depend on `@frontmcp/adapters`; the cache only round-trips
+ * JSON and never inspects the bundle's shape.
+ */
+export interface EdgeBundleCacheStore {
+    read(): Promise<unknown>;
+    write(bundle: unknown): Promise<void>;
+}
+/** Tuning for {@link createKvBundleCache}. */
+export interface KvBundleCacheOptions {
+    /** KV key for the serialized last-good bundle. Default `frontmcp:bundle:last-good`. */
+    key?: string;
+    /** Optional KV TTL (seconds). Omit to persist indefinitely (the usual choice — it's a fallback). */
+    expirationTtl?: number;
+}
+/**
+ * Lazily resolve a cache from the per-request Worker `env`. Cloudflare bindings
+ * (KV namespaces, etc.) live on the `env` argument passed to `fetch`/`scheduled`
+ * — NOT in module scope — so a cache that needs a binding must be built from
+ * `env` at request time, not when the module first evaluates.
+ */
+export type EdgeBundleCacheFactory = (env: unknown) => EdgeBundleCacheStore | undefined;
+/**
+ * Build a {@link EdgeBundleCacheStore} backed by a Cloudflare KV namespace.
+ *
+ * Reads tolerate a missing key (cold KV) and corrupt JSON by resolving to
+ * `undefined` — the source then treats it as "no last-good cache" and surfaces
+ * the original pull failure, rather than crashing on a bad cache entry.
+ */
+export declare function createKvBundleCache(kv: EdgeKvNamespace, options?: KvBundleCacheOptions): EdgeBundleCacheStore;
+/**
+ * Convenience {@link EdgeBundleCacheFactory}: read a KV namespace from
+ * `env[binding]` at request time and wrap it as a bundle cache. Pass this as
+ * `managed.cache` so the binding is resolved from the Worker's `env` (where CF
+ * bindings actually live) instead of at module-eval where it doesn't exist yet.
+ *
+ * ```ts
+ * managed: { …, cache: kvBundleCacheFromEnv('BUNDLE_CACHE') }
+ * ```
+ *
+ * Returns `undefined` (no cache → source uses no fallback) when the binding is
+ * absent, rather than throwing — a misconfigured binding shouldn't crash boot.
+ */
+export declare function kvBundleCacheFromEnv(binding: string, options?: KvBundleCacheOptions): EdgeBundleCacheFactory;

package/managed.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Managed edge mode — an auto-updating, skilled-OpenAPI-backed edge server.
+ *
+ * Points the edge runtime at a SaaS endpoint that serves a signed
+ * **skilled-openapi** bundle (OpenAPI specs compiled into MCP skills + tools).
+ * The bundle is pulled on boot and kept fresh by polling (and/or a push
+ * webhook), so the server's capabilities update **without redeploying** —
+ * backed by the existing `@frontmcp/plugin-skilled-openapi` SaaS-pull source
+ * (which handles signature verification, replay/SSRF guards, and last-good
+ * cache fallback).
+ */
+import type { EdgeBundleCacheFactory, EdgeBundleCacheStore } from './kv-cache';
+export interface ManagedEdgeOptions {
+    /** SaaS pull endpoint serving the signed bundle (HTTPS). */
+    endpoint: string;
+    /** Pinned JWT the SaaS issued for this server. */
+    authToken: string;
+    /** RFC 8707 resource indicator the JWT must encode (verified on pull/push). */
+    expectedAudience: string;
+    /** JWKS URL for verifying SaaS-issued tokens (HTTPS). */
+    jwksUrl: string;
+    /** Expected `iss` (issuer) claim. */
+    expectedIssuer: string;
+    /**
+     * Auto-update polling interval in ms (the boot pull is always immediate).
+     * Default 300000 (5 min) — the plugin re-pulls and hot-swaps on change.
+     *
+     * NOTE: IGNORED on the edge. `createEdgeMcp` disables the internal poll loop
+     * (Workers have no background execution between requests); a Cron Trigger
+     * drives {@link EdgeMcp.scheduled} → refresh instead. Set your refresh cadence
+     * via `[triggers] crontabs` in `wrangler.toml`, not this field.
+     */
+    pollIntervalMs?: number;
+    /** Also mount a push webhook (`POST /__skilled_openapi/push`) for synchronous updates. */
+    enableWebhook?: boolean;
+    /** Require a signed bundle. Default true. */
+    requireSignature?: boolean;
+    /** Trusted public keys for bundle signature verification. */
+    trustedKeys?: unknown[];
+    /** Dev mode — bypass signature checks + relax defaults (loud warning). Never in production. */
+    dev?: boolean;
+    /** Static credential map seeded into the executor's resolver (dev / single-tenant). */
+    credentials?: Record<string, string>;
+    /** Outbound HTTP / SSRF options for the executor. */
+    outbound?: Record<string, unknown>;
+    /**
+     * Cache dir for the last-good bundle (boot fallback when a fresh pull fails).
+     * Filesystem-only — a no-op on a Worker (there is no filesystem); use {@link
+     * ManagedEdgeOptions.cache} there instead.
+     */
+    bundleCacheDir?: string;
+    /**
+     * Pluggable last-good bundle cache, replacing the on-disk cache entirely.
+     *
+     * On Cloudflare Workers a KV binding lives on the per-request `env`, not in
+     * module scope, so prefer the `env`-resolving factory form — e.g.
+     * `cache: kvBundleCacheFromEnv('BUNDLE_CACHE')` (or a custom
+     * `(env) => createKvBundleCache(env.MY_KV)`). A plain store is also accepted
+     * for runtimes where the cache is available at construction time.
+     */
+    cache?: EdgeBundleCacheStore | EdgeBundleCacheFactory;
+}
+/**
+ * Map {@link ManagedEdgeOptions} → the options object that
+ * `@frontmcp/plugin-skilled-openapi`'s `init(...)` accepts (a `saas` bundle
+ * source + plugin flags). Pure + dependency-free so it's unit-testable without
+ * loading the plugin.
+ */
+export declare function buildManagedOpenApiPluginOptions(managed: ManagedEdgeOptions): Record<string, unknown>;

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@frontmcp/edge",
+  "version": "0.0.1",
+  "description": "Run a FrontMCP MCP server on Cloudflare Workers / V8 isolates from a plain config — no decorators, no build step",
+  "author": "AgentFront <info@agentfront.dev>",
+  "license": "Apache-2.0",
+  "keywords": [
+    "frontmcp",
+    "mcp",
+    "cloudflare",
+    "cloudflare-workers",
+    "workerd",
+    "edge",
+    "deno",
+    "bun",
+    "fetch",
+    "v8-isolate"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/agentfront/frontmcp.git",
+    "directory": "libs/edge"
+  },
+  "bugs": {
+    "url": "https://github.com/agentfront/frontmcp/issues"
+  },
+  "homepage": "https://github.com/agentfront/frontmcp/blob/main/libs/edge/README.md",
+  "type": "commonjs",
+  "main": "./index.js",
+  "module": "./esm/index.mjs",
+  "types": "./index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "require": {
+        "types": "./index.d.ts",
+        "default": "./index.js"
+      },
+      "import": {
+        "types": "./index.d.ts",
+        "default": "./esm/index.mjs"
+      }
+    },
+    "./esm": null
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "peerDependencies": {
+    "@frontmcp/plugin-skilled-openapi": "1.4.0",
+    "@frontmcp/sdk": "1.4.0"
+  },
+  "peerDependenciesMeta": {
+    "@frontmcp/plugin-skilled-openapi": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.0.0"
+  }
+}

package/session-host.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Cloudflare **Durable Object** session host for stateful MCP on Workers.
+ *
+ * The stateless web path can't support the Streamable HTTP standalone GET
+ * notification stream: each request gets a fresh isolate/transport, so a
+ * `tools/call`'s notifications have no path back to the client's open GET
+ * stream. A Durable Object fixes this — one instance per `Mcp-Session-Id` holds
+ * a **persistent** `McpServer` + session-bound transport, so the GET stream
+ * stays open across requests and notifications reach it.
+ *
+ * It runs the SAME `http:request` flow as the stateless path (auth, quota,
+ * router, audit, metrics + hooks) — only the transport persists. The worker
+ * routes a request to its session DO; the DO runs the flow with its persistent
+ * transport threaded in.
+ */
+import { runHttpRequestFlowWeb, type WebFetchSessionRouter, type WebStandardMcpPair } from '@frontmcp/sdk';
+/** The FrontMCP scope type, derived to avoid widening the SDK's public surface. */
+type Scope = Parameters<typeof runHttpRequestFlowWeb>[0];
+/**
+ * Build the {@link WebFetchSessionRouter} that forwards an MCP request to its
+ * per-session Durable Object — addressed by `Mcp-Session-Id`, minting a fresh id
+ * for new sessions (`initialize`). Returns `undefined` (→ stateless fallback)
+ * when the DO binding isn't present or for CORS preflight (handled by the adapter).
+ */
+export declare function createEdgeSessionRouter(bindingName: string): WebFetchSessionRouter;
+/**
+ * Build the Durable Object class for stateful MCP sessions. `buildScope(env)`
+ * builds the FrontMCP scope inside the DO's isolate; `bridgeEnv(env)` mirrors the
+ * Worker `env` into `process.env` (so `session:verify` sees `MCP_SESSION_SECRET`,
+ * etc.). Each instance lazily builds its scope + a persistent transport once,
+ * then handles every request for its session on them.
+ */
+export declare function createEdgeSessionDurableObject(buildScope: (env: unknown) => Promise<Scope>, bridgeEnv: (env: unknown) => void): {
+    new (_state: unknown, env: unknown): {
+        "__#private@#scopePromise"?: Promise<Scope>;
+        "__#private@#pair"?: WebStandardMcpPair;
+        readonly "__#private@#doEnv": unknown;
+        fetch(request: Request): Promise<Response>;
+    };
+};
+export {};

package/skill-index-cache.d.ts

@@ -0,0 +1,51 @@
+/**
+ * KV-backed cache for the skill SEARCH INDEX (the TF-IDF / BM25 "embedding"
+ * model + per-skill vectors), for fast cold starts on Cloudflare Workers.
+ *
+ * Building the index means tokenizing every skill, computing IDF across the
+ * corpus, and embedding each document — work a long-lived server pays once but a
+ * Worker would otherwise repeat on EVERY cold start. This adapter persists the
+ * built index snapshot to a Cloudflare **KV namespace** (keyed by a content hash
+ * of the indexed skills), so a cold start restores it instead of recomputing.
+ *
+ * ```ts
+ * import { createEdgeMcp } from '@frontmcp/edge';
+ *
+ * export default createEdgeMcp({
+ *   info: { name: 'my-worker', version: '1.0.0' },
+ *   apps: [MyApp],
+ *   tasks: { enabled: false },
+ *   skillIndex: { binding: 'FRONTMCP_SKILL_INDEX' }, // KV namespace binding
+ * });
+ * ```
+ */
+import type { SkillIndexCache } from '@frontmcp/sdk';
+import type { EdgeKvNamespace } from './kv-cache';
+/** Tuning for {@link createKvSkillIndexCache}. */
+export interface KvSkillIndexCacheOptions {
+    /** KV key prefix for snapshots. The content hash is appended. Default `frontmcp:skill-index:`. */
+    keyPrefix?: string;
+    /** Optional KV TTL (seconds). Omit to persist indefinitely. */
+    expirationTtl?: number;
+}
+/**
+ * Lazily resolve a skill-index cache from the per-request Worker `env`. CF
+ * bindings (KV namespaces) live on `env`, not module scope, so a cache that
+ * needs a binding must be built from `env` at request time.
+ */
+export type EdgeSkillIndexCacheFactory = (env: unknown) => SkillIndexCache | undefined;
+/**
+ * Build a {@link SkillIndexCache} backed by a Cloudflare KV namespace.
+ *
+ * Reads tolerate a missing key (cold KV) and corrupt JSON by resolving to
+ * `undefined` (a miss → rebuild). Writes are best-effort: a KV write failure is
+ * swallowed so a persist error never fails search.
+ */
+export declare function createKvSkillIndexCache(kv: EdgeKvNamespace, options?: KvSkillIndexCacheOptions): SkillIndexCache;
+/**
+ * Convenience {@link EdgeSkillIndexCacheFactory}: read a KV namespace from
+ * `env[binding]` at request time and wrap it. Returns `undefined` when the
+ * binding is absent (caching is simply skipped — search still works), rather
+ * than throwing, so a missing binding never bricks boot.
+ */
+export declare function kvSkillIndexCacheFromEnv(binding: string, options?: KvSkillIndexCacheOptions): EdgeSkillIndexCacheFactory;