@winstonsayno/mcp-gateway 4.6.0 → 4.8.0

package/CHANGELOG.md

@@ -9,6 +9,41 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [4.8.0] - 2026-10-08
+
+### Added
+- **Offline / edge sync** for the edge gateway (`@winstonsayno/mcp-gateway/edge`, new `EdgeSync`, `memoryStore`):
+  - **Config snapshots** from a Node gateway acting as control plane (`GET /api/v1/admin/edge/snapshot`, ETag /
+    `If-None-Match`): enabled `streamable-http` servers with their known tool catalog, unscoped API keys as `sha256:`
+    digests, tool naming, CORS. The last good snapshot is kept in a KV store (Workers KV compatible), so a cold isolate
+    boots while the control plane is down. Local servers / headers / settings win over the snapshot.
+  - Upstream headers are only included with `includeSecrets` (`?secrets=true`), which needs `admin.configApi: true`.
+  - **Offline tool lists**: when an upstream is unreachable, `tools/list` serves the last list or the snapshot catalog.
+  - **Offline queue** (`offline.queueTools` globs): calls to an unreachable / 5xx upstream are queued (REST `202`
+    with `queued`, MCP `structuredContent: { queued: true, id }`) and replayed on the next sync; rejected calls are
+    dropped and reported.
+  - **Usage outbox**: live / queued / replayed calls are pushed to `POST /api/v1/admin/edge/sync` and show up in the
+    control plane's metrics as client `edge:<edgeId>`; `GET /api/v1/admin/edge/nodes` lists edges.
+  - `gw.sync()`, background sync on requests (`syncIntervalMs`, Workers `waitUntil`), `GET /api/v1/edge/status`,
+    `POST /api/v1/edge/sync`; `workersHandler()` gains `scheduled` (Cron Triggers); `configFromEnv` reads
+    `MCP_GATEWAY_CONTROL_PLANE`, `_CONTROL_KEY`, `_EDGE_ID`, `_QUEUE_TOOLS`, `_SYNC_INTERVAL_MS` and the `MCP_GATEWAY_KV` binding.
+- The GitHub Pages demo simulates the edge control plane endpoints.
+
+## [4.7.0] - 2026-10-08
+
+### Added
+- **Python SDK** (`clients/python`, package `mcp-gateway-client`): stdlib-only (`urllib`), Python ≥ 3.9, typed
+  `health` / `ready` / `metrics`, `servers`, `list_tools`, `tool_schemas` + `call_llm_tool`, `call_tool`, resources,
+  prompts, approvals; `GatewayError` with `status`, `code`, `retry_after`, `is_policy_error`. `py.typed`.
+- **Go SDK** (`clients/go`, module `github.com/HarrisonCN/mcp-gateway/clients/go`): `net/http` only, Go ≥ 1.21,
+  context-aware `Health`, `Ready`, `Servers`, `ListTools`, `ToolSchemas` + `CallLLMTool`, `CallTool`, `Approve` / `Deny`;
+  `*mcpgateway.Error` with `Code()`, `IsPolicyError()`, `RetryAfter`.
+- **Swift SDK** (`clients/swift`, SwiftPM `MCPGateway`): async/await, `URLSession` by default with a pluggable
+  transport, macOS 12 / iOS 15 / Linux; `GatewayError.isPolicyError`.
+- New **SDKs** CI workflow (`.github/workflows/sdks.yml`): Python 3.9 / 3.12 / 3.13 tests + sdist/wheel build,
+  Go 1.21 / stable `vet` + `test -race`, Swift 6.0 `build` + `test` on Linux. Package-registry publishing (PyPI, Go
+  module tags, Swift Package Index) is not automated yet.
+
 ## [4.6.0] - 2026-10-08
 
 ### Added

package/README.md

