@absolutejs/sync 1.7.8 → 1.8.0

package/dist/mcp/server.d.ts

@@ -0,0 +1,107 @@
+/**
+ * `@absolutejs/sync/mcp` — a Model Context Protocol server that surfaces
+ * a {@link SyncEngine}'s public read + mutate surface to MCP-aware
+ * clients (Claude Code, Cursor, custom agents).
+ *
+ * The agent gets four tools out of the box:
+ *
+ *   - `list_collections` — registered collection names + kinds + tables.
+ *   - `list_mutations` — registered mutation names.
+ *   - `inspect_engine` — full {@link EngineInspection} snapshot
+ *     (collections, mutations, schedules, readers, writers, recent
+ *     changes).
+ *   - `get_snapshot` — `{ collection, params?, ctx? }` → current rows.
+ *   - `run_mutation` — `{ mutation, args, ctx? }` → result.
+ *
+ * Tools that take a `ctx` accept the agent's per-call override; if
+ * omitted, the server's `defaultCtx` is used. That's how multi-tenant
+ * gating works: the platform spawns one MCP server per tenant with
+ * `defaultCtx: { tenantId }`, and the agent can't reach across.
+ *
+ * ## Why
+ *
+ * Val.town's MCP server ([val.town/mcp](https://blog.val.town/mcp))
+ * exposes its entire UI through 36+ tools — that's the 2026 entry
+ * point for "let me run code on a platform." Cloudflare's MCP server
+ * does the same for the Cloudflare API, fitting "the entire surface
+ * through just two tools in under 1,000 tokens" via Code Mode
+ * ([blog.cloudflare.com/dynamic-workers](https://blog.cloudflare.com/dynamic-workers/)).
+ *
+ * Sync's MCP server is the same play for the sync engine itself: an
+ * agent can wire up a real-time leaderboard in three messages, then
+ * `run_mutation` to drive it without ever touching source files.
+ *
+ * ## Usage (stdio)
+ *
+ * ```ts
+ * // mcp-stdio-server.ts — point your MCP client (claude-code, etc.)
+ * // at this file's path.
+ * import { createSyncEngine, ... } from '@absolutejs/sync/engine';
+ * import { createSyncMcpServer, serveStdio } from '@absolutejs/sync/mcp';
+ *
+ * const engine = createSyncEngine();
+ * // ... register your collections / mutations ...
+ *
+ * const server = createSyncMcpServer({
+ *   engine,
+ *   defaultCtx: { tenantId: 'demo' },
+ * });
+ * await serveStdio(server);
+ * ```
+ *
+ * Run it as the MCP server: in your client's MCP config, add an entry
+ * like:
+ *
+ * ```json
+ * {
+ *   "mcpServers": {
+ *     "my-sync": {
+ *       "command": "bun",
+ *       "args": ["./mcp-stdio-server.ts"]
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * ## Optional peer dep
+ *
+ * `@modelcontextprotocol/sdk` is an optional peer — install only if
+ * you use the MCP surface. The dynamic `import()` below makes this
+ * subpath load-free when not used.
+ */
+import type { SyncEngine } from '../engine/syncEngine';
+/** Per-call context default + override behaviour. */
+export type SyncMcpServerOptions = {
+    /** The engine to expose. */
+    engine: SyncEngine;
+    /**
+     * Default `ctx` for `get_snapshot` and `run_mutation`. Tools accept
+     * an optional `ctx` override on each call; if absent, this default
+     * is used. Set per-tenant when running one server per tenant.
+     */
+    defaultCtx?: unknown;
+    /**
+     * Display name advertised to the MCP client. Defaults to
+     * `'sync-engine'`. Useful when one client connects to multiple
+     * sync MCP servers (e.g. `'sync-prod'` / `'sync-staging'`).
+     */
+    name?: string;
+    /** Semver string surfaced to the MCP client. Defaults to `'0.1.0'`. */
+    version?: string;
+};
+/** A precompiled MCP server with the sync tools already registered. */
+export type SyncMcpServer = {
+    /** The underlying SDK server — register additional tools on it if you want. */
+    server: import('@modelcontextprotocol/sdk/server/mcp.js').McpServer;
+    /** Wire to a transport (stdio, sse, custom). The SDK handles the rest. */
+    connect: (transport: import('@modelcontextprotocol/sdk/shared/transport.js').Transport) => Promise<void>;
+};
+export declare const createSyncMcpServer: (options: SyncMcpServerOptions) => Promise<SyncMcpServer>;
+/**
+ * Convenience: wire a {@link SyncMcpServer} to stdio. This is the
+ * normal path for "I want claude-code to talk to my sync engine."
+ *
+ * Blocks until the transport closes. The server stays alive across
+ * many tool calls.
+ */
+export declare const serveStdio: (syncMcp: SyncMcpServer | Promise<SyncMcpServer>) => Promise<void>;

