@absolutejs/mcp 0.5.1 → 0.7.0

package/README.md

@@ -50,6 +50,13 @@ tasks: {
 }
 ```
 
+For multi-instance production deployments, use
+`createPostgresMcpTaskStore()` and `createPostgresMcpSessionStore()` after
+applying `mcpPostgresSchemaSql()`. Task updates and cancellation protect
+terminal states in the database, task reads enforce TTL, and session access
+atomically extends only unexpired sessions. The adapters accept a structural
+SQL client and do not require a particular PostgreSQL driver.
+
 Nothing here depends on a model. The tool shape is structurally compatible with
 [`@absolutejs/ai`](https://github.com/absolutejs/ai)'s `AIToolMap`, so an AI tool
 registry serves over MCP without conversion — but any typed tool registry works.
@@ -255,6 +262,32 @@ elicitation is safe behind a load balancer with **no sticky routing** — there
 a test for exactly that: instance A asks, the answer lands on B, the bus carries
 it back, and A's call finishes.
 
+AbsoluteJS already ships both production transports. PostgreSQL is the default;
+Redis is an optional at-most-once fan-out optimization:
+
+```ts
+import { createPostgresChannelBus } from "@absolutejs/sync-bus-pg";
+import type { McpElicitAnswer } from "@absolutejs/mcp";
+
+const bus = createPostgresChannelBus<McpElicitAnswer>({
+  sql,
+  channel: "absolutejs_mcp_elicitation",
+  spill: "always",
+});
+
+const config = {
+  // ...
+  elicitation: {
+    enabled: true,
+    store: createPostgresMcpSessionStore({ sql }),
+    bus,
+  },
+};
+```
+
+The channel is only coordination: durable jobs and side effects belong in
+`@absolutejs/queue` / `@absolutejs/execution`, not Redis pub/sub or NOTIFY.
+
 Consuming a server that elicits? Pass `onElicit` to `createMcpClient` — that is
 what declares the capability, and what the package uses to answer. Omit it and
 servers are told you cannot ask anyone.

package/dist/index.js

@@ -786,14 +786,14 @@ var resourcesRead = async (config, caller, id, params) => {
     ]
   });
 };
-var elicitAnswer = (message, context) => {
+var elicitAnswer = async (message, context) => {
   const requestId = typeof message.id === "string" ? message.id : null;
   if (!requestId || !context.sessions)
     return notificationAck();
   const result = isRecord(message.result) ? message.result : null;
   const action = result?.action;
   const answer = action === "accept" && isRecord(result?.content) ? { action: "accept", content: result.content } : action === "decline" ? { action: "decline" } : { action: "cancel" };
-  context.sessions.resolveElicit({
+  await context.sessions.resolveElicit({
     requestId,
     result: answer,
     sessionId: context.sessionId ?? null
@@ -984,6 +984,7 @@ var createSessionRegistry = (options) => {
   const elicitTimeoutMs = options?.elicitTimeoutMs ?? DEFAULT_ELICIT_TIMEOUT_MS;
   const store = options?.store ?? createMemoryStore(ttlMs);
   const pending = new Map;
+  let unsubscribe;
   const resolveLocal = (answer) => {
     const waiting = pending.get(answer.requestId);
     if (!waiting)
@@ -993,19 +994,39 @@ var createSessionRegistry = (options) => {
     waiting.resolve(answer.result);
     return true;
   };
-  options?.bus?.subscribe((answer) => {
+  const ready = options?.bus ? Promise.resolve(options.bus.subscribe((answer) => {
     resolveLocal(answer);
-  });
+  })).then((stop) => {
+    unsubscribe = stop;
+  }) : Promise.resolve();
   return {
-    create: async (canElicit) => await store.create({ canElicit }),
+    ready,
+    close: async () => {
+      await ready;
+      await unsubscribe?.();
+      pending.forEach(({ resolve, timer }) => {
+        clearTimeout(timer);
+        resolve({ action: "cancel" });
+      });
+      pending.clear();
+    },
+    create: async (canElicit) => {
+      await ready;
+      return await store.create({ canElicit });
+    },
     drop: async (id) => {
+      await ready;
       await store.drop(id);
     },
-    get: async (id) => id ? await store.get(id) : null,
-    resolveElicit: (answer) => {
+    get: async (id) => {
+      await ready;
+      return id ? await store.get(id) : null;
+    },
+    resolveElicit: async (answer) => {
+      await ready;
       if (resolveLocal(answer))
         return true;
-      options?.bus?.publish(answer);
+      await options?.bus?.publish(answer);
       return false;
     },
     startElicit: (request) => {
@@ -1129,15 +1150,121 @@ var mcpServer = (config) => {
   const app = config.serveRootMetadata ? base.get(ROOT_METADATA_PATH, () => metadataResponse(config)) : base;
   return app;
 };
+// src/postgres.ts
+var namespaceOf = (namespace) => {
+  if (!/^[a-z_][a-z0-9_]*$/.test(namespace))
+    throw new Error("MCP PostgreSQL namespace must be a simple identifier");
+  return namespace;
+};
+var mcpPostgresSchemaSql = (namespace = "mcp") => {
+  const ns = namespaceOf(namespace);
+  return `CREATE SCHEMA IF NOT EXISTS ${ns};
+CREATE TABLE IF NOT EXISTS ${ns}.tasks (
+  task_id text PRIMARY KEY,
+  authorization_key text NOT NULL,
+  status text NOT NULL CHECK (status IN ('working','input_required','completed','failed','cancelled')),
+  created_at timestamptz NOT NULL,
+  updated_at timestamptz NOT NULL,
+  expires_at timestamptz,
+  data jsonb NOT NULL
+);
+CREATE INDEX IF NOT EXISTS tasks_authorization_updated_idx ON ${ns}.tasks (authorization_key, updated_at DESC);
+CREATE INDEX IF NOT EXISTS tasks_expiry_idx ON ${ns}.tasks (expires_at) WHERE expires_at IS NOT NULL;
+CREATE TABLE IF NOT EXISTS ${ns}.sessions (
+  session_id text PRIMARY KEY,
+  can_elicit boolean NOT NULL,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  last_seen_at timestamptz NOT NULL DEFAULT now(),
+  expires_at timestamptz NOT NULL
+);
+CREATE INDEX IF NOT EXISTS sessions_expiry_idx ON ${ns}.sessions (expires_at);`;
+};
+var createPostgresMcpTaskStore = ({
+  client,
+  namespace = "mcp",
+  now = () => new Date
+}) => {
+  const ns = namespaceOf(namespace);
+  return {
+    cancel: async (taskId) => {
+      const updatedAt = now().toISOString();
+      await client.query(`UPDATE ${ns}.tasks SET status = 'cancelled', updated_at = $2::timestamptz, data = data || $3::jsonb WHERE task_id = $1 AND status NOT IN ('cancelled','completed','failed')`, [
+        taskId,
+        updatedAt,
+        JSON.stringify({ lastUpdatedAt: updatedAt, status: "cancelled" })
+      ]);
+    },
+    get: async (taskId) => (await client.query(`SELECT data FROM ${ns}.tasks WHERE task_id = $1 AND (expires_at IS NULL OR expires_at > $2::timestamptz)`, [taskId, now().toISOString()])).rows[0]?.data ?? null,
+    save: async (task) => {
+      const expiresAt = task.ttlMs === null ? null : new Date(new Date(task.createdAt).getTime() + task.ttlMs).toISOString();
+      await client.query(`INSERT INTO ${ns}.tasks (task_id, authorization_key, status, created_at, updated_at, expires_at, data) VALUES ($1, $2, $3, $4::timestamptz, $5::timestamptz, $6::timestamptz, $7::jsonb) ON CONFLICT (task_id) DO NOTHING`, [
+        task.taskId,
+        task.authorizationKey,
+        task.status,
+        task.createdAt,
+        task.lastUpdatedAt,
+        expiresAt,
+        JSON.stringify(task)
+      ]);
+    },
+    update: async (taskId, update) => {
+      const updatedAt = now().toISOString();
+      const data = { ...update, lastUpdatedAt: updatedAt };
+      const result = await client.query(`UPDATE ${ns}.tasks SET status = COALESCE($2::text, status), updated_at = $3::timestamptz, data = data || $4::jsonb WHERE task_id = $1 AND status NOT IN ('cancelled','completed','failed') RETURNING data`, [taskId, update.status ?? null, updatedAt, JSON.stringify(data)]);
+      if (result.rows[0] !== undefined)
+        return result.rows[0].data;
+      return (await client.query(`SELECT data FROM ${ns}.tasks WHERE task_id = $1`, [taskId])).rows[0]?.data ?? null;
+    }
+  };
+};
+var createPostgresMcpSessionStore = ({
+  client,
+  namespace = "mcp",
+  now = () => new Date,
+  ttlMs = 3600000
+}) => {
+  const ns = namespaceOf(namespace);
+  return {
+    create: async ({ canElicit }) => {
+      const id = crypto.randomUUID();
+      const current = now();
+      await client.query(`INSERT INTO ${ns}.sessions (session_id, can_elicit, created_at, last_seen_at, expires_at) VALUES ($1, $2, $3::timestamptz, $3::timestamptz, $4::timestamptz)`, [
+        id,
+        canElicit,
+        current.toISOString(),
+        new Date(current.getTime() + ttlMs).toISOString()
+      ]);
+      return id;
+    },
+    drop: async (id) => {
+      await client.query(`DELETE FROM ${ns}.sessions WHERE session_id = $1`, [
+        id
+      ]);
+    },
+    get: async (id) => {
+      const current = now();
+      const result = await client.query(`UPDATE ${ns}.sessions SET last_seen_at = $2::timestamptz, expires_at = $3::timestamptz WHERE session_id = $1 AND expires_at > $2::timestamptz RETURNING can_elicit`, [
+        id,
+        current.toISOString(),
+        new Date(current.getTime() + ttlMs).toISOString()
+      ]);
+      const row = result.rows[0];
+      return row === undefined ? null : { canElicit: row.can_elicit };
+    }
+  };
+};
 export {
   verifyBearer,
   publicMcpTask,
   protectedResourceMetadata,
   metadataPathFor,
   mcpServer,
+  mcpPostgresSchemaSql,
   feedbackTools,
   dispatchMcp,
   createSessionRegistry,
+  createPostgresMcpTaskStore,
+  createPostgresMcpSessionStore,
   createMemoryMcpTaskStore,
   createMcpHandler,
   createMcpClient,

package/dist/src/index.d.ts

@@ -39,4 +39,5 @@ export { metadataPathFor, protectedResourceMetadata, type ProtectedResourceMetad
 export { mcpServer } from "./server";
 export { createSessionRegistry, type SessionRegistry } from "./sessions";
 export { createMemoryMcpTaskStore, publicMcpTask } from "./tasks";
+export { createPostgresMcpSessionStore, createPostgresMcpTaskStore, mcpPostgresSchemaSql, type McpSqlClient, type McpSqlResult, } from "./postgres";
 export type { McpAgencyOptions, McpAudioContent, McpElicitAnswer, McpElicitationRequest, McpElicitBus, McpElicitResult, McpSessionStore, McpAuthResult, McpCallGate, McpCallMeta, McpContent, McpImageContent, McpPromptArgument, McpPromptDefinition, McpPrompts, McpResource, McpResourceLink, McpResources, McpServerConfig, McpServerInfo, McpTextContent, McpTask, McpTaskStatus, McpTaskStore, McpTasksOptions, McpTool, McpToolAnnotations, McpToolCallContext, McpToolContext, McpToolRegistry, McpToolResult, McpToolReturn, } from "./types";

package/dist/src/postgres.d.ts

@@ -0,0 +1,20 @@
+import type { McpSessionStore, McpTaskStore } from "./types";
+export type McpSqlResult<Row> = {
+    rowCount: number;
+    rows: ReadonlyArray<Row>;
+};
+export type McpSqlClient = {
+    query: <Row = Record<string, unknown>>(sql: string, parameters?: ReadonlyArray<unknown>) => Promise<McpSqlResult<Row>>;
+};
+export declare const mcpPostgresSchemaSql: (namespace?: string) => string;
+export declare const createPostgresMcpTaskStore: ({ client, namespace, now, }: {
+    client: McpSqlClient;
+    namespace?: string;
+    now?: () => Date;
+}) => McpTaskStore;
+export declare const createPostgresMcpSessionStore: ({ client, namespace, now, ttlMs, }: {
+    client: McpSqlClient;
+    namespace?: string;
+    now?: () => Date;
+    ttlMs?: number;
+}) => McpSessionStore;

package/dist/src/sessions.d.ts

@@ -6,6 +6,8 @@ export declare const createSessionRegistry: (options?: {
     store?: McpSessionStore;
     ttlMs?: number;
 }) => {
+    ready: Promise<void>;
+    close: () => Promise<void>;
     create: (canElicit: boolean) => Promise<string>;
     drop: (id: string) => Promise<void>;
     get: (id: string | null) => Promise<{
@@ -14,7 +16,7 @@ export declare const createSessionRegistry: (options?: {
     /** The client answered. If the call that asked is running HERE, resolve it.
      *  If not, put the answer on the bus so the instance that is waiting can —
      *  the answer must find the promise, and the promise cannot move. */
-    resolveElicit: (answer: McpElicitAnswer) => boolean;
+    resolveElicit: (answer: McpElicitAnswer) => Promise<boolean>;
     /** Register an outbound question. Returns the id to send it under and the
      *  promise that settles when the user answers — or when they never do. */
     startElicit: (request: McpElicitationRequest) => {

package/dist/src/types.d.ts

@@ -93,8 +93,8 @@ export type McpSessionStore = {
  *  routing. Omit it and you must run a single instance (or pin sessions). */
 export type McpElicitBus = {
     /** An answer nobody here was waiting for — someone else might be. */
-    publish: (answer: McpElicitAnswer) => void;
-    subscribe: (handler: (answer: McpElicitAnswer) => void) => void;
+    publish: (answer: McpElicitAnswer) => void | Promise<void>;
+    subscribe: (handler: (answer: McpElicitAnswer) => void) => void | (() => void | Promise<void>) | Promise<void | (() => void | Promise<void>)>;
 };
 /** Passed to a tool handler as its second argument. Ignore it and nothing
  *  changes — every existing handler keeps working. */

package/package.json

@@ -11,7 +11,7 @@
     "elysia": ">=1.1.0"
   },
   "dependencies": {
-    "@absolutejs/agency": "^0.2.0",
+    "@absolutejs/agency": "^0.3.0",
     "@absolutejs/manifest": "^0.2.0",
     "@sinclair/typebox": "^0.34.0"
   },
@@ -58,5 +58,5 @@
     "typecheck": "tsc --noEmit --project tsconfig.json"
   },
   "types": "./dist/src/index.d.ts",
-  "version": "0.5.1"
+  "version": "0.7.0"
 }