@collage-dam/mcp-server 0.1.0

package/dist/conventions/response-budget.js

@@ -0,0 +1,89 @@
+import { z } from 'zod';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Soft-warn threshold — log a warning when a single tool response exceeds this. */
+export const SOFT_WARN_TOKENS = 4_000;
+/** Hard cap — automatically truncate responses that exceed this. */
+export const HARD_CAP_TOKENS = 12_000;
+// ---------------------------------------------------------------------------
+// Token estimation
+// ---------------------------------------------------------------------------
+/**
+ * Rough token-count heuristic for English text.
+ *
+ * cl100k_base averages ~4 characters per token for typical English /
+ * JSON-serialised content.  This avoids pulling in the full tiktoken
+ * dependency while remaining "good enough" for budget enforcement.
+ */
+export function estimateTokens(text) {
+    return Math.ceil(text.length / 4);
+}
+// ---------------------------------------------------------------------------
+// Response budget result schema & type
+// ---------------------------------------------------------------------------
+/**
+ * Zod schema factory for a budget-wrapped response.
+ *
+ * Usage:
+ *   const schema = responseBudgetResultSchema(z.array(myItemSchema));
+ */
+export function responseBudgetResultSchema(dataSchema) {
+    return z.object({
+        data: dataSchema,
+        token_estimate: z.number().int().nonnegative(),
+        truncated: z.boolean(),
+        next_cursor: z.string().nullable().optional(),
+    });
+}
+/**
+ * Walk through `items`, accumulating estimated tokens.  If the running
+ * total would exceed {@link HARD_CAP_TOKENS}, stop early, mark the
+ * response as truncated, and attach a `next_cursor` so the caller can
+ * resume.
+ */
+export function applyResponseBudget(items, opts) {
+    const { serialize, offset } = opts;
+    const accepted = [];
+    let cumulativeTokens = 0;
+    for (let i = 0; i < items.length; i++) {
+        const serialised = serialize(items[i]);
+        const itemTokens = estimateTokens(serialised);
+        if (cumulativeTokens + itemTokens > HARD_CAP_TOKENS && accepted.length > 0) {
+            // Would exceed the hard cap — stop here.
+            return {
+                data: accepted,
+                token_estimate: cumulativeTokens,
+                truncated: true,
+                next_cursor: String(offset + accepted.length),
+            };
+        }
+        // Always include at least one item even if it alone exceeds the cap,
+        // so clients never receive an empty page.
+        accepted.push(items[i]);
+        cumulativeTokens += itemTokens;
+    }
+    return {
+        data: accepted,
+        token_estimate: cumulativeTokens,
+        truncated: false,
+        next_cursor: null,
+    };
+}
+// ---------------------------------------------------------------------------
+// Soft-warn helper
+// ---------------------------------------------------------------------------
+/**
+ * Log a warning to stderr when a response exceeds {@link SOFT_WARN_TOKENS}.
+ *
+ * This intentionally writes to `process.stderr` so it stays out of MCP
+ * stdout transport.  Will be replaced with pino once the shared logger
+ * convention lands.
+ */
+export function warnIfOverBudget(tokenEstimate, toolName) {
+    if (tokenEstimate > SOFT_WARN_TOKENS) {
+        process.stderr.write(`[response-budget] WARNING: "${toolName}" response ~${tokenEstimate} tokens ` +
+            `(soft limit ${SOFT_WARN_TOKENS})\n`);
+    }
+}
+//# sourceMappingURL=response-budget.js.map

