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

package/README.ja.md

@@ -10,14 +10,16 @@
 ## 全体の構成
 
 ```
-MCP クライアント (.mcp.json)
-  └── HTTP Bearer トークン (amk_...)
-        └── mcp-handler Lambda (packages/backend/src/functions/mcp-handler.ts)
-              └── @ampless/mcp-server/tools  ← このパッケージ
-                    └── ToolDefinition[], dispatchToolCall
+Admin MCP:  クライアント (.mcp.json) ── Bearer amk_… ──▶ mcp-handler Lambda (@ampless/backend)
+                                                          ├── @ampless/mcp-server/tools    (admin ツールレジストリ)
+                                                          └── @ampless/mcp-server/jsonrpc  (共有 JSON-RPC dispatch)
+
+Public MCP: 匿名クライアント ────────────────────────▶ /api/mcp ルート (@ampless/runtime)
+                                                          ├── @ampless/mcp-server/public   (読み取り専用ツール)
+                                                          └── @ampless/mcp-server/jsonrpc  (共有 JSON-RPC dispatch)
 ```
 
-`mcp-handler` Lambda は Bearer トークンを `McpToken` AppSync モデル（admin 専用）に照合し、`ToolContext`（GraphQL クライアント + S3 クライアント + サイトコンテキスト）を構築して、各ツール呼び出しをこのパッケージの `dispatchToolCall` に委譲します。
+admin の `mcp-handler` Lambda は Bearer トークンを `McpToken` AppSync モデル（admin 専用）に照合し、`ToolContext`（GraphQL クライアント + S3 クライアント + サイトコンテキスト）を構築して、各リクエストを共有 `dispatchJsonRpc` で admin の `tools` レジストリに対して実行します。公開 runtime ルートは読み取り専用の `PublicToolContext` を注入し、同じ `dispatchJsonRpc` を `publicTools` に対して実行します — トークン不要・公開投稿のみ。
 
 エンドユーザーは管理画面経由で MCP を設定します：
 
@@ -43,6 +45,14 @@ HTTP MCP のアーキテクチャ全体については `docs/architecture/04-acc
 
 ## エクスポート
 
+3 つのサブパスエントリ：
+
+| サブパス | 用途 |
+|---|---|
+| `@ampless/mcp-server/tools` | admin ツールレジストリ（トークン認証、フル read/write） |
+| `@ampless/mcp-server/jsonrpc` | 両エンドポイントで共有するトランスポート非依存の JSON-RPC 2.0 dispatch |
+| `@ampless/mcp-server/public` | 読み取り専用の公開ツール（匿名、公開投稿のみ） |
+
 ### `./tools`
 
 ```typescript
@@ -52,27 +62,64 @@ import type { ToolDefinition, ToolContext, ResolvedSite } from '@ampless/mcp-ser
 
 | エクスポート | 説明 |
 |---|---|
-| `getTools()` | `ToolDefinition` オブジェクトのリスト（name、description、inputSchema）を返す |
-| `dispatchToolCall(name, args, ctx)` | 名前でツール呼び出しをディスパッチする。不明なツール名の場合は例外をスロー |
-| `ToolDefinition` | 単一ツールのインターフェース（name、description、inputSchema、handler） |
-| `ToolContext` | ランタイムコンテキストのインターフェース（graphql、storage、site） |
-| `ResolvedSite` | 解決済みサイトコンテキストのインターフェース（name、url、environment、siteId） |
+| `tools` / `getTools()` | admin の `ToolDefinition[]` レジストリ |
+| `dispatchToolCall(name, args, ctx)` | 名前でツールを引いて handler を呼ぶ（不明なら `null`） |
+| `ToolDefinition<TCtx>` | 単一ツール（name、description、inputSchema、handler、`readOnly?`、`destructive?`） |
+| `ToolContext` | admin ランタイムコンテキスト（graphql、storage、site） |
+| `ResolvedSite` | 解決済みサイトコンテキスト（name、url、environment、siteId） |
+
+### `./jsonrpc`
+
+```typescript
+import { dispatchJsonRpc } from '@ampless/mcp-server/jsonrpc'
+import type { JsonRpcRequest, JsonRpcResponse } 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` で拒否 |
+| `jsonRpcResult` / `jsonRpcError` / `JSON_RPC_*` | エンベロープヘルパ + 標準エラーコード |
+| `SUPPORTED_PROTOCOL_VERSIONS` | `['2025-03-26', '2024-11-05']` |
+
+### `./public`
+
+```typescript
+import { publicTools } from '@ampless/mcp-server/public'
+import type { PublicToolContext } from '@ampless/mcp-server/public'
+```
+
+| エクスポート | 説明 |
+|---|---|
+| `publicTools` | 読み取り専用の 4 ツール（`ToolDefinition<PublicToolContext>`） |
+| `PublicToolContext` | runtime が注入する最小の読み取り面（`listPublishedPosts` / `getPublishedPost` / `postToMarkdown`） |
+| `toPublicSummary` | `Post` のフィールド allowlist 射影 |
 
 ## ツール一覧
 