package/dist/scheduled.js

@@ -1,4 +1,18 @@
 // @bun
+var __defProp = Object.defineProperty;
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: __exportSetter.bind(all, name)
+    });
+};
 var __require = import.meta.require;
 
 // src/scheduled.ts
@@ -31,5 +45,5 @@ export {
   scheduled
 };
 
-//# debugId=E19FF3C14F5836C764756E2164756E21
+//# debugId=8CB5CC79F76D462364756E2164756E21
 //# sourceMappingURL=scheduled.js.map

package/dist/scheduled.js.map

@@ -4,7 +4,7 @@
   "sourcesContent": [
     "import { Elysia } from 'elysia';\nimport { cron } from '@elysiajs/cron';\nimport type { SyncEngine } from './engine/syncEngine';\n\nexport type ScheduledOptions = {\n\t/** The engine whose registered schedules (see `registerSchedule`) to run. */\n\tengine: SyncEngine;\n\t/** Prefix for the cron job names registered on Elysia's store. Default `sync`. */\n\tprefix?: string;\n\t/** Called when a scheduled run throws (the batch is rolled back). */\n\tonError?: (name: string, error: unknown) => void;\n};\n\n/**\n * Elysia plugin that fires the engine's registered scheduled functions on their\n * cron patterns, via `@elysiajs/cron`. Cron decides *when*; the engine runs the\n * schedule and makes its writes go live through the change feed (and a schedule\n * can `enqueue` into `@absolutejs/queue` for durable, retryable work).\n *\n * Register schedules with `engine.registerSchedule(...)` before mounting this, so\n * each one becomes a cron job named `<prefix>:<schedule.name>`. Mount once.\n */\nexport const scheduled = ({\n\tengine,\n\tprefix = 'sync',\n\tonError\n}: ScheduledOptions) => {\n\tconst run = (name: string) => () => {\n\t\tvoid engine.runSchedule(name).catch((error) => {\n\t\t\tif (onError === undefined) {\n\t\t\t\tthrow error;\n\t\t\t}\n\t\t\tonError(name, error);\n\t\t});\n\t};\n\n\t// `.use` registers the cron job on this instance (mutating), so a loop builds\n\t// one plugin carrying every schedule's cron trigger.\n\tconst app = new Elysia({ name: '@absolutejs/sync/scheduled' });\n\tfor (const schedule of engine.listSchedules()) {\n\t\tapp.use(\n\t\t\tcron({\n\t\t\t\tname: `${prefix}:${schedule.name}`,\n\t\t\t\tpattern: schedule.pattern,\n\t\t\t\trun: run(schedule.name)\n\t\t\t})\n\t\t);\n\t}\n\treturn app;\n};\n"
   ],
