@frontmcp/edge 0.0.1

package/esm/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": "module",
+  "main": "../index.js",
+  "module": "./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": "./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/index.d.ts

@@ -0,0 +1,122 @@
+/**
+ * `@frontmcp/edge` — run a FrontMCP server on a V8-isolate runtime
+ * (Cloudflare Workers, Deno Deploy, Bun) from a plain config object.
+ *
+ * No `@FrontMcp` decorator, no `frontmcp build` step: the edge entry imports
+ * this package, passes a config, and exports the returned `fetch` handler. The
+ * bundler (wrangler/esbuild) handles the rest.
+ *
+ * ```ts
+ * // worker.ts (~10 lines)
+ * import { createEdgeMcp } from '@frontmcp/edge';
+ * import { MyApp } from './apps';
+ *
+ * export default createEdgeMcp({
+ *   info: { name: 'my-worker', version: '1.0.0' },
+ *   apps: [MyApp],
+ *   tasks: { enabled: false }, // edge has no Redis here
+ * });
+ * ```
+ *
+ * **Managed mode** (auto-updating): point it at a SaaS endpoint serving a
+ * signed skilled-openapi bundle (OpenAPI → skills + tools), pulled on boot and
+ * refreshed by polling — no redeploy on capability changes.
+ *
+ * ```ts
+ * export default createEdgeMcp({
+ *   info: { name: 'my-worker', version: '1.0.0' },
+ *   apps: [],
+ *   tasks: { enabled: false },
+ *   managed: {
+ *     endpoint: 'https://cloud.frontmcp.dev/v1/bundles/acme',
+ *     authToken: env.FRONTMCP_PULL_TOKEN,
+ *     expectedAudience: 'acme-mcp',
+ *     jwksUrl: 'https://cloud.frontmcp.dev/.well-known/jwks.json',
+ *     expectedIssuer: 'https://cloud.frontmcp.dev',
+ *   },
+ * });
+ * ```
+ */
+import { FrontMcpInstance } from '@frontmcp/sdk';
+import { type ManagedEdgeOptions } from './managed';
+import { type EdgeSkillIndexCacheFactory } from './skill-index-cache';
+export type { ManagedEdgeOptions } from './managed';
+export { buildManagedOpenApiPluginOptions } from './managed';
+export { createKvBundleCache, kvBundleCacheFromEnv, type EdgeBundleCacheFactory, type EdgeBundleCacheStore, type EdgeKvNamespace, type KvBundleCacheOptions, } from './kv-cache';
+export { createKvSkillIndexCache, kvSkillIndexCacheFromEnv, type EdgeSkillIndexCacheFactory, type KvSkillIndexCacheOptions, } from './skill-index-cache';
+/** The plain FrontMCP config the SDK accepts (same shape `@FrontMcp(...)` takes). */
+type BaseConfig = Parameters<typeof FrontMcpInstance.createForGraph>[0];
+/**
+ * Config accepted by {@link createEdgeMcp} — the FrontMCP config plus an
+ * optional `managed` block for the auto-updating skilled-openapi path.
+ */
+export type EdgeMcpConfig = BaseConfig & {
+    /**
+     * Managed mode — pull an auto-updating skilled-openapi bundle from a SaaS
+     * endpoint. Requires the optional peer `@frontmcp/plugin-skilled-openapi`.
+     */
+    managed?: ManagedEdgeOptions;
+    /**
+     * Enable **stateful MCP sessions** via a Cloudflare Durable Object, so the
+     * Streamable HTTP standalone GET notification stream stays open across
+     * requests and a `tools/call`'s notifications reach it (the stateless worker
+     * can't do this). Export the returned {@link EdgeMcp.SessionDurableObject} and
+     * bind it in `wrangler.toml` under this `binding` name (default
+     * `FRONTMCP_SESSIONS`). When omitted, the worker is stateless.
+     */
+    sessions?: {
+        binding?: string;
+    };
+    /**
+     * Enable a **KV-backed skill search-index cache** for fast cold starts. The
+     * built TF-IDF/BM25 index (embeddings + IDF model) is persisted to a Cloudflare
+     * KV namespace keyed by a content hash of the indexed skills, so a cold start
+     * restores it instead of recomputing the whole corpus. Bind a KV namespace in
+     * `wrangler.toml` under this `binding` name (default `FRONTMCP_SKILL_INDEX`).
+     *
+     * Accepts either a `{ binding }` (resolved from `env` at request time) or a
+     * ready factory `(env) => SkillIndexCache | undefined`. When omitted, or when
+     * the binding is absent on `env`, the index is rebuilt each cold start.
+     */
+    skillIndex?: {
+        binding?: string;
+        ttlSeconds?: number;
+    } | EdgeSkillIndexCacheFactory;
+};
+/** An edge module: `export default createEdgeMcp(config)`. */
+export interface EdgeMcp {
+    fetch: (request: Request, env?: unknown, ctx?: unknown) => Promise<Response>;
+    /**
+     * Cloudflare **Cron Trigger** entrypoint — present only in managed mode.
+     * Wire a `[triggers] crontabs = ["*&#47;5 * * * *"]` in `wrangler.toml` and
+     * the runtime calls this on schedule; it pulls a fresh bundle and hot-swaps
+     * it (Workers have no background timers, so this replaces internal polling).
+     */
+    scheduled?: (event?: unknown, env?: unknown, ctx?: unknown) => Promise<void>;
+    /**
+     * The **Durable Object class** for stateful sessions. Always present; re-export
+     * it from the worker entry and bind it in `wrangler.toml` (with a migration)
+     * to enable stateful sessions:
+     *
+     * ```ts
+     * const mcp = createEdgeMcp({ ..., sessions: {} });
+     * export default mcp;
+     * export const FrontMcpSession = mcp.SessionDurableObject;
+     * ```
+     */
+    SessionDurableObject: new (state: unknown, env: unknown) => {
+        fetch(request: Request): Promise<Response>;
+    };
+}
+/**
+ * Build an edge module (`{ fetch }`) from a FrontMCP config.
+ *
+ * The FrontMCP scope is built **lazily on the first request** and memoized —
+ * V8 isolates forbid timers / random / I-O at module-eval (global) scope, and
+ * scope initialization legitimately does those; deferring to the first `fetch`
+ * runs that work inside a request context, where it is allowed.
+ *
+ * Durable Object classes (sessions/event store) are not part of this skeleton
+ * yet — the handler is stateless. They arrive with `@frontmcp/adapters/cloudflare`.
+ */
+export declare function createEdgeMcp(config: EdgeMcpConfig): EdgeMcp;