+### Admin（`./tools`、トークン認証）
+
 | ツール | role | 説明 |
 |---|---|---|
-| `list_posts` | reader | 投稿の軽量サマリーを返す（body なし — 本文は `get_post` を使用）。検索/ソート/フィルター対応。`{ posts, total, offset, limit }` を返す |
+| `list_posts` | reader | 投稿の軽量サマリー（body なし — 本文は `get_post`）。検索/ソート/フィルター対応。`{ posts, total, offset, limit }` を返す |
 | `get_post` | reader | slug または postId で単一の投稿を取得 |
 | `create_post` | editor | 新しい投稿を作成（下書きまたは公開済み） |
 | `update_post` | editor | 既存の投稿のフィールドをパッチ更新 |
 | `delete_post` | editor | 投稿を削除しタグインデックスをクリーンアップ |
-| `upload_media` | editor | Base64 エンコードされたバイト列を S3 にアップロードし Media レコードを作成 |
-| `list_media` | reader | メディア一覧を取得。`mimeType`（前方一致）/ `prefix` / `createdAfter` / `createdBefore` フィルターとページネーション対応 |
+| `upload_media` | editor | Base64 バイト列を S3 にアップロードし Media レコードを作成 |
+| `list_media` | reader | メディア一覧。`mimeType`（前方一致）/ `prefix` / `createdAfter` / `createdBefore` フィルターとページネーション対応 |
 | `search_media` | reader | ファイル名 / `src` / `mimeType` への部分一致でメディアを検索 |
-| `delete_media` | editor | メディアファイルを削除（S3 オブジェクト + Media 行）。`mediaId` または `src` で指定。`dryRun: true` で削除せずにプレビュー |
+| `delete_media` | editor | メディアファイルを削除（S3 オブジェクト + Media 行）。`mediaId` または `src` で指定。`dryRun: true` でプレビュー |
 | `get_schema` | reader | CMS コンテンツスキーマを返す |
-| `upload_static_bundle` | editor | ビルド済み静的バンドルを S3 にアップロード |
-| `list_static_files` | reader | 静的バンドルファイルを一覧表示 |
-| `delete_static_file` | editor | 静的ファイルを S3 から削除 |
-| `get_site_context` | reader | 現在のサイトコンテキスト（name、url、environment）を返す |
+| `upload_static_bundle` | editor | ビルド済み静的バンドル（zip）を S3 に 1 発でアップロード |
+| `upload_static_file` | editor | 静的バンドルの S3 プレフィックスに 1 ファイルずつ差分アップロード |
+| `delete_static_file` | editor | 静的バンドルの S3 プレフィックスからファイルを差分削除 |
+| `commit_static_post` | editor | S3 プレフィックスから Post manifest を再構築（"save" ステップ） |
+
+### Public（`./public`、匿名、公開投稿のみ）
+
+| ツール | 説明 |
+|---|---|
+| `list_posts` | 新しい順の公開投稿サマリー 1 ページ + 不透明な `nextCursor` |
+| `get_post` | slug で公開投稿 1 件、本文を `markdown` にレンダリング（10 万字超は切り詰め） |
+| `search_posts` | 有界走査に対する title / slug / tags / excerpt への大小無視部分一致 |
+| `list_tags` | 同じ有界走査でのタグ出現数（降順） |

package/README.md

