@adcp/client 4.22.1 → 4.24.0

package/dist/lib/server/postgres-task-store.js

@@ -0,0 +1,267 @@
+"use strict";
+/**
+ * PostgreSQL-backed TaskStore for distributed MCP servers.
+ *
+ * Replaces InMemoryTaskStore when running multiple server instances behind
+ * a load balancer. Tasks are stored in a shared table so any instance can
+ * create, retrieve, or update a task regardless of which instance handled
+ * the original request.
+ *
+ * @example
+ * ```typescript
+ * import { Pool } from 'pg';
+ * import { PostgresTaskStore, serve, createTaskCapableServer } from '@adcp/client';
+ *
+ * const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+ * const taskStore = new PostgresTaskStore(pool);
+ *
+ * serve(({ taskStore }) => createTaskCapableServer('My Agent', '1.0.0', { taskStore }), {
+ *   taskStore,
+ * });
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PostgresTaskStore = exports.MCP_TASKS_MIGRATION = void 0;
+exports.getMcpTasksMigration = getMcpTasksMigration;
+exports.cleanupExpiredTasks = cleanupExpiredTasks;
+const node_crypto_1 = require("node:crypto");
+/** Default table name — vendor-prefixed to avoid collisions in consumer databases. */
+const DEFAULT_TABLE = 'adcp_mcp_tasks';
+/** Validates a SQL identifier to prevent injection via table/constraint names. */
+const VALID_IDENTIFIER = /^[a-z_][a-z0-9_]*$/;
+/** Page size for listTasks pagination (matches InMemoryTaskStore). */
+const PAGE_SIZE = 10;
+/**
+ * Generate the SQL DDL for the task store table.
+ *
+ * Constraint and index names are derived from the table name to avoid
+ * collisions when multiple stores share the same database.
+ *
+ * @example
+ * ```typescript
+ * import { getMcpTasksMigration } from '@adcp/client';
+ * await pool.query(getMcpTasksMigration()); // creates adcp_mcp_tasks
+ * await pool.query(getMcpTasksMigration({ tableName: 'my_tasks' })); // custom name
+ * ```
+ */
+function getMcpTasksMigration(options) {
+    const table = options?.tableName ?? DEFAULT_TABLE;
+    if (!VALID_IDENTIFIER.test(table)) {
+        throw new Error(`Invalid table name "${table}": must match ${VALID_IDENTIFIER}`);
+    }
+    return `
+CREATE TABLE IF NOT EXISTS ${table} (
+  task_id         TEXT PRIMARY KEY,
+  status          TEXT NOT NULL DEFAULT 'working',
+  ttl             INTEGER,
+  poll_interval   INTEGER NOT NULL DEFAULT 1000,
+  status_message  TEXT,
+  request_id      TEXT NOT NULL,
+  request         JSONB NOT NULL,
+  result          JSONB,
+  created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  last_updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  expires_at      TIMESTAMPTZ,
+
+  CONSTRAINT ${table}_valid_status CHECK (
+    status IN ('working', 'input_required', 'completed', 'failed', 'cancelled')
+  )
+);
+
+CREATE INDEX IF NOT EXISTS idx_${table}_expires_at
+  ON ${table}(expires_at) WHERE expires_at IS NOT NULL;
+
+CREATE INDEX IF NOT EXISTS idx_${table}_created_at
+  ON ${table}(created_at);
+`.trim();
+}
+/** Backward-compatible constant using the default table name. */
+exports.MCP_TASKS_MIGRATION = getMcpTasksMigration();
+/** Convert a database row to an MCP Task object. */
+function rowToTask(row) {
+    const task = {
+        taskId: row.task_id,
+        status: row.status,
+        ttl: row.ttl,
+        createdAt: new Date(row.created_at).toISOString(),
+        lastUpdatedAt: new Date(row.last_updated_at).toISOString(),
+    };
+    if (row.poll_interval != null) {
+        task.pollInterval = row.poll_interval;
+    }
+    if (row.status_message != null) {
+        task.statusMessage = row.status_message;
+    }
+    return task;
+}
+/** WHERE clause that filters out expired tasks. */
+const NOT_EXPIRED = `(expires_at IS NULL OR expires_at > NOW())`;
+/**
+ * PostgreSQL-backed implementation of the MCP SDK TaskStore interface.
+ *
+ * All reads filter out expired tasks (via `expires_at`), so no background
+ * timer is needed — expired tasks are simply invisible. Call
+ * `cleanupExpired()` periodically to reclaim storage.
+ */
+class PostgresTaskStore {
+    db;
+    table;
+    constructor(db, options) {
+        this.db = db;
+        this.table = options?.tableName ?? DEFAULT_TABLE;
+        if (!VALID_IDENTIFIER.test(this.table)) {
+            throw new Error(`Invalid table name "${this.table}": must match ${VALID_IDENTIFIER}`);
+        }
+    }
+    async createTask(taskParams, requestId, request, _sessionId) {
+        const taskId = (0, node_crypto_1.randomBytes)(16).toString('hex');
+        const ttl = taskParams.ttl ?? null;
+        const pollInterval = taskParams.pollInterval ?? 1000;
+        const { rows } = await this.db.query(`INSERT INTO ${this.table} (task_id, status, ttl, poll_interval, request_id, request, expires_at)
+       VALUES ($1, 'working', $2, $3, $4, $5,
+               CASE WHEN $2::integer IS NOT NULL
+                    THEN NOW() + ($2::integer || ' milliseconds')::interval
+                    ELSE NULL END)
+       RETURNING *`, [taskId, ttl, pollInterval, String(requestId), JSON.stringify(request)]);
+        return rowToTask(rows[0]);
+    }
+    async getTask(taskId, _sessionId) {
+        const { rows } = await this.db.query(`SELECT * FROM ${this.table} WHERE task_id = $1 AND ${NOT_EXPIRED}`, [taskId]);
+        return rows.length > 0 ? rowToTask(rows[0]) : null;
+    }
+    async storeTaskResult(taskId, status, result, _sessionId) {
+        // Atomic check-and-update: only modify if task exists and is non-terminal.
+        const { rowCount, rows } = await this.db.query(`UPDATE ${this.table}
+       SET status = $2,
+           result = $3,
+           last_updated_at = NOW(),
+           expires_at = CASE WHEN ttl IS NOT NULL
+                             THEN NOW() + (ttl || ' milliseconds')::interval
+                             ELSE NULL END
+       WHERE task_id = $1
+         AND status NOT IN ('completed', 'failed', 'cancelled')
+         AND ${NOT_EXPIRED}
+       RETURNING status`, [taskId, status, JSON.stringify(result)]);
+        if (!rowCount || rows.length === 0) {
+            // Distinguish "not found" / "expired" from "already terminal".
+            const { rows: existing } = await this.db.query(`SELECT status FROM ${this.table} WHERE task_id = $1 AND ${NOT_EXPIRED}`, [taskId]);
+            if (existing.length === 0) {
+                throw new Error(`Task with ID ${taskId} not found`);
+            }
+            throw new Error(`Cannot store result for task ${taskId} in terminal status '${existing[0].status}'. Task results can only be stored once.`);
+        }
+    }
+    async getTaskResult(taskId, _sessionId) {
+        const { rows } = await this.db.query(`SELECT result FROM ${this.table} WHERE task_id = $1 AND ${NOT_EXPIRED}`, [
+            taskId,
+        ]);
+        if (rows.length === 0) {
+            throw new Error(`Task with ID ${taskId} not found`);
+        }
+        const row = rows[0];
+        if (row.result == null) {
+            throw new Error(`Task ${taskId} has no result stored`);
+        }
+        return row.result;
+    }
+    async updateTaskStatus(taskId, status, statusMessage, _sessionId) {
+        // Atomic: only update if not already in a terminal state.
+        const { rowCount, rows } = await this.db.query(`UPDATE ${this.table}
+       SET status = $2,
+           status_message = COALESCE($3, status_message),
+           last_updated_at = NOW(),
+           expires_at = CASE
+             WHEN $2 IN ('completed', 'failed', 'cancelled') AND ttl IS NOT NULL
+               THEN NOW() + (ttl || ' milliseconds')::interval
+             ELSE expires_at END
+       WHERE task_id = $1
+         AND status NOT IN ('completed', 'failed', 'cancelled')
+         AND ${NOT_EXPIRED}
+       RETURNING status`, [taskId, status, statusMessage ?? null]);
+        if (!rowCount || rows.length === 0) {
+            const { rows: existing } = await this.db.query(`SELECT status FROM ${this.table} WHERE task_id = $1 AND ${NOT_EXPIRED}`, [taskId]);
+            if (existing.length === 0) {
+                throw new Error(`Task with ID ${taskId} not found`);
+            }
+            throw new Error(`Cannot update task ${taskId} from terminal status '${existing[0].status}' to '${status}'. Terminal states (completed, failed, cancelled) cannot transition to other states.`);
+        }
+    }
+    async listTasks(cursor, _sessionId) {
+        let rawRows;
+        if (cursor) {
+            // Decode cursor: "created_at|task_id" — split on first | only,
+            // so task IDs containing | are handled correctly.
+            const sepIndex = cursor.indexOf('|');
+            if (sepIndex < 1) {
+                throw new Error(`Invalid cursor: ${cursor}`);
+            }
+            const cursorCreatedAt = cursor.slice(0, sepIndex);
+            const cursorTaskId = cursor.slice(sepIndex + 1);
+            if (!cursorTaskId || isNaN(Date.parse(cursorCreatedAt))) {
+                throw new Error(`Invalid cursor: ${cursor}`);
+            }
+            ({ rows: rawRows } = await this.db.query(`SELECT *, created_at::text AS created_at_raw FROM ${this.table}
+         WHERE ${NOT_EXPIRED}
+           AND (created_at, task_id) > ($1::timestamptz, $2)
+         ORDER BY created_at, task_id
+         LIMIT $3`, [cursorCreatedAt, cursorTaskId, PAGE_SIZE + 1]));
+        }
+        else {
+            ({ rows: rawRows } = await this.db.query(`SELECT *, created_at::text AS created_at_raw FROM ${this.table}
+         WHERE ${NOT_EXPIRED}
+         ORDER BY created_at, task_id
+         LIMIT $1`, [PAGE_SIZE + 1]));
+        }
+        const rows = rawRows;
+        const hasMore = rows.length > PAGE_SIZE;
+        const pageRows = hasMore ? rows.slice(0, PAGE_SIZE) : rows;
+        const tasks = pageRows.map(rowToTask);
+        let nextCursor;
+        if (hasMore && pageRows.length > 0) {
+            const last = pageRows[pageRows.length - 1];
+            // Use the raw PostgreSQL text representation to preserve microsecond
+            // precision. JavaScript Date only has millisecond precision, which
+            // causes keyset pagination to re-include rows when multiple tasks
+            // share the same millisecond.
+            nextCursor = `${last.created_at_raw}|${last.task_id}`;
+        }
+        return { tasks, nextCursor };
+    }
+    /**
+     * Delete expired tasks from the table.
+     *
+     * Call this on a schedule (e.g., every 5 minutes) to reclaim storage.
+     * Reads automatically filter expired rows, so this is purely a storage
+     * optimization — not required for correctness.
+     *
+     * @returns The number of deleted rows.
+     */
+    async cleanupExpired() {
+        const { rowCount } = await this.db.query(`DELETE FROM ${this.table} WHERE expires_at IS NOT NULL AND expires_at <= NOW()`);
+        return rowCount ?? 0;
+    }
+    /**
+     * No-op — PostgresTaskStore has no timers or background processes.
+     * Matches the cleanup() method that InMemoryTaskStore exposes.
+     */
+    cleanup() {
+        // Nothing to clean up — no timers.
+    }
+}
+exports.PostgresTaskStore = PostgresTaskStore;
+/**
+ * Delete expired tasks from the task store table.
+ *
+ * Standalone version of `PostgresTaskStore.cleanupExpired()` for use
+ * without a store instance.
+ *
+ * @returns The number of deleted rows.
+ */
+async function cleanupExpiredTasks(db, tableName = DEFAULT_TABLE) {
+    if (!VALID_IDENTIFIER.test(tableName)) {
+        throw new Error(`Invalid table name "${tableName}": must match ${VALID_IDENTIFIER}`);
+    }
+    const { rowCount } = await db.query(`DELETE FROM ${tableName} WHERE expires_at IS NOT NULL AND expires_at <= NOW()`);
+    return rowCount ?? 0;
+}
+//# sourceMappingURL=postgres-task-store.js.map

