@absolutejs/mcp 0.3.0 → 0.4.1

package/README.md

@@ -177,11 +177,40 @@ spec also forbids eliciting **sensitive information**.
 **The trade-off, stated plainly.** Elicitation is the one MCP feature a
 stateless server cannot do: the question goes out on the SSE stream of an
 in-flight `tools/call`, and the client answers on a _separate_ HTTP POST. Two
-requests have to meet, so the pending call is remembered in-process and the
-endpoint becomes **session-stateful** (`Mcp-Session-Id`). Run one instance, or
-pin sessions. Leave `elicitation` off — the default — and nothing changes: the
-server stays stateless, `tools/call` keeps answering with a plain JSON body, and
-only tools marked `mayElicit` ever stream.
+requests have to meet, so the endpoint becomes **session-stateful**
+(`Mcp-Session-Id`). Leave `elicitation` off — the default — and nothing changes:
+the server stays stateless, `tools/call` keeps answering with a plain JSON body,
+and only tools marked `mayElicit` ever stream.
+
+**Running more than one instance.** Behind one server the defaults handle it.
+Behind several, two different things break, and each has a seam:
+
+```ts
+elicitation: {
+  enabled: true,
+  // (1) The client initializes on A and calls a tool on B, which has never
+  //     heard of the session. Put session state where every instance sees it.
+  //     It is an id and a boolean — nothing sensitive, nothing large.
+  store: {
+    create: ({ canElicit }) => db.insertSession(canElicit), // → id
+    get: (id) => db.findSession(id),                        // → { canElicit } | null
+    drop: (id) => db.deleteSession(id),
+  },
+  // (2) The tool call and its question live on ONE instance, but the user's
+  //     answer POST can land on any of them. A promise cannot move, so route
+  //     the answer to the instance that is waiting — over whatever fan-out you
+  //     already run (Postgres LISTEN/NOTIFY, Redis, …).
+  bus: {
+    publish: (answer) => notify("mcp_elicit", answer),
+    subscribe: (handler) => listen("mcp_elicit", handler),
+  },
+}
+```
+
+Supply neither and run a single instance (or pin sessions). Supply both and
+elicitation is safe behind a load balancer with **no sticky routing** — there is
+a test for exactly that: instance A asks, the answer lands on B, the bus carries
+it back, and A's call finishes.
 
 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

package/dist/index.js

@@ -345,7 +345,7 @@ var clientCanElicit = (params) => {
     return false;
   return isRecord(params.capabilities.elicitation);
 };