@@ -10,14 +10,16 @@ MCP tool registry for [ampless](https://github.com/heavymoons/ampless).
 ## How it fits together
 
 ```
-MCP client (.mcp.json)
-  └── HTTP Bearer token (amk_...)
-        └── mcp-handler Lambda (packages/backend/src/functions/mcp-handler.ts)
-              └── @ampless/mcp-server/tools  ← this package
-                    └── ToolDefinition[], dispatchToolCall
+Admin MCP:  client (.mcp.json) ── Bearer amk_… ──▶ mcp-handler Lambda (@ampless/backend)
+                                                     ├── @ampless/mcp-server/tools    (admin tool registry)
+                                                     └── @ampless/mcp-server/jsonrpc  (shared JSON-RPC dispatch)
+
+Public MCP: anonymous client ──────────────────▶ /api/mcp route (@ampless/runtime)
+                                                     ├── @ampless/mcp-server/public   (read-only tools)
+                                                     └── @ampless/mcp-server/jsonrpc  (shared JSON-RPC dispatch)
 ```
 
-The `mcp-handler` Lambda resolves the Bearer token against the `McpToken` AppSync model (admin-only), builds a `ToolContext` (GraphQL client + S3 client + site context), and delegates each incoming tool call to `dispatchToolCall` from this package.
+The admin `mcp-handler` Lambda resolves the Bearer token against the `McpToken` AppSync model (admin-only), builds a `ToolContext` (GraphQL client + S3 client + site context), and runs each request through the shared `dispatchJsonRpc` over the admin `tools` registry. The public runtime route injects a read-only `PublicToolContext` and runs the same `dispatchJsonRpc` over `publicTools` — no token, published posts only.
 
 End users configure MCP via the admin UI:
 
@@ -43,6 +45,14 @@ See `docs/architecture/04-access-layer-mcp.md` for the full HTTP MCP architectur
 
 ## Exports
 
+Three subpath entries:
+
+| Subpath | Purpose |
+|---|---|
+| `@ampless/mcp-server/tools` | Admin tool registry (token-authenticated, full read/write) |
+| `@ampless/mcp-server/jsonrpc` | Transport-agnostic JSON-RPC 2.0 dispatch shared by both endpoints |
+| `@ampless/mcp-server/public` | Read-only public tools (anonymous, published posts only) |
+
 ### `./tools`
 
 ```typescript
@@ -52,17 +62,45 @@ import type { ToolDefinition, ToolContext, ResolvedSite } from '@ampless/mcp-ser
 
 | Export | Description |
 |---|---|
-| `getTools()` | Returns the list of `ToolDefinition` objects (name, description, inputSchema) |
-| `dispatchToolCall(name, args, ctx)` | Dispatches a tool call by name; throws if unknown |
-| `ToolDefinition` | Interface for a single tool (name, description, inputSchema, handler) |
-| `ToolContext` | Interface for the runtime context (graphql, storage, site) |
-| `ResolvedSite` | Interface for the resolved site context (name, url, environment, siteId) |
+| `tools` / `getTools()` | The admin `ToolDefinition[]` registry |
+| `dispatchToolCall(name, args, ctx)` | Look up a tool by name and invoke its handler (returns `null` if unknown) |
+| `ToolDefinition<TCtx>` | A single tool (name, description, inputSchema, handler, `readOnly?`, `destructive?`) |
+| `ToolContext` | Admin runtime context (graphql, storage, site) |
+| `ResolvedSite` | Resolved site context (name, url, environment, siteId) |
+
+### `./jsonrpc`
+
+```typescript
+import { dispatchJsonRpc } from '@ampless/mcp-server/jsonrpc'
+import type { JsonRpcRequest, JsonRpcResponse } 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`. |
+| `jsonRpcResult` / `jsonRpcError` / `JSON_RPC_*` | Envelope helpers + standard error codes |
+| `SUPPORTED_PROTOCOL_VERSIONS` | `['2025-03-26', '2024-11-05']` |
+
+### `./public`
+
+```typescript
+import { publicTools } from '@ampless/mcp-server/public'
+import type { PublicToolContext } from '@ampless/mcp-server/public'
+```
+
+| Export | Description |
+|---|---|
+| `publicTools` | The four read-only `ToolDefinition<PublicToolContext>` tools |
+| `PublicToolContext` | The minimal read-only surface the runtime injects (`listPublishedPosts` / `getPublishedPost` / `postToMarkdown`) |
+| `toPublicSummary` | Explicit field-allowlist projection of a `Post` |
 
 ## Tools
 
+### Admin (`./tools`, token-authenticated)
+
 | Tool | Role | Description |
 |---|---|---|
-| `list_posts` | reader | Returns lightweight post summaries (no body — use `get_post` for content) with search / sort / filters. Returns `{ posts, total, offset, limit }` |
+| `list_posts` | reader | Lightweight post summaries (no body — use `get_post`) with search / sort / filters. Returns `{ posts, total, offset, limit }` |
 | `get_post` | reader | Fetch a single post by slug or postId |
 | `create_post` | editor | Create a new post (draft or published) |
 | `update_post` | editor | Patch fields on an existing post |
@@ -70,9 +108,18 @@ import type { ToolDefinition, ToolContext, ResolvedSite } from '@ampless/mcp-ser
 | `upload_media` | editor | Upload base64-encoded bytes to S3 and create a Media record |
 | `list_media` | reader | List media with optional `mimeType` (prefix) / `prefix` / `createdAfter` / `createdBefore` filters + pagination |
 | `search_media` | reader | Search media by substring across filename / `src` / `mimeType` |
-| `delete_media` | editor | Delete a media file (S3 object + Media row). Pass `mediaId` or `src`; `dryRun: true` previews without deleting |
+| `delete_media` | editor | Delete a media file (S3 object + Media row). Pass `mediaId` or `src`; `dryRun: true` previews |
 | `get_schema` | reader | Return the CMS content schema |
-| `upload_static_bundle` | editor | Upload a pre-built static bundle to S3 |
-| `list_static_files` | reader | List static bundle files |
-| `delete_static_file` | editor | Delete a static file from S3 |
-| `get_site_context` | reader | Return current site context (name, url, environment) |
+| `upload_static_bundle` | editor | Upload a pre-built static bundle (zip) to S3 in one shot |
+| `upload_static_file` | editor | Incrementally write a single file into a static bundle's S3 prefix |
+| `delete_static_file` | editor | Incrementally delete a file from a static bundle's S3 prefix |
+| `commit_static_post` | editor | Rebuild the Post manifest from the S3 prefix (the "save" step) |
+
+### Public (`./public`, anonymous, published posts only)
+
+| Tool | Description |
+|---|---|
+| `list_posts` | One page of newest-first published-post summaries + opaque `nextCursor` |
+| `get_post` | A single published post by slug, body rendered to `markdown` (truncated past 100k chars) |
+| `search_posts` | Case-insensitive substring over title / slug / tags / excerpt across a bounded scan |
+| `list_tags` | Tag occurrence counts (descending) over the same bounded scan |

package/dist/jsonrpc/index.d.ts

@@ -0,0 +1,80 @@
+import { ToolDefinition } from '../tools/index.js';
+import 'ampless';
+
+declare const JSON_RPC_PARSE_ERROR = -32700;
+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 SUPPORTED_PROTOCOL_VERSIONS: readonly ["2025-03-26", "2024-11-05"];
+declare const LATEST_SUPPORTED_PROTOCOL_VERSION: "2025-03-26";
+interface JsonRpcRequest {
+    jsonrpc: '2.0';
+    /**
+     * Absent (`undefined`) marks a JSON-RPC *notification*: per spec the
+     * server must not send any response (the method still executes). MCP
+     * forbids `id: null`, and JSON-RPC numeric ids SHOULD NOT contain
+     * fractional parts — `hasValidJsonRpcId` rejects both as
+     * INVALID_REQUEST before dispatch.
+     */
+    id?: number | string;
+    method: string;
+    params?: Record<string, unknown>;
+}
+interface JsonRpcResponse {
+    jsonrpc: '2.0';
+    id: number | string | null;
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+}
+declare function jsonRpcResult(id: JsonRpcResponse['id'], result: unknown): JsonRpcResponse;
+declare function jsonRpcError(id: JsonRpcResponse['id'], code: number, message: string, data?: unknown): JsonRpcResponse;
+interface JsonRpcDispatchOptions<TCtx> {
+    tools: readonly ToolDefinition<TCtx>[];
+    /**
+     * Resolves the tool context. Called lazily — only on a valid
+     * `tools/call` for a known tool — so `initialize` / `tools/list`
+     * never pay for client construction.
+     */
+    getContext: () => TCtx;
+    serverInfo: {
+        name: string;
+        version: string;
+    };
+    /**
+     * 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.
+     */
+    formatToolError?: (err: unknown) => string;
+}
+/**
+ * Validates the `id` member of a decoded request envelope. A valid id
+ * is a string or an integer number; an *absent* id is also valid (it
+ * marks a notification — JSON cannot express `undefined`, so a
+ * present-but-undefined id from an in-process caller is treated the
+ * same). MCP explicitly forbids `id: null`, and the JSON-RPC 2.0 spec
+ * says numeric ids SHOULD NOT contain fractional parts — both are
+ * rejected (callers map `false` to INVALID_REQUEST). Exported so each
+ * transport's pre-dispatch envelope check enforces the same rule as
+ * `dispatchJsonRpc` itself.
+ */
+declare function hasValidJsonRpcId(req: object): boolean;
+/**
+ * Dispatch one parsed JSON-RPC request against a tool registry.
+ * Returns the response envelope, or `null` for a notification (the
+ * caller maps that to an empty 202/no-body HTTP response).
+ *
+ * Notification suppression is centralised here: a notification (id
+ * absent) still *executes* its method — including a `tools/call`
+ * handler and its side effects — but the response envelope is
+ * discarded, per the JSON-RPC 2.0 spec.
+ */
+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 };

package/dist/jsonrpc/index.js

@@ -0,0 +1,129 @@
+// 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}`);
+  }
+}
+export {
+  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,
+  SUPPORTED_PROTOCOL_VERSIONS,
+  dispatchJsonRpc,
+  hasValidJsonRpcId,
+  jsonRpcError,
+  jsonRpcResult
+};