package/dist/lib/server/postgres-task-store.js.map

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

package/dist/lib/server/responses.d.ts

@@ -42,6 +42,7 @@ export interface McpToolResponse {
     }>;
     structuredContent: Record<string, unknown>;
 }
+export declare function toStructuredContent(data: object): Record<string, unknown>;
 /**
  * Build a get_adcp_capabilities response.
  *

package/dist/lib/server/responses.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"responses.d.ts","sourceRoot":"","sources":["../../../src/lib/server/responses.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,0BAA0B,CAAC;AAC5E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AACnE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AACrE,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,0BAA0B,CAAC;AAE5E;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IACvB,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC5C;AASD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,2BAA2B,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,eAAe,CAKzG;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,mBAAmB,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,eAAe,CAK7F;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,qBAAqB,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,eAAe,CAK/F;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,2BAA2B,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,eAAe,CAYrG"}
+{"version":3,"file":"responses.d.ts","sourceRoot":"","sources":["../../../src/lib/server/responses.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,0BAA0B,CAAC;AAC5E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AACnE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AACrE,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,0BAA0B,CAAC;AAE5E;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IACvB,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC5C;AAKD,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEzE;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,2BAA2B,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,eAAe,CAKzG;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,mBAAmB,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,eAAe,CAK7F;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,qBAAqB,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,eAAe,CAK/F;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,2BAA2B,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,eAAe,CAYrG"}

package/dist/lib/server/responses.js

@@ -27,6 +27,7 @@
  * ```
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.toStructuredContent = toStructuredContent;
 exports.capabilitiesResponse = capabilitiesResponse;
 exports.productsResponse = productsResponse;
 exports.mediaBuyResponse = mediaBuyResponse;

package/dist/lib/server/responses.js.map

@@ -1 +1 @@
-{"version":3,"file":"responses.js","sourceRoot":"","sources":["../../../src/lib/server/responses.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;;AA+BH,oDAKC;AAKD,4CAKC;AAKD,4CAKC;AAKD,4CAYC;AAvDD,4FAA4F;AAC5F,uFAAuF;AACvF,yDAAyD;AACzD,SAAS,mBAAmB,CAAC,IAAY;IACvC,OAAO,IAA0C,CAAC;AACpD,CAAC;AAED;;;;;GAKG;AACH,SAAgB,oBAAoB,CAAC,IAAiC,EAAE,OAAgB;IACtF,OAAO;QACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,IAAI,8BAA8B,EAAE,CAAC;QAC5E,iBAAiB,EAAE,mBAAmB,CAAC,IAAI,CAAC;KAC7C,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,SAAgB,gBAAgB,CAAC,IAAyB,EAAE,OAAgB;IAC1E,OAAO;QACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,IAAI,SAAS,IAAI,CAAC,QAAQ,CAAC,MAAM,WAAW,EAAE,CAAC;QACtF,iBAAiB,EAAE,mBAAmB,CAAC,IAAI,CAAC;KAC7C,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,SAAgB,gBAAgB,CAAC,IAA2B,EAAE,OAAgB;IAC5E,OAAO;QACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,IAAI,aAAa,IAAI,CAAC,YAAY,UAAU,EAAE,CAAC;QACtF,iBAAiB,EAAE,mBAAmB,CAAC,IAAI,CAAC;KAC7C,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,SAAgB,gBAAgB,CAAC,IAAiC,EAAE,OAAgB;IAClF,OAAO;QACL,OAAO,EAAE;YACP;gBACE,IAAI,EAAE,MAAM;gBACZ,IAAI,EACF,OAAO;oBACP,qBAAqB,IAAI,CAAC,oBAAoB,CAAC,MAAM,aAAa,IAAI,CAAC,oBAAoB,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,EAAE;aACxH;SACF;QACD,iBAAiB,EAAE,mBAAmB,CAAC,IAAI,CAAC;KAC7C,CAAC;AACJ,CAAC"}
+{"version":3,"file":"responses.js","sourceRoot":"","sources":["../../../src/lib/server/responses.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;;AAqBH,kDAEC;AAQD,oDAKC;AAKD,4CAKC;AAKD,4CAKC;AAKD,4CAYC;AAvDD,4FAA4F;AAC5F,uFAAuF;AACvF,yDAAyD;AACzD,SAAgB,mBAAmB,CAAC,IAAY;IAC9C,OAAO,IAA0C,CAAC;AACpD,CAAC;AAED;;;;;GAKG;AACH,SAAgB,oBAAoB,CAAC,IAAiC,EAAE,OAAgB;IACtF,OAAO;QACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,IAAI,8BAA8B,EAAE,CAAC;QAC5E,iBAAiB,EAAE,mBAAmB,CAAC,IAAI,CAAC;KAC7C,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,SAAgB,gBAAgB,CAAC,IAAyB,EAAE,OAAgB;IAC1E,OAAO;QACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,IAAI,SAAS,IAAI,CAAC,QAAQ,CAAC,MAAM,WAAW,EAAE,CAAC;QACtF,iBAAiB,EAAE,mBAAmB,CAAC,IAAI,CAAC;KAC7C,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,SAAgB,gBAAgB,CAAC,IAA2B,EAAE,OAAgB;IAC5E,OAAO;QACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,IAAI,aAAa,IAAI,CAAC,YAAY,UAAU,EAAE,CAAC;QACtF,iBAAiB,EAAE,mBAAmB,CAAC,IAAI,CAAC;KAC7C,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,SAAgB,gBAAgB,CAAC,IAAiC,EAAE,OAAgB;IAClF,OAAO;QACL,OAAO,EAAE;YACP;gBACE,IAAI,EAAE,MAAM;gBACZ,IAAI,EACF,OAAO;oBACP,qBAAqB,IAAI,CAAC,oBAAoB,CAAC,MAAM,aAAa,IAAI,CAAC,oBAAoB,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,EAAE;aACxH;SACF;QACD,iBAAiB,EAAE,mBAAmB,CAAC,IAAI,CAAC;KAC7C,CAAC;AACJ,CAAC"}

package/dist/lib/server/test-controller.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Server-side comply_test_controller implementation.
+ *
+ * Sellers call registerTestController(server, store) to add the
+ * comply_test_controller tool to their MCP server. The TestControllerStore
+ * interface lets sellers wire up their own state management while the SDK
+ * handles request parsing, scenario dispatch, and response formatting.
+ *
+ * @example
+ * ```typescript
+ * import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+ * import { registerTestController } from '@adcp/client/server';
+ *
+ * const store: TestControllerStore = {
+ *   async forceAccountStatus(accountId, status) {
+ *     const prev = await db.getAccountStatus(accountId);
+ *     await db.setAccountStatus(accountId, status);
+ *     return { success: true, previous_state: prev, current_state: status };
+ *   },
+ *   // ... implement other scenarios as needed
+ * };
+ *
+ * registerTestController(server, store);
+ * ```
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ListScenariosSuccess, StateTransitionSuccess, SimulationSuccess, ControllerError, ComplyTestControllerResponse } from '../types/tools.generated';
+import type { AccountStatus, MediaBuyStatus, CreativeStatus } from '../types/core.generated';
+/** Scenario names the controller can support (derived from generated schema). */
+export type ControllerScenario = ListScenariosSuccess['scenarios'][number];
+/**
+ * Seller-side store for comply_test_controller.
+ *
+ * Implement the methods for each scenario you support.
+ * Unimplemented methods mean that scenario is not advertised in list_scenarios.
+ */
+export interface TestControllerStore {
+    /** Transition a creative to the specified status. */
+    forceCreativeStatus?(creativeId: string, status: CreativeStatus, rejectionReason?: string): Promise<StateTransitionSuccess>;
+    /** Transition an account to the specified status. */
+    forceAccountStatus?(accountId: string, status: AccountStatus): Promise<StateTransitionSuccess>;
+    /** Transition a media buy to the specified status. */
+    forceMediaBuyStatus?(mediaBuyId: string, status: MediaBuyStatus, rejectionReason?: string): Promise<StateTransitionSuccess>;
+    /** Transition an SI session to a terminal status. */
+    forceSessionStatus?(sessionId: string, status: 'complete' | 'terminated', terminationReason?: string): Promise<StateTransitionSuccess>;
+    /** Inject synthetic delivery data for a media buy. */
+    simulateDelivery?(mediaBuyId: string, params: {
+        impressions?: number;
+        clicks?: number;
+        reported_spend?: {
+            amount: number;
+            currency: string;
+        };
+        conversions?: number;
+    }): Promise<SimulationSuccess>;
+    /** Simulate budget consumption to a specified percentage. */
+    simulateBudgetSpend?(params: {
+        account_id?: string;
+        media_buy_id?: string;
+        spend_percentage: number;
+    }): Promise<SimulationSuccess>;
+}
+/**
+ * Throw from TestControllerStore methods to return a typed controller error.
+ *
+ * @example
+ * ```typescript
+ * throw new TestControllerError('NOT_FOUND', `Account ${id} not found`);
+ * throw new TestControllerError('INVALID_TRANSITION', 'Cannot pause a completed buy', 'completed');
+ * ```
+ */
+export declare class TestControllerError extends Error {
+    readonly code: ControllerError['error'];
+    readonly currentState?: string | null | undefined;
+    constructor(code: ControllerError['error'], message: string, currentState?: string | null | undefined);
+}
+/**
+ * Handle a comply_test_controller request. Exported for unit testing.
+ */
+export declare function handleTestControllerRequest(store: TestControllerStore, input: Record<string, unknown>): Promise<ComplyTestControllerResponse>;
+/**
+ * Register the comply_test_controller tool on an MCP server.
+ *
+ * The store determines which scenarios are supported. Unimplemented
+ * store methods are excluded from list_scenarios and return UNKNOWN_SCENARIO.
+ */
+export declare function registerTestController(server: McpServer, store: TestControllerStore): void;
+//# sourceMappingURL=test-controller.d.ts.map