-var initialize = (config, id, params, context) => {
+var initialize = async (config, id, params, context) => {
   const supported = config.supportedProtocols ?? DEFAULT_PROTOCOLS;
   const capabilities = {
     tools: { listChanged: false }
@@ -363,7 +363,7 @@ var initialize = (config, id, params, context) => {
   });
   if (!config.elicitation?.enabled || !context.sessions)
     return response;
-  const sessionId = context.sessions.create(clientCanElicit(params));
+  const sessionId = await context.sessions.create(clientCanElicit(params));
   response.headers.set("Mcp-Session-Id", sessionId);
   return response;
 };
@@ -418,7 +418,7 @@ var runTool = async (config, caller, id, name, args, meta, tool, context) => {
     await config.onCall({ args, caller, meta, name, ok });
   return payload;
 };
-var toolsCallStreaming = (config, caller, id, name, args, meta, tool, sessions, sessionId, canElicit) => {
+var toolsCallStreaming = (config, caller, id, name, args, meta, tool, sessions, canElicit) => {
   const encoder = new TextEncoder;
   const body = new ReadableStream({
     async start(controller) {
@@ -437,9 +437,7 @@ var toolsCallStreaming = (config, caller, id, name, args, meta, tool, sessions,
         elicit: async (request) => {
           if (!canElicit)
             return { action: "unsupported" };
-          const pending = sessions.startElicit(sessionId, request);
-          if (!pending.id)
-            return { action: "cancel" };
+          const pending = sessions.startElicit(request);
           send({
             id: pending.id,
             jsonrpc: "2.0",
@@ -479,10 +477,10 @@ var toolsCall = async (config, caller, scopes, id, params, context) => {
   if (!tool || !scopeAllows(tool, scopes)) {
     return rpcError(id, JSONRPC_INVALID_PARAMS, `Unknown tool: ${name}`);
   }
-  const session = context.sessions?.get(context.sessionId ?? null);
-  const streaming = tool.mayElicit === true && config.elicitation?.enabled === true && context.sessions !== undefined && session !== null && session !== undefined && typeof context.sessionId === "string";
-  if (streaming && context.sessions && typeof context.sessionId === "string") {
-    return toolsCallStreaming(config, caller, id, name, args, meta, tool, context.sessions, context.sessionId, session?.canElicit === true);
+  const sessions = context.sessions;
+  const session = sessions ? await sessions.get(context.sessionId ?? null) : null;
+  if (tool.mayElicit === true && config.elicitation?.enabled === true && sessions && session) {
+    return toolsCallStreaming(config, caller, id, name, args, meta, tool, sessions, session.canElicit);
   }
   const payload = await runTool(config, caller, id, name, args, meta, tool, noElicit);
   return new Response(JSON.stringify(payload), {
@@ -559,7 +557,11 @@ var elicitAnswer = (message, context) => {
   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(context.sessionId ?? null, requestId, answer);
+  context.sessions.resolveElicit({
+    requestId,
+    result: answer,
+    sessionId: context.sessionId ?? null
+  });
   return notificationAck();
 };
 var dispatchMcp = async (config, caller, scopes, message, context = {}) => {
@@ -574,7 +576,7 @@ var dispatchMcp = async (config, caller, scopes, message, context = {}) => {
   const method = typeof message.method === "string" ? message.method : "";
   const { params } = message;
   if (method === "initialize") {
-    return initialize(config, id, params, context);
+    return await initialize(config, id, params, context);
   }
   if (method === "ping")
     return rpcResult(id, {});
@@ -694,9 +696,7 @@ var feedbackTools = (config) => ({
 var DEFAULT_SESSION_TTL_MS = 3600000;
 var DEFAULT_ELICIT_TIMEOUT_MS = 120000;
 var SWEEP_EVERY = 50;
-var createSessionRegistry = (options) => {
-  const ttlMs = options?.ttlMs ?? DEFAULT_SESSION_TTL_MS;
-  const elicitTimeoutMs = options?.elicitTimeoutMs ?? DEFAULT_ELICIT_TIMEOUT_MS;
+var createMemoryStore = (ttlMs) => {
   const sessions = new Map;
   let sinceSweep = 0;
   const sweep = () => {
@@ -706,66 +706,66 @@ var createSessionRegistry = (options) => {
     sinceSweep = 0;
     const cutoff = Date.now() - ttlMs;
     sessions.forEach((session, id) => {
-      if (session.lastSeen >= cutoff)
-        return;
-      session.pending.forEach((pending) => {
-        clearTimeout(pending.timer);
-        pending.resolve({ action: "cancel" });
-      });
-      sessions.delete(id);
+      if (session.lastSeen < cutoff)
+        sessions.delete(id);
     });
   };
-  const touch = (id) => {
-    if (!id)
-      return null;
-    const session = sessions.get(id);
-    if (!session)
-      return null;
-    session.lastSeen = Date.now();
-    return session;
-  };
   return {
-    create: (canElicit) => {
+    create: (session) => {
       sweep();
       const id = crypto.randomUUID();
-      sessions.set(id, { canElicit, lastSeen: Date.now(), pending: new Map });
+      sessions.set(id, { canElicit: session.canElicit, lastSeen: Date.now() });
       return id;
     },
     drop: (id) => {
-      const session = sessions.get(id);
-      session?.pending.forEach((pending) => {
-        clearTimeout(pending.timer);
-        pending.resolve({ action: "cancel" });
-      });
       sessions.delete(id);
     },
-    get: (id) => touch(id),
-    resolveElicit: (sessionId, requestId, result) => {
-      const session = touch(sessionId);
-      const pending = session?.pending.get(requestId);
-      if (!session || !pending)
-        return false;
-      clearTimeout(pending.timer);
-      session.pending.delete(requestId);
-      pending.resolve(result);
-      return true;
+    get: (id) => {
+      const session = sessions.get(id);
+      if (!session)
+        return null;
+      session.lastSeen = Date.now();
+      return { canElicit: session.canElicit };
+    }
+  };
+};
+var createSessionRegistry = (options) => {
+  const ttlMs = options?.ttlMs ?? DEFAULT_SESSION_TTL_MS;
+  const elicitTimeoutMs = options?.elicitTimeoutMs ?? DEFAULT_ELICIT_TIMEOUT_MS;
+  const store = options?.store ?? createMemoryStore(ttlMs);
+  const pending = new Map;
+  const resolveLocal = (answer) => {
+    const waiting = pending.get(answer.requestId);
+    if (!waiting)
+      return false;
+    clearTimeout(waiting.timer);
+    pending.delete(answer.requestId);
+    waiting.resolve(answer.result);
+    return true;
+  };
+  options?.bus?.subscribe((answer) => {
+    resolveLocal(answer);
+  });
+  return {
+    create: async (canElicit) => await store.create({ canElicit }),
+    drop: async (id) => {
+      await store.drop(id);
+    },
+    get: async (id) => id ? await store.get(id) : null,
+    resolveElicit: (answer) => {
+      if (resolveLocal(answer))
+        return true;
+      options?.bus?.publish(answer);
+      return false;
     },
-    startElicit: (sessionId, request) => {
-      const session = sessions.get(sessionId);
-      if (!session) {
-        return {
-          answer: Promise.resolve({ action: "cancel" }),
-          id: "",
-          request
-        };
-      }
+    startElicit: (request) => {
       const id = `elicit_${crypto.randomUUID()}`;
       const answer = new Promise((resolve) => {
         const timer = setTimeout(() => {
-          session.pending.delete(id);
+          pending.delete(id);
           resolve({ action: "cancel" });
         }, elicitTimeoutMs);
-        session.pending.set(id, { resolve, timer });
+        pending.set(id, { resolve, timer });
       });
       return { answer, id, request };
     }
@@ -787,6 +787,9 @@ var JSON_HEADERS = {
 };
 var HTTP_NOT_FOUND = 404;
 var registries = new WeakMap;
+var primeMcpSessions = (config) => {
+  registryFor(config);
+};
 var registryFor = (config) => {
   if (!config.elicitation?.enabled)
     return;
@@ -794,7 +797,9 @@ var registryFor = (config) => {
   if (existing)
     return existing;
   const created = createSessionRegistry({
-    elicitTimeoutMs: config.elicitation.timeoutMs
+    ...config.elicitation.bus === undefined ? {} : { bus: config.elicitation.bus },
+    ...config.elicitation.timeoutMs === undefined ? {} : { elicitTimeoutMs: config.elicitation.timeoutMs },
+    ...config.elicitation.store === undefined ? {} : { store: config.elicitation.store }
   });
   registries.set(config, created);
   return created;
@@ -817,7 +822,7 @@ var runMcpPost = async (config, request, body) => {
   }
   const sessions = registryFor(config);
   const sessionId = request.headers.get("mcp-session-id");
-  if (sessions && sessionId && !sessions.get(sessionId)) {
+  if (sessions && sessionId && !await sessions.get(sessionId)) {
     return new Response(null, { status: HTTP_NOT_FOUND });
   }
   return dispatchMcp(config, auth.caller, auth.scopes ?? [], body, {
@@ -825,13 +830,13 @@ var runMcpPost = async (config, request, body) => {
     sessions
   }).catch(() => rpcError(null, JSONRPC_INVALID_REQUEST, "Internal error"));
 };
-var runMcpDelete = (config, request) => {
+var runMcpDelete = async (config, request) => {
   const sessions = registryFor(config);
   const sessionId = request.headers.get("mcp-session-id");
   if (!sessions || !sessionId) {
     return new Response(null, { status: HTTP_METHOD_NOT_ALLOWED });
   }
-  sessions.drop(sessionId);
+  await sessions.drop(sessionId);
   return new Response(null, { status: HTTP_NO_CONTENT });
 };
 var handleMcpRequest = async (config, request) => {
@@ -861,11 +866,15 @@ var handleMcpRequest = async (config, request) => {
 };
 
 // src/handler.ts
-var createMcpHandler = (config) => (request) => handleMcpRequest(config, request);
+var createMcpHandler = (config) => {
+  primeMcpSessions(config);
+  return (request) => handleMcpRequest(config, request);
+};
 // src/server.ts
 import { Elysia } from "elysia";
 var mcpServer = (config) => {
   const metadataPath = metadataPathFor(config.path);
+  primeMcpSessions(config);
   const base = new Elysia().get(metadataPath, () => metadataResponse(config)).get(config.path, () => new Response(null, { status: HTTP_METHOD_NOT_ALLOWED })).post(config.path, ({ body, request }) => runMcpPost(config, request, body)).delete(config.path, ({ request }) => runMcpDelete(config, request));
   const app = config.serveRootMetadata ? base.get(ROOT_METADATA_PATH, () => metadataResponse(config)) : base;
   return app;

package/dist/src/core.d.ts

@@ -1,5 +1,10 @@
 import type { McpServerConfig } from "./types";
 export declare const ROOT_METADATA_PATH = "/.well-known/oauth-protected-resource";
+/** Build the session registry NOW rather than on the first request. The bus
+ *  subscription has to exist before any answer can arrive, and an instance that
+ *  has served no traffic yet is exactly the one a load balancer is about to
+ *  hand an answer to. */
+export declare const primeMcpSessions: <Caller>(config: McpServerConfig<Caller>) => void;
 export declare const metadataResponse: <Caller>(config: McpServerConfig<Caller>) => Response;
 /** Run one POST: authorize → validate the (already-decoded) body → dispatch.
  *  The body is passed in because Elysia pre-parses it while a raw handler must
@@ -8,7 +13,7 @@ export declare const runMcpPost: <Caller>(config: McpServerConfig<Caller>, reque
 /** The client is done with its session and says so (spec: Session Management).
  *  Only meaningful when elicitation put us in a session at all — otherwise 405,
  *  which the spec explicitly allows for servers that don't do sessions. */
-export declare const runMcpDelete: <Caller>(config: McpServerConfig<Caller>, request: Request) => Response;
+export declare const runMcpDelete: <Caller>(config: McpServerConfig<Caller>, request: Request) => Promise<Response>;
 /** The full path-aware handler over web-standard Request/Response. Returns a
  *  Response for any MCP route (POST endpoint, GET 405, discovery metadata) and
  *  `null` for anything else, so a host can compose it with its own routes. */

package/dist/src/sessions.d.ts

@@ -1,34 +1,25 @@
-import type { McpElicitResult, McpElicitationRequest } from "./types";
-type Pending = {
-    resolve: (result: McpElicitResult) => void;
-    timer: ReturnType<typeof setTimeout>;
-};
-type Session = {
-    /** The client declared the `elicitation` capability at initialize. */
-    canElicit: boolean;
-    lastSeen: number;
-    /** In-flight elicitations, keyed by the JSON-RPC id we sent. */
-    pending: Map<string, Pending>;
-};
+import type { McpElicitAnswer, McpElicitBus, McpElicitResult, McpElicitationRequest, McpSessionStore } from "./types";
 export type SessionRegistry = ReturnType<typeof createSessionRegistry>;
 export declare const createSessionRegistry: (options?: {
+    bus?: McpElicitBus;
     elicitTimeoutMs?: number;
+    store?: McpSessionStore;
     ttlMs?: number;
 }) => {
-    /** A new session, returned to the client as `Mcp-Session-Id`. */
-    create: (canElicit: boolean) => `${string}-${string}-${string}-${string}-${string}`;
-    drop: (id: string) => void;
-    get: (id: string | null) => Session | null;
-    /** The client answered one of our elicitation requests. Returns false when
-     *  the id is unknown (a stale answer, or a foreign session) — the caller
-     *  should still 202 it, per the transport rules. */
-    resolveElicit: (sessionId: string | null, requestId: string, result: McpElicitResult) => boolean;
-    /** Register an outbound elicitation and get back the id to send with it,
-     *  plus the promise that settles when the client answers (or gives up). */
-    startElicit: (sessionId: string, request: McpElicitationRequest) => {
+    create: (canElicit: boolean) => Promise<string>;
+    drop: (id: string) => Promise<void>;
+    get: (id: string | null) => Promise<{
+        canElicit: boolean;
+    } | null>;
+    /** 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;
+    /** 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) => {
         answer: Promise<McpElicitResult>;
         id: string;
         request: McpElicitationRequest;
     };
 };
-export {};

package/dist/src/types.d.ts

@@ -64,6 +64,36 @@ export type McpElicitResult = {
 } | {
     action: "unsupported";
 };
+/** The client's answer, on its way back to whichever instance is waiting. */
+export type McpElicitAnswer = {
+    requestId: string;
+    result: McpElicitResult;
+    sessionId: string | null;
+};
+/** Where session state lives. The default is in-memory (one instance). Put it
+ *  in your database and any instance can serve any session. Nothing here is
+ *  sensitive or large — an id and a capability flag. */
+export type McpSessionStore = {
+    create: (session: {
+        canElicit: boolean;
+    }) => Promise<string> | string;
+    drop: (id: string) => Promise<void> | void;
+    get: (id: string) => Promise<{
+        canElicit: boolean;
+    } | null> | {
+        canElicit: boolean;
+    } | null;
+};
+/** How an answer reaches the instance that asked the question. The tool call
+ *  and its pending promise live on ONE process; the client's answer POST can
+ *  land on any of them. Wire this to whatever fan-out you already run
+ *  (Postgres LISTEN/NOTIFY, Redis, …) and elicitation works with no sticky
+ *  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;
+};
 /** Passed to a tool handler as its second argument. Ignore it and nothing
  *  changes — every existing handler keeps working. */
 export type McpToolCallContext = {
@@ -181,7 +211,13 @@ export type McpServerConfig<Caller> = {
      *  remembered in-process. Run one instance, or pin `Mcp-Session-Id`. Tools
      *  must also opt in with `mayElicit`. */
     elicitation?: {
+        /** Route answers to the instance that asked. Required to run more than one
+         *  instance without sticky sessions. */
+        bus?: McpElicitBus;
         enabled: true;
+        /** Shared session state. Required to run more than one instance. */
+        store?: McpSessionStore;
+        /** How long a question waits for a human before it gives up (default 2m). */
         timeoutMs?: number;
     };
     /** Page size for tools/prompts/resources list pagination (default 50). */

package/package.json

@@ -37,5 +37,5 @@
     "typecheck": "tsc --noEmit --project tsconfig.json"
   },
   "types": "./dist/src/index.d.ts",
-  "version": "0.3.0"
+  "version": "0.4.1"
 }