package/dist/public/index.d.ts

@@ -0,0 +1,51 @@
+import { ToolDefinition } from '../tools/index.js';
+import { Post } from 'ampless';
+
+/**
+ * The minimal, read-only surface the public MCP tools need. The runtime
+ * (`@ampless/runtime`, PR-8) injects a concrete implementation backed by
+ * its apiKey-mode `listPublishedPosts` / `getPublishedPost` (which strip
+ * drafts server-side) and `postToMarkdown`.
+ *
+ * `listPostsByTag` is intentionally excluded: `list_tags` is served by
+ * scanning + aggregating the published index, so the tool layer never
+ * needs a tag-name-keyed lookup. Keeping the injected surface to three
+ * methods minimises PR-8's wiring.
+ */
+interface PublicToolContext {
+    listPublishedPosts(opts: {
+        limit?: number;
+        nextToken?: string;
+    }): Promise<{
+        items: Post[];
+        nextToken: string | null;
+    }>;
+    getPublishedPost(slug: string): Promise<Post | null>;
+    postToMarkdown(post: Post, opts?: {
+        frontmatter?: boolean;
+    }): Promise<string>;
+}
+/**
+ * Field allowlist surfaced to anonymous callers. Deliberately omits
+ * `postId`, `status`, `metadata`, and `body` — see `toPublicSummary`.
+ */
+interface PublicPostSummary {
+    slug: string;
+    title: string;
+    excerpt?: string;
+    tags?: string[];
+    publishedAt?: string;
+    updatedAt?: string;
+    format: string;
+}
+/**
+ * Explicit pick — the core of the leakage defence. Never spread a
+ * `Post` into the response: only the allowlisted fields below reach an
+ * anonymous caller. `postId` / `status` / `metadata` / `body` are never
+ * copied.
+ */
+declare function toPublicSummary(post: Post): PublicPostSummary;
+
+declare const publicTools: readonly ToolDefinition<PublicToolContext>[];
+
+export { type PublicPostSummary, type PublicToolContext, publicTools, toPublicSummary };

