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

package/README.ja.md

@@ -71,13 +71,19 @@ 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, 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` を使うこと |
+| `MAX_BATCH` | batch 要素数の既定上限（`50`） |
 | `jsonRpcResult` / `jsonRpcError` / `JSON_RPC_*` | エンベロープヘルパ + 標準エラーコード |
 | `SUPPORTED_PROTOCOL_VERSIONS` | `['2025-03-26', '2024-11-05']` |
 

package/README.md

@@ -71,13 +71,19 @@ 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, 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. |
+| `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/jsonrpc/index.d.ts

@@ -65,6 +65,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 +126,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, dispatchJsonRpc, dispatchJsonRpcMessage, hasValidJsonRpcId, jsonRpcError, jsonRpcResult };

package/dist/jsonrpc/index.js

@@ -25,6 +25,69 @@ function hasValidJsonRpcId(req) {
 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;
@@ -121,8 +184,10 @@ export {
   JSON_RPC_METHOD_NOT_FOUND,
   JSON_RPC_PARSE_ERROR,
   LATEST_SUPPORTED_PROTOCOL_VERSION,
+  MAX_BATCH,
   SUPPORTED_PROTOCOL_VERSIONS,
   dispatchJsonRpc,
+  dispatchJsonRpcMessage,
   hasValidJsonRpcId,
   jsonRpcError,
   jsonRpcResult

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ampless/mcp-server",
-  "version": "1.0.0-beta.66",
+  "version": "1.0.0-beta.67",
   "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.60"
   },
   "keywords": [
     "ampless",