@absolutejs/mcp 0.1.0 → 0.3.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"
@@ -150,16 +221,26 @@ var createMcpClient = (options) => {
     await notify("notifications/initialized");
     return isRecord(result) ? result : {};
   };
+  const MAX_LIST_PAGES = 40;
   const listTools = async () => {
-    const result = await rpc("tools/list");
-    const tools = isRecord(result) && Array.isArray(result.tools) ? result.tools : [];
-    return tools.filter(isRecord).map((tool) => ({
-      annotations: isRecord(tool.annotations) ? tool.annotations : undefined,
-      description: typeof tool.description === "string" ? tool.description : undefined,
-      inputSchema: isRecord(tool.inputSchema) ? tool.inputSchema : undefined,
-      name: typeof tool.name === "string" ? tool.name : "",
-      outputSchema: isRecord(tool.outputSchema) ? tool.outputSchema : undefined
-    }));
+    const collected = [];
+    let cursor;
+    for (let page = 0;page < MAX_LIST_PAGES; page += 1) {
+      const result = await rpc("tools/list", cursor === undefined ? undefined : { cursor });
+      const tools = isRecord(result) && Array.isArray(result.tools) ? result.tools : [];
+      collected.push(...tools.filter(isRecord).map((tool) => ({
+        annotations: isRecord(tool.annotations) ? tool.annotations : undefined,
+        description: typeof tool.description === "string" ? tool.description : undefined,
+        inputSchema: isRecord(tool.inputSchema) ? tool.inputSchema : undefined,
+        name: typeof tool.name === "string" ? tool.name : "",
+        outputSchema: isRecord(tool.outputSchema) ? tool.outputSchema : undefined
+      })));
+      const next = isRecord(result) && typeof result.nextCursor === "string" ? result.nextCursor : undefined;
+      if (next === undefined)
+        break;
+      cursor = next;
+    }
+    return collected;
   };
   const callTool = async (name, args) => {
     const result = await rpc("tools/call", { arguments: args ?? {}, name });
@@ -169,8 +250,19 @@ var createMcpClient = (options) => {
     return { content: [], isError: false };
   };
   const listResources = async () => {
-    const result = await rpc("resources/list");
-    return isRecord(result) && Array.isArray(result.resources) ? result.resources : [];
+    const collected = [];
+    let cursor;
+    for (let page = 0;page < MAX_LIST_PAGES; page += 1) {
+      const result = await rpc("resources/list", cursor === undefined ? undefined : { cursor });
+      if (isRecord(result) && Array.isArray(result.resources)) {
+        collected.push(...result.resources);
+      }
+      const next = isRecord(result) && typeof result.nextCursor === "string" ? result.nextCursor : undefined;
+      if (next === undefined)
+        break;
+      cursor = next;
+    }
+    return collected;
   };
   const readResource = async (uri) => rpc("resources/read", { uri });
   const ping = async () => {
@@ -185,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 = {
@@ -212,6 +305,26 @@ var unauthorized = (metadataUrl, detail) => new Response(JSON.stringify({
 // src/dispatch.ts
 var DEFAULT_PROTOCOLS = ["2025-06-18", "2025-03-26", "2024-11-05"];
 var DEFAULT_RESOURCE_MIME = "text/markdown";
+var DEFAULT_LIST_PAGE_SIZE = 50;
+var decodeCursor = (params) => {
+  if (!isRecord(params) || typeof params.cursor !== "string")
+    return 0;
+  try {
+    const parsed = Number.parseInt(atob(params.cursor), 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : 0;
+  } catch {
+    return 0;
+  }
+};
+var encodeCursor = (offset) => btoa(String(offset));
+var paginate = (items, offset, pageSize) => {
+  const page = items.slice(offset, offset + pageSize);
+  const nextOffset = offset + pageSize;
+  return {
+    items: page,
+    ...nextOffset < items.length ? { nextCursor: encodeCursor(nextOffset) } : {}
+  };
+};
 var idOf = (message) => typeof message.id === "string" || typeof message.id === "number" ? message.id : null;
 var negotiateProtocol = (supported, params) => {
   const preferred = supported[0] ?? DEFAULT_PROTOCOLS[0] ?? "";
@@ -227,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 = (config, id, params, context) => {
   const supported = config.supportedProtocols ?? DEFAULT_PROTOCOLS;
   const capabilities = {
     tools: { listChanged: false }
@@ -237,27 +355,114 @@ 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 = context.sessions.create(clientCanElicit(params));
+  response.headers.set("Mcp-Session-Id", sessionId);
+  return response;
 };
-var toolsList = async (config, caller, scopes, id) => {
+var toolsList = async (config, caller, scopes, id, params) => {
   const tools = await config.tools({ caller, meta: {} });
+  const visible = Object.entries(tools).filter(([, tool]) => scopeAllows(tool, scopes)).map(([name, tool]) => ({
+    annotations: tool.annotations,
+    description: tool.description,
+    inputSchema: tool.inputSchema,
+    name,
+    ...tool.outputSchema === undefined ? {} : { outputSchema: tool.outputSchema }
+  }));
+  const { items, nextCursor } = paginate(visible, decodeCursor(params), config.listPageSize ?? DEFAULT_LIST_PAGE_SIZE);
   return rpcResult(id, {
-    tools: Object.entries(tools).filter(([, tool]) => scopeAllows(tool, scopes)).map(([name, tool]) => ({
-      annotations: tool.annotations,
-      description: tool.description,
-      inputSchema: tool.inputSchema,
-      name,
-      ...tool.outputSchema === undefined ? {} : { outputSchema: tool.outputSchema }
-    }))
+    tools: items,
+    ...nextCursor === undefined ? {} : { nextCursor }
   });
 };
 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, sessionId, 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(sessionId, request);
+          if (!pending.id)
+            return { action: "cancel" };
+          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");
   }
@@ -274,29 +479,28 @@ 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 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);
   }
-  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) => {
+var promptsList = (config, id, params) => {
   const definitions = config.prompts?.definitions ?? {};
+  const all = Object.entries(definitions).map(([name, def]) => ({
+    arguments: def.arguments ?? [],
+    description: def.description,
+    name,
+    title: def.title
+  }));
+  const { items, nextCursor } = paginate(all, decodeCursor(params), config.listPageSize ?? DEFAULT_LIST_PAGE_SIZE);
   return rpcResult(id, {
-    prompts: Object.entries(definitions).map(([name, def]) => ({
-      arguments: def.arguments ?? [],
-      description: def.description,
-      name,
-      title: def.title
-    }))
+    prompts: items,
+    ...nextCursor === undefined ? {} : { nextCursor }
   });
 };
 var promptsGet = async (config, caller, id, params) => {
@@ -320,11 +524,15 @@ var promptsGet = async (config, caller, id, params) => {
     messages: [{ content: { text, type: "text" }, role: "user" }]
   });
 };
-var resourcesList = async (config, caller, id) => {
+var resourcesList = async (config, caller, id, params) => {
   const resources = config.resources;
   if (!resources)
     return rpcResult(id, { resources: [] });
-  return rpcResult(id, { resources: await resources.list({ caller }) });
+  const { items, nextCursor } = paginate(await resources.list({ caller }), decodeCursor(params), config.listPageSize ?? DEFAULT_LIST_PAGE_SIZE);
+  return rpcResult(id, {
+    resources: items,
+    ...nextCursor === undefined ? {} : { nextCursor }
+  });
 };
 var resourcesRead = async (config, caller, id, params) => {
   const resources = config.resources;
@@ -344,35 +552,226 @@ 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(context.sessionId ?? null, requestId, answer);
+  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 initialize(config, id, params, context);
+  }
   if (method === "ping")
     return rpcResult(id, {});
-  if (method === "tools/list")
-    return toolsList(config, caller, scopes, 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);
+    return promptsList(config, id, params);
   if (method === "prompts/get")
     return promptsGet(config, caller, id, params);
-  if (method === "resources/list")
-    return resourcesList(config, caller, id);
+  if (method === "resources/list") {
+    return resourcesList(config, caller, id, params);
+  }
   if (method === "resources/read") {
     return resourcesRead(config, caller, id, params);
   }
   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 createSessionRegistry = (options) => {
+  const ttlMs = options?.ttlMs ?? DEFAULT_SESSION_TTL_MS;
+  const elicitTimeoutMs = options?.elicitTimeoutMs ?? DEFAULT_ELICIT_TIMEOUT_MS;
+  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)
+        return;
+      session.pending.forEach((pending) => {
+        clearTimeout(pending.timer);
+        pending.resolve({ action: "cancel" });
+      });
+      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) => {
+      sweep();
+      const id = crypto.randomUUID();
+      sessions.set(id, { canElicit, lastSeen: Date.now(), pending: new Map });
+      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;
+    },
+    startElicit: (sessionId, request) => {
+      const session = sessions.get(sessionId);
+      if (!session) {
+        return {
+          answer: Promise.resolve({ action: "cancel" }),
+          id: "",
+          request
+        };
+      }
+      const id = `elicit_${crypto.randomUUID()}`;
+      const answer = new Promise((resolve) => {
+        const timer = setTimeout(() => {
+          session.pending.delete(id);
+          resolve({ action: "cancel" });
+        }, elicitTimeoutMs);
+        session.pending.set(id, { resolve, timer });
+      });
+      return { answer, id, request };
+    }
+  };
+};
+
 // src/metadata.ts
 var protectedResourceMetadata = (input) => ({
   authorization_servers: [input.issuer],
@@ -386,6 +785,20 @@ 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 registryFor = (config) => {
+  if (!config.elicitation?.enabled)
+    return;
+  const existing = registries.get(config);
+  if (existing)
+    return existing;
+  const created = createSessionRegistry({
+    elicitTimeoutMs: config.elicitation.timeoutMs
+  });
+  registries.set(config, created);
+  return created;
+};
 var metadataResponse = (config) => new Response(JSON.stringify(protectedResourceMetadata({
   issuer: config.issuer,
   resource: `${config.issuer}${config.path}`,
@@ -402,7 +815,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 && !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 = (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);
+  return new Response(null, { status: HTTP_NO_CONTENT });
 };
 var handleMcpRequest = async (config, request) => {
   const { pathname } = new URL(request.url);
@@ -424,6 +854,9 @@ var handleMcpRequest = async (config, request) => {
     });
     return runMcpPost(config, request, body);
   }
+  if (request.method === "DELETE" && pathname === config.path) {
+    return runMcpDelete(config, request);
+  }
   return null;
 };
 
@@ -433,7 +866,7 @@ var createMcpHandler = (config) => (request) => handleMcpRequest(config, request
 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));
+  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;
 };
@@ -442,8 +875,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

@@ -5,6 +5,10 @@ export declare const metadataResponse: <Caller>(config: McpServerConfig<Caller>)
  *  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) => 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,34 @@
+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>;
+};
+export type SessionRegistry = ReturnType<typeof createSessionRegistry>;
+export declare const createSessionRegistry: (options?: {
+    elicitTimeoutMs?: number;
+    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) => {
+        answer: Promise<McpElicitResult>;
+        id: string;
+        request: McpElicitationRequest;
+    };
+};
+export {};

package/dist/src/types.d.ts

@@ -40,12 +40,52 @@ 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";
+};
+/** 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 +175,17 @@ 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?: {
+        enabled: true;
+        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
      *  tool handler wrote during the call. */
     onCall?: (record: {

package/package.json

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