package/dist/public/index.js

@@ -0,0 +1,228 @@
+// src/public/types.ts
+function toPublicSummary(post) {
+  const summary = {
+    slug: post.slug,
+    title: post.title,
+    format: post.format
+  };
+  if (post.excerpt !== void 0) summary.excerpt = post.excerpt;
+  if (post.tags !== void 0) summary.tags = post.tags;
+  if (post.publishedAt !== void 0) summary.publishedAt = post.publishedAt;
+  if (post.updatedAt !== void 0) summary.updatedAt = post.updatedAt;
+  return summary;
+}
+
+// src/public/shared.ts
+import { collectBounded } from "ampless";
+var MAX_BODY_CHARS = 1e5;
+var SEARCH_SCAN_LIMIT = 200;
+var PUBLIC_PAGE_SIZE_CAP = 50;
+var PUBLIC_SCAN_MAX_PAGES = 5;
+var MAX_SLUG_LEN = 512;
+var MAX_CURSOR_LEN = 4096;
+var MAX_QUERY_LEN = 256;
+function clampInt(v, fallback, min, max) {
+  const n = Number(v);
+  if (!Number.isFinite(n)) return fallback;
+  return Math.min(max, Math.max(min, Math.trunc(n)));
+}
+function validateSlug(v) {
+  if (typeof v !== "string") {
+    throw new Error("`slug` is required and must be a string");
+  }
+  if (v.length === 0) {
+    throw new Error("`slug` must not be empty");
+  }
+  if (v.length > MAX_SLUG_LEN) {
+    throw new Error(`\`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");
+  }
+  if (v.length > MAX_CURSOR_LEN) {
+    throw new Error(`\`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");
+  }
+  const trimmed = v.trim();
+  if (trimmed.length === 0) {
+    throw new Error("`query` must not be empty");
+  }
+  return trimmed.length > MAX_QUERY_LEN ? trimmed.slice(0, MAX_QUERY_LEN) : trimmed;
+}
+async function scanRecentPublished(ctx) {
+  const { items, truncated } = await collectBounded(
+    (args) => ctx.listPublishedPosts({ limit: args.limit, nextToken: args.nextToken }),
+    {
+      limit: SEARCH_SCAN_LIMIT,
+      pageSizeCap: PUBLIC_PAGE_SIZE_CAP,
+      maxPages: PUBLIC_SCAN_MAX_PAGES
+    }
+  );
+  return { posts: items, scanTruncated: truncated !== null };
+}
+
+// src/public/list-posts.ts
+var DEFAULT_LIMIT = 20;
+var MIN_LIMIT = 1;
+var MAX_LIMIT = 50;
+var listPostsSchema = {
+  type: "object",
+  properties: {
+    limit: {
+      type: "integer",
+      minimum: MIN_LIMIT,
+      maximum: MAX_LIMIT,
+      description: `Max posts to return (${MIN_LIMIT}\u2013${MAX_LIMIT}, default ${DEFAULT_LIMIT})`
+    },
+    cursor: {
+      type: "string",
+      maxLength: MAX_CURSOR_LEN,
+      description: "Opaque pagination cursor from a previous call (`nextCursor`)"
+    }
+  }
+};
+var listPostsTool = {
+  name: "list_posts",
+  description: "List published posts, newest first (read-only, published posts only). Returns lightweight summaries (no body \u2014 use get_post for content) and an opaque `nextCursor` for pagination. Args: `limit` (1\u201350, default 20), `cursor` (from a previous response).",
+  inputSchema: listPostsSchema,
+  readOnly: true,
+  destructive: false,
+  handler: async (args, ctx) => {
+    const limit = clampInt(args.limit, DEFAULT_LIMIT, MIN_LIMIT, MAX_LIMIT);
+    const cursor = validateCursor(args.cursor);
+    const { items, nextToken } = await ctx.listPublishedPosts({ limit, nextToken: cursor });
+    return {
+      posts: items.map(toPublicSummary),
+      nextCursor: nextToken
+    };
+  }
+};
+
+// src/public/get-post.ts
+var getPostSchema = {
+  type: "object",
+  properties: {
+    slug: {
+      type: "string",
+      maxLength: MAX_SLUG_LEN,
+      description: "Slug of the published post to fetch"
+    },
+    frontmatter: {
+      type: "boolean",
+      description: "Include YAML frontmatter in the markdown (default true)"
+    }
+  },
+  required: ["slug"]
+};
+var getPostTool = {
+  name: "get_post",
+  description: "Fetch a single published post by slug (read-only, published posts only). Returns the summary fields plus the post body rendered to `markdown`. Args: `slug` (required), `frontmatter` (default true). Errors if no published post matches the slug. Very long bodies are truncated (`truncated: true`).",
+  inputSchema: getPostSchema,
+  readOnly: true,
+  destructive: false,
+  handler: async (args, ctx) => {
+    const slug = validateSlug(args.slug);
+    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}`);
+    }
+    const summary = toPublicSummary(post);
+    const rendered = await ctx.postToMarkdown(post, { frontmatter });
+    const truncated = rendered.length > MAX_BODY_CHARS;
+    const markdown = truncated ? rendered.slice(0, MAX_BODY_CHARS) : rendered;
+    return { ...summary, markdown, truncated };
+  }
+};
+
+// src/public/search-posts.ts
+var DEFAULT_LIMIT2 = 10;
+var MIN_LIMIT2 = 1;
+var MAX_LIMIT2 = 20;
+var searchPostsSchema = {
+  type: "object",
+  properties: {
+    query: {
+      type: "string",
+      minLength: 1,
+      maxLength: MAX_QUERY_LEN,
+      description: "Case-insensitive substring matched against title / slug / tags / excerpt"
+    },
+    limit: {
+      type: "integer",
+      minimum: MIN_LIMIT2,
+      maximum: MAX_LIMIT2,
+      description: `Max matches to return (${MIN_LIMIT2}\u2013${MAX_LIMIT2}, default ${DEFAULT_LIMIT2})`
+    }
+  },
+  required: ["query"]
+};
+function matchesQuery(post, needle) {
+  const haystacks = [post.title, post.slug];
+  if (post.excerpt) haystacks.push(post.excerpt);
+  if (post.tags) haystacks.push(...post.tags);
+  return haystacks.some((h) => h.toLowerCase().includes(needle));
+}
+var searchPostsTool = {
+  name: "search_posts",
+  description: "Search published posts by case-insensitive substring over title / slug / tags / excerpt (read-only, published posts only; body text is not searched). Scans a bounded window of the most recent posts. Args: `query` (required, 1\u2013256 chars), `limit` (1\u201320, default 10). `scanTruncated: true` means older posts were beyond the scan window.",
+  inputSchema: searchPostsSchema,
+  readOnly: true,
+  destructive: false,
+  handler: async (args, ctx) => {
+    const query = validateQuery(args.query);
+    const limit = clampInt(args.limit, DEFAULT_LIMIT2, MIN_LIMIT2, MAX_LIMIT2);
+    const needle = query.toLowerCase();
+    const { posts, scanTruncated } = await scanRecentPublished(ctx);
+    const matches = posts.filter((post) => matchesQuery(post, needle)).slice(0, limit);
+    return {
+      posts: matches.map(toPublicSummary),
+      scanTruncated
+    };
+  }
+};
+
+// src/public/list-tags.ts
+var listTagsSchema = {
+  type: "object",
+  properties: {}
+};
+var listTagsTool = {
+  name: "list_tags",
+  description: "List tags used by published posts with occurrence counts, most frequent first (read-only, published posts only). Aggregated over a bounded scan of the most recent posts. Returns `{ tags: [{ tag, count }], scanTruncated }`; `scanTruncated: true` means counts cover only the scan window.",
+  inputSchema: listTagsSchema,
+  readOnly: true,
+  destructive: false,
+  handler: async (_args, ctx) => {
+    const { posts, scanTruncated } = await scanRecentPublished(ctx);
+    const counts = /* @__PURE__ */ new Map();
+    for (const post of posts) {
+      for (const tag of post.tags ?? []) {
+        counts.set(tag, (counts.get(tag) ?? 0) + 1);
+      }
+    }
+    const tags = [...counts.entries()].map(([tag, count]) => ({ tag, count })).sort((a, b) => b.count - a.count || a.tag.localeCompare(b.tag));
+    return { tags, scanTruncated };
+  }
+};
+
+// src/public/index.ts
+var publicTools = [
+  listPostsTool,
+  getPostTool,
+  searchPostsTool,
+  listTagsTool
+];
+export {
+  publicTools,
+  toPublicSummary
+};