package/dist/lib/server/test-controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-controller.d.ts","sourceRoot":"","sources":["../../../src/lib/server/test-controller.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,KAAK,EACV,oBAAoB,EACpB,sBAAsB,EACtB,iBAAiB,EACjB,eAAe,EACf,4BAA4B,EAC7B,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAS7F,iFAAiF;AACjF,MAAM,MAAM,kBAAkB,GAAG,oBAAoB,CAAC,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC;AAE3E;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,qDAAqD;IACrD,mBAAmB,CAAC,CAClB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,cAAc,EACtB,eAAe,CAAC,EAAE,MAAM,GACvB,OAAO,CAAC,sBAAsB,CAAC,CAAC;IAEnC,qDAAqD;IACrD,kBAAkB,CAAC,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAAC;IAE/F,sDAAsD;IACtD,mBAAmB,CAAC,CAClB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,cAAc,EACtB,eAAe,CAAC,EAAE,MAAM,GACvB,OAAO,CAAC,sBAAsB,CAAC,CAAC;IAEnC,qDAAqD;IACrD,kBAAkB,CAAC,CACjB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,UAAU,GAAG,YAAY,EACjC,iBAAiB,CAAC,EAAE,MAAM,GACzB,OAAO,CAAC,sBAAsB,CAAC,CAAC;IAEnC,sDAAsD;IACtD,gBAAgB,CAAC,CACf,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE;QACN,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,cAAc,CAAC,EAAE;YAAE,MAAM,EAAE,MAAM,CAAC;YAAC,QAAQ,EAAE,MAAM,CAAA;SAAE,CAAC;QACtD,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,GACA,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAE9B,6DAA6D;IAC7D,mBAAmB,CAAC,CAAC,MAAM,EAAE;QAC3B,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,gBAAgB,EAAE,MAAM,CAAC;KAC1B,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;CAChC;AAMD;;;;;;;;GAQG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;aAE1B,IAAI,EAAE,eAAe,CAAC,OAAO,CAAC;aAE9B,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI;gBAF5B,IAAI,EAAE,eAAe,CAAC,OAAO,CAAC,EAC9C,OAAO,EAAE,MAAM,EACC,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,YAAA;CAK/C;AAiCD;;GAEG;AACH,wBAAsB,2BAA2B,CAC/C,KAAK,EAAE,mBAAmB,EAC1B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,OAAO,CAAC,4BAA4B,CAAC,CAqIvC;AA8BD;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,mBAAmB,GAAG,IAAI,CAU1F"}