package/dist/conventions/response-budget.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"response-budget.js","sourceRoot":"","sources":["../../src/conventions/response-budget.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,8EAA8E;AAC9E,YAAY;AACZ,8EAA8E;AAE9E,oFAAoF;AACpF,MAAM,CAAC,MAAM,gBAAgB,GAAG,KAAK,CAAC;AAEtC,oEAAoE;AACpE,MAAM,CAAC,MAAM,eAAe,GAAG,MAAM,CAAC;AAEtC,8EAA8E;AAC9E,mBAAmB;AACnB,8EAA8E;AAE9E;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AACpC,CAAC;AAED,8EAA8E;AAC9E,uCAAuC;AACvC,8EAA8E;AAE9E;;;;;GAKG;AACH,MAAM,UAAU,0BAA0B,CAAyB,UAAa;IAC9E,OAAO,CAAC,CAAC,MAAM,CAAC;QACd,IAAI,EAAE,UAAU;QAChB,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;QAC9C,SAAS,EAAE,CAAC,CAAC,OAAO,EAAE;QACtB,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;KAC9C,CAAC,CAAC;AACL,CAAC;AAuBD;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CACjC,KAAU,EACV,IAAgC;IAEhC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IAEnC,MAAM,QAAQ,GAAQ,EAAE,CAAC;IACzB,IAAI,gBAAgB,GAAG,CAAC,CAAC;IAEzB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,MAAM,UAAU,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC,CAAM,CAAC,CAAC;QAC5C,MAAM,UAAU,GAAG,cAAc,CAAC,UAAU,CAAC,CAAC;QAE9C,IAAI,gBAAgB,GAAG,UAAU,GAAG,eAAe,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC3E,yCAAyC;YACzC,OAAO;gBACL,IAAI,EAAE,QAAQ;gBACd,cAAc,EAAE,gBAAgB;gBAChC,SAAS,EAAE,IAAI;gBACf,WAAW,EAAE,MAAM,CAAC,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC;aAC9C,CAAC;QACJ,CAAC;QAED,qEAAqE;QACrE,0CAA0C;QAC1C,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAM,CAAC,CAAC;QAC7B,gBAAgB,IAAI,UAAU,CAAC;IACjC,CAAC;IAED,OAAO;QACL,IAAI,EAAE,QAAQ;QACd,cAAc,EAAE,gBAAgB;QAChC,SAAS,EAAE,KAAK;QAChB,WAAW,EAAE,IAAI;KAClB,CAAC;AACJ,CAAC;AAED,8EAA8E;AAC9E,mBAAmB;AACnB,8EAA8E;AAE9E;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,aAAqB,EAAE,QAAgB;IACtE,IAAI,aAAa,GAAG,gBAAgB,EAAE,CAAC;QACrC,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,+BAA+B,QAAQ,eAAe,aAAa,UAAU;YAC3E,eAAe,gBAAgB,KAAK,CACvC,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/conventions/schema-version.d.ts

@@ -0,0 +1,27 @@
+import { z } from 'zod';
+/**
+ * Single source of truth for the MCP schema version.
+ * Every tool response includes this as a top-level `schema_version` field.
+ *
+ * Versioning policy:
+ * - MVP ships at 0.1.x with no compatibility guarantees until 1.0.0
+ * - Breaking changes to any tool shape bump the major version
+ * - Additive changes bump the minor version
+ */
+export declare const COLLAGE_MCP_SCHEMA_VERSION = "0.1.0";
+/**
+ * Zod literal schema matching the current schema version.
+ * Use in tool response schemas to enforce the exact version string.
+ */
+export declare const SchemaVersionSchema: z.ZodLiteral<"0.1.0">;
+/**
+ * Stamps a tool response object with the current schema version.
+ */
+export declare function addSchemaVersion<T extends Record<string, unknown>>(response: T): T & {
+    schema_version: string;
+};
+/**
+ * Checks whether a version string matches the current schema version constant.
+ */
+export declare function validateSchemaVersion(version: string): boolean;
+//# sourceMappingURL=schema-version.d.ts.map

package/dist/conventions/schema-version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-version.d.ts","sourceRoot":"","sources":["../../src/conventions/schema-version.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;GAQG;AACH,eAAO,MAAM,0BAA0B,UAAU,CAAC;AAElD;;;GAGG;AACH,eAAO,MAAM,mBAAmB,uBAAwC,CAAC;AAEzE;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChE,QAAQ,EAAE,CAAC,GACV,CAAC,GAAG;IAAE,cAAc,EAAE,MAAM,CAAA;CAAE,CAEhC;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAE9D"}

package/dist/conventions/schema-version.js

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+/**
+ * Single source of truth for the MCP schema version.
+ * Every tool response includes this as a top-level `schema_version` field.
+ *
+ * Versioning policy:
+ * - MVP ships at 0.1.x with no compatibility guarantees until 1.0.0
+ * - Breaking changes to any tool shape bump the major version
+ * - Additive changes bump the minor version
+ */
+export const COLLAGE_MCP_SCHEMA_VERSION = '0.1.0';
+/**
+ * Zod literal schema matching the current schema version.
+ * Use in tool response schemas to enforce the exact version string.
+ */
+export const SchemaVersionSchema = z.literal(COLLAGE_MCP_SCHEMA_VERSION);
+/**
+ * Stamps a tool response object with the current schema version.
+ */
+export function addSchemaVersion(response) {
+    return { ...response, schema_version: COLLAGE_MCP_SCHEMA_VERSION };
+}
+/**
+ * Checks whether a version string matches the current schema version constant.
+ */
+export function validateSchemaVersion(version) {
+    return version === COLLAGE_MCP_SCHEMA_VERSION;
+}
+//# sourceMappingURL=schema-version.js.map

package/dist/conventions/schema-version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-version.js","sourceRoot":"","sources":["../../src/conventions/schema-version.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,OAAO,CAAC;AAElD;;;GAGG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,OAAO,CAAC,0BAA0B,CAAC,CAAC;AAEzE;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAC9B,QAAW;IAEX,OAAO,EAAE,GAAG,QAAQ,EAAE,cAAc,EAAE,0BAA0B,EAAE,CAAC;AACrE,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAAe;IACnD,OAAO,OAAO,KAAK,0BAA0B,CAAC;AAChD,CAAC"}

package/dist/conventions/state-store-redis.d.ts

@@ -0,0 +1,32 @@
+import { Redis } from 'ioredis';
+import type { EphemeralStateStore } from './state-store.js';
+export interface RedisStateStoreOptions {
+    redis: Redis;
+    prefix?: string;
+}
+/**
+ * Redis-backed implementation of `EphemeralStateStore`.
+ *
+ * Values are JSON-serialised before storage and deserialised on read.
+ * Keys are namespaced with a configurable prefix (default `collage-mcp:`).
+ * TTL is delegated to Redis via `SET … EX`.
+ */
+export declare class RedisStateStore<T> implements EphemeralStateStore<T> {
+    private readonly redis;
+    private readonly prefix;
+    constructor(options: RedisStateStoreOptions);
+    get(key: string): Promise<T | undefined>;
+    set(key: string, value: T, ttlMs?: number): Promise<void>;
+    delete(key: string): Promise<boolean>;
+    getAndDelete(key: string): Promise<T | undefined>;
+    has(key: string): Promise<boolean>;
+    private prefixed;
+}
+/**
+ * Create a `RedisStateStore` from a Redis connection URL.
+ *
+ * The returned store owns the `Redis` instance; callers should call
+ * `redis.quit()` when shutting down.
+ */
+export declare function createRedisStateStore<T>(redisUrl: string, prefix?: string): RedisStateStore<T>;
+//# sourceMappingURL=state-store-redis.d.ts.map

package/dist/conventions/state-store-redis.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-store-redis.d.ts","sourceRoot":"","sources":["../../src/conventions/state-store-redis.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAEhC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAQ5D,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,KAAK,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;GAMG;AACH,qBAAa,eAAe,CAAC,CAAC,CAAE,YAAW,mBAAmB,CAAC,CAAC,CAAC;IAC/D,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAQ;IAC9B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;gBAEpB,OAAO,EAAE,sBAAsB;IAKrC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IAQxC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,GAAE,MAAuB,GAAG,OAAO,CAAC,IAAI,CAAC;IAMzE,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAKrC,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IAsBjD,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAOxC,OAAO,CAAC,QAAQ;CAGjB;AAID;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,EACrC,QAAQ,EAAE,MAAM,EAChB,MAAM,CAAC,EAAE,MAAM,GACd,eAAe,CAAC,CAAC,CAAC,CAGpB"}

package/dist/conventions/state-store-redis.js

@@ -0,0 +1,77 @@
+// ── Redis State Store ────────────────────────────────────────────────
+// Redis-backed adapter for EphemeralStateStore, used by the self-hosted
+// HTTP transport. Values are JSON-serialized; all keys are prefixed.
+import { Redis } from 'ioredis';
+import { DEFAULT_TTL_MS } from './state-store.js';
+// ── Constants ────────────────────────────────────────────────────────
+const DEFAULT_PREFIX = 'collage-mcp:';
+/**
+ * Redis-backed implementation of `EphemeralStateStore`.
+ *
+ * Values are JSON-serialised before storage and deserialised on read.
+ * Keys are namespaced with a configurable prefix (default `collage-mcp:`).
+ * TTL is delegated to Redis via `SET … EX`.
+ */
+export class RedisStateStore {
+    redis;
+    prefix;
+    constructor(options) {
+        this.redis = options.redis;
+        this.prefix = options.prefix ?? DEFAULT_PREFIX;
+    }
+    async get(key) {
+        const raw = await this.redis.get(this.prefixed(key));
+        if (raw === null) {
+            return undefined;
+        }
+        return JSON.parse(raw);
+    }
+    async set(key, value, ttlMs = DEFAULT_TTL_MS) {
+        const serialised = JSON.stringify(value);
+        const ttlSeconds = Math.ceil(ttlMs / 1000);
+        await this.redis.set(this.prefixed(key), serialised, 'EX', ttlSeconds);
+    }
+    async delete(key) {
+        const count = await this.redis.del(this.prefixed(key));
+        return count > 0;
+    }
+    async getAndDelete(key) {
+        const prefixedKey = this.prefixed(key);
+        const pipeline = this.redis.multi();
+        pipeline.get(prefixedKey);
+        pipeline.del(prefixedKey);
+        const results = await pipeline.exec();
+        if (results === null) {
+            return undefined;
+        }
+        // results[0] is [error, value] for the GET command
+        const [getError, raw] = results[0];
+        if (getError !== null) {
+            throw getError;
+        }
+        if (raw === null) {
+            return undefined;
+        }
+        return JSON.parse(raw);
+    }
+    async has(key) {
+        const count = await this.redis.exists(this.prefixed(key));
+        return count > 0;
+    }
+    // ── Private ──────────────────────────────────────────────────────
+    prefixed(key) {
+        return `${this.prefix}${key}`;
+    }
+}
+// ── Factory ──────────────────────────────────────────────────────────
+/**
+ * Create a `RedisStateStore` from a Redis connection URL.
+ *
+ * The returned store owns the `Redis` instance; callers should call
+ * `redis.quit()` when shutting down.
+ */
+export function createRedisStateStore(redisUrl, prefix) {
+    const redis = new Redis(redisUrl);
+    return new RedisStateStore({ redis, prefix });
+}
+//# sourceMappingURL=state-store-redis.js.map

package/dist/conventions/state-store-redis.js.map

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

package/dist/conventions/state-store.d.ts

@@ -0,0 +1,46 @@
+/** Default time-to-live for state entries: 5 minutes. */
+export declare const DEFAULT_TTL_MS = 300000;
+/** Interval for evicting expired entries: 60 seconds. */
+export declare const CLEANUP_INTERVAL_MS = 60000;
+/**
+ * A backend-agnostic contract for ephemeral key-value storage.
+ * Callers depend on this interface only; adapters implement it.
+ */
+export interface EphemeralStateStore<T> {
+    /** Retrieve a value by key. Returns `undefined` if missing or expired. */
+    get(key: string): Promise<T | undefined>;
+    /** Store a value with an optional TTL (defaults to `DEFAULT_TTL_MS`). */
+    set(key: string, value: T, ttlMs?: number): Promise<void>;
+    /** Delete a key. Returns `true` if the key existed and was removed. */
+    delete(key: string): Promise<boolean>;
+    /** Atomically retrieve and delete a value. Used by the execute step. */
+    getAndDelete(key: string): Promise<T | undefined>;
+    /** Check whether a non-expired entry exists for the key. */
+    has(key: string): Promise<boolean>;
+}
+/**
+ * In-memory implementation of `EphemeralStateStore`.
+ *
+ * Backed by a `Map` keyed by confirmation ID. Entries are evicted
+ * on access if expired, and a periodic cleanup sweep runs every
+ * `CLEANUP_INTERVAL_MS`. The cleanup interval is `unref()`'d so
+ * it does not keep the Node.js process alive.
+ */
+export declare class InMemoryStateStore<T> implements EphemeralStateStore<T> {
+    private readonly store;
+    private readonly cleanupTimer;
+    constructor();
+    get(key: string): Promise<T | undefined>;
+    set(key: string, value: T, ttlMs?: number): Promise<void>;
+    delete(key: string): Promise<boolean>;
+    getAndDelete(key: string): Promise<T | undefined>;
+    has(key: string): Promise<boolean>;
+    /** Returns the count of non-expired entries. */
+    get size(): number;
+    /** Remove all entries and stop the cleanup timer. */
+    clear(): void;
+    /** Stop the background cleanup interval. */
+    destroy(): void;
+    private evictExpired;
+}
+//# sourceMappingURL=state-store.d.ts.map

package/dist/conventions/state-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-store.d.ts","sourceRoot":"","sources":["../../src/conventions/state-store.ts"],"names":[],"mappings":"AAOA,yDAAyD;AACzD,eAAO,MAAM,cAAc,SAAU,CAAC;AAEtC,yDAAyD;AACzD,eAAO,MAAM,mBAAmB,QAAS,CAAC;AAI1C;;;GAGG;AACH,MAAM,WAAW,mBAAmB,CAAC,CAAC;IACpC,0EAA0E;IAC1E,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;IAEzC,yEAAyE;IACzE,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE1D,uEAAuE;IACvE,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEtC,wEAAwE;IACxE,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;IAElD,4DAA4D;IAC5D,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACpC;AASD;;;;;;;GAOG;AACH,qBAAa,kBAAkB,CAAC,CAAC,CAAE,YAAW,mBAAmB,CAAC,CAAC,CAAC;IAClE,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAoC;IAC1D,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAiC;;IAaxD,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IAYxC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,GAAE,MAAuB,GAAG,OAAO,CAAC,IAAI,CAAC;IAOzE,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAIrC,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IAYjD,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAYxC,gDAAgD;IAChD,IAAI,IAAI,IAAI,MAAM,CAWjB;IAED,qDAAqD;IACrD,KAAK,IAAI,IAAI;IAIb,4CAA4C;IAC5C,OAAO,IAAI,IAAI;IAOf,OAAO,CAAC,YAAY;CAQrB"}

package/dist/conventions/state-store.js

@@ -0,0 +1,105 @@
+// ── Ephemeral State Store ────────────────────────────────────────────
+// Backend-agnostic ephemeral state store interface and in-memory adapter.
+// Used by the dry-run framework to store confirmation tokens.
+// No external dependencies; stdio transport uses the in-memory adapter.
+// ── Constants ────────────────────────────────────────────────────────
+/** Default time-to-live for state entries: 5 minutes. */
+export const DEFAULT_TTL_MS = 300_000;
+/** Interval for evicting expired entries: 60 seconds. */
+export const CLEANUP_INTERVAL_MS = 60_000;
+/**
+ * In-memory implementation of `EphemeralStateStore`.
+ *
+ * Backed by a `Map` keyed by confirmation ID. Entries are evicted
+ * on access if expired, and a periodic cleanup sweep runs every
+ * `CLEANUP_INTERVAL_MS`. The cleanup interval is `unref()`'d so
+ * it does not keep the Node.js process alive.
+ */
+export class InMemoryStateStore {
+    store = new Map();
+    cleanupTimer;
+    constructor() {
+        this.cleanupTimer = setInterval(() => {
+            this.evictExpired();
+        }, CLEANUP_INTERVAL_MS);
+        // Ensure the timer doesn't prevent process exit
+        if (typeof this.cleanupTimer === 'object' && 'unref' in this.cleanupTimer) {
+            this.cleanupTimer.unref();
+        }
+    }
+    async get(key) {
+        const entry = this.store.get(key);
+        if (entry === undefined) {
+            return undefined;
+        }
+        if (Date.now() >= entry.expiresAt) {
+            this.store.delete(key);
+            return undefined;
+        }
+        return entry.value;
+    }
+    async set(key, value, ttlMs = DEFAULT_TTL_MS) {
+        this.store.set(key, {
+            value,
+            expiresAt: Date.now() + ttlMs,
+        });
+    }
+    async delete(key) {
+        return this.store.delete(key);
+    }
+    async getAndDelete(key) {
+        const entry = this.store.get(key);
+        if (entry === undefined) {
+            return undefined;
+        }
+        this.store.delete(key);
+        if (Date.now() >= entry.expiresAt) {
+            return undefined;
+        }
+        return entry.value;
+    }
+    async has(key) {
+        const entry = this.store.get(key);
+        if (entry === undefined) {
+            return false;
+        }
+        if (Date.now() >= entry.expiresAt) {
+            this.store.delete(key);
+            return false;
+        }
+        return true;
+    }
+    /** Returns the count of non-expired entries. */
+    get size() {
+        let count = 0;
+        const now = Date.now();
+        for (const [key, entry] of this.store) {
+            if (now >= entry.expiresAt) {
+                this.store.delete(key);
+            }
+            else {
+                count++;
+            }
+        }
+        return count;
+    }
+    /** Remove all entries and stop the cleanup timer. */
+    clear() {
+        this.store.clear();
+    }
+    /** Stop the background cleanup interval. */
+    destroy() {
+        clearInterval(this.cleanupTimer);
+        this.store.clear();
+    }
+    // ── Private ──────────────────────────────────────────────────────
+    evictExpired() {
+        const now = Date.now();
+        for (const [key, entry] of this.store) {
+            if (now >= entry.expiresAt) {
+                this.store.delete(key);
+            }
+        }
+    }
+}
+//# sourceMappingURL=state-store.js.map

package/dist/conventions/state-store.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export { COLLAGE_MCP_SCHEMA_VERSION, SchemaVersionSchema, addSchemaVersion, validateSchemaVersion, } from './conventions/schema-version.js';
+export declare function createServer(): Promise<McpServer>;
+//# 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":";AACA,OAAO,EAAE,SAAS,EAAoB,MAAM,yCAAyC,CAAC;AA4OtF,OAAO,EACL,0BAA0B,EAC1B,mBAAmB,EACnB,gBAAgB,EAChB,qBAAqB,GACtB,MAAM,iCAAiC,CAAC;AAoCzC,wBAAsB,YAAY,IAAI,OAAO,CAAC,SAAS,CAAC,CAylBvD"}