@absolutejs/mcp 0.2.0 → 0.4.0

package/README.md

@@ -107,6 +107,86 @@ onCall: ({ meta, name, ok }) =>
   ledger.write({ tool: name, ok, member: meta.touched }),
 ```
 
+## Feedback: the channel a client can't give you
+
+A connected AI client renders no UI for your server. There is no button for the
+user to press, so when they say _"that was wrong"_ the only path back to you is
+the model relaying it. Every MCP server has this hole, and every one of them
+hand-rolls the same two tools.
+
+```ts
+import { feedbackTools, FEEDBACK_INSTRUCTIONS } from "@absolutejs/mcp";
+
+mcpServer<Caller>({
+  instructions: `${myInstructions} ${FEEDBACK_INSTRUCTIONS}`,
+  tools: ({ caller }) => ({
+    ...myTools(caller),
+    ...feedbackTools({
+      caller,
+      store: {
+        reportProblem: ({ caller, report }) => file(caller, report), // → "Filed as #42."
+        submitFeedback: ({ caller, feedback }) => record(caller, feedback),
+      },
+    }),
+  }),
+});
+```
+
+`FEEDBACK_INSTRUCTIONS` is the load-bearing half. Without it a model treats a
+complaint as something to apologise for, and the signal dies where it was
+spoken.
+
+## Elicitation: ask the user a question mid-call
+
+A tool that can't finish without something only the user knows can **ask them**
+(`elicitation/create`) and wait for the answer.
+
+```ts
+mcpServer<Caller>({
+  elicitation: { enabled: true },
+  tools: () => ({
+    book_table: {
+      description: "Book a table.",
+      inputSchema: { type: "object" },
+      mayElicit: true, // opt in: this tool may ask
+      handler: async (args, { canElicit, elicit }) => {
+        if (!canElicit) return "Tell me the party size and I'll book it.";
+        const answer = await elicit({
+          message: "How many people?",
+          requestedSchema: {
+            type: "object",
+            properties: { people: { type: "integer", minimum: 1 } },
+            required: ["people"],
+          },
+        });
+        if (answer.action !== "accept") return "No problem — cancelled.";
+        return `Booked for ${answer.content.people}.`;
+      },
+    },
+  }),
+});
+```
+
+`requestedSchema` is a **flat object of primitives** (string / number / integer
+/ boolean / enum) — the spec restricts it so any client can render a form. The
+answer is `accept` (with `content`), `decline` (they said no), `cancel` (they
+dismissed it), or `unsupported` (this client can't ask anyone — check
+`canElicit` and take another path). Never fabricate an answer for the user; the
+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.
+
+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.
+
 ## A second, stricter endpoint
 
 `mcpServer` is per-endpoint, so an admin console is the same call with a

package/dist/index.js

@@ -65,6 +65,50 @@ var parseBody = async (response, maxBytes) => {
   }
   throw new McpClientError("No JSON-RPC response in the event stream");
 };
+var consumeSseStream = async (response, maxBytes, onRequest) => {
+  const reader = response.body?.getReader();
+  if (!reader)
+    throw new McpClientError("The event stream had no body");
+  const decoder = new TextDecoder;
+  let buffer = "";
+  let seen = 0;
+  for (;; ) {
+    const { done, value } = await reader.read();
+    if (done)
+      break;
+    seen += value?.length ?? 0;
+    if (maxBytes > 0 && seen > maxBytes) {
+      await reader.cancel().catch(() => {
+        return;
+      });
+      throw new McpClientError("Response exceeded the size cap");
+    }
+    buffer += decoder.decode(value, { stream: true });
+    const frames = buffer.split(`
+
+`);
+    buffer = frames.pop() ?? "";
+    for (const frame of frames) {
+      const line = frame.split(/\r?\n/).find((entry) => entry.startsWith("data:"));
+      if (!line)
+        continue;
+      const parsed = JSON.parse(line.slice("data:".length).trim());
+      if (!isRecord(parsed))
+        continue;
+      if (typeof parsed.method === "string") {
+        await onRequest(parsed);
+        continue;
+      }
+      if ("result" in parsed || "error" in parsed) {
+        await reader.cancel().catch(() => {
+          return;
+        });
+        return parsed;
+      }
+    }
+  }
+  throw new McpClientError("No JSON-RPC response in the event stream");
+};
 var createMcpClient = (options) => {
   const doFetch = options.request ?? fetch;
   const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
@@ -72,6 +116,32 @@ var createMcpClient = (options) => {
   let protocolVersion = options.protocolVersion ?? DEFAULT_PROTOCOL;
   let sessionId = null;
   let nextId = 1;
+  const respond = async (id, result) => {
+    const headers = {
+      "content-type": "application/json",
+      "mcp-protocol-version": protocolVersion,
+      ...options.headers
+    };
+    if (sessionId !== null)
+      headers["mcp-session-id"] = sessionId;
+    await doFetch(options.url, {
+      body: JSON.stringify({ id, jsonrpc: "2.0", result }),
+      headers,
+      method: "POST"
+    }).catch(() => {
+      return;
+    });
+  };
+  const answerServer = async (message) => {
+    if (message.method !== "elicitation/create")
+      return;
+    const request = isRecord(message.params) ? {
+      message: typeof message.params.message === "string" ? message.params.message : "",
+      requestedSchema: isRecord(message.params.requestedSchema) ? message.params.requestedSchema : {}
+    } : { message: "", requestedSchema: {} };
+    const result = options.onElicit ? await options.onElicit(request) : { action: "decline" };
+    await respond(message.id, result);
+  };
   const rpc = async (method, params) => {
     const controller = new AbortController;
     const timer = setTimeout(() => {
@@ -105,7 +175,8 @@ var createMcpClient = (options) => {
           status: 401
         });
       }
-      const payload = await parseBody(response, maxBytes);
+      const isStream = (response.headers.get("content-type") ?? "").includes("text/event-stream");
+      const payload = isStream ? await consumeSseStream(response, maxBytes, answerServer) : await parseBody(response, maxBytes);
       if (!isRecord(payload)) {
         throw new McpClientError("Malformed JSON-RPC response");
       }
@@ -137,7 +208,7 @@ var createMcpClient = (options) => {
   };
   const initialize = async () => {
     const result = await rpc("initialize", {
-      capabilities: {},
+      capabilities: options.onElicit ? { elicitation: {} } : {},
       clientInfo: options.clientInfo ?? {
         name: "@absolutejs/mcp",
         version: "0"
@@ -206,6 +277,7 @@ var JSONRPC_METHOD_NOT_FOUND = -32601;
 var JSONRPC_INVALID_PARAMS = -32602;
 var JSONRPC_INTERNAL_ERROR = -32603;
 var HTTP_ACCEPTED = 202;
+var HTTP_NO_CONTENT = 204;
 var HTTP_UNAUTHORIZED = 401;
 var HTTP_METHOD_NOT_ALLOWED = 405;
 var jsonHeaders = {
@@ -268,7 +340,12 @@ var normalizeResult = (value) => {
     return { content: value, isError: false };
   return { isError: false, ...value };
 };
-var initialize = (config, id, params) => {
+var clientCanElicit = (params) => {
+  if (!isRecord(params) || !isRecord(params.capabilities))
+    return false;
+  return isRecord(params.capabilities.elicitation);
+};
+var initialize = async (config, id, params, context) => {
   const supported = config.supportedProtocols ?? DEFAULT_PROTOCOLS;
   const capabilities = {
     tools: { listChanged: false }
@@ -278,12 +355,17 @@ var initialize = (config, id, params) => {
   if (config.resources) {
     capabilities.resources = { listChanged: false, subscribe: false };
   }
-  return rpcResult(id, {
+  const response = rpcResult(id, {
     capabilities,
     ...config.instructions === undefined ? {} : { instructions: config.instructions },
     protocolVersion: negotiateProtocol(supported, params),
     serverInfo: config.serverInfo
   });
+  if (!config.elicitation?.enabled || !context.sessions)
+    return response;
+  const sessionId = await context.sessions.create(clientCanElicit(params));
+  response.headers.set("Mcp-Session-Id", sessionId);
+  return response;
 };
 var toolsList = async (config, caller, scopes, id, params) => {
   const tools = await config.tools({ caller, meta: {} });
@@ -301,7 +383,84 @@ var toolsList = async (config, caller, scopes, id, params) => {
   });
 };
 var errorResult = (id, text) => rpcResult(id, { content: [{ text, type: "text" }], isError: true });
-var toolsCall = async (config, caller, scopes, id, params) => {
+var noElicit = {
+  canElicit: false,
+  elicit: () => Promise.resolve({ action: "unsupported" })
+};
+var SSE_HEADERS = {
+  "cache-control": "no-cache",
+  connection: "keep-alive",
+  "content-type": "text/event-stream",
+  "x-accel-buffering": "no"
+};
+var sseFrame = (message) => `data: ${JSON.stringify(message)}
+
+`;
+var runTool = async (config, caller, id, name, args, meta, tool, context) => {
+  let ok = false;
+  let payload;
+  try {
+    const result = normalizeResult(await tool.handler(args, context));
+    ok = result.isError !== true;
+    payload = { id, jsonrpc: "2.0", result };
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : "unknown error";
+    payload = {
+      id,
+      jsonrpc: "2.0",
+      result: {
+        content: [{ text: `Tool failed: ${detail}`, type: "text" }],
+        isError: true
+      }
+    };
+  }
+  if (config.onCall)
+    await config.onCall({ args, caller, meta, name, ok });
+  return payload;
+};
+var toolsCallStreaming = (config, caller, id, name, args, meta, tool, sessions, canElicit) => {
+  const encoder = new TextEncoder;
+  const body = new ReadableStream({
+    async start(controller) {
+      let open = true;
+      const send = (message) => {
+        if (!open)
+          return;
+        try {
+          controller.enqueue(encoder.encode(sseFrame(message)));
+        } catch {
+          open = false;
+        }
+      };
+      const context = {
+        canElicit,
+        elicit: async (request) => {
+          if (!canElicit)
+            return { action: "unsupported" };
+          const pending = sessions.startElicit(request);
+          send({
+            id: pending.id,
+            jsonrpc: "2.0",
+            method: "elicitation/create",
+            params: request
+          });
+          return await pending.answer;
+        }
+      };
+      const payload = await runTool(config, caller, id, name, args, meta, tool, context);
+      send(payload);
+      if (open) {
+        try {
+          controller.close();
+        } catch {
+          open = false;
+        }
+      }
+    }
+  });
+  return new Response(body, { headers: SSE_HEADERS });
+};
+var toolsCall = async (config, caller, scopes, id, params, context) => {
   if (!isRecord(params) || typeof params.name !== "string") {
     return rpcError(id, JSONRPC_INVALID_PARAMS, "tools/call needs a name");
   }
@@ -318,19 +477,15 @@ var toolsCall = async (config, caller, scopes, id, params) => {
   if (!tool || !scopeAllows(tool, scopes)) {
     return rpcError(id, JSONRPC_INVALID_PARAMS, `Unknown tool: ${name}`);
   }
-  let ok = false;
-  let response;
-  try {
-    const result = normalizeResult(await tool.handler(args));
-    ok = result.isError !== true;
-    response = rpcResult(id, result);
-  } catch (error) {
-    const detail = error instanceof Error ? error.message : "unknown error";
-    response = errorResult(id, `Tool failed: ${detail}`);
+  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);
   }
-  if (config.onCall)
-    await config.onCall({ args, caller, meta, name, ok });
-  return response;
+  const payload = await runTool(config, caller, id, name, args, meta, tool, noElicit);
+  return new Response(JSON.stringify(payload), {
+    headers: { "content-type": "application/json" }
+  });
 };
 var promptsList = (config, id, params) => {
   const definitions = config.prompts?.definitions ?? {};
@@ -395,24 +550,41 @@ var resourcesRead = async (config, caller, id, params) => {
     ]
   });
 };
-var dispatchMcp = async (config, caller, scopes, message) => {
+var elicitAnswer = (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({
+    requestId,
+    result: answer,
+    sessionId: context.sessionId ?? null
+  });
+  return notificationAck();
+};
+var dispatchMcp = async (config, caller, scopes, message, context = {}) => {
   if (!isRecord(message) || message.jsonrpc !== "2.0") {
     return rpcError(null, JSONRPC_INVALID_REQUEST, "Not a JSON-RPC 2.0 message");
   }
   if (!("id" in message))
     return notificationAck();
+  if (!("method" in message))
+    return elicitAnswer(message, context);
   const id = idOf(message);
   const method = typeof message.method === "string" ? message.method : "";
   const { params } = message;
-  if (method === "initialize")
-    return initialize(config, id, params);
+  if (method === "initialize") {
+    return await initialize(config, id, params, context);
+  }
   if (method === "ping")
     return rpcResult(id, {});
   if (method === "tools/list") {
     return toolsList(config, caller, scopes, id, params);
   }
   if (method === "tools/call") {
-    return toolsCall(config, caller, scopes, id, params);
+    return toolsCall(config, caller, scopes, id, params, context);
   }
   if (method === "prompts/list")
     return promptsList(config, id, params);
@@ -426,6 +598,180 @@ var dispatchMcp = async (config, caller, scopes, message) => {
   }
   return rpcError(id, JSONRPC_METHOD_NOT_FOUND, `Unknown method: ${method}`);
 };
+// src/feedback.ts
+var FEEDBACK_INSTRUCTIONS = "FEEDBACK: you are the user's only channel back to this server's team \u2014 there are no buttons in this client. If the user says something was wrong, unhelpful, or not what they asked for, call submit_feedback with their reason in their own words; if something is outright broken, call report_problem. Do this INSTEAD of only apologising, and tell them you've passed it on. Log the good as well as the bad.";
+var asText = (input, key) => {
+  if (typeof input !== "object" || input === null)
+    return;
+  const value = Reflect.get(input, key);
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+};
+var isRating = (value) => value === "good" || value === "bad";
+var feedbackTools = (config) => ({
+  report_problem: {
+    annotations: {
+      destructiveHint: false,
+      openWorldHint: false,
+      readOnlyHint: false,
+      title: "Report a problem"
+    },
+    description: "Report a bug or broken behaviour on the user's behalf. Use when the user says something is broken, wrong, or not working \u2014 confirm the details with them first, then file it. Reports as THIS user's account.",
+    handler: async (args) => {
+      const problem = asText(args, "problem");
+      if (!problem)
+        return "Tell me what's broken and I'll report it.";
+      const reply = await config.store.reportProblem({
+        caller: config.caller,
+        report: {
+          expected: asText(args, "expected"),
+          problem,
+          steps: asText(args, "steps"),
+          where: asText(args, "where")
+        }
+      });
+      return reply ?? "Reported. Tell the user it's been filed with the team.";
+    },
+    inputSchema: {
+      properties: {
+        expected: {
+          description: "What the user expected to happen",
+          type: "string"
+        },
+        problem: {
+          description: "What is broken, in the user's words \u2014 one sentence",
+          type: "string"
+        },
+        steps: { description: "How to reproduce it", type: "string" },
+        where: {
+          description: "Where it happened (page, feature, or tool)",
+          type: "string"
+        }
+      },
+      required: ["problem"],
+      type: "object"
+    }
+  },
+  submit_feedback: {
+    annotations: {
+      destructiveHint: false,
+      openWorldHint: false,
+      readOnlyHint: false,
+      title: "Pass on feedback"
+    },
+    description: "Record the user's verdict on how this is going \u2014 call whenever they say a result was wrong, unhelpful, or missed what they asked for (rating 'bad'), or that something worked well (rating 'good'). Pass their reason in their OWN words. This is the only way feedback from this client reaches the team, so use it rather than only apologising.",
+    handler: async (args) => {
+      const rating = Reflect.get(args ?? {}, "rating");
+      const reason = asText(args, "reason");
+      if (!isRating(rating) || !reason) {
+        return "Provide the rating ('good' or 'bad') and the user's reason.";
+      }
+      const reply = await config.store.submitFeedback({
+        caller: config.caller,
+        feedback: { rating, reason, tool: asText(args, "tool") }
+      });
+      return reply ?? (rating === "bad" ? "Passed on to the team, with the user's reason attached." : "Logged as positive feedback.");
+    },
+    inputSchema: {
+      properties: {
+        rating: {
+          description: "'good' or 'bad'",
+          enum: ["good", "bad"],
+          type: "string"
+        },
+        reason: {
+          description: "What was wrong (or right), in the user's own words",
+          type: "string"
+        },
+        tool: {
+          description: "The tool this is about, if it was about one",
+          type: "string"
+        }
+      },
+      required: ["rating", "reason"],
+      type: "object"
+    }
+  }
+});
+// src/sessions.ts
+var DEFAULT_SESSION_TTL_MS = 3600000;
+var DEFAULT_ELICIT_TIMEOUT_MS = 120000;
+var SWEEP_EVERY = 50;
+var createMemoryStore = (ttlMs) => {
+  const sessions = new Map;
+  let sinceSweep = 0;
+  const sweep = () => {
+    sinceSweep += 1;
+    if (sinceSweep < SWEEP_EVERY)
+      return;
+    sinceSweep = 0;
+    const cutoff = Date.now() - ttlMs;
+    sessions.forEach((session, id) => {
+      if (session.lastSeen < cutoff)
+        sessions.delete(id);
+    });
+  };
+  return {
+    create: (session) => {
+      sweep();
+      const id = crypto.randomUUID();
+      sessions.set(id, { canElicit: session.canElicit, lastSeen: Date.now() });
+      return id;
+    },
+    drop: (id) => {
+      sessions.delete(id);
+    },
+    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: (request) => {
+      const id = `elicit_${crypto.randomUUID()}`;
+      const answer = new Promise((resolve) => {
+        const timer = setTimeout(() => {
+          pending.delete(id);
+          resolve({ action: "cancel" });
+        }, elicitTimeoutMs);
+        pending.set(id, { resolve, timer });
+      });
+      return { answer, id, request };
+    }
+  };
+};
+
 // src/metadata.ts
 var protectedResourceMetadata = (input) => ({
   authorization_servers: [input.issuer],
@@ -439,6 +785,25 @@ var ROOT_METADATA_PATH = "/.well-known/oauth-protected-resource";
 var JSON_HEADERS = {
   "content-type": "application/json"
 };
+var HTTP_NOT_FOUND = 404;
+var registries = new WeakMap;
+var primeMcpSessions = (config) => {
+  registryFor(config);
+};
+var registryFor = (config) => {
+  if (!config.elicitation?.enabled)
+    return;
+  const existing = registries.get(config);
+  if (existing)
+    return existing;
+  const created = createSessionRegistry({
+    ...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;
+};
 var metadataResponse = (config) => new Response(JSON.stringify(protectedResourceMetadata({
   issuer: config.issuer,
   resource: `${config.issuer}${config.path}`,
@@ -455,7 +820,24 @@ var runMcpPost = async (config, request, body) => {
   if (Array.isArray(body)) {
     return rpcError(null, JSONRPC_INVALID_REQUEST, "Batching is not supported");
   }
-  return dispatchMcp(config, auth.caller, auth.scopes ?? [], body).catch(() => rpcError(null, JSONRPC_INVALID_REQUEST, "Internal error"));
+  const sessions = registryFor(config);
+  const sessionId = request.headers.get("mcp-session-id");
+  if (sessions && sessionId && !await sessions.get(sessionId)) {
+    return new Response(null, { status: HTTP_NOT_FOUND });
+  }
+  return dispatchMcp(config, auth.caller, auth.scopes ?? [], body, {
+    sessionId,
+    sessions
+  }).catch(() => rpcError(null, JSONRPC_INVALID_REQUEST, "Internal error"));
+};
+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 });
+  }
+  await sessions.drop(sessionId);
+  return new Response(null, { status: HTTP_NO_CONTENT });
 };
 var handleMcpRequest = async (config, request) => {
   const { pathname } = new URL(request.url);
@@ -477,16 +859,23 @@ var handleMcpRequest = async (config, request) => {
     });
     return runMcpPost(config, request, body);
   }
+  if (request.method === "DELETE" && pathname === config.path) {
+    return runMcpDelete(config, request);
+  }
   return null;
 };
 
 // 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);
-  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));
+  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;
 };
@@ -495,8 +884,11 @@ export {
   protectedResourceMetadata,
   metadataPathFor,
   mcpServer,
+  feedbackTools,
   dispatchMcp,
+  createSessionRegistry,
   createMcpHandler,
   createMcpClient,
-  McpClientError
+  McpClientError,
+  FEEDBACK_INSTRUCTIONS
 };

package/dist/src/client.d.ts

@@ -1,4 +1,4 @@
-import type { McpToolAnnotations, McpToolResult } from "./types";
+import type { McpElicitationRequest, McpElicitResult, McpToolAnnotations, McpToolResult } from "./types";
 export declare class McpClientError extends Error {
     readonly code: number | undefined;
     readonly status: number | undefined;
@@ -12,6 +12,12 @@ export type McpClientOptions = {
         name: string;
         version: string;
     };
+    /** Answer a server's `elicitation/create` — a question for the USER, asked
+     *  mid-tool-call. Supplying it declares the `elicitation` capability, so a
+     *  server may then ask; omit it and servers are told you can't. Return
+     *  `{action:"decline"}` (the user said no) or `{action:"cancel"}` (they
+     *  dismissed it) — NEVER fabricate content on the user's behalf. */
+    onElicit?: (request: McpElicitationRequest) => Promise<McpElicitResult> | McpElicitResult;
     /** Sent on every request (e.g. `{ authorization: "Bearer …" }`). */
     headers?: Record<string, string>;
     /** Reject responses whose body exceeds this many bytes (0 = no cap). */

package/dist/src/core.d.ts

@@ -1,10 +1,19 @@
 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
  *  parse it itself; both funnel through here so the logic lives in one place. */
 export declare const runMcpPost: <Caller>(config: McpServerConfig<Caller>, request: Request, body: unknown) => Promise<Response>;
+/** 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) => 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/dispatch.d.ts

@@ -1,5 +1,10 @@
+import type { SessionRegistry } from "./sessions";
 import type { McpServerConfig } from "./types";
-/** Route one decoded JSON-RPC message to its handler. `scopes` are the caller's
- *  granted scopes (from `authorize`); they gate scope-restricted tools.
- *  Notifications (no `id`) get a bare 202; unknown methods get method-not-found. */
-export declare const dispatchMcp: <Caller>(config: McpServerConfig<Caller>, caller: Caller, scopes: string[], message: unknown) => Promise<Response>;
+/** Everything a dispatch needs to know about the HTTP request it came in on.
+ *  Only elicitation uses it; without it the dispatcher is exactly as stateless
+ *  as it was. */
+export type McpDispatchContext = {
+    sessionId?: string | null;
+    sessions?: SessionRegistry;
+};
+export declare const dispatchMcp: <Caller>(config: McpServerConfig<Caller>, caller: Caller, scopes: string[], message: unknown, context?: McpDispatchContext) => Promise<Response>;

package/dist/src/feedback.d.ts

@@ -0,0 +1,48 @@
+import type { McpToolRegistry } from "./types";
+export type McpFeedbackRating = "bad" | "good";
+export type McpProblemReport = {
+    /** What the user expected instead. */
+    expected?: string;
+    /** What is broken, in the user's words. */
+    problem: string;
+    /** How to reproduce it. */
+    steps?: string;
+    /** Where it happened — a page, a feature, a tool name. */
+    where?: string;
+};
+export type McpFeedbackReport = {
+    rating: McpFeedbackRating;
+    /** Why — in the USER's words, not the model's summary. */
+    reason: string;
+    /** The tool the feedback is about, if it was about one. */
+    tool?: string;
+};
+/** Where feedback goes. Both handlers return the sentence the model relays back
+ *  to the user, so the host controls what it promises them (a ticket id, an
+ *  SLA, a thank-you). Returning nothing is fine — a default is used. */
+export type McpFeedbackStore<Caller> = {
+    reportProblem: (input: {
+        caller: Caller;
+        report: McpProblemReport;
+    }) => Promise<string | void> | string | void;
+    submitFeedback: (input: {
+        caller: Caller;
+        feedback: McpFeedbackReport;
+    }) => Promise<string | void> | string | void;
+};
+/** Append to your server's `instructions`. Without this the model treats a
+ *  complaint as something to apologise for rather than something to report. */
+export declare const FEEDBACK_INSTRUCTIONS = "FEEDBACK: you are the user's only channel back to this server's team \u2014 there are no buttons in this client. If the user says something was wrong, unhelpful, or not what they asked for, call submit_feedback with their reason in their own words; if something is outright broken, call report_problem. Do this INSTEAD of only apologising, and tell them you've passed it on. Log the good as well as the bad.";
+/** The two tools, bound to one caller. Call inside your `tools` factory:
+ *
+ *  ```ts
+ *  tools: ({ caller }) => ({
+ *    ...myTools(caller),
+ *    ...feedbackTools({ caller, store }),
+ *  })
+ *  ```
+ */
+export declare const feedbackTools: <Caller>(config: {
+    caller: Caller;
+    store: McpFeedbackStore<Caller>;
+}) => McpToolRegistry;

package/dist/src/index.d.ts

@@ -13,6 +13,14 @@
  * `scope` gating, and rich tool results (text/image/structured) are all
  * built in; the package ships no opinion about billing, storage, or access.
  *
+ * **Feedback.** A connected AI client gives a server no UI, so a user's "that
+ * was wrong" can only come back through the model. {@link feedbackTools} is the
+ * pair of tools that carries it (report_problem / submit_feedback), and
+ * {@link FEEDBACK_INSTRUCTIONS} is the sentence that makes a model actually use
+ * them instead of just apologising. {@link McpServerConfig.elicitation} goes
+ * further: a tool marked `mayElicit` can ASK the user a question mid-call
+ * (`elicitation/create`) and wait for the answer.
+ *
  * **Consume.** {@link createMcpClient} is a streamable-HTTP client for calling
  * OTHER MCP servers — the half you need to expose a user's own connected tools
  * to your agent. Safety wrapping around untrusted remote tools (namespacing,
@@ -24,8 +32,10 @@
  */
 export { verifyBearer, type BearerResult, type BearerVerifier, type VerifiedJwt, type VerifyBearerConfig, } from "./auth";
 export { createMcpClient, McpClientError, type McpClient, type McpClientOptions, type McpInitializeResult, type McpRemoteTool, } from "./client";
-export { dispatchMcp } from "./dispatch";
+export { dispatchMcp, type McpDispatchContext } from "./dispatch";
+export { FEEDBACK_INSTRUCTIONS, feedbackTools, type McpFeedbackRating, type McpFeedbackReport, type McpFeedbackStore, type McpProblemReport, } from "./feedback";
 export { createMcpHandler } from "./handler";
 export { metadataPathFor, protectedResourceMetadata, type ProtectedResourceMetadata, } from "./metadata";
 export { mcpServer } from "./server";
-export type { McpAudioContent, McpAuthResult, McpCallGate, McpCallMeta, McpContent, McpImageContent, McpPromptArgument, McpPromptDefinition, McpPrompts, McpResource, McpResourceLink, McpResources, McpServerConfig, McpServerInfo, McpTextContent, McpTool, McpToolAnnotations, McpToolContext, McpToolRegistry, McpToolResult, McpToolReturn, } from "./types";
+export { createSessionRegistry, type SessionRegistry } from "./sessions";
+export type { McpAudioContent, McpElicitationRequest, McpElicitResult, McpAuthResult, McpCallGate, McpCallMeta, McpContent, McpImageContent, McpPromptArgument, McpPromptDefinition, McpPrompts, McpResource, McpResourceLink, McpResources, McpServerConfig, McpServerInfo, McpTextContent, McpTool, McpToolAnnotations, McpToolCallContext, McpToolContext, McpToolRegistry, McpToolResult, McpToolReturn, } from "./types";

package/dist/src/jsonrpc.d.ts

@@ -4,6 +4,7 @@ export declare const JSONRPC_METHOD_NOT_FOUND = -32601;
 export declare const JSONRPC_INVALID_PARAMS = -32602;
 export declare const JSONRPC_INTERNAL_ERROR = -32603;
 export declare const HTTP_ACCEPTED = 202;
+export declare const HTTP_NO_CONTENT = 204;
 export declare const HTTP_UNAUTHORIZED = 401;
 export declare const HTTP_METHOD_NOT_ALLOWED = 405;
 export type JsonRpcId = string | number | null;

package/dist/src/server.d.ts

@@ -3,8 +3,10 @@ import type { McpServerConfig } from "./types";
 /** Build the MCP endpoint as an Elysia plugin. Mount it with `.use(...)`.
  *
  *  Serves:
- *   - `POST <path>`   — the JSON-RPC endpoint (stateless streamable HTTP)
- *   - `GET  <path>`   — 405 (no server-initiated stream to subscribe to)
+ *   - `POST <path>`   — the JSON-RPC endpoint (streamable HTTP; answers with a
+ *     plain JSON body, or an SSE stream when a tool may elicit)
+ *   - `GET  <path>`   — 405 (no standalone server-initiated stream)
+ *   - `DELETE <path>` — end an elicitation session (405 when sessionless)
  *   - `GET  /.well-known/oauth-protected-resource<path>` — RFC 9728 metadata
  *   - `GET  /.well-known/oauth-protected-resource` — the same, if
  *     `serveRootMetadata` is set (only one endpoint per app should). */

package/dist/src/sessions.d.ts

@@ -0,0 +1,25 @@
+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;
+}) => {
+    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;
+    };
+};

package/dist/src/types.d.ts

@@ -40,12 +40,82 @@ export type McpToolResult = {
 };
 /** What a tool handler may return. A bare string is the common case. */
 export type McpToolReturn = McpContent[] | McpToolResult | string;
+/** A question the SERVER asks the USER, mid-tool-call, through the client
+ *  (`elicitation/create`). The schema is a deliberately restricted subset of
+ *  JSON Schema — a FLAT object of primitives (string / number / integer /
+ *  boolean / enum), so any client can render a form for it. Nested objects and
+ *  arrays are not allowed by the spec.
+ *
+ *  Servers MUST NOT elicit sensitive information (spec, Security). */
+export type McpElicitationRequest = {
+    message: string;
+    requestedSchema: Record<string, unknown>;
+};
+/** What came back. `unsupported` is ours, not the spec's: it is what you get
+ *  when the client never declared the elicitation capability, so a tool can
+ *  fall back instead of pretending the user declined. */
+export type McpElicitResult = {
+    action: "accept";
+    content: Record<string, unknown>;
+} | {
+    action: "cancel";
+} | {
+    action: "decline";
+} | {
+    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 = {
+    /** True when this client can actually show the user a form. Check it before
+     *  designing a flow around elicit(). */
+    canElicit: boolean;
+    /** Ask the user a question and wait for the answer. Resolves to
+     *  `{action:"unsupported"}` immediately when the client can't elicit, and to
+     *  `{action:"cancel"}` if they never answer. */
+    elicit: (request: McpElicitationRequest) => Promise<McpElicitResult>;
+};
 /** One callable tool. `inputSchema` is a JSON Schema object. */
 export type McpTool = {
     annotations?: McpToolAnnotations;
     description: string;
-    handler: (args: unknown) => McpToolReturn | Promise<McpToolReturn>;
+    handler: (args: unknown, context: McpToolCallContext) => McpToolReturn | Promise<McpToolReturn>;
     inputSchema: Record<string, unknown>;
+    /** Set when this tool may call `context.elicit`. It makes the server answer
+     *  the `tools/call` with an SSE stream (the only way to send the user a
+     *  question mid-call) instead of a plain JSON body — so it is opt-in per
+     *  tool, and a server whose tools never elicit stays purely stateless. */
+    mayElicit?: boolean;
     /** JSON Schema for `structuredContent`, advertised on `tools/list`. */
     outputSchema?: Record<string, unknown>;
     /** If set, the tool is only listed and callable when the caller's scopes
@@ -135,6 +205,21 @@ export type McpServerConfig<Caller> = {
     instructions?: string;
     /** The token issuer — used for discovery metadata and the challenge URL. */
     issuer: string;
+    /** Turn on elicitation (server asks the USER a question mid-tool-call).
+     *  Off by default, because it makes the endpoint SESSION-STATEFUL: the
+     *  client answers on a separate HTTP request, so the pending call has to be
+     *  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). */
     listPageSize?: number;
     /** Fired after every `tools/call` for auditing. `meta` carries anything the

package/package.json

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