@@ -84,7 +84,7 @@ As [MCP](https://modelcontextprotocol.io) becomes the standard protocol for AI a
 - **YAML/JSON config** — simple, declarative configuration with env var overrides
 - **Docker-ready** — official Docker image, Compose examples included
 - **TypeScript SDK** — embed the gateway as a library in your own project
-- **Client libraries** — a dependency-free TypeScript client ([`clients/js`](clients/js), browser + Node) and a Kotlin/JVM/Android client ([`clients/kotlin`](clients/kotlin))
+- **Client libraries** — a dependency-free TypeScript client ([`clients/js`](clients/js), browser + Node) a Kotlin/JVM/Android client ([`clients/kotlin`](clients/kotlin)), and Python, Go and Swift SDKs ([`clients/python`](clients/python), [`clients/go`](clients/go), [`clients/swift`](clients/swift))
 - **LLM tool schemas** — `GET /api/v1/tools?format=openai|anthropic` returns ready-to-use function-calling definitions
 
 ## Quick Start
@@ -267,6 +267,9 @@ Names follow `mcp.toolNaming`, are sanitised to `^[a-zA-Z0-9_-]{1,64}$` and de-d
 |---|---|
 | **TypeScript / JavaScript** — [`clients/js`](clients/js) | `@winstonsayno/mcp-gateway-client`: zero dependencies, `fetch`-based (browser, Node 18+, Deno, Bun, React Native), typed `health`, `servers`, `listTools`, `toolSchemas`, `callTool`, `callLlmTool`, plus a small MCP-over-`/mcp` session helper |
 | **Kotlin / JVM / Android** — [`clients/kotlin`](clients/kotlin) | OkHttp + kotlinx.serialization, Java 11 bytecode; same API surface, `McpSession` for `/mcp` |
+| **Python** — [`clients/python`](clients/python) | `mcp-gateway-client`: stdlib only, Python ≥ 3.9, typed `health`, `list_tools`, `tool_schemas`, `call_tool`, `call_llm_tool`, approvals, `GatewayError.is_policy_error` |
+| **Go** — [`clients/go`](clients/go) | `github.com/HarrisonCN/mcp-gateway/clients/go`: `net/http` only, Go ≥ 1.21, context-aware, `*mcpgateway.Error` with `IsPolicyError()` |
+| **Swift** — [`clients/swift`](clients/swift) | SwiftPM `MCPGateway`: async/await, `URLSession` (pluggable transport), macOS 12 / iOS 15 / Linux |
 
 Both are in this repository and not yet published to npm / Maven Central.
 
@@ -583,6 +586,23 @@ await gateway.start();
 process.on('SIGTERM', () => gateway.stop());
 ```
 
+## What's New in v4.8
+
+| Feature | Description |
+|---------|-------------|
+| **Edge config sync** | Edges pull ETag'd snapshots from a Node control plane and boot from the cached one offline |
+| **Offline queue** | Queue calls to unreachable upstreams (`offline.queueTools`), replay on the next sync |
+| **Usage outbox** | Edge calls flow back into the control plane's metrics; `/admin/edge/nodes` lists edges |
+
+## What's New in v4.7
+
+| Feature | Description |
+|---------|-------------|
+| **Python SDK** | `clients/python` — stdlib only, typed, policy-aware errors |
+| **Go SDK** | `clients/go` — `net/http` only, context-aware |
+| **Swift SDK** | `clients/swift` — async/await, macOS / iOS / Linux |
+| **SDK CI** | New `sdks.yml` workflow builds and tests all three |
+
 ## What's New in v4.6
 
 | Feature | Description |

package/dist/edge/adapters.d.ts

@@ -9,7 +9,9 @@
  * Config can also come from environment variables with `configFromEnv(env)`:
  * `MCP_GATEWAY_SERVERS` (JSON array of `{ id, url, headers?, tools? }`),
  * `MCP_GATEWAY_API_KEYS` (comma separated), `MCP_GATEWAY_TOOL_NAMING`,
- * `MCP_GATEWAY_CORS_ORIGINS`.
+ * `MCP_GATEWAY_CORS_ORIGINS`; offline / edge sync (4.8): `MCP_GATEWAY_CONTROL_PLANE`,
+ * `MCP_GATEWAY_CONTROL_KEY`, `MCP_GATEWAY_EDGE_ID`, `MCP_GATEWAY_QUEUE_TOOLS` (comma separated globs),
+ * `MCP_GATEWAY_SYNC_INTERVAL_MS` and a KV namespace bound as `MCP_GATEWAY_KV`.
  *
  * @module edge/adapters
  */
@@ -17,9 +19,16 @@ import { type EdgeConfig } from './index.js';
 type Env = Record<string, unknown>;
 /** Edge config from environment variables / Worker bindings. */
 export declare function configFromEnv(env: Env): EdgeConfig;
-/** Cloudflare Workers module handler. The gateway (and its upstream sessions) is reused per isolate. */
+interface WorkersCtx {
+    waitUntil(p: Promise<unknown>): void;
+}
+/**
+ * Cloudflare Workers module handler. The gateway (and its upstream sessions) is reused per isolate.
+ * With sync configured, add a Cron Trigger: `scheduled` pulls config, replays queued calls and pushes usage.
+ */
 export declare function workersHandler(build?: (env: Env) => EdgeConfig): {
-    fetch(request: Request, env?: Env): Promise<Response>;
+    fetch(request: Request, env?: Env, ctx?: WorkersCtx): Promise<Response>;
+    scheduled(_event: unknown, env?: Env, ctx?: WorkersCtx): Promise<unknown>;
 };
 interface ServeOptions {
     port?: number;

package/dist/edge/adapters.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"adapters.d.ts","sourceRoot":"","sources":["../../src/edge/adapters.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAqB,KAAK,UAAU,EAAoB,MAAM,YAAY,CAAC;AAElF,KAAK,GAAG,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEnC,gEAAgE;AAChE,wBAAgB,aAAa,CAAC,GAAG,EAAE,GAAG,GAAG,UAAU,CAgBlD;AAED,wGAAwG;AACxG,wBAAgB,cAAc,CAAC,KAAK,GAAE,CAAC,GAAG,EAAE,GAAG,KAAK,UAA0B;mBAI3D,OAAO,QAAO,GAAG,GAAQ,OAAO,CAAC,QAAQ,CAAC;EAQ5D;AAED,UAAU,YAAY;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,0BAA0B;AAC1B,wBAAgB,SAAS,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,GAAE,YAAiB,GAAG,OAAO,CAK9E;AAED,wBAAwB;AACxB,wBAAgB,QAAQ,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,GAAE,YAAiB,GAAG,OAAO,CAK7E;AAED,qGAAqG;AACrG,wBAAsB,SAAS,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,GAAE,YAAiB,GAAG,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,CAAC,CAyBlI"}
+{"version":3,"file":"adapters.d.ts","sourceRoot":"","sources":["../../src/edge/adapters.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAqB,KAAK,UAAU,EAAoB,MAAM,YAAY,CAAC;AAGlF,KAAK,GAAG,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEnC,gEAAgE;AAChE,wBAAgB,aAAa,CAAC,GAAG,EAAE,GAAG,GAAG,UAAU,CAiClD;AAED,UAAU,UAAU;IAClB,SAAS,CAAC,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC;CACtC;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,GAAE,CAAC,GAAG,EAAE,GAAG,KAAK,UAA0B;mBAW3D,OAAO,QAAO,GAAG,QAAa,UAAU,GAAG,OAAO,CAAC,QAAQ,CAAC;sBAGzD,OAAO,QAAO,GAAG,QAAa,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC;EAMhF;AAED,UAAU,YAAY;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,0BAA0B;AAC1B,wBAAgB,SAAS,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,GAAE,YAAiB,GAAG,OAAO,CAK9E;AAED,wBAAwB;AACxB,wBAAgB,QAAQ,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,GAAE,YAAiB,GAAG,OAAO,CAK7E;AAED,qGAAqG;AACrG,wBAAsB,SAAS,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,GAAE,YAAiB,GAAG,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,CAAC,CAyBlI"}

package/dist/edge/adapters.js

@@ -9,7 +9,9 @@
  * Config can also come from environment variables with `configFromEnv(env)`:
  * `MCP_GATEWAY_SERVERS` (JSON array of `{ id, url, headers?, tools? }`),
  * `MCP_GATEWAY_API_KEYS` (comma separated), `MCP_GATEWAY_TOOL_NAMING`,
- * `MCP_GATEWAY_CORS_ORIGINS`.
+ * `MCP_GATEWAY_CORS_ORIGINS`; offline / edge sync (4.8): `MCP_GATEWAY_CONTROL_PLANE`,
+ * `MCP_GATEWAY_CONTROL_KEY`, `MCP_GATEWAY_EDGE_ID`, `MCP_GATEWAY_QUEUE_TOOLS` (comma separated globs),
+ * `MCP_GATEWAY_SYNC_INTERVAL_MS` and a KV namespace bound as `MCP_GATEWAY_KV`.
  *
  * @module edge/adapters
  */
@@ -26,24 +28,52 @@ export function configFromEnv(env) {
         servers = parsed;
     }
     const naming = str('MCP_GATEWAY_TOOL_NAMING');
+    const list = (k) => str(k)?.split(',').map((x) => x.trim()).filter(Boolean);
+    const cp = str('MCP_GATEWAY_CONTROL_PLANE');
+    const kv = env.MCP_GATEWAY_KV;
+    const interval = Number(str('MCP_GATEWAY_SYNC_INTERVAL_MS'));
     return {
         servers,
-        apiKeys: str('MCP_GATEWAY_API_KEYS')?.split(',').map((k) => k.trim()).filter(Boolean),
-        toolNaming: naming === 'prefix' ? 'prefix' : 'auto',
-        corsOrigins: str('MCP_GATEWAY_CORS_ORIGINS')?.split(',').map((o) => o.trim()).filter(Boolean),
+        apiKeys: list('MCP_GATEWAY_API_KEYS'),
+        // With a control plane, an unset naming comes from the snapshot.
+        toolNaming: naming === 'prefix' ? 'prefix' : naming === 'auto' || !cp ? 'auto' : undefined,
+        corsOrigins: list('MCP_GATEWAY_CORS_ORIGINS'),
+        ...(cp
+            ? {
+                sync: {
+                    controlPlane: cp,
+                    apiKey: str('MCP_GATEWAY_CONTROL_KEY'),
+                    edgeId: str('MCP_GATEWAY_EDGE_ID'),
+                    store: kv && typeof kv.get === 'function' ? kv : undefined,
+                },
+                offline: { queueTools: list('MCP_GATEWAY_QUEUE_TOOLS') },
+                ...(Number.isFinite(interval) && str('MCP_GATEWAY_SYNC_INTERVAL_MS') ? { syncIntervalMs: interval } : {}),
+            }
+            : {}),
     };
 }
-/** Cloudflare Workers module handler. The gateway (and its upstream sessions) is reused per isolate. */
+/**
+ * Cloudflare Workers module handler. The gateway (and its upstream sessions) is reused per isolate.
+ * With sync configured, add a Cron Trigger: `scheduled` pulls config, replays queued calls and pushes usage.
+ */
 export function workersHandler(build = configFromEnv) {
     let gw;
     let built;
+    const get = (env) => {
+        if (!gw || built !== env) {
+            gw = createEdgeGateway(build(env));
+            built = env;
+        }
+        return gw;
+    };
     return {
-        fetch(request, env = {}) {
-            if (!gw || built !== env) {
-                gw = createEdgeGateway(build(env));
-                built = env;
-            }
-            return gw.fetch(request);
+        fetch(request, env = {}, ctx) {
+            return get(env).fetch(request, ctx ? (p) => ctx.waitUntil(p) : undefined);
+        },
+        scheduled(_event, env = {}, ctx) {
+            const p = get(env).sync();
+            ctx?.waitUntil(p);
+            return p;
         },
     };
 }

package/dist/edge/adapters.js.map

@@ -1 +1 @@
-{"version":3,"file":"adapters.js","sourceRoot":"","sources":["../../src/edge/adapters.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"adapters.js","sourceRoot":"","sources":["../../src/edge/adapters.ts"],"names":[],"mappings":"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"}

package/dist/edge/entry.d.ts

@@ -3,6 +3,8 @@
  * Imports nothing from Node (except `serveNode`, which loads `node:http` lazily).
  */
 export { createEdgeGateway, EdgeUpstream, readRpcReply, EDGE_PROTOCOL_VERSION } from './index.js';
-export type { EdgeConfig, EdgeServerConfig, EdgeGateway } from './index.js';
+export type { EdgeConfig, EdgeServerConfig, EdgeGateway, EdgeOfflineConfig, EdgeSyncReport } from './index.js';
+export { EdgeSync, memoryStore } from './sync.js';
+export type { EdgeSyncOptions, EdgeSyncStore, EdgeSnapshot, EdgeEvent, QueuedCall, PullResult, EdgeCatalogTool } from './sync.js';
 export { workersHandler, serveDeno, serveBun, serveNode, configFromEnv } from './adapters.js';
 //# sourceMappingURL=entry.d.ts.map

package/dist/edge/entry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"entry.d.ts","sourceRoot":"","sources":["../../src/edge/entry.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,YAAY,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAClG,YAAY,EAAE,UAAU,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC5E,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,QAAQ,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC"}
+{"version":3,"file":"entry.d.ts","sourceRoot":"","sources":["../../src/edge/entry.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,YAAY,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAClG,YAAY,EAAE,UAAU,EAAE,gBAAgB,EAAE,WAAW,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC/G,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAClD,YAAY,EAAE,eAAe,EAAE,aAAa,EAAE,YAAY,EAAE,SAAS,EAAE,UAAU,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAClI,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,QAAQ,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC"}

package/dist/edge/entry.js

@@ -3,5 +3,6 @@
  * Imports nothing from Node (except `serveNode`, which loads `node:http` lazily).
  */
 export { createEdgeGateway, EdgeUpstream, readRpcReply, EDGE_PROTOCOL_VERSION } from './index.js';
+export { EdgeSync, memoryStore } from './sync.js';
 export { workersHandler, serveDeno, serveBun, serveNode, configFromEnv } from './adapters.js';
 //# sourceMappingURL=entry.js.map

package/dist/edge/entry.js.map

@@ -1 +1 @@
-{"version":3,"file":"entry.js","sourceRoot":"","sources":["../../src/edge/entry.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,YAAY,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAElG,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,QAAQ,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC"}
+{"version":3,"file":"entry.js","sourceRoot":"","sources":["../../src/edge/entry.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,YAAY,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAElG,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAElD,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,QAAQ,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC"}

package/dist/edge/index.d.ts

@@ -14,6 +14,7 @@
  * @module edge
  */
 import type { ToolFilterConfig } from '../utils/types.js';
+import { EdgeSync, type EdgeCatalogTool, type EdgeSyncOptions, type PullResult } from './sync.js';
 export declare const EDGE_PROTOCOL_VERSION = "2025-06-18";
 export interface EdgeServerConfig {
     id: string;
@@ -23,6 +24,15 @@ export interface EdgeServerConfig {
     headers?: Record<string, string>;
     tools?: ToolFilterConfig;
     timeoutMs?: number;
+    /** Known tools (from a control-plane snapshot): served by `tools/list` while the upstream is unreachable. */
+    catalog?: EdgeCatalogTool[];
+}
+export interface EdgeOfflineConfig {
+    /**
+     * Tools (globs on the exposed name, or `<server>__<tool>`) whose calls are queued while their upstream is
+     * unreachable and replayed on the next sync. Needs `sync`. Only for idempotent / fire-and-forget tools.
+     */
+    queueTools?: string[];
 }
 export interface EdgeConfig {
     servers: EdgeServerConfig[];
@@ -38,6 +48,11 @@ export interface EdgeConfig {
     fetch?: typeof fetch;
     name?: string;
     version?: string;
+    /** Control-plane sync (4.8): config snapshots, usage outbox, offline queue. */
+    sync?: EdgeSync | EdgeSyncOptions;
+    /** Minimum time between background syncs triggered by requests (default 60 s; 0 = only explicit `sync()`). */
+    syncIntervalMs?: number;
+    offline?: EdgeOfflineConfig;
 }
 interface UpstreamTool {
     name: string;
@@ -61,11 +76,30 @@ export declare class EdgeUpstream {
     private post;
     private init;
     request(method: string, params?: Json, retried?: boolean): Promise<unknown>;
+    /** True while the last tools/list failed and tools come from the stale cache or the snapshot catalog. */
+    offline: boolean;
     tools(maxAgeMs?: number): Promise<UpstreamTool[]>;
+    /** Carry the session and tool cache over to a replacement with the same endpoint. */
+    adopt(prev: EdgeUpstream): void;
+}
+export interface EdgeSyncReport {
+    config: PullResult['status'] | 'disabled';
+    etag?: string;
+    replayed: number;
+    failed: number;
+    pending: number;
+    pushed: number;
+    offline: boolean;
+    errors: string[];
 }
 export interface EdgeGateway {
-    fetch(request: Request): Promise<Response>;
+    /** Fetch handler; `waitUntil` (Workers `ctx.waitUntil`) keeps background syncs alive after the response. */
+    fetch(request: Request, waitUntil?: (p: Promise<unknown>) => void): Promise<Response>;
     upstreams: ReadonlyMap<string, EdgeUpstream>;
+    /** Pull config, replay queued calls, push usage events (no-op report when `sync` is not configured). */
+    sync(): Promise<EdgeSyncReport>;
+    /** The sync client, when configured. */
+    readonly syncClient?: EdgeSync;
 }
 /** Build the edge gateway's Fetch handler. */
 export declare function createEdgeGateway(config: EdgeConfig): EdgeGateway;

package/dist/edge/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/edge/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAE1D,eAAO,MAAM,qBAAqB,eAAe,CAAC;AAGlD,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2DAA2D;IAC3D,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,KAAK,CAAC,EAAE,gBAAgB,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAC5B,8EAA8E;IAC9E,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,4CAA4C;IAC5C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,2FAA2F;IAC3F,UAAU,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAC;IAC/B,2CAA2C;IAC3C,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,mDAAmD;IACnD,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,UAAU,YAAY;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAQD,KAAK,IAAI,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAsBpC,+EAA+E;AAC/E,wBAAsB,YAAY,CAAC,GAAG,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA2BpF;AAYD,2DAA2D;AAC3D,qBAAa,YAAY;IAMrB,QAAQ,CAAC,GAAG,EAAE,gBAAgB;IAC9B,OAAO,CAAC,QAAQ,CAAC,SAAS;IAN5B,OAAO,CAAC,OAAO,CAAC,CAAU;IAC1B,OAAO,CAAC,GAAG,CAAK;IAChB,OAAO,CAAC,UAAU,CAAC,CAAwC;gBAGhD,GAAG,EAAE,gBAAgB,EACb,SAAS,EAAE,OAAO,KAAK;YAG5B,IAAI;YAgBJ,IAAI;IA4BZ,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,IAAI,EAAE,OAAO,UAAQ,GAAG,OAAO,CAAC,OAAO,CAAC;IAezE,KAAK,CAAC,QAAQ,SAAS,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;CAcxD;AAQD,MAAM,WAAW,WAAW;IAC1B,KAAK,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC3C,SAAS,EAAE,WAAW,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;CAC9C;AAED,8CAA8C;AAC9C,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,UAAU,GAAG,WAAW,CAgKjE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/edge/index.ts"],"names":[],"mappings":"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"}

package/dist/edge/index.js

@@ -14,6 +14,7 @@
  * @module edge
  */
 import { globToRegExp } from '../utils/tool-filter.js';
+import { EdgeSync } from './sync.js';
 export const EDGE_PROTOCOL_VERSION = '2025-06-18';
 const SUPPORTED_VERSIONS = ['2025-06-18', '2025-03-26', '2024-11-05'];
 const isObj = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
@@ -72,10 +73,14 @@ export async function readRpcReply(res, id) {
 class RpcError extends Error {
     code;
     data;
-    constructor(code, message, data) {
+    transient;
+    constructor(code, message, data, 
+    /** The upstream could not be reached or answered 5xx (worth queueing / retrying). */
+    transient = false) {
         super(message);
         this.code = code;
         this.data = data;
+        this.transient = transient;
     }
 }
 /** Minimal Streamable HTTP MCP client for one upstream. */
@@ -145,35 +150,180 @@ export class EdgeUpstream {
             return this.request(method, params, true);
         }
         if (!res.ok)
-            throw new RpcError(-32000, `Upstream "${this.cfg.id}" HTTP ${res.status}`);
+            throw new RpcError(-32000, `Upstream "${this.cfg.id}" HTTP ${res.status}`, undefined, res.status >= 500);
         const reply = await readRpcReply(res, id);
         if (isObj(reply.error))
             throw new RpcError(Number(reply.error.code ?? -32603), String(reply.error.message ?? 'error'), reply.error.data);
         return reply.result;
     }
+    /** True while the last tools/list failed and tools come from the stale cache or the snapshot catalog. */
+    offline = false;
     async tools(maxAgeMs = 30_000) {
         if (this.toolsCache && Date.now() - this.toolsCache.at < maxAgeMs)
             return this.toolsCache.tools;
         const all = [];
         let cursor;
-        for (let page = 0; page < 50; page++) {
-            const r = (await this.request('tools/list', cursor ? { cursor } : undefined));
-            all.push(...(r?.tools ?? []));
-            cursor = r?.nextCursor;
-            if (!cursor)
-                break;
+        try {
+            for (let page = 0; page < 50; page++) {
+                const r = (await this.request('tools/list', cursor ? { cursor } : undefined));
+                all.push(...(r?.tools ?? []));
+                cursor = r?.nextCursor;
+                if (!cursor)
+                    break;
+            }
         }
+        catch (err) {
+            // Offline: keep serving the last known tool list (or the control-plane catalog).
+            const known = this.toolsCache?.tools ?? this.cfg.catalog?.filter((t) => allowed(t.name, this.cfg.tools));
+            if (known?.length && isTransient(err)) {
+                this.offline = true;
+                return known;
+            }
+            throw err;
+        }
+        this.offline = false;
         const tools = all.filter((t) => allowed(t.name, this.cfg.tools));
         this.toolsCache = { at: Date.now(), tools };
         return tools;
     }
+    /** Carry the session and tool cache over to a replacement with the same endpoint. */
+    adopt(prev) {
+        this.session = prev.session;
+        this.seq = prev.seq;
+        this.toolsCache = prev.toolsCache;
+    }
+}
+/** Network failure, timeout, or upstream 5xx: the call may succeed later. */
+function isTransient(err) {
+    return err instanceof RpcError ? err.transient : true;
 }
 /** Build the edge gateway's Fetch handler. */
 export function createEdgeGateway(config) {
     const fetchImpl = config.fetch ?? ((...a) => fetch(...a));
     const upstreams = new Map(config.servers.map((s) => [s.id, new EdgeUpstream(s, fetchImpl)]));
     const mcpPath = config.mcpPath ?? '/mcp';
-    const keys = (config.apiKeys ?? []).filter(Boolean);
+    let keys = (config.apiKeys ?? []).filter(Boolean);
+    let toolNaming = config.toolNaming;
+    let corsOrigins = config.corsOrigins;
+    const sync = config.sync instanceof EdgeSync ? config.sync : config.sync ? new EdgeSync({ fetch: config.fetch, ...config.sync }) : undefined;
+    const queueRes = (config.offline?.queueTools ?? []).map((g) => globToRegExp(g));
+    const syncInterval = config.syncIntervalMs ?? 60_000;
+    let appliedEtag;
+    let lastSync = 0;
+    let lastReport;
+    let syncing;
+    let booted;
+    /** Merge a control-plane snapshot with the local config (local servers / headers / settings win). */
+    function applySnapshot(snap) {
+        if (snap.etag === appliedEtag)
+            return;
+        appliedEtag = snap.etag;
+        const local = new Map(config.servers.map((s) => [s.id, s]));
+        const merged = snap.config.servers.map((s) => {
+            const l = local.get(s.id);
+            return l ? { ...s, ...l, headers: { ...(s.headers ?? {}), ...(l.headers ?? {}) }, catalog: l.catalog ?? s.catalog } : s;
+        });
+        for (const l of config.servers)
+            if (!merged.some((m) => m.id === l.id))
+                merged.push(l);
+        const next = new Map();
+        for (const s of merged) {
+            const u = new EdgeUpstream(s, fetchImpl);
+            const prev = upstreams.get(s.id);
+            if (prev && prev.cfg.url === s.url && JSON.stringify(prev.cfg.headers ?? {}) === JSON.stringify(s.headers ?? {}))
+                u.adopt(prev);
+            next.set(s.id, u);
+        }
+        upstreams.clear();
+        for (const [k, v] of next)
+            upstreams.set(k, v);
+        keys = [...new Set([...(config.apiKeys ?? []), ...(snap.config.apiKeys ?? [])].filter(Boolean))];
+        toolNaming = config.toolNaming ?? snap.config.toolNaming;
+        corsOrigins = config.corsOrigins ?? snap.config.corsOrigins;
+    }
+    /** First request: apply the cached snapshot, or pull one when nothing is cached. */
+    function boot() {
+        if (!sync)
+            return Promise.resolve();
+        booted ??= (async () => {
+            const cached = await sync.cached();
+            if (cached)
+                applySnapshot(cached);
+            else
+                await runSync();
+        })().catch(() => undefined);
+        return booted;
+    }
+    async function runSync() {
+        if (!sync)
+            return { config: 'disabled', replayed: 0, failed: 0, pending: 0, pushed: 0, offline: false, errors: [] };
+        syncing ??= (async () => {
+            const errors = [];
+            const pulled = await sync.pull();
+            if (pulled.snapshot)
+                applySnapshot(pulled.snapshot);
+            if (pulled.error)
+                errors.push(`pull: ${pulled.error}`);
+            // Replay queued calls (oldest first); stop at the first upstream that is still unreachable.
+            let replayed = 0;
+            let failed = 0;
+            const done = [];
+            const retry = [];
+            const down = new Set();
+            for (const q of await sync.queued()) {
+                if (down.has(q.server)) {
+                    retry.push(q.id);
+                    continue;
+                }
+                const started = Date.now();
+                try {
+                    const u = upstreams.get(q.server);
+                    if (!u)
+                        throw new RpcError(-32602, `Unknown server: ${q.server}`);
+                    await u.request('tools/call', { name: q.tool, arguments: q.arguments });
+                    replayed++;
+                    done.push(q.id);
+                    await sync.record({ ts: new Date().toISOString(), server: q.server, tool: q.tool, durationMs: Date.now() - started, ok: true, mode: 'replayed' });
+                }
+                catch (err) {
+                    if (isTransient(err)) {
+                        down.add(q.server);
+                        retry.push(q.id);
+                    }
+                    else {
+                        failed++;
+                        done.push(q.id);
+                        const msg = err instanceof Error ? err.message : String(err);
+                        await sync.record({ ts: new Date().toISOString(), server: q.server, tool: q.tool, durationMs: Date.now() - started, ok: false, mode: 'replayed', error: msg });
+                    }
+                }
+            }
+            if (done.length || retry.length)
+                await sync.settle(done, retry);
+            const pushed = await sync.push();
+            if (pushed.error)
+                errors.push(`push: ${pushed.error}`);
+            lastSync = Date.now();
+            lastReport = {
+                config: pulled.status,
+                etag: pulled.snapshot?.etag,
+                replayed,
+                failed,
+                pending: retry.length,
+                pushed: pushed.sent,
+                offline: pulled.status === 'offline' || pulled.status === 'none' || pushed.offline,
+                errors,
+            };
+            return lastReport;
+        })().finally(() => {
+            syncing = undefined;
+        });
+        return syncing;
+    }
+    function record(ev) {
+        if (sync)
+            void sync.record(ev).catch(() => undefined);
+    }
     const json = (status, body, extra = {}) => new Response(JSON.stringify(body), { status, headers: { 'content-type': 'application/json', ...extra } });
     async function authorized(req) {
         if (keys.length === 0)
@@ -202,7 +352,7 @@ export function createEdgeGateway(config) {
             count.set(t.tool.name, (count.get(t.tool.name) ?? 0) + 1);
         const list = flat.map((t) => ({
             ...t,
-            exposed: config.toolNaming === 'prefix' || (count.get(t.tool.name) ?? 0) > 1 ? `${t.serverId}__${t.tool.name}` : t.tool.name,
+            exposed: toolNaming === 'prefix' || (count.get(t.tool.name) ?? 0) > 1 ? `${t.serverId}__${t.tool.name}` : t.tool.name,
         }));
         return { list, errors };
     }
@@ -211,12 +361,36 @@ export function createEdgeGateway(config) {
         const hit = server ? list.find((t) => t.serverId === server && t.tool.name === name) : list.find((t) => t.exposed === name) ?? list.find((t) => t.tool.name === name);
         if (!hit)
             throw new RpcError(-32602, `Unknown tool: ${name}`);
-        const result = await upstreams.get(hit.serverId).request('tools/call', { name: hit.tool.name, arguments: args });
-        return { serverId: hit.serverId, result };
+        const started = Date.now();
+        const ev = { server: hit.serverId, tool: hit.tool.name };
+        try {
+            const result = await upstreams.get(hit.serverId).request('tools/call', { name: hit.tool.name, arguments: args });
+            record({ ts: new Date().toISOString(), ...ev, durationMs: Date.now() - started, ok: true, mode: 'live' });
+            return { serverId: hit.serverId, result };
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            const queueable = sync && isTransient(err) && queueRes.some((re) => re.test(hit.exposed) || re.test(`${hit.serverId}__${hit.tool.name}`));
+            if (queueable) {
+                const q = await sync.enqueue({ server: hit.serverId, tool: hit.tool.name, arguments: args });
+                record({ ts: new Date().toISOString(), ...ev, durationMs: Date.now() - started, ok: true, mode: 'queued', error: msg });
+                return {
+                    serverId: hit.serverId,
+                    queued: q.id,
+                    result: {
+                        content: [{ type: 'text', text: `Upstream "${hit.serverId}" is unreachable; the call was queued for delivery (${q.id}).` }],
+                        structuredContent: { queued: true, id: q.id },
+                        _meta: { 'mcp-gateway/queued': q.id },
+                    },
+                };
+            }
+            record({ ts: new Date().toISOString(), ...ev, durationMs: Date.now() - started, ok: false, mode: 'live', error: msg });
+            throw err;
+        }
     }
     function cors(req, res) {
         const origin = req.headers.get('origin');
-        const allowedOrigins = config.corsOrigins ?? [];
+        const allowedOrigins = corsOrigins ?? [];
         if (origin && (allowedOrigins.includes('*') || allowedOrigins.includes(origin))) {
             res.headers.set('access-control-allow-origin', allowedOrigins.includes('*') ? '*' : origin);
             res.headers.set('access-control-allow-headers', 'authorization, content-type, mcp-session-id, mcp-protocol-version, x-api-key');
@@ -322,18 +496,42 @@ export function createEdgeGateway(config) {
             const started = Date.now();
             try {
                 const r = await callTool(b.tool, isObj(b.arguments) ? b.arguments : {}, typeof b.server === 'string' ? b.server : undefined);
-                return json(200, { result: r.result, server: r.serverId, tool: b.tool, durationMs: Date.now() - started });
+                return json(r.queued ? 202 : 200, { result: r.result, server: r.serverId, tool: b.tool, durationMs: Date.now() - started, ...(r.queued ? { queued: r.queued } : {}) });
             }
             catch (err) {
                 const e = err instanceof RpcError ? err : new RpcError(-32603, err instanceof Error ? err.message : String(err));
                 return json(e.code === -32602 ? 404 : 502, { error: e.code === -32602 ? 'Not Found' : 'Bad Gateway', message: e.message, code: e.code });
             }
         }
+        if (path === '/api/v1/edge/status' && req.method === 'GET') {
+            return json(200, {
+                sync: !!sync,
+                edgeId: sync ? await sync.id() : undefined,
+                etag: appliedEtag ?? null,
+                lastSync: lastSync ? new Date(lastSync).toISOString() : null,
+                lastReport: lastReport ?? null,
+                outbox: sync ? (await sync.outbox()).length : 0,
+                queued: sync ? (await sync.queued()).length : 0,
+                offlineServers: [...upstreams.values()].filter((u) => u.offline).map((u) => u.cfg.id),
+            });
+        }
+        if (path === '/api/v1/edge/sync' && req.method === 'POST') {
+            return json(sync ? 200 : 404, sync ? await runSync() : { error: 'Not Found', message: 'sync is not configured' });
+        }
         return json(404, { error: 'Not Found' });
     }
     return {
         upstreams,
-        async fetch(request) {
+        syncClient: sync,
+        sync: runSync,
+        async fetch(request, waitUntil) {
+            await boot();
+            if (sync && syncInterval > 0 && !syncing && Date.now() - lastSync >= syncInterval) {
+                // Mark now so concurrent requests do not each start a sync.
+                lastSync = Date.now();
+                const p = runSync().catch(() => undefined);
+                waitUntil?.(p);
+            }
             return cors(request, await route(request));
         },
     };