@ampless/mcp-server 1.0.0-beta.66 → 1.0.0-beta.68

package/README.ja.md

@@ -71,13 +71,25 @@ import type { ToolDefinition, ToolContext, ResolvedSite } from '@ampless/mcp-ser
 ### `./jsonrpc`
 
 ```typescript
-import { dispatchJsonRpc } from '@ampless/mcp-server/jsonrpc'
-import type { JsonRpcRequest, JsonRpcResponse } from '@ampless/mcp-server/jsonrpc'
+import {
+  dispatchJsonRpcMessage,
+  dispatchJsonRpc,
+  ToolUserError,
+  MAX_BATCH,
+} from '@ampless/mcp-server/jsonrpc'
+import type {
+  JsonRpcRequest,
+  JsonRpcResponse,
+  JsonRpcMessageResult,
+} from '@ampless/mcp-server/jsonrpc'
 ```
 
 | エクスポート | 説明 |
 |---|---|
-| `dispatchJsonRpc(req, opts)` | JSON-RPC リクエストを 1 件ツールレジストリに対して実行（`initialize` のバージョンネゴシエーション、annotations 付き `tools/list`、`tools/call`、notification 処理）。notification（`id` 無し）は method を実行しつつレスポンスの代わりに `null` を返す。`id: null` / 小数 id は `INVALID_REQUEST` で拒否 |
+| `dispatchJsonRpcMessage(input, opts)` | **推奨エントリポイント。** 未検証のデコード済みメッセージ（`unknown` — 単一オブジェクト **または** batch 配列）を受け取り、タグ付き `JsonRpcMessageResult` を返す：`{ status: 'invalid', body }`（HTTP 400 — 非オブジェクト / 空 / 過大 batch）、`{ status: 'ok', body }`（HTTP 200 — 単一レスポンス、または batch のレスポンス配列）、`{ status: 'no-content' }`（HTTP 202 — notification のみ）。エンベロープ検証と batch 処理（逐次・順序維持・batch 内 `initialize` 禁止）をここに集約したので、トランスポートは `JSON.parse` の生の結果をそのまま渡せる。`opts.maxBatch` の既定は `MAX_BATCH` |
+| `dispatchJsonRpc(req, opts)` | **検証済みの** JSON-RPC リクエストを 1 件ツールレジストリに対して実行（`initialize` のバージョンネゴシエーション、annotations 付き `tools/list`、`tools/call`、notification 処理）。notification（`id` 無し）は method を実行しつつレスポンスの代わりに `null` を返す。`id: null` / 小数 id は `INVALID_REQUEST` で拒否。ワイヤから来たものはエンベロープ検証と batch 対応を集約した `dispatchJsonRpcMessage` を使うこと |
+| `ToolUserError` / `isToolUserError` | client に返して安全な message を持つ想定内の tool failure を示す。独立 bundle の package entry 間でも認識でき、dispatcher はこの class に対して `formatToolError` と logging を迂回する。message に secret、内部詳細、未処理のユーザ入力を絶対に入れないこと |
+| `MAX_BATCH` | batch 要素数の既定上限（`50`） |
 | `jsonRpcResult` / `jsonRpcError` / `JSON_RPC_*` | エンベロープヘルパ + 標準エラーコード |
 | `SUPPORTED_PROTOCOL_VERSIONS` | `['2025-03-26', '2024-11-05']` |
 

package/README.md

@@ -71,13 +71,25 @@ import type { ToolDefinition, ToolContext, ResolvedSite } from '@ampless/mcp-ser
 ### `./jsonrpc`
 
 ```typescript
-import { dispatchJsonRpc } from '@ampless/mcp-server/jsonrpc'
-import type { JsonRpcRequest, JsonRpcResponse } from '@ampless/mcp-server/jsonrpc'
+import {
+  dispatchJsonRpcMessage,
+  dispatchJsonRpc,
+  ToolUserError,
+  MAX_BATCH,
+} from '@ampless/mcp-server/jsonrpc'
+import type {
+  JsonRpcRequest,
+  JsonRpcResponse,
+  JsonRpcMessageResult,
+} from '@ampless/mcp-server/jsonrpc'
 ```
 
 | Export | Description |
 |---|---|
