@ampless/mcp-server 1.0.0-alpha.16 → 1.0.0-alpha.18

package/README.ja.md

@@ -3,151 +3,73 @@
 
 # @ampless/mcp-server
 
-[ampless](https://github.com/heavymoons/ampless) 向け MCP（Model Context Protocol）サーバー。Claude Desktop、Cursor、Claude Code、その他 MCP 対応ツールから AI エージェントが CMS インスタンスの投稿を読み書きしたり、メディアをアップロードしたりできます。
+[ampless](https://github.com/heavymoons/ampless) 向け MCP ツールレジストリ。
 
-> **プレリリース / アルファ版。** v1.0 まではマイナーバージョンでも破壊的変更が入る可能性があります。
+**直接インストールする必要はありません。** `@ampless/backend` の `mcp-handler` Lambda が `./tools` サブパスエクスポート経由で使い、`@ampless/admin` / `@ampless/backend` を入れると推移的に付いてきます。
 
-## ツール一覧
-
-| ツール | 機能 |
-|---|---|
-| `list_posts` | オプションの `status` フィルターとページネーション付きで投稿一覧を取得 |
-| `get_post` | `slug` または `postId` で単一の投稿を取得 |
-| `create_post` | 新しい投稿を作成（下書きまたは公開済み） |
-| `update_post` | 既存の投稿のフィールドをパッチ更新 |
-| `delete_post` | 投稿を削除しタグインデックスをクリーンアップ |
-| `upload_media` | Base64 エンコードされたバイト列を S3 にアップロードし `Media` レコードを作成 |
-| `get_schema` | CMS コンテンツスキーマ（Post / Page / Media のフィールド形状）を返す |
-
-サーバーは指定した認証情報（環境変数）で Cognito ユーザープールにサインインするため、各ツールはそのユーザーのロール（`ampless-admin` または `ampless-editor`）で動作します。下書きや編集内容は認証済みユーザーにのみ表示されます。リゾルバー側の `status === 'published'` フィルターにより、未公開コンテンツはパブリック読み取りからは見えません。
-
-## インストール
-
-サーバーは Node CLI として公開されています。グローバルインストールは通常不要です — MCP クライアントから `npx -y @ampless/mcp-server@alpha` を指定してください。
-
-## 設定
-
-以下が必要です：
-
-1. **`amplify_outputs.json`** — `npx ampx sandbox` または `npx ampx pipeline-deploy` で生成されます。パスは `--outputs` で渡します。
-2. **Cognito ユーザーアカウント** — ユーザープールのメールアドレスとパスワード。管理 UI から最初に作成したユーザーは自動的に `ampless-admin` に登録されます。
-3. **AWS 認証情報** — `upload_media` を使用する場合にのみ必要です。デフォルトの認証情報チェーン（`AWS_PROFILE`、環境変数、インスタンスロール）が使用されます。読み取り専用ツールは AWS 認証情報なしで動作します。
-
-### Claude Desktop
-
-`~/Library/Application Support/Claude/claude_desktop_config.json`（macOS）またはプラットフォームに応じた同等のパスを編集します：
+## 全体の構成
 
-```json
-{
-  "mcpServers": {
-    "ampless": {
-      "command": "npx",
-      "args": [
-        "-y",
-        "@ampless/mcp-server",
-        "--outputs",
-        "/absolute/path/to/your-site/amplify_outputs.json"
-      ],
-      "env": {
-        "AMPLESS_MCP_EMAIL": "you@example.com",
-        "AMPLESS_MCP_PASSWORD": "your-password"
-      }
-    }
-  }
-}
+```
+MCP クライアント (.mcp.json)
+  └── HTTP Bearer トークン (amk_...)
+        └── mcp-handler Lambda (packages/backend/src/functions/mcp-handler.ts)
+              └── @ampless/mcp-server/tools  ← このパッケージ
+                    └── ToolDefinition[], dispatchToolCall
 ```
 
-Claude Desktop を再起動すると、7 つのツールが `/mcp` の下に表示されます。
+`mcp-handler` Lambda は Bearer トークンを `McpToken` AppSync モデル（admin 専用）に照合し、`ToolContext`（GraphQL クライアント + S3 クライアント + サイトコンテキスト）を構築して、各ツール呼び出しをこのパッケージの `dispatchToolCall` に委譲します。
 
-### Cursor
+エンドユーザーは管理画面経由で MCP を設定します：
 
-`~/.cursor/mcp.json` を編集するか、**Cursor Settings → MCP** を使用します。設定の形式は Claude Desktop と同じです：
+1. `/admin/mcp-tokens` にアクセスし、Bearer トークン（`amk_...`）を発行する。
+2. Amplify コンソールまたは `amplify_outputs.json` で `mcp-handler` Lambda の Function URL を確認する。
+3. MCP クライアントの設定ファイル（`.mcp.json`、`claude_desktop_config.json` など）にエントリを追加する：
 
 ```json
 {
   "mcpServers": {
     "ampless": {
-      "command": "npx",
-      "args": ["-y", "@ampless/mcp-server", "--outputs", "/path/to/amplify_outputs.json"],
-      "env": {
-        "AMPLESS_MCP_EMAIL": "you@example.com",
-        "AMPLESS_MCP_PASSWORD": "your-password"
+      "url": "https://<function-url-id>.lambda-url.<region>.on.aws/",
+      "transport": "http",
+      "headers": {
+        "Authorization": "Bearer amk_..."
       }
     }
   }
 }
 ```
 
-### Claude Code
+HTTP MCP のアーキテクチャ全体については `docs/architecture/04-access-layer-mcp.md` を参照してください。
 
-プロジェクトレベルの MCP サーバーを追加します：
+## エクスポート
 
-```bash
-claude mcp add ampless \
-  --env AMPLESS_MCP_EMAIL=you@example.com \
-  --env AMPLESS_MCP_PASSWORD=your-password \
-  -- npx -y @ampless/mcp-server --outputs /path/to/amplify_outputs.json
-```
-
-## 使用例
-
-登録後、AI エージェントに次のように指示できます：
-
-- 「最新の投稿を 5 件表示して。」
-- 「スラッグ `welcome` の投稿を見せて。」
-- 「タイトル '2 記事目' の下書きを markdown 形式で、本文 'Hello world.' で作成して。」
-- 「投稿 `post-1234` を公開して。」
-- 「スラッグ `bad-draft` の投稿を削除して。」
-
-エージェントが自動的に適切なツールを選択します。
-
-### `format` ごとの `body` の形式
-
-- `format: 'markdown'` → body は markdown ソース文字列
-- `format: 'html'` → body は生の HTML 文字列（そのままレンダリングされます — 下記のエディタートラストモデルを参照）
-- `format: 'tiptap'` → body は tiptap ドキュメント JSON、例：
-
-  ```json
-  {
-    "type": "doc",
-    "content": [
-      { "type": "paragraph", "content": [{ "type": "text", "text": "Hello" }] }
-    ]
-  }
-  ```
-
-AI に投稿本文を生成させる場合は、markdown を指定するのが最も簡単です。
-
-## セキュリティに関する注意
-
-- **エディタートラストモデル。** ampless は `editor` と `admin` を同一のトラストクラスとして扱います — どちらも投稿本文に任意の HTML / JS を格納できます（`docs/architecture/04-access-layer-mcp.md` 参照）。MCP サーバーが書き込める内容は、そのユーザーアカウントが管理 UI から書き込める内容と同じです。
-- **設定ファイル内の認証情報。** `AMPLESS_MCP_PASSWORD` は Claude Desktop / Cursor の設定ファイル内にプレーンテキストで保存されます。SSH 秘密鍵と同様に扱ってください。OS キーチェーン連携はロードマップで対応予定です。
-- **AWS 認証情報。** `upload_media` のみ必要です。サイトの S3 バケットへの書き込み権限のみを持つ専用の IAM ユーザー / ロールを使用してください。
-
-## CLI フラグ
+### `./tools`
 
+```typescript
+import { getTools, dispatchToolCall } from '@ampless/mcp-server/tools'
+import type { ToolDefinition, ToolContext, ResolvedSite } from '@ampless/mcp-server/tools'
 ```
-ampless-mcp [options]
-
-  --outputs <path>        amplify_outputs.json へのパス（AMPLESS_MCP_OUTPUTS でも指定可）
-  --site-name <name>      コンテキスト用のサイト表示名（AMPLESS_MCP_SITE_NAME でも指定可、例: "mysite.net"）
-  --site-url <url>        ツール結果に含めるサイト URL（AMPLESS_MCP_SITE_URL でも指定可、省略可）
-  --environment <env>     デプロイ環境: prod | stg | dev（AMPLESS_MCP_ENVIRONMENT でも指定可、デフォルト "dev"）
-  --site-id <id>          クエリのデフォルト siteId（AMPLESS_MCP_SITE_ID でも指定可、デフォルト "default"）
-```
-
-`--site-name` を設定すると、MCP クライアントに表示されるサーバー名にサイトと環境が含まれ（例: `@ampless/mcp-server [mysite.net/prod]`）、ツールの description に `[mysite.net / prod]` が前置され、結果が `{ site, result }` でラップされます。`--environment prod` 設定時、破壊的ツール（`delete_post`、`delete_static_file`、`upload_static_bundle`）の呼び出しにはサイト名と一致する `confirmSite` 引数が必要です。
 
-必須の環境変数：
-
-```
-AMPLESS_MCP_EMAIL          Cognito ユーザーのメールアドレス
-AMPLESS_MCP_PASSWORD       Cognito ユーザーのパスワード
-```
+| エクスポート | 説明 |
+|---|---|
+| `getTools()` | `ToolDefinition` オブジェクトのリスト（name、description、inputSchema）を返す |
+| `dispatchToolCall(name, args, ctx)` | 名前でツール呼び出しをディスパッチする。不明なツール名の場合は例外をスロー |
+| `ToolDefinition` | 単一ツールのインターフェース（name、description、inputSchema、handler） |
+| `ToolContext` | ランタイムコンテキストのインターフェース（graphql、storage、site） |
+| `ResolvedSite` | 解決済みサイトコンテキストのインターフェース（name、url、environment、siteId） |
 
-## トラブルシューティング
+## ツール一覧
 
-- **`NotAuthorizedException: Incorrect username or password.`** — 認証情報が誤っているか、メールアドレスが未確認です。まず Web の `/login` から一度サインインしてください。
-- **`InvalidPasswordException`** — ユーザーが `FORCE_CHANGE_PASSWORD` 状態です。Web UI からサインインして永続パスワードを設定してください。
-- **`AppSync 401`** — ID トークンが拒否された可能性があります。サーバーは次の呼び出し時に自動更新します。繰り返し 401 が発生する場合は、ユーザープールが再デプロイされている可能性があるため認証情報を更新してください。
-- **`upload_media` が AWS 認証情報なしで失敗する** — MCP サーバーの環境に `AWS_PROFILE` または `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` を設定してください。
+| ツール | role | 説明 |
+|---|---|---|
+| `list_posts` | reader | オプションの status フィルターとページネーション付きで投稿一覧を取得 |
+| `get_post` | reader | slug または postId で単一の投稿を取得 |
+| `create_post` | editor | 新しい投稿を作成（下書きまたは公開済み） |
+| `update_post` | editor | 既存の投稿のフィールドをパッチ更新 |
+| `delete_post` | editor | 投稿を削除しタグインデックスをクリーンアップ |
+| `upload_media` | editor | Base64 エンコードされたバイト列を S3 にアップロードし Media レコードを作成 |
+| `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）を返す |

package/README.md

@@ -3,151 +3,73 @@
 
 # @ampless/mcp-server
 
-MCP (Model Context Protocol) server for [ampless](https://github.com/heavymoons/ampless). Lets AI agents — Claude Desktop, Cursor, Claude Code, and anything else that speaks MCP — read and write posts and upload media on your CMS instance.
+MCP tool registry for [ampless](https://github.com/heavymoons/ampless).
 
-> **Pre-release / alpha.** Breaking changes possible in any minor version until v1.0.
+**No direct install needed.** This package is consumed by `@ampless/backend`'s `mcp-handler` Lambda via the `./tools` subpath export, and arrives transitively when you install `@ampless/admin` or `@ampless/backend`.
 
-## Tools
-
-| Tool | What it does |
-|---|---|
-| `list_posts` | List posts with optional `status` filter and pagination |
-| `get_post` | Fetch a single post by `slug` or `postId` |
-| `create_post` | Create a new post (draft or published) |
-| `update_post` | Patch fields on an existing post |
-| `delete_post` | Delete a post and clean up its tag index |
-| `upload_media` | Upload base64-encoded bytes to S3 and create a `Media` record |
-| `get_schema` | Return the CMS content schema (Post / Page / Media field shapes) |
-
-The server signs in to your Cognito User Pool with the credentials you provide (env vars), so each tool runs with the role of that user (`ampless-admin` or `ampless-editor`). Drafts and editing surface only to authenticated users; the resolver-side `status === 'published'` filter still keeps unpublished content invisible to public reads.
-
-## Install
-
-The server is published as a Node CLI; you typically don't install it globally — point your MCP client at `npx -y @ampless/mcp-server@alpha` instead.
-
-## Configure
-
-You need:
-
-1. **`amplify_outputs.json`** — generated by `npx ampx sandbox` or `npx ampx pipeline-deploy`. The path is passed via `--outputs`.
-2. **A Cognito user account** — email + password from your User Pool. The first user created via the admin UI is automatically in `ampless-admin`.
-3. **AWS credentials** — only required if you intend to use `upload_media`. The default credential chain (`AWS_PROFILE`, env vars, instance role) is used. Read-only tools work without AWS credentials.
-
-### Claude Desktop
-
-Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or the equivalent path on your platform:
+## How it fits together
 
-```json
-{
-  "mcpServers": {
-    "ampless": {
-      "command": "npx",
-      "args": [
-        "-y",
-        "@ampless/mcp-server",
-        "--outputs",
-        "/absolute/path/to/your-site/amplify_outputs.json"
-      ],
-      "env": {
-        "AMPLESS_MCP_EMAIL": "you@example.com",
-        "AMPLESS_MCP_PASSWORD": "your-password"
-      }
-    }
-  }
-}
+```
+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
 ```
 
-Restart Claude Desktop. The 7 tools should appear under `/mcp`.
+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.
 
-### Cursor
+End users configure MCP via the admin UI:
 
-Edit `~/.cursor/mcp.json` (or use **Cursor Settings → MCP**). The config shape is the same as Claude Desktop:
+1. Go to `/admin/mcp-tokens` and issue a Bearer token (`amk_...`).
+2. Find the `mcp-handler` Lambda Function URL in the Amplify console or `amplify_outputs.json`.
+3. Add an entry to your MCP client's config (`.mcp.json`, `claude_desktop_config.json`, etc.):
 
 ```json
 {
   "mcpServers": {
     "ampless": {
-      "command": "npx",
-      "args": ["-y", "@ampless/mcp-server", "--outputs", "/path/to/amplify_outputs.json"],
-      "env": {
-        "AMPLESS_MCP_EMAIL": "you@example.com",
-        "AMPLESS_MCP_PASSWORD": "your-password"
+      "url": "https://<function-url-id>.lambda-url.<region>.on.aws/",
+      "transport": "http",
+      "headers": {
+        "Authorization": "Bearer amk_..."
       }
     }
   }
 }
 ```
 
-### Claude Code
+See `docs/architecture/04-access-layer-mcp.md` for the full HTTP MCP architecture.
 
-Add a project-level MCP server:
+## Exports
 
-```bash
-claude mcp add ampless \
-  --env AMPLESS_MCP_EMAIL=you@example.com \
-  --env AMPLESS_MCP_PASSWORD=your-password \
-  -- npx -y @ampless/mcp-server --outputs /path/to/amplify_outputs.json
-```
-
-## Usage examples
-
-Once registered, prompt your AI agent:
-
-- "List the latest 5 posts."
-- "Show me the post with slug `welcome`."
-- "Create a draft titled 'My second post' with format markdown and body 'Hello world.'"
-- "Publish post `post-1234`."
-- "Delete the post with slug `bad-draft`."
-
-The agent will pick the right tool automatically.
-
-### `body` shape per `format`
-
-- `format: 'markdown'` → body is a markdown source string
-- `format: 'html'` → body is a raw HTML string (rendered verbatim — see editor trust model below)
-- `format: 'tiptap'` → body is the tiptap document JSON, e.g.
-
-  ```json
-  {
-    "type": "doc",
-    "content": [
-      { "type": "paragraph", "content": [{ "type": "text", "text": "Hello" }] }
-    ]
-  }
-  ```
-
-If you're letting the AI generate post bodies, asking for markdown is usually easiest.
-
-## Security notes
-
-- **Editor trust model.** ampless treats `editor` and `admin` as a single trust class — both can store arbitrary HTML/JS in post bodies (see `docs/architecture/04-access-layer-mcp.md`). Whatever the MCP server can write, that user account could already write through the admin UI.
-- **Credentials in the config file.** `AMPLESS_MCP_PASSWORD` lives in plaintext inside Claude Desktop / Cursor's config file. Treat that file like an SSH private key. OS keychain integration is on the roadmap.
-- **AWS credentials.** Only `upload_media` requires them. Use a dedicated IAM user / role with write access only to your site's S3 bucket.
-
-## CLI flags
+### `./tools`
 
+```typescript
+import { getTools, dispatchToolCall } from '@ampless/mcp-server/tools'
+import type { ToolDefinition, ToolContext, ResolvedSite } from '@ampless/mcp-server/tools'
 ```
-ampless-mcp [options]
-
-  --outputs <path>        Path to amplify_outputs.json (also AMPLESS_MCP_OUTPUTS)
-  --site-name <name>      Site display name for context (also AMPLESS_MCP_SITE_NAME; e.g. "mysite.net")
-  --site-url <url>        Site URL included in tool results (also AMPLESS_MCP_SITE_URL; optional)
-  --environment <env>     Deployment environment: prod | stg | dev (also AMPLESS_MCP_ENVIRONMENT; default "dev")
-  --site-id <id>          Default siteId for queries (also AMPLESS_MCP_SITE_ID; default "default")
-```
-
-When `--site-name` is set, the server name shown in MCP clients includes the site and environment (e.g. `@ampless/mcp-server [mysite.net/prod]`), tool descriptions are prefixed with `[mysite.net / prod]`, and results are wrapped in `{ site, result }`. Destructive tools (`delete_post`, `delete_static_file`, `upload_static_bundle`) require a `confirmSite` argument equal to the site name when `--environment prod` is set.
 
-Required env:
-
-```
-AMPLESS_MCP_EMAIL          Cognito user email
-AMPLESS_MCP_PASSWORD       Cognito user password
-```
+| 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) |
 
-## Troubleshooting
+## Tools
 
-- **`NotAuthorizedException: Incorrect username or password.`** — Wrong creds, or the user hasn't confirmed their email. Sign in via the web `/login` once first.
-- **`InvalidPasswordException`** — The user is in `FORCE_CHANGE_PASSWORD` state. Sign in via the web UI to set a permanent password.
-- **`AppSync 401`** — id token may have been rejected; the server auto-refreshes on the next call. Repeated 401s usually mean the User Pool was redeployed and your creds need updating.
-- **`upload_media` fails with no AWS credentials** — set `AWS_PROFILE` or `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` in the MCP server's environment.
+| Tool | Role | Description |
+|---|---|---|
+| `list_posts` | reader | List posts with optional status filter and pagination |
+| `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 |
+| `delete_post` | editor | Delete a post and clean up its tag index |
+| `upload_media` | editor | Upload base64-encoded bytes to S3 and create a Media record |
+| `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) |

package/dist/index.d.ts

@@ -1,2 +1,128 @@
+import { BundleExtractResult } from 'ampless';
 
-export {  }
+/**
+ * Site context passed from the HTTP transport into each tool call.
+ * The mcp-handler Lambda resolves this from the MCP access token.
+ */
+interface ResolvedSite {
+    name: string;
+    url?: string;
+    environment: 'prod' | 'stg' | 'dev';
+    siteId: string;
+}
+/**
+ * Abstract contracts each tool handler depends on. Concrete
+ * implementations live in `@ampless/backend`'s mcp-handler Lambda:
+ *
+ *   - `mcp-graphql-client.ts` — AppSync GraphQL client (Bearer token)
+ *   - `mcp-storage-client.ts` — S3 client for media operations
+ *
+ * Both satisfy these interfaces structurally (no `implements` needed)
+ * — TypeScript's structural typing checks the shape on the call site.
+ * Tools never instantiate these themselves; the caller passes a ready
+ * `ToolContext` into `dispatchToolCall`.
+ */
+interface GraphqlClient {
+    query<T>(operation: string, variables?: Record<string, unknown>): Promise<T>;
+}
+interface StorageObject {
+    /** Full S3 key including any prefix. */
+    key: string;
+    /** Object size in bytes (0 when the backend can't supply it). */
+    size: number;
+    /** ISO 8601 timestamp of the last write, when the backend supplies it. */
+    lastModified?: string;
+}
+interface StorageClient {
+    /**
+     * Upload `body` to the bucket at `key` with `contentType`. Returns
+     * the public URL of the stored object (same format both routes use:
+     * https://{bucket}.s3.{region}.amazonaws.com/{key}).
+     */
+    putObject(key: string, body: Uint8Array, contentType: string): Promise<string>;
+    /**
+     * Remove the object at `key`. Implementations should treat a missing
+     * key as success (S3 DeleteObject is idempotent by default).
+     */
+    deleteObject(key: string): Promise<void>;
+    /**
+     * List every object under `prefix`. Implementations are expected to
+     * paginate internally so the caller gets the full set in a single
+     * resolved promise — the static-bundle tools never expect more than
+     * a few hundred entries per bundle in practice.
+     */
+    listObjects(prefix: string): Promise<StorageObject[]>;
+}
+interface ToolContext {
+    graphql: GraphqlClient;
+    storage: () => StorageClient;
+    site?: ResolvedSite;
+}
+
+/**
+ * Server-side zip extractor used by the static-bundle MCP tools. Both
+ * the stdio CLI and the Lambda HTTP transport run this — `fflate` is
+ * a workspace dependency of `@ampless/mcp-server`, so the import
+ * resolves identically in both. The browser-side admin uploader has
+ * its own `extractZip(File)` based on JSZip (works on a `File`, not a
+ * `Buffer`).
+ *
+ * Behaviour parity with the admin extractor:
+ *  - Skip directory entries (fflate gives byte arrays only, so this
+ *    is naturally satisfied unless the zip has empty-byte directory
+ *    placeholders — those still get filtered out by validateBundlePath
+ *    returning "directory entry" for any path ending with `/`).
+ *  - Silently drop OS-specific junk (`__MACOSX/*`, `.DS_Store`,
+ *    `Thumbs.db`) so callers don't see them as bundle entries.
+ *  - Surface structural issues (absolute paths, parent traversal, null
+ *    bytes) so the tool can reject the upload.
+ *  - Strip a common single top-level directory (macOS Finder zips
+ *    wrap their contents in a folder).
+ */
+
+interface ExtractZipOptions {
+    /**
+     * Hard ceiling on uncompressed bundle bytes. Defaults to 50 MB,
+     * matching the browser uploader's MAX_BUNDLE_BYTES. Callers running
+     * inside a tight Lambda envelope (Function URL payload cap ~6 MB
+     * post-base64) can tighten this; setting it lower than the bundle
+     * causes `extractZipFromBuffer` to throw before fully populating
+     * `files`.
+     */
+    maxBytes?: number;
+}
+/**
+ * Unzip `buffer` in memory and return the same shape the browser
+ * `extractZip(File)` helper returns. Throws if the unzip itself fails
+ * (corrupt archive) or if the uncompressed size exceeds `maxBytes`.
+ */
+declare function extractZipFromBuffer(buffer: Uint8Array, opts?: ExtractZipOptions): BundleExtractResult;
+/**
+ * Decode an extracted file's bytes as UTF-8 text. Used by the tool
+ * handler before running cross-file `validateBundle` so we don't
+ * instantiate a TextDecoder per entry. fflate provides a fast helper.
+ */
+declare function decodeUtf8(data: Uint8Array): string;
+
+interface ToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    handler: (args: Record<string, unknown>, ctx: ToolContext) => Promise<unknown>;
+    destructive?: boolean;
+}
+declare const tools: ToolDefinition[];
+/**
+ * Look up a tool definition by name and invoke its handler. Returns
+ * `null` when no tool with that name is registered — callers should
+ * surface that as a JSON-RPC "method not found" error.
+ */
+declare function dispatchToolCall(name: string, args: Record<string, unknown>, ctx: ToolContext): Promise<unknown>;
+/**
+ * `tools` is the canonical registry; `getTools()` returns it for
+ * callers that prefer a function over a top-level constant (admin's
+ * HTTP factory exposes this through its options shape).
+ */
+declare function getTools(): readonly ToolDefinition[];
+
+export { type ExtractZipOptions, type GraphqlClient, type StorageClient, type StorageObject, type ToolContext, type ToolDefinition, decodeUtf8, dispatchToolCall, extractZipFromBuffer, getTools, tools };