package/dist/{index.d.ts → tools/index.d.ts}

@@ -128,12 +128,24 @@ declare function extractZipFromBuffer(buffer: Uint8Array, opts?: ExtractZipOptio
  */
 declare function decodeUtf8(data: Uint8Array): string;
 
-interface ToolDefinition {
+interface ToolDefinition<TCtx = ToolContext> {
     name: string;
     description: string;
     inputSchema: Record<string, unknown>;
-    handler: (args: Record<string, unknown>, ctx: ToolContext) => Promise<unknown>;
+    handler: (args: Record<string, unknown>, ctx: TCtx) => Promise<unknown>;
+    /**
+     * `true` when the tool can destroy or irreversibly overwrite existing
+     * state. Surfaced as the MCP `destructiveHint` annotation. Left
+     * `undefined` only for tools that have not been classified — the
+     * shared dispatch then omits the hint so the spec default (`true`,
+     * the safe side) applies.
+     */
     destructive?: boolean;
+    /**
+     * `true` when the tool only reads and never mutates state. Surfaced
+     * as the MCP `readOnlyHint` annotation.
+     */
+    readOnly?: boolean;
 }
 declare const tools: ToolDefinition[];
 /**

package/dist/{index.js → tools/index.js}

@@ -1731,50 +1731,66 @@ var tools = [
     name: "list_posts",
     description: "Returns lightweight post summaries (no body \u2014 use get_post for content) with search / sort / filters. `total` reflects the filtered count. Supports query (substring over title/slug/tags), tag (exact), status, sort, limit (1\u2013100, default 20), offset (default 0).",
     inputSchema: listPostsSchema,
-    handler: (args, ctx) => listPosts(ctx.graphql, args)
+    handler: (args, ctx) => listPosts(ctx.graphql, args),
+    readOnly: true,
+    destructive: false
   },
   {
     name: "get_post",
     description: "Fetch a single post by slug or postId. Returns null if not found.",
     inputSchema: getPostSchema,
-    handler: (args, ctx) => getPost(ctx.graphql, args)
+    handler: (args, ctx) => getPost(ctx.graphql, args),
+    readOnly: true,
+    destructive: false
   },
   {
     name: "create_post",
     description: 'Create a new post. Title and slug are required. Body shape depends on format: tiptap=JSON node tree, markdown=source string, html=raw HTML string. Defaults to status=draft. Pass `metadata: { no_layout: true }` alongside format=html to publish the body as a bare HTML page with no theme chrome (middleware rewrites the /<slug> request to the internal bare-HTML handler). Pass `metadata: { cache: "deep" | "hot" }` to override the default cooldown-based cache strategy \u2014 see get_schema.notes.cacheStrategy for details.',
     inputSchema: createPostSchema,
-    handler: (args, ctx) => createPost(ctx.graphql, args)
+    handler: (args, ctx) => createPost(ctx.graphql, args),
+    readOnly: false,
+    destructive: false
   },
   {
     name: "update_post",
     description: "Update an existing post by postId. Only the fields you pass are changed. Tag list / publishedAt changes also update the PostTag denormalized index. Passing `metadata` REPLACES the existing object \u2014 call get_post first if you only want to add or change one key.",
     inputSchema: updatePostSchema,
-    handler: (args, ctx) => updatePost(ctx.graphql, args)
+    handler: (args, ctx) => updatePost(ctx.graphql, args),
+    readOnly: false,
+    // Overwrites an existing post's fields — not a pure additive write.
+    destructive: true
   },
   {
     name: "delete_post",
     description: "Delete a post by postId. Also drops associated PostTag index entries.",
     inputSchema: deletePostSchema,
     handler: (args, ctx) => deletePost(ctx.graphql, args),
+    readOnly: false,
     destructive: true
   },
   {
     name: "upload_media",
     description: "Upload a file to the site's media S3 bucket. Pass base64-encoded bytes; the server stores them verbatim under public/media/YYYY/MM/. Returns the public URL and Media record. The server does not transcode \u2014 pre-process (e.g. resize/webp) on the client.",
     inputSchema: uploadMediaSchema,
-    handler: (args, ctx) => uploadMedia(ctx.graphql, ctx.storage(), args)
+    handler: (args, ctx) => uploadMedia(ctx.graphql, ctx.storage(), args),
+    readOnly: false,
+    destructive: false
   },
   {
     name: "list_media",
     description: 'List media files in the CMS. Optional filters: `mimeType` (prefix match \u2014 "image/" matches all images, "image/png" only PNG), `prefix` (S3 key prefix on `src`, e.g. "public/media/2024/"), `createdAfter` / `createdBefore` (ISO 8601 date range). Returns up to `limit` rows (default 20) \u2014 each `{ mediaId, src, url, mimeType, size, createdAt, updatedAt }` \u2014 plus a `nextToken` cursor. Note: filters apply after the page read, so a page may return fewer than `limit` rows while a `nextToken` remains \u2014 follow the cursor. Use this to find media to delete without remembering `upload_media` responses.',
     inputSchema: listMediaSchema,
-    handler: (args, ctx) => listMedia(ctx.graphql, ctx.storage(), args)
+    handler: (args, ctx) => listMedia(ctx.graphql, ctx.storage(), args),
+    readOnly: true,
+    destructive: false
   },
   {
     name: "search_media",
     description: 'Search media by substring (case-sensitive `contains`) across `src` (which includes the filename) and `mimeType`. Pass `query` (e.g. "logo", ".png", "image/png"). Walks DynamoDB pages internally until it collects at least `limit` matches (default 20), exhausts the table, or hits its page cap \u2014 so `limit` is a soft target and the result may run slightly past it. Returns the same row shape as `list_media` plus `nextToken`; `truncated: true` means the page cap was hit with more to scan (pass `nextToken` back to continue).',
     inputSchema: searchMediaSchema,
-    handler: (args, ctx) => searchMedia(ctx.graphql, ctx.storage(), args)
+    handler: (args, ctx) => searchMedia(ctx.graphql, ctx.storage(), args),
+    readOnly: true,
+    destructive: false
   },
   {
     name: "delete_media",
@@ -1785,13 +1801,16 @@ var tools = [
       ctx.storage(),
       args
     ),
+    readOnly: false,
     destructive: true
   },
   {
     name: "get_schema",
     description: "Returns the CMS content schema (Post/Page/Media field shapes, format enum, notes). Useful as the first call to understand what fields are available.",
     inputSchema: getSchemaSchema,
-    handler: async () => getSchema()
+    handler: async () => getSchema(),
+    readOnly: true,
+    destructive: false
   },
   {
     name: "upload_static_bundle",
@@ -1802,6 +1821,7 @@ var tools = [
       ctx.storage(),
       args
     ),
+    readOnly: false,
     destructive: true
   },
   {
@@ -1811,7 +1831,10 @@ var tools = [
     handler: (args, ctx) => uploadStaticFile(
       ctx.storage(),
       args
-    )
+    ),
+    readOnly: false,
+    // Overwrites whatever file currently sits at that S3 key.
+    destructive: true
   },
   {
     name: "delete_static_file",
@@ -1821,6 +1844,7 @@ var tools = [
       ctx.storage(),
       args
     ),
+    readOnly: false,
     destructive: true
   },
   {
@@ -1831,7 +1855,10 @@ var tools = [
       ctx.graphql,
       ctx.storage(),
       args
-    )
+    ),
+    readOnly: false,
+    // Rebuilds (overwrites) the existing Post row's manifest.
+    destructive: true
   }
 ];
 async function dispatchToolCall(name, args, ctx) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ampless/mcp-server",
-  "version": "1.0.0-beta.64",
+  "version": "1.0.0-beta.66",
   "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"
@@ -9,8 +9,16 @@
   "type": "module",
   "exports": {
     "./tools": {
-      "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
+      "import": "./dist/tools/index.js",
+      "types": "./dist/tools/index.d.ts"
+    },
+    "./jsonrpc": {
+      "import": "./dist/jsonrpc/index.js",
+      "types": "./dist/jsonrpc/index.d.ts"
+    },
+    "./public": {
+      "import": "./dist/public/index.js",
+      "types": "./dist/public/index.d.ts"
     }
   },
   "files": [
@@ -26,7 +34,7 @@
   "bugs": "https://github.com/heavymoons/ampless/issues",
   "dependencies": {
     "fflate": "^0.8.3",
-    "ampless": "1.0.0-beta.57"
+    "ampless": "1.0.0-beta.59"
   },
   "keywords": [
     "ampless",