-| `dispatchJsonRpc(req, opts)` | Runs one JSON-RPC request against a tool registry (`initialize` with protocol negotiation, `tools/list` with annotations, `tools/call`, notification handling). A notification (`id` absent) still executes the method but returns `null` instead of a response; `id: null` / fractional ids are rejected as `INVALID_REQUEST`. |
+| `dispatchJsonRpcMessage(input, opts)` | **Preferred entry point.** Takes an *unvalidated* decoded message (`unknown` — a single object **or** a batch array) and returns a tagged `JsonRpcMessageResult`: `{ status: 'invalid', body }` (HTTP 400 — top-level malformed / empty / over-size batch), `{ status: 'ok', body }` (HTTP 200 — single response or a batch's response array), or `{ status: 'no-content' }` (HTTP 202 — notification(s) only). Envelope validation and batch handling (sequential, order-preserving, `initialize` forbidden inside a batch) live here, so transports pass their raw `JSON.parse` result straight through. `opts.maxBatch` defaults to `MAX_BATCH`. |
+| `dispatchJsonRpc(req, opts)` | Runs **one already-validated** JSON-RPC request against a tool registry (`initialize` with protocol negotiation, `tools/list` with annotations, `tools/call`, notification handling). A notification (`id` absent) still executes the method but returns `null` instead of a response; `id: null` / fractional ids are rejected as `INVALID_REQUEST`. Prefer `dispatchJsonRpcMessage` for anything coming off the wire — it centralises envelope checks and batch support. |
+| `ToolUserError` / `isToolUserError` | Marks an expected tool failure whose message is safe to return to clients, including across independently bundled package entry points. The dispatcher bypasses `formatToolError` and logging for this class. Never put secrets, internal details, or unprocessed user input in its message. |
+| `MAX_BATCH` | Default batch-element cap (`50`) |
 | `jsonRpcResult` / `jsonRpcError` / `JSON_RPC_*` | Envelope helpers + standard error codes |
 | `SUPPORTED_PROTOCOL_VERSIONS` | `['2025-03-26', '2024-11-05']` |
 

package/dist/chunk-4REBPD2N.js

@@ -0,0 +1,211 @@
+// src/jsonrpc/index.ts
+var JSON_RPC_PARSE_ERROR = -32700;
+var JSON_RPC_INVALID_REQUEST = -32600;
+var JSON_RPC_METHOD_NOT_FOUND = -32601;
+var JSON_RPC_INVALID_PARAMS = -32602;
+var JSON_RPC_INTERNAL_ERROR = -32603;
+var TOOL_USER_ERROR_BRAND = /* @__PURE__ */ Symbol.for("ampless.mcp.toolUserError");
+var ToolUserError = class extends Error {
+  [TOOL_USER_ERROR_BRAND] = true;
+  constructor(message) {
+    super(message);
+    this.name = "ToolUserError";
+  }
+};
+function isToolUserError(error) {
+  return error instanceof Error && error[TOOL_USER_ERROR_BRAND] === true;
+}
+var SUPPORTED_PROTOCOL_VERSIONS = ["2025-03-26", "2024-11-05"];
+var LATEST_SUPPORTED_PROTOCOL_VERSION = SUPPORTED_PROTOCOL_VERSIONS[0];
+function jsonRpcResult(id, result) {
+  return { jsonrpc: "2.0", id, result };
+}
+function jsonRpcError(id, code, message, data) {
+  const error = { code, message };
+  if (data !== void 0) error.data = data;
+  return { jsonrpc: "2.0", id, error };
+}
+function isNotification(req) {
+  return req.id === void 0;
+}
+function hasValidJsonRpcId(req) {
+  const id = req.id;
+  if (id === void 0) return true;
+  return typeof id === "string" || typeof id === "number" && Number.isInteger(id);
+}
+function isPlainObject(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+var MAX_BATCH = 50;
+function idForError(input) {
+  if (isPlainObject(input) && hasValidJsonRpcId(input)) {
+    return input.id ?? null;
+  }
+  return null;
+}
+function validateEnvelope(input, inBatch) {
+  if (!isPlainObject(input)) {
+    return { ok: false, error: jsonRpcError(null, JSON_RPC_INVALID_REQUEST, "Invalid Request") };
+  }
+  const jsonrpc = input.jsonrpc;
+  const method = input.method;
+  if (jsonrpc !== "2.0" || typeof method !== "string" || !hasValidJsonRpcId(input)) {
+    return {
+      ok: false,
+      error: jsonRpcError(idForError(input), JSON_RPC_INVALID_REQUEST, "Invalid Request")
+    };
+  }
+  if (inBatch && method === "initialize") {
+    return {
+      ok: false,
+      error: jsonRpcError(
+        idForError(input),
+        JSON_RPC_INVALID_REQUEST,
+        "Invalid Request: `initialize` is not allowed in a batch"
+      )
+    };
+  }
+  return { ok: true, req: input };
+}
+async function dispatchJsonRpcMessage(input, opts) {
+  const maxBatch = opts.maxBatch ?? MAX_BATCH;
+  if (Array.isArray(input)) {
+    if (input.length === 0 || input.length > maxBatch) {
+      return {
+        status: "invalid",
+        body: jsonRpcError(
+          null,
+          JSON_RPC_INVALID_REQUEST,
+          input.length === 0 ? "Invalid Request: empty batch" : `Invalid Request: batch exceeds the maximum of ${maxBatch} elements`
+        )
+      };
+    }
+    const responses = [];
+    for (const element of input) {
+      const validated2 = validateEnvelope(element, true);
+      if (!validated2.ok) {
+        responses.push(validated2.error);
+        continue;
+      }
+      const res2 = await dispatchJsonRpc(validated2.req, opts);
+      if (res2 !== null) responses.push(res2);
+    }
+    return responses.length === 0 ? { status: "no-content" } : { status: "ok", body: responses };
+  }
+  const validated = validateEnvelope(input, false);
+  if (!validated.ok) {
+    return { status: "invalid", body: validated.error };
+  }
+  const res = await dispatchJsonRpc(validated.req, opts);
+  return res === null ? { status: "no-content" } : { status: "ok", body: res };
+}
+function toolAnnotations(t) {
+  const annotations = {};
+  if (typeof t.readOnly === "boolean") annotations.readOnlyHint = t.readOnly;
+  if (typeof t.destructive === "boolean") annotations.destructiveHint = t.destructive;
+  return annotations;
+}
+async function dispatchJsonRpc(req, opts) {
+  if (!hasValidJsonRpcId(req)) {
+    return jsonRpcError(
+      null,
+      JSON_RPC_INVALID_REQUEST,
+      "Invalid Request: `id` must be a string or an integer"
+    );
+  }
+  const response = await dispatchMethod(req, opts);
+  return isNotification(req) ? null : response;
+}
+async function dispatchMethod(req, opts) {
+  const id = req.id ?? null;
+  switch (req.method) {
+    case "initialize": {
+      const requested = req.params?.protocolVersion;
+      if (typeof requested !== "string") {
+        return jsonRpcError(
+          id,
+          JSON_RPC_INVALID_PARAMS,
+          "initialize requires a string `protocolVersion` parameter"
+        );
+      }
+      const protocolVersion = SUPPORTED_PROTOCOL_VERSIONS.includes(
+        requested
+      ) ? requested : LATEST_SUPPORTED_PROTOCOL_VERSION;
+      return jsonRpcResult(id, {
+        protocolVersion,
+        capabilities: { tools: {} },
+        serverInfo: opts.serverInfo
+      });
+    }
+    case "notifications/initialized":
+      return jsonRpcResult(id, {});
+    case "tools/list":
+      return jsonRpcResult(id, {
+        tools: opts.tools.map((t) => ({
+          name: t.name,
+          description: t.description,
+          inputSchema: t.inputSchema,
+          annotations: toolAnnotations(t)
+        }))
+      });
+    case "tools/call": {
+      const params = req.params;
+      if (!params || typeof params.name !== "string") {
+        return jsonRpcError(id, JSON_RPC_INVALID_PARAMS, "tools/call requires a `name` parameter");
+      }
+      const rawArgs = params.arguments;
+      if (rawArgs !== void 0 && !isPlainObject(rawArgs)) {
+        return jsonRpcError(
+          id,
+          JSON_RPC_INVALID_PARAMS,
+          "tools/call `arguments` must be an object"
+        );
+      }
+      const tool = opts.tools.find((t) => t.name === params.name);
+      if (!tool) {
+        return jsonRpcError(id, JSON_RPC_METHOD_NOT_FOUND, `unknown tool: ${params.name}`);
+      }
+      const ctx = opts.getContext();
+      try {
+        const result = await tool.handler(rawArgs ?? {}, ctx);
+        return jsonRpcResult(id, {
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+        });
+      } catch (err) {
+        const rawMessage = err instanceof Error ? err.message : String(err);
+        const userError = isToolUserError(err);
+        if (!userError) {
+          console.error("[mcp-jsonrpc] tool dispatch failed", {
+            tool: params.name,
+            message: rawMessage
+          });
+        }
+        const message = userError ? rawMessage : opts.formatToolError ? opts.formatToolError(err) : rawMessage;
+        return jsonRpcResult(id, {
+          isError: true,
+          content: [{ type: "text", text: message }]
+        });
+      }
+    }
+    default:
+      return jsonRpcError(id, JSON_RPC_METHOD_NOT_FOUND, `Method not found: ${req.method}`);
+  }
+}
+
+export {
+  JSON_RPC_PARSE_ERROR,
+  JSON_RPC_INVALID_REQUEST,
+  JSON_RPC_METHOD_NOT_FOUND,
+  JSON_RPC_INVALID_PARAMS,
+  JSON_RPC_INTERNAL_ERROR,
+  ToolUserError,
+  isToolUserError,
+  SUPPORTED_PROTOCOL_VERSIONS,
+  LATEST_SUPPORTED_PROTOCOL_VERSION,
+  jsonRpcResult,
+  jsonRpcError,
+  hasValidJsonRpcId,
+  MAX_BATCH,
+  dispatchJsonRpcMessage,
+  dispatchJsonRpc
+};

package/dist/jsonrpc/index.d.ts

@@ -6,6 +6,18 @@ declare const JSON_RPC_INVALID_REQUEST = -32600;
 declare const JSON_RPC_METHOD_NOT_FOUND = -32601;
 declare const JSON_RPC_INVALID_PARAMS = -32602;
 declare const JSON_RPC_INTERNAL_ERROR = -32603;
+declare const TOOL_USER_ERROR_BRAND: unique symbol;
+/**
+ * A tool failure whose message is intentionally safe to expose to MCP
+ * clients. Messages must not include secrets, internal details, or
+ * unprocessed user input.
+ */
+declare class ToolUserError extends Error {
+    readonly [TOOL_USER_ERROR_BRAND] = true;
+    constructor(message: string);
+}
+/** Recognises ToolUserError instances across independently bundled entry points. */
+declare function isToolUserError(error: unknown): error is ToolUserError;
 declare const SUPPORTED_PROTOCOL_VERSIONS: readonly ["2025-03-26", "2024-11-05"];
 declare const LATEST_SUPPORTED_PROTOCOL_VERSION: "2025-03-26";
 interface JsonRpcRequest {
@@ -49,7 +61,8 @@ interface JsonRpcDispatchOptions<TCtx> {
      * Converts a tool handler exception into the string surfaced to the
      * client. Omit to expose the raw error message (admin transport).
      * The public transport passes a fixed message here and logs the
-     * detail server-side instead.
+     * detail server-side instead. ToolUserError messages bypass this
+     * formatter because they are explicitly marked as client-safe.
      */
     formatToolError?: (err: unknown) => string;
 }
@@ -65,6 +78,55 @@ interface JsonRpcDispatchOptions<TCtx> {
  * `dispatchJsonRpc` itself.
  */
 declare function hasValidJsonRpcId(req: object): boolean;
+declare const MAX_BATCH = 50;
+/**
+ * Result of dispatching an *unvalidated* decoded JSON-RPC message
+ * (single object or batch array) through `dispatchJsonRpcMessage`. The
+ * `status` tag tells the HTTP transport which response to emit:
+ *
+ *   - `invalid`    → 400 (top-level malformed: non-object scalar, empty
+ *                    batch, or over-size batch). `body` is the single
+ *                    error envelope to return.
+ *   - `ok`         → 200. `body` is a single response, or a batch's
+ *                    array of responses (invalid *elements* of a batch
+ *                    are error responses *inside* this array, still 200).
+ *   - `no-content` → 202 empty body (a lone notification, or a batch
+ *                    made entirely of notifications).
+ */
+type JsonRpcMessageResult = {
+    status: 'invalid';
+    body: JsonRpcResponse;
+} | {
+    status: 'ok';
+    body: JsonRpcResponse | JsonRpcResponse[];
+} | {
+    status: 'no-content';
+};
+interface JsonRpcDispatchMessageOptions<TCtx> extends JsonRpcDispatchOptions<TCtx> {
+    /** Batch element cap. Defaults to `MAX_BATCH` (50). */
+    maxBatch?: number;
+}
+/**
+ * Dispatch an *unvalidated* decoded JSON-RPC message — the single entry
+ * point every transport should use once it has `JSON.parse`d the body.
+ * Envelope validation, batch handling, and MCP method semantics are all
+ * centralised here so the admin (backend Lambda) and public (runtime)
+ * transports share one implementation; the transport keeps only HTTP
+ * framing (body decode, status codes, CORS, auth).
+ *
+ * Batch semantics (JSON-RPC 2.0):
+ *   - An array is a batch. Empty / over-`maxBatch` batches are rejected
+ *     wholesale as a single top-level INVALID_REQUEST (`status: 'invalid'`).
+ *   - Elements are processed **sequentially** (never `Promise.all`) so a
+ *     batch of tool calls cannot fan out into concurrent handler runs.
+ *   - Malformed elements yield an INVALID_REQUEST response inside the
+ *     result array (id echoed when valid, else null); `initialize` is
+ *     not allowed as a batch element. Notifications execute but emit no
+ *     response. Non-notification responses keep the input order.
+ *   - A batch that yields no responses at all (all notifications) →
+ *     `no-content`.
+ */
+declare function dispatchJsonRpcMessage<TCtx>(input: unknown, opts: JsonRpcDispatchMessageOptions<TCtx>): Promise<JsonRpcMessageResult>;
 /**
  * Dispatch one parsed JSON-RPC request against a tool registry.
  * Returns the response envelope, or `null` for a notification (the
@@ -77,4 +139,4 @@ declare function hasValidJsonRpcId(req: object): boolean;
  */
 declare function dispatchJsonRpc<TCtx>(req: JsonRpcRequest, opts: JsonRpcDispatchOptions<TCtx>): Promise<JsonRpcResponse | null>;
 
-export { JSON_RPC_INTERNAL_ERROR, JSON_RPC_INVALID_PARAMS, JSON_RPC_INVALID_REQUEST, JSON_RPC_METHOD_NOT_FOUND, JSON_RPC_PARSE_ERROR, type JsonRpcDispatchOptions, type JsonRpcRequest, type JsonRpcResponse, LATEST_SUPPORTED_PROTOCOL_VERSION, SUPPORTED_PROTOCOL_VERSIONS, dispatchJsonRpc, hasValidJsonRpcId, jsonRpcError, jsonRpcResult };
+export { JSON_RPC_INTERNAL_ERROR, JSON_RPC_INVALID_PARAMS, JSON_RPC_INVALID_REQUEST, JSON_RPC_METHOD_NOT_FOUND, JSON_RPC_PARSE_ERROR, type JsonRpcDispatchMessageOptions, type JsonRpcDispatchOptions, type JsonRpcMessageResult, type JsonRpcRequest, type JsonRpcResponse, LATEST_SUPPORTED_PROTOCOL_VERSION, MAX_BATCH, SUPPORTED_PROTOCOL_VERSIONS, ToolUserError, dispatchJsonRpc, dispatchJsonRpcMessage, hasValidJsonRpcId, isToolUserError, jsonRpcError, jsonRpcResult };

package/dist/jsonrpc/index.js

@@ -1,119 +1,20 @@
-// src/jsonrpc/index.ts
-var JSON_RPC_PARSE_ERROR = -32700;
-var JSON_RPC_INVALID_REQUEST = -32600;
-var JSON_RPC_METHOD_NOT_FOUND = -32601;
-var JSON_RPC_INVALID_PARAMS = -32602;
-var JSON_RPC_INTERNAL_ERROR = -32603;
-var SUPPORTED_PROTOCOL_VERSIONS = ["2025-03-26", "2024-11-05"];
-var LATEST_SUPPORTED_PROTOCOL_VERSION = SUPPORTED_PROTOCOL_VERSIONS[0];
-function jsonRpcResult(id, result) {
-  return { jsonrpc: "2.0", id, result };
-}
-function jsonRpcError(id, code, message, data) {
-  const error = { code, message };
-  if (data !== void 0) error.data = data;
-  return { jsonrpc: "2.0", id, error };
-}
-function isNotification(req) {
-  return req.id === void 0;
-}
-function hasValidJsonRpcId(req) {
-  const id = req.id;
-  if (id === void 0) return true;
-  return typeof id === "string" || typeof id === "number" && Number.isInteger(id);
-}
-function isPlainObject(v) {
-  return typeof v === "object" && v !== null && !Array.isArray(v);
-}
-function toolAnnotations(t) {
-  const annotations = {};
-  if (typeof t.readOnly === "boolean") annotations.readOnlyHint = t.readOnly;
-  if (typeof t.destructive === "boolean") annotations.destructiveHint = t.destructive;
-  return annotations;
-}
-async function dispatchJsonRpc(req, opts) {
-  if (!hasValidJsonRpcId(req)) {
-    return jsonRpcError(
-      null,
-      JSON_RPC_INVALID_REQUEST,
-      "Invalid Request: `id` must be a string or an integer"
-    );
-  }
-  const response = await dispatchMethod(req, opts);
-  return isNotification(req) ? null : response;
-}
-async function dispatchMethod(req, opts) {
-  const id = req.id ?? null;
-  switch (req.method) {
-    case "initialize": {
-      const requested = req.params?.protocolVersion;
-      if (typeof requested !== "string") {
-        return jsonRpcError(
-          id,
-          JSON_RPC_INVALID_PARAMS,
-          "initialize requires a string `protocolVersion` parameter"
-        );
-      }
-      const protocolVersion = SUPPORTED_PROTOCOL_VERSIONS.includes(
-        requested
-      ) ? requested : LATEST_SUPPORTED_PROTOCOL_VERSION;
-      return jsonRpcResult(id, {
-        protocolVersion,
-        capabilities: { tools: {} },
-        serverInfo: opts.serverInfo
-      });
-    }
-    case "notifications/initialized":
-      return jsonRpcResult(id, {});
-    case "tools/list":
-      return jsonRpcResult(id, {
-        tools: opts.tools.map((t) => ({
-          name: t.name,
-          description: t.description,
-          inputSchema: t.inputSchema,
-          annotations: toolAnnotations(t)
-        }))
-      });
-    case "tools/call": {
-      const params = req.params;
-      if (!params || typeof params.name !== "string") {
-        return jsonRpcError(id, JSON_RPC_INVALID_PARAMS, "tools/call requires a `name` parameter");
-      }
-      const rawArgs = params.arguments;
-      if (rawArgs !== void 0 && !isPlainObject(rawArgs)) {
-        return jsonRpcError(
-          id,
-          JSON_RPC_INVALID_PARAMS,
-          "tools/call `arguments` must be an object"
-        );
-      }
-      const tool = opts.tools.find((t) => t.name === params.name);
-      if (!tool) {
-        return jsonRpcError(id, JSON_RPC_METHOD_NOT_FOUND, `unknown tool: ${params.name}`);
-      }
-      const ctx = opts.getContext();
-      try {
-        const result = await tool.handler(rawArgs ?? {}, ctx);
-        return jsonRpcResult(id, {
-          content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
-        });
-      } catch (err) {
-        const rawMessage = err instanceof Error ? err.message : String(err);
-        console.error("[mcp-jsonrpc] tool dispatch failed", {
-          tool: params.name,
-          message: rawMessage
-        });
-        const message = opts.formatToolError ? opts.formatToolError(err) : rawMessage;
-        return jsonRpcResult(id, {
-          isError: true,
-          content: [{ type: "text", text: message }]
-        });
-      }
-    }
-    default:
-      return jsonRpcError(id, JSON_RPC_METHOD_NOT_FOUND, `Method not found: ${req.method}`);
-  }
-}
+import {
+  JSON_RPC_INTERNAL_ERROR,
+  JSON_RPC_INVALID_PARAMS,
+  JSON_RPC_INVALID_REQUEST,
+  JSON_RPC_METHOD_NOT_FOUND,
+  JSON_RPC_PARSE_ERROR,
+  LATEST_SUPPORTED_PROTOCOL_VERSION,
+  MAX_BATCH,
+  SUPPORTED_PROTOCOL_VERSIONS,
+  ToolUserError,
+  dispatchJsonRpc,
+  dispatchJsonRpcMessage,
+  hasValidJsonRpcId,
+  isToolUserError,
+  jsonRpcError,
+  jsonRpcResult
+} from "../chunk-4REBPD2N.js";
 export {
   JSON_RPC_INTERNAL_ERROR,
   JSON_RPC_INVALID_PARAMS,
@@ -121,9 +22,13 @@ export {
   JSON_RPC_METHOD_NOT_FOUND,
   JSON_RPC_PARSE_ERROR,
   LATEST_SUPPORTED_PROTOCOL_VERSION,
+  MAX_BATCH,
   SUPPORTED_PROTOCOL_VERSIONS,
+  ToolUserError,
   dispatchJsonRpc,
+  dispatchJsonRpcMessage,
   hasValidJsonRpcId,
+  isToolUserError,
   jsonRpcError,
   jsonRpcResult
 };

package/dist/public/index.js

@@ -1,3 +1,7 @@
+import {
+  ToolUserError
+} from "../chunk-4REBPD2N.js";
+
 // src/public/types.ts
 function toPublicSummary(post) {
   const summary = {
@@ -28,33 +32,33 @@ function clampInt(v, fallback, min, max) {
 }
 function validateSlug(v) {
   if (typeof v !== "string") {
-    throw new Error("`slug` is required and must be a string");
+    throw new ToolUserError("`slug` is required and must be a string");
   }
   if (v.length === 0) {
-    throw new Error("`slug` must not be empty");
+    throw new ToolUserError("`slug` must not be empty");
   }
   if (v.length > MAX_SLUG_LEN) {
-    throw new Error(`\`slug\` must be at most ${MAX_SLUG_LEN} characters`);
+    throw new ToolUserError(`\`slug\` must be at most ${MAX_SLUG_LEN} characters`);
   }
   return v;
 }
 function validateCursor(v) {
   if (v === void 0 || v === null) return void 0;
   if (typeof v !== "string") {
-    throw new Error("`cursor` must be a string");
+    throw new ToolUserError("`cursor` must be a string");
   }
   if (v.length > MAX_CURSOR_LEN) {
-    throw new Error(`\`cursor\` must be at most ${MAX_CURSOR_LEN} characters`);
+    throw new ToolUserError(`\`cursor\` must be at most ${MAX_CURSOR_LEN} characters`);
   }
   return v;
 }
 function validateQuery(v) {
   if (typeof v !== "string") {
-    throw new Error("`query` is required and must be a string");
+    throw new ToolUserError("`query` is required and must be a string");
   }
   const trimmed = v.trim();
   if (trimmed.length === 0) {
-    throw new Error("`query` must not be empty");
+    throw new ToolUserError("`query` must not be empty");
   }
   return trimmed.length > MAX_QUERY_LEN ? trimmed.slice(0, MAX_QUERY_LEN) : trimmed;
 }
@@ -134,7 +138,7 @@ var getPostTool = {
     const frontmatter = typeof args.frontmatter === "boolean" ? args.frontmatter : true;
     const post = await ctx.getPublishedPost(slug);
     if (!post) {
-      throw new Error(`No published post found for slug: ${slug}`);
+      throw new ToolUserError("No published post found for the requested slug.");
     }
     const summary = toPublicSummary(post);
     const rendered = await ctx.postToMarkdown(post, { frontmatter });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ampless/mcp-server",
-  "version": "1.0.0-beta.66",
+  "version": "1.0.0-beta.68",
   "description": "MCP tool registry shared by @ampless/backend mcp-handler Lambda. Installed transitively via @ampless/admin / @ampless/backend; no direct install needed.",
   "publishConfig": {
     "access": "public"
@@ -34,7 +34,7 @@
   "bugs": "https://github.com/heavymoons/ampless/issues",
   "dependencies": {
     "fflate": "^0.8.3",
-    "ampless": "1.0.0-beta.59"
+    "ampless": "1.0.0-beta.61"
   },
   "keywords": [
     "ampless",
@@ -45,6 +45,7 @@
     "build": "tsup",
     "dev": "tsup --watch",
     "lint": "tsc --noEmit",
-    "test": "vitest run --passWithNoTests"
+    "test": "vitest run --passWithNoTests",
+    "test:dist": "node scripts/tool-user-error-dist-smoke.mjs"
   }
 }