package/dist/lib/server/test-controller.js

@@ -0,0 +1,227 @@
+"use strict";
+/**
+ * Server-side comply_test_controller implementation.
+ *
+ * Sellers call registerTestController(server, store) to add the
+ * comply_test_controller tool to their MCP server. The TestControllerStore
+ * interface lets sellers wire up their own state management while the SDK
+ * handles request parsing, scenario dispatch, and response formatting.
+ *
+ * @example
+ * ```typescript
+ * import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+ * import { registerTestController } from '@adcp/client/server';
+ *
+ * const store: TestControllerStore = {
+ *   async forceAccountStatus(accountId, status) {
+ *     const prev = await db.getAccountStatus(accountId);
+ *     await db.setAccountStatus(accountId, status);
+ *     return { success: true, previous_state: prev, current_state: status };
+ *   },
+ *   // ... implement other scenarios as needed
+ * };
+ *
+ * registerTestController(server, store);
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TestControllerError = void 0;
+exports.handleTestControllerRequest = handleTestControllerRequest;
+exports.registerTestController = registerTestController;
+const zod_1 = require("zod");
+const schemas_generated_1 = require("../types/schemas.generated");
+const responses_1 = require("./responses");
+// ────────────────────────────────────────────────────────────
+// Error class for sellers
+// ────────────────────────────────────────────────────────────
+/**
+ * Throw from TestControllerStore methods to return a typed controller error.
+ *
+ * @example
+ * ```typescript
+ * throw new TestControllerError('NOT_FOUND', `Account ${id} not found`);
+ * throw new TestControllerError('INVALID_TRANSITION', 'Cannot pause a completed buy', 'completed');
+ * ```
+ */
+class TestControllerError extends Error {
+    code;
+    currentState;
+    constructor(code, message, currentState) {
+        super(message);
+        this.code = code;
+        this.currentState = currentState;
+        this.name = 'TestControllerError';
+    }
+}
+exports.TestControllerError = TestControllerError;
+// ────────────────────────────────────────────────────────────
+// Request handler (exported for testing)
+// ────────────────────────────────────────────────────────────
+/** Map store method presence to scenario names. */
+const SCENARIO_MAP = [
+    ['forceCreativeStatus', 'force_creative_status'],
+    ['forceAccountStatus', 'force_account_status'],
+    ['forceMediaBuyStatus', 'force_media_buy_status'],
+    ['forceSessionStatus', 'force_session_status'],
+    ['simulateDelivery', 'simulate_delivery'],
+    ['simulateBudgetSpend', 'simulate_budget_spend'],
+];
+function listScenarios(store) {
+    return SCENARIO_MAP.filter(([method]) => typeof store[method] === 'function').map(([, scenario]) => scenario);
+}
+function controllerError(code, detail, currentState) {
+    return {
+        success: false,
+        error: code,
+        error_detail: detail,
+        ...(currentState !== undefined && { current_state: currentState }),
+    };
+}
+/**
+ * Handle a comply_test_controller request. Exported for unit testing.
+ */
+async function handleTestControllerRequest(store, input) {
+    const scenario = input.scenario;
+    if (!scenario) {
+        return controllerError('INVALID_PARAMS', 'Missing required field: scenario');
+    }
+    // list_scenarios — no params needed
+    if (scenario === 'list_scenarios') {
+        return { success: true, scenarios: listScenarios(store) };
+    }
+    const params = input.params;
+    try {
+        switch (scenario) {
+            case 'force_creative_status': {
+                if (!store.forceCreativeStatus) {
+                    return controllerError('UNKNOWN_SCENARIO', `Scenario not supported: ${scenario}`);
+                }
+                if (!params?.creative_id || !params?.status) {
+                    return controllerError('INVALID_PARAMS', 'force_creative_status requires params.creative_id and params.status');
+                }
+                const creativeStatus = schemas_generated_1.CreativeStatusSchema.safeParse(params.status);
+                if (!creativeStatus.success) {
+                    return controllerError('INVALID_PARAMS', `Invalid creative status: ${params.status}`);
+                }
+                return await store.forceCreativeStatus(params.creative_id, creativeStatus.data, params.rejection_reason);
+            }
+            case 'force_account_status': {
+                if (!store.forceAccountStatus) {
+                    return controllerError('UNKNOWN_SCENARIO', `Scenario not supported: ${scenario}`);
+                }
+                if (!params?.account_id || !params?.status) {
+                    return controllerError('INVALID_PARAMS', 'force_account_status requires params.account_id and params.status');
+                }
+                const accountStatus = schemas_generated_1.AccountStatusSchema.safeParse(params.status);
+                if (!accountStatus.success) {
+                    return controllerError('INVALID_PARAMS', `Invalid account status: ${params.status}`);
+                }
+                return await store.forceAccountStatus(params.account_id, accountStatus.data);
+            }
+            case 'force_media_buy_status': {
+                if (!store.forceMediaBuyStatus) {
+                    return controllerError('UNKNOWN_SCENARIO', `Scenario not supported: ${scenario}`);
+                }
+                if (!params?.media_buy_id || !params?.status) {
+                    return controllerError('INVALID_PARAMS', 'force_media_buy_status requires params.media_buy_id and params.status');
+                }
+                const mediaBuyStatus = schemas_generated_1.MediaBuyStatusSchema.safeParse(params.status);
+                if (!mediaBuyStatus.success) {
+                    return controllerError('INVALID_PARAMS', `Invalid media buy status: ${params.status}`);
+                }
+                return await store.forceMediaBuyStatus(params.media_buy_id, mediaBuyStatus.data, params.rejection_reason);
+            }
+            case 'force_session_status': {
+                if (!store.forceSessionStatus) {
+                    return controllerError('UNKNOWN_SCENARIO', `Scenario not supported: ${scenario}`);
+                }
+                if (!params?.session_id || !params?.status) {
+                    return controllerError('INVALID_PARAMS', 'force_session_status requires params.session_id and params.status');
+                }
+                const validSessionStatuses = ['complete', 'terminated'];
+                if (!validSessionStatuses.includes(params.status)) {
+                    return controllerError('INVALID_PARAMS', `Invalid session status: ${params.status}`);
+                }
+                return await store.forceSessionStatus(params.session_id, params.status, params.termination_reason);
+            }
+            case 'simulate_delivery': {
+                if (!store.simulateDelivery) {
+                    return controllerError('UNKNOWN_SCENARIO', `Scenario not supported: ${scenario}`);
+                }
+                if (!params?.media_buy_id) {
+                    return controllerError('INVALID_PARAMS', 'simulate_delivery requires params.media_buy_id');
+                }
+                return await store.simulateDelivery(params.media_buy_id, {
+                    impressions: params.impressions,
+                    clicks: params.clicks,
+                    reported_spend: params.reported_spend,
+                    conversions: params.conversions,
+                });
+            }
+            case 'simulate_budget_spend': {
+                if (!store.simulateBudgetSpend) {
+                    return controllerError('UNKNOWN_SCENARIO', `Scenario not supported: ${scenario}`);
+                }
+                if (params?.spend_percentage === undefined || params?.spend_percentage === null) {
+                    return controllerError('INVALID_PARAMS', 'simulate_budget_spend requires params.spend_percentage');
+                }
+                if (!params?.account_id && !params?.media_buy_id) {
+                    return controllerError('INVALID_PARAMS', 'simulate_budget_spend requires params.account_id or params.media_buy_id');
+                }
+                return await store.simulateBudgetSpend({
+                    account_id: params.account_id,
+                    media_buy_id: params.media_buy_id,
+                    spend_percentage: params.spend_percentage,
+                });
+            }
+            default:
+                return controllerError('UNKNOWN_SCENARIO', 'Unrecognized scenario name');
+        }
+    }
+    catch (err) {
+        if (err instanceof TestControllerError) {
+            return controllerError(err.code, err.message, err.currentState);
+        }
+        return controllerError('INTERNAL_ERROR', 'An unexpected error occurred in the test controller store');
+    }
+}
+// ────────────────────────────────────────────────────────────
+// MCP tool registration
+// ────────────────────────────────────────────────────────────
+function summarize(data) {
+    if (data.success === false)
+        return `Controller error: ${data.error}`;
+    if ('scenarios' in data)
+        return `Supported scenarios: ${data.scenarios.join(', ')}`;
+    if ('previous_state' in data)
+        return `Transitioned from ${data.previous_state} to ${data.current_state}`;
+    return `Simulation complete: ${JSON.stringify(data.simulated)}`;
+}
+function toMcpResponse(data) {
+    const isError = data.success === false;
+    return {
+        content: [{ type: 'text', text: summarize(data) }],
+        structuredContent: (0, responses_1.toStructuredContent)(data),
+        ...(isError && { isError: true }),
+    };
+}
+const TOOL_INPUT_SHAPE = {
+    scenario: zod_1.z.string().describe('Scenario to execute (e.g., list_scenarios, force_account_status)'),
+    params: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).optional().describe('Scenario-specific parameters'),
+    account: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).optional().describe('Account context for sandbox scoping'),
+    context: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).optional().describe('AdCP context object'),
+    ext: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).optional().describe('AdCP extension object'),
+};
+/**
+ * Register the comply_test_controller tool on an MCP server.
+ *
+ * The store determines which scenarios are supported. Unimplemented
+ * store methods are excluded from list_scenarios and return UNKNOWN_SCENARIO.
+ */
+function registerTestController(server, store) {
+    server.tool('comply_test_controller', 'Triggers seller-side state transitions for compliance testing. Sandbox only.', TOOL_INPUT_SHAPE, async (input) => {
+        const response = await handleTestControllerRequest(store, input);
+        return toMcpResponse(response);
+    });
+}
+//# sourceMappingURL=test-controller.js.map

package/dist/lib/server/test-controller.js.map

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