@adcp/sdk API Reference - v14.0.0-beta.6
    Preparing search index...

    Class PostgresTaskStore

    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.

    Implements

    Index

    Constructors

    constructor

    Methods

    createTask getTask storeTaskResult getTaskResult updateTaskStatus listTasks cleanupExpired cleanup

    Constructors

    Methods

    • Create a new task. Pass taskParams.taskId to use a caller-supplied ID verbatim (useful for compliance-controller scenarios where the runner needs deterministic task IDs). If omitted, a random hex ID is generated. Throws if the supplied ID is empty / longer than 128 chars, or already exists. The 128-char ceiling is an SDK policy (matches typical request-id / session-id field lengths and keeps the task_id index efficient) — Postgres TEXT itself imposes no limit.

      Task IDs remain globally unique, as required by MCP. When a session ID is supplied it is recorded as the task owner and enforced on session-bound reads and writes. Calls that omit sessionId address a task by its cryptographically random ID; this privileged/capability path is required by MCP background workers, which receive only the task ID. Caller-supplied IDs used without a session must therefore be unguessable.

      Parameters

      • taskParams: CreateTaskOptions & { taskId?: string }
      • requestId: RequestId
      • request: {
            method: string;
            params?: {
                _meta?: {
                    progressToken?: string | number;
                    "io.modelcontextprotocol/related-task"?: { taskId: string };
                    [key: string]: unknown;
                };
                [key: string]: unknown;
            };
        }
      • OptionalsessionId: string

      Returns Promise<
          {
              taskId: string;
              status: | "failed"
              | "completed"
              | "cancelled"
              | "working"
              | "input_required";
              ttl: number
              | null;
              createdAt: string;
              lastUpdatedAt: string;
              pollInterval?: number;
              statusMessage?: string;
          },
      >

    • Gets the current status of a task.

      Parameters

      • taskId: string

        The task identifier

      • OptionalsessionId: string

        Optional session ID for binding the query to a specific session

      Returns Promise<
          | {
              taskId: string;
              status: | "failed"
              | "completed"
              | "cancelled"
              | "working"
              | "input_required";
              ttl: number
              | null;
              createdAt: string;
              lastUpdatedAt: string;
              pollInterval?: number;
              statusMessage?: string;
          }
          | null,
      >

      The task object, or null if it does not exist

    • Stores the result of a task and sets its final status.

      Parameters

      • taskId: string

        The task identifier

      • status: "failed" | "completed"

        The final status: 'completed' for success, 'failed' for errors

      • result: {
            _meta?: {
                progressToken?: string | number;
                "io.modelcontextprotocol/related-task"?: { taskId: string };
                [key: string]: unknown;
            };
            [key: string]: unknown;
        }

        The result to store

        • [key: string]: unknown
        • Optional_meta?: {
              progressToken?: string | number;
              "io.modelcontextprotocol/related-task"?: { taskId: string };
              [key: string]: unknown;
          }

          See MCP specification for notes on _meta usage.

          • OptionalprogressToken?: string | number

            If specified, the caller is requesting out-of-band progress notifications for this request (as represented by notifications/progress). The value of this parameter is an opaque token that will be attached to any subsequent notifications. The receiver is not obligated to provide these notifications.

          • Optionalio.modelcontextprotocol/related-task?: { taskId: string }

            If specified, this request is related to the provided task.

      • OptionalsessionId: string

        Optional session ID for binding the operation to a specific session

      Returns Promise<void>

    • Retrieves the stored result of a task.

      Parameters

      • taskId: string

        The task identifier

      • OptionalsessionId: string

        Optional session ID for binding the query to a specific session

      Returns Promise<
          {
              _meta?: {
                  progressToken?: string
                  | number;
                  "io.modelcontextprotocol/related-task"?: { taskId: string };
                  [key: string]: unknown;
              };
              [key: string]: unknown;
          },
      >

      The stored result

    • Updates a task's status (e.g., to 'cancelled', 'failed', 'completed').

      Parameters

      • taskId: string

        The task identifier

      • status: "failed" | "completed" | "cancelled" | "working" | "input_required"

        The new status

      • OptionalstatusMessage: string

        Optional diagnostic message for failed tasks or other status information

      • OptionalsessionId: string

        Optional session ID for binding the operation to a specific session

      Returns Promise<void>

    • Lists tasks, optionally starting from a pagination cursor.

      Parameters

      • Optionalcursor: string

        Optional cursor for pagination

      • OptionalsessionId: string

        Optional session ID for binding the query to a specific session

      Returns Promise<
          {
              tasks: {
                  taskId: string;
                  status: | "failed"
                  | "completed"
                  | "cancelled"
                  | "working"
                  | "input_required";
                  ttl: number
                  | null;
                  createdAt: string;
                  lastUpdatedAt: string;
                  pollInterval?: number;
                  statusMessage?: string;
              }[];
              nextCursor?: string;
          },
      >

      An object containing the tasks array and an optional 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 Promise<number>

      The number of deleted rows.

    • No-op — PostgresTaskStore has no timers or background processes. Matches the cleanup() method that InMemoryTaskStore exposes.

      Returns void

    Settings

    Member Visibility

    On This Page

    Constructors
    Methods