-  "mappings": ";;;;AAAA;AACA;AAqBO,IAAM,YAAY;AAAA,EACxB;AAAA,EACA,SAAS;AAAA,EACT;AAAA,MACuB;AAAA,EACvB,MAAM,MAAM,CAAC,SAAiB,MAAM;AAAA,IAC9B,OAAO,YAAY,IAAI,EAAE,MAAM,CAAC,UAAU;AAAA,MAC9C,IAAI,YAAY,WAAW;AAAA,QAC1B,MAAM;AAAA,MACP;AAAA,MACA,QAAQ,MAAM,KAAK;AAAA,KACnB;AAAA;AAAA,EAKF,MAAM,MAAM,IAAI,OAAO,EAAE,MAAM,6BAA6B,CAAC;AAAA,EAC7D,WAAW,YAAY,OAAO,cAAc,GAAG;AAAA,IAC9C,IAAI,IACH,KAAK;AAAA,MACJ,MAAM,GAAG,UAAU,SAAS;AAAA,MAC5B,SAAS,SAAS;AAAA,MAClB,KAAK,IAAI,SAAS,IAAI;AAAA,IACvB,CAAC,CACF;AAAA,EACD;AAAA,EACA,OAAO;AAAA;",
-  "debugId": "E19FF3C14F5836C764756E2164756E21",
+  "mappings": ";;;;;;;;;;;;;;;;;;AAAA;AACA;AAqBO,IAAM,YAAY;AAAA,EACxB;AAAA,EACA,SAAS;AAAA,EACT;AAAA,MACuB;AAAA,EACvB,MAAM,MAAM,CAAC,SAAiB,MAAM;AAAA,IAC9B,OAAO,YAAY,IAAI,EAAE,MAAM,CAAC,UAAU;AAAA,MAC9C,IAAI,YAAY,WAAW;AAAA,QAC1B,MAAM;AAAA,MACP;AAAA,MACA,QAAQ,MAAM,KAAK;AAAA,KACnB;AAAA;AAAA,EAKF,MAAM,MAAM,IAAI,OAAO,EAAE,MAAM,6BAA6B,CAAC;AAAA,EAC7D,WAAW,YAAY,OAAO,cAAc,GAAG;AAAA,IAC9C,IAAI,IACH,KAAK;AAAA,MACJ,MAAM,GAAG,UAAU,SAAS;AAAA,MAC5B,SAAS,SAAS;AAAA,MAClB,KAAK,IAAI,SAAS,IAAI;AAAA,IACvB,CAAC,CACF;AAAA,EACD;AAAA,EACA,OAAO;AAAA;",
+  "debugId": "8CB5CC79F76D462364756E2164756E21",
   "names": []
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@absolutejs/sync",
-	"version": "1.7.8",
+	"version": "1.8.0",
 	"description": "Lightweight reactive-push and write-behind-cache primitives for Elysia and the AbsoluteJS ecosystem — kill polling and keep a remote store off your hot path, without adopting a whole sync-engine backend.",
 	"repository": {
 		"type": "git",
@@ -23,6 +23,11 @@
 			"import": "./dist/scheduled.js",
 			"default": "./dist/scheduled.js"
 		},
+		"./mcp": {
+			"types": "./dist/mcp/index.d.ts",
+			"import": "./dist/mcp/index.js",
+			"default": "./dist/mcp/index.js"
+		},
 		"./client": {
 			"types": "./dist/client/index.d.ts",
 			"import": "./dist/client/index.js",
@@ -63,6 +68,11 @@
 			"import": "./dist/adapters/sqlite/index.js",
 			"default": "./dist/adapters/sqlite/index.js"
 		},
+		"./tanstack-db": {
+			"types": "./dist/adapters/tanstack-db/index.d.ts",
+			"import": "./dist/adapters/tanstack-db/index.js",
+			"default": "./dist/adapters/tanstack-db/index.js"
+		},
 		"./react": {
 			"types": "./dist/react/index.d.ts",
 			"import": "./dist/react/index.js",
@@ -121,18 +131,23 @@
 	],
 	"peerDependencies": {
 		"@absolutejs/isolated-jsc": ">= 0.6.0",
+		"@modelcontextprotocol/sdk": ">= 1.29.0",
 		"@angular/core": ">= 21.0.0",
 		"@elysiajs/cron": ">= 1.4.0",
 		"drizzle-orm": ">= 0.44.0",
 		"elysia": ">= 1.4.26",
 		"react": ">= 19.0.0",
 		"svelte": ">= 5.0.0",
-		"vue": ">= 3.5.0"
+		"vue": ">= 3.5.0",
+		"@tanstack/db": ">= 0.6.7 <0.7"
 	},
 	"peerDependenciesMeta": {
 		"@absolutejs/isolated-jsc": {
 			"optional": true
 		},
+		"@modelcontextprotocol/sdk": {
+			"optional": true
+		},
 		"@angular/core": {
 			"optional": true
 		},
@@ -153,6 +168,9 @@
 		},
 		"vue": {
 			"optional": true
+		},
+		"@tanstack/db": {
+			"optional": true
 		}
 	},
 	"devDependencies": {
@@ -161,6 +179,8 @@
 		"@angular/core": "^21.0.0",
 		"@elysiajs/cron": "^1.4.2",
 		"@elysiajs/eden": "^1.4.9",
+		"@modelcontextprotocol/sdk": "^1.29.0",
+		"@tanstack/db": "0.6.7",
 		"@types/bun": "latest",
 		"@types/react": "^19.2.0",
 		"drizzle-orm": "^0.45.2",