@pecot/tools-mcp 1.0.1 → 1.1.0

package/cli/dist/mcp/serve.js

@@ -1,42 +1,22 @@
-// `pecot-tools mcp` — MCP サーバとして stdio で待ち受ける実装。
-//
-// cli.ts は薄い Command だけを持つ。
-// 本モジュールは action 内の dynamic import で初めて読み込まれる (MCP SDK の読み込みを mcp 実行時に限定するため)。
-//
-// exit code 規約:
-//   0 = 正常終了 (クライアントが stdin を閉じるまで待ち受ける)
-//   1 = 起動失敗 (transport 接続エラー等) / stdout への書き込み失敗
+// `pecot-tools mcp` の実装。cli.ts の dynamic import で読む。exit code は 0=正常 / 1=起動失敗・stdout 書き込み失敗。
 import { Writable } from 'node:stream';
 import { serveStdio, StdioServerTransport } from '@modelcontextprotocol/server/stdio';
+import { createDiagnostics } from '../diagnostics.js';
 import { killRunningAwscli } from '../infra/awscli.js';
 import { shutdownLoginRegistry } from '../infra/sso/login-registry.js';
 import { createMcpServer } from './server.js';
 import { allTools } from './tools/index.js';
 import { ignoreRejection } from '../infra/ignore-rejection.js';
 /**
-診断行の接頭辞。stdout は JSON-RPC 専有なので、報告先は stderr のみ。
-*/
-const LOG_PREFIX = 'pecot-tools mcp:';
-/**
 SIGTERM / SIGINT を受けたときの終了コード (シェルの慣習どおり 128 + シグナル番号)。
 */
 const SIGTERM_EXIT_CODE = 143;
 const SIGINT_EXIT_CODE = 130;
-// 同じ stdout に二重でガードを張ると、2 回目が「1 回目の転送用 write」を元の write として束縛する。
-// すると JSON-RPC が stderr へ回る。張り済みの stdout には、最初に作った Writable をそのまま返す。
-// キーが stream オブジェクトなので、テストごとに別のフェイクを使っても混入しない。
+// 二重に張ると 2 回目が転送用 write を元の write として束縛し、JSON-RPC が stderr へ回る。張り済みなら初回の Writable を返す。
 const installedGuards = new WeakMap();
 /**
-stdio の stdout を JSON-RPC 専有にするガードを張る。
-
-返した Writable だけが本物の stdout へ届き、それ以外の stdout 書き込み
-(console.log・依存ライブラリの進捗表示など) は stderr へ逃がす。
-
-「process.stdout.write を差し替えるだけ」では、transport 自身の JSON-RPC 応答まで stderr に流れる。
-するとクライアントが無応答になる。
-そのため、差し替え前に束縛した元の write を使う専用 Writable を transport へ渡す、という二段構えが必須になる。
-
-同じ stdout に対しては冪等で、2 回目以降は初回に作った Writable を返す。
+stdout を JSON-RPC 専有にする。返した Writable だけが本物の stdout へ届き、ほかの書き込みは stderr へ逃がす。
+同じ stdout に対しては冪等。
 */
 export function installStdoutGuard(stdout, stderr) {
     const installed = installedGuards.get(stdout);
@@ -44,16 +24,14 @@ export function installStdoutGuard(stdout, stderr) {
         return installed;
     const isOriginalWrite = stdout.write.bind(stdout);
     const isForwardToStderr = (chunk, encodingOrCallback, callback) => {
-        // `process.stdout.write(chunk, encoding?, callback?)` の両シグネチャを受ける。
-        // encoding は意図的に捨てる: 逃がす先の stderr は既定の utf8 で解釈すればよく、
-        // ここで扱うのは console 系が書く utf8 文字列か Buffer に限られる。
+        // encoding は捨てる。逃がす先の stderr は既定の utf8 で足りる。
         const done = typeof encodingOrCallback === 'function' ? encodingOrCallback : callback;
+        // eslint-disable-next-line no-restricted-syntax -- stdout へ書かれた生の chunk を、行に整えず stderr へ逃がす
         const isWritten = stderr.write(chunk);
         done?.();
         return isWritten;
     };
-    // 代入ではなく defineProperty を使うのは、オーバーロード付きの write に単一シグネチャの
-    // 関数を代入する際の型アサーションを避けるため。
+    // 代入だと、オーバーロード付きの write への型アサーションが要る。
     Object.defineProperty(stdout, 'write', {
         value: isForwardToStderr,
         writable: true,
@@ -64,10 +42,9 @@ export function installStdoutGuard(stdout, stderr) {
             isOriginalWrite(chunk, callback);
         },
     });
-    // stdout の相手が消えた後の書き込み (EPIPE) は Writable の 'error' として上がる。
-    // 拾わないと uncaught 例外でスタックトレースごと落ちるため、1 行報告して終了コードを立てる。
+    // EPIPE は 'error' として上がる。拾わないと uncaught 例外で落ちる。
     protocolStdout.on('error', (error) => {
-        stderr.write(`${LOG_PREFIX} stdout への書き込みに失敗しました: ${error.message}\n`);
+        createDiagnostics(stderr).error(`failed to write to stdout: ${error.message}`);
         process.exitCode = 1;
     });
     installedGuards.set(stdout, protocolStdout);
@@ -78,10 +55,7 @@ function runShutdown(dependencies) {
         hook();
 }
 /**
-後始末を終了処理へ配線する。
-
-SIGTERM / SIGINT はハンドラを登録した時点で既定の即終了が無効になるので、明示的に exit する。
-'exit' は最後の網で、同期処理しか実行されないため後始末だけを呼ぶ。
+後始末を終了処理へ配線する。SIGTERM / SIGINT は既定の即終了が無効になるので、明示的に exit する
 */
 function installShutdownHandlers(dependencies) {
     dependencies.signals.on('SIGTERM', () => {
@@ -97,31 +71,20 @@ function installShutdownHandlers(dependencies) {
     });
 }
 /**
-MCP サーバを stdio で待ち受ける。
-
-serveStdio が接続ごとに 2025 系と 2026-07-28 系のどちらかを選び、factory のインスタンスを
-1 つ固定して配る。factory は 1 接続で複数回呼ばれ得る (2026-07-28 は探査用インスタンスを捨てることがある)。
-そのため createServer() と onerror の設定以外の副作用は持たせない。
-後始末の配線 (signals / stdin) は factory の外で 1 回だけ行う。
-
-接続が完了しても待ち受けは続く。クライアントが stdin を閉じたら子プロセスを落として
-接続を閉じ、SIGTERM を待たずにプロセスが自力で終了できるようにする。
+MCP サーバを stdio で待ち受ける。factory は 1 接続で複数回呼ばれ得るため、createServer() と onerror 以外の副作用を持たせない。
+stdin が閉じたら子プロセスを落として接続を閉じる
 */
 export function runMcpServe(dependencies) {
     const protocolStdout = dependencies.installStdoutGuard();
     const transport = dependencies.createTransport(dependencies.stdin, protocolStdout);
     installShutdownHandlers(dependencies);
-    // 不正な JSON-RPC やハンドラ不在など、リクエスト単位の応答にならない異常は onerror にしか出てこない。
-    // stdout は JSON-RPC 専有なので stderr へ 1 行流す。
-    // 接続側 (options.onerror) とインスタンス内部 (server.server.onerror) は通知元が別なので、同じ報告関数を両方に渡す。
-    // serveStdio は接続確定後の異常を、接続側とインスタンスの両方へ流す。
-    // そのため同じ Error は 1 回だけ報告する。
+    // 接続側とインスタンスの両方の onerror に同じ Error が流れるので、1 回だけ報告する。
     const reported = new WeakSet();
     const report = (error) => {
         if (reported.has(error))
             return;
         reported.add(error);
-        dependencies.stderr.write(`${LOG_PREFIX} ${error.message}\n`);
+        createDiagnostics(dependencies.stderr).error(error.message);
     };
     const handle = serveStdio(() => {
         try {
@@ -131,8 +94,7 @@ export function runMcpServe(dependencies) {
             return server;
         }
         catch (error) {
-            // factory の失敗は serveStdio が onerror (report) へ流して接続側へ内部エラーを返す。
-            // 起動に失敗したプロセスは待ち受けを続けても役に立たないため、終了コードを立てて閉じる。
+            // 起動に失敗したプロセスは待ち受けても役に立たないため、終了コードを立てて閉じる。
             process.exitCode = 1;
             // 終了処理中の close 失敗は報告先が無いため握り潰す。
             void ignoreRejection(handle.close());
@@ -140,8 +102,7 @@ export function runMcpServe(dependencies) {
         }
     }, { transport, onerror: report });
     dependencies.stdin.once('end', () => {
-        // 子プロセスを先に落とす。子の stdio パイプがイベントループを保持するため、
-        // 残したままだと接続を閉じるだけでは自力終了できない。
+        // 子を先に落とさないと、接続を閉じても自力終了できない。
         runShutdown(dependencies);
         // 終了処理中の close 失敗は報告先が無いため握り潰す。
         void ignoreRejection(handle.close());
@@ -149,10 +110,7 @@ export function runMcpServe(dependencies) {
     return handle;
 }
 /**
-`pecot-tools mcp` の action 本体。
-
-program.parse は action の Promise を await しない。
-そのため例外はここで捕まえて、process.exitCode へ反映する (unhandled rejection にしない)。
+`pecot-tools mcp` の action 本体。program.parse は Promise を await しないので、例外はここで process.exitCode へ反映する
 */
 export function executeMcpServe(buildDependencies) {
     const dependencies = buildDependencies();
@@ -160,7 +118,7 @@ export function executeMcpServe(buildDependencies) {
         runMcpServe(dependencies);
     }
     catch (error) {
-        dependencies.stderr.write(`${LOG_PREFIX} ${formatError(error)}\n`);
+        createDiagnostics(dependencies.stderr).error(formatError(error));
         process.exitCode = 1;
     }
 }
@@ -172,9 +130,7 @@ export function mcpServeDefaultDependencies() {
         installStdoutGuard: () => installStdoutGuard(process.stdout, process.stderr),
         stdin: process.stdin,
         stderr: process.stderr,
-        // tools/call 実行中の awscli 子プロセスと、SSO ログインで待機中の子プロセスを落とす。
-        // 親が先に消えると、子は PPID 1 へ再親付けされる。
-        // timeout を張っていた親が居なくなるので、打ち切りも働かなくなる（SSO は最長 10 分待つ）。
+        // 親が先に消えると子が残り、timeout も働かない（SSO は最長 10 分待つ）。
         onShutdown: [killRunningAwscli, shutdownLoginRegistry],
         signals: process,
     };

package/cli/dist/mcp/server.d.ts

@@ -2,18 +2,11 @@ import { McpServer } from '@modelcontextprotocol/server';
 import type { CallToolResult, ToolAnnotations } from '@modelcontextprotocol/server';
 import type { z } from 'zod';
 /**
-MCP サーバ名。initialize の serverInfo.name として返る値。
-
-`.mcp.json` の `mcpServers` の登録キーと必ず揃える。食い違うとクライアント側の表示と
-ツール名の名前空間（`mcp__plugin_pecot-t_<サーバ名>__*`）が噛み合わなくなる。
+MCP サーバ名。`.mcp.json` の `mcpServers` の登録キーと揃える。食い違うとツール名の名前空間が噛み合わない。
 */
 export declare const MCP_SERVER_NAME = "pecot-tools";
 /**
-registerTool に渡すツールのメタ情報。
-
-inputSchema / outputSchema は自前の zod の `z.object()` で書く。SDK は渡されたスキーマ自身から JSON Schema を作る。
-そのため SDK 同梱の zod と混在しない。引数を取らないツールは inputSchema に
-`z.object({})` を渡す。
+registerTool に渡すツールのメタ情報。スキーマは自前の zod で書き、SDK 同梱の zod と混在させない。
 */
 export interface ToolConfig {
     readonly title?: string;
@@ -29,10 +22,7 @@ export interface ToolConfig {
     readonly annotations?: ToolAnnotations;
 }
 /**
-tools/call ハンドラの第 2 引数。ハンドラが使う面だけを SDK の ServerContext から切り出す。
-
-signal はクライアントのキャンセル (notifications/cancelled) と stdin の EOF で abort される。
-SDK の型を直接渡さないのは、ツール側とテストのフェイクを SDK の型から切り離すため。
+tools/call ハンドラの第 2 引数。使う面だけを切り出し、ツール側とテストのフェイクを SDK の型から切り離す。
 */
 export interface ToolCallContext {
     readonly signal: AbortSignal;
@@ -56,13 +46,7 @@ interface McpServerOptions {
     readonly progressIntervalMs?: number;
 }
 /**
-MCP サーバを生成し、渡されたツール定義を登録する。
-
-各ハンドラは登録時に実行器で包む。tools/call が並行に届いても、同時に実行されるのは 4 件までになる
-(上限はここで構造的に保証し、ツール実装側には依存しない)。
-あわせて progress ハートビートもここで包む。全ツールに一律で適用され、ツール実装側の適用判断が要らなくなる。
-
-呼び出しごとに新しい McpServer と実行器を生成する (singleton にしない)。
+MCP サーバを生成し、ツール定義を登録する。ハンドラは実行器と progress ハートビートで包み、呼び出しごとに新しく作る。
 */
 export declare function createMcpServer(tools?: readonly ToolDefinition[], options?: McpServerOptions): McpServer;
 export {};

package/cli/dist/mcp/server.js

@@ -1,24 +1,13 @@
 // MCP サーバのファクトリ。ツール登録シームと上限付き並行実行器の所有をここで持つ。
-//
-// ツール 1 件以上のときは McpServer.registerTool だけを使う。
-// 低レベルの setRequestHandler('tools/list', ...) で一覧ハンドラを先に張る。
-// すると、後から registerTool したときに SDK が「handler already exists」で throw する。
-// 一方でツール 0 件の McpServer は、tools capability と一覧ハンドラを持たない。
-// そのため tools/list に -32601 を返す。
-// 0 件のときだけ明示登録する。両者は排他。
-/* eslint-disable @typescript-eslint/prefer-readonly-parameter-types -- ツールハンドラの第 2 引数は mutable。
-   SDK の ServerContext が signal / notify 等のメンバを持つ。
-   readonly 化すると、registerTool のコールバック型と適合しなくなる。 */
+// 1 件以上は registerTool だけを使う（先に一覧ハンドラを張ると SDK が throw する）。
+// 0 件のときだけ一覧ハンドラを明示登録する。
+/* eslint-disable @typescript-eslint/prefer-readonly-parameter-types -- ツールハンドラの第 2 引数は mutable */
 import { McpServer } from '@modelcontextprotocol/server';
 import { readVersion } from '../version.js';
 import { createBoundedExecutor } from './executor.js';
 import { ignoreRejection } from '../infra/ignore-rejection.js';
 /**
-progress ハートビートの送出周期 (ms)。
-
-守る相手は MCP クライアントの「無音タイムアウト」。
-Claude Code で計測した値は、30 分の idle watchdog (progress 受信でリセット・判定周期 30s)。
-10s はそこから十分な余裕があり、かつ長時間ツール 1 件で通知が積み上がりすぎない粒度になる。
+progress ハートビートの送出周期 (ms)。クライアントの無音タイムアウト（Claude Code で 30 分）に十分な余裕を取る。
 */
 const PROGRESS_HEARTBEAT_INTERVAL_MS = 10_000;
 /**
@@ -26,20 +15,11 @@ tools/call の同時実行数の上限 (research R9)。
 */
 const CONCURRENCY_LIMIT = 4;
 /**
-MCP サーバ名。initialize の serverInfo.name として返る値。
-
-`.mcp.json` の `mcpServers` の登録キーと必ず揃える。食い違うとクライアント側の表示と
-ツール名の名前空間（`mcp__plugin_pecot-t_<サーバ名>__*`）が噛み合わなくなる。
+MCP サーバ名。`.mcp.json` の `mcpServers` の登録キーと揃える。食い違うとツール名の名前空間が噛み合わない。
 */
 export const MCP_SERVER_NAME = 'pecot-tools';
 /**
-tools/call 1 件分の progress 通知を開始し、即座に 1 発目 (順番待ち中) を送る。
-
-MCP では progressToken を伴わないリクエストに notifications/progress を返せない。
-そのためクライアントが token を付けてこなかった場合は、何も送らず undefined を返す。
-
-送出は run() の前から始める。守りたいのは実行中だけでなく「上限に掛かって順番待ちしている
-間も無音時計が進む」区間で、ハンドラ内に置くラッパーでは待機中を守れない。
+tools/call 1 件分の progress 通知を開始する。token が無ければ undefined。順番待ちの間も守るため、run() の前から始める。
 */
 function startProgressHeartbeat(toolName, serverContext, intervalMs) {
     const { signal } = serverContext.mcpReq;
@@ -47,7 +27,7 @@ function startProgressHeartbeat(toolName, serverContext, intervalMs) {
     if (progressToken === undefined)
         return undefined;
     let progress = 0;
-    let phase = '順番待ち中';
+    let phase = 'queued';
     const send = () => {
         progress += 1;
         // 通知はベストエフォート。クライアント切断後の reject を await の流れに乗せると、
@@ -72,18 +52,12 @@ function startProgressHeartbeat(toolName, serverContext, intervalMs) {
         send();
     }
     return {
-        markRunning: () => { phase = '実行中'; },
+        markRunning: () => { phase = 'running'; },
         stop,
     };
 }
 /**
-MCP サーバを生成し、渡されたツール定義を登録する。
-
-各ハンドラは登録時に実行器で包む。tools/call が並行に届いても、同時に実行されるのは 4 件までになる
-(上限はここで構造的に保証し、ツール実装側には依存しない)。
-あわせて progress ハートビートもここで包む。全ツールに一律で適用され、ツール実装側の適用判断が要らなくなる。
-
-呼び出しごとに新しい McpServer と実行器を生成する (singleton にしない)。
+MCP サーバを生成し、ツール定義を登録する。ハンドラは実行器と progress ハートビートで包み、呼び出しごとに新しく作る。
 */
 export function createMcpServer(tools = [], options = {}) {
     const server = new McpServer({ name: MCP_SERVER_NAME, version: readVersion() });

package/cli/dist/mcp/tools/_shared.d.ts

@@ -24,20 +24,13 @@ export declare const COMMAND_NOT_FOUND_EXIT_CODE = 127;
 */
 export declare const UNKNOWN_FAILURE_EXIT_CODE = 1;
 /**
-`profile` だけの入力。
-
-SSO の 2 件は region を取らない（contracts/mcp-tools.md §SSO 認証）。
-そのため共通入力から profile だけを切り出し、両方が同じ書式・同じ説明文を公開できるようにする。
+`profile` だけの入力。SSO の 2 件は region を取らないので、共通入力から切り出す。
 */
 export declare const PROFILE_INPUT_SHAPE: {
     profile: z.ZodOptional<z.ZodString>;
 };
 /**
-全ツール共通の任意入力。
-
-書式の定義は domain/allowlist.ts の PROFILE_PATTERN / REGION_PATTERN にある。
-ここはその定数をそのまま inputSchema へ載せる（契約書の共通規約を tools/list で見せるため）。
-値を書き写さないので、定義は 1 箇所のまま。書式違反はハンドラ到達前に入力検証エラーとなる。awscli は起動しない。
+全ツール共通の任意入力。書式は allowlist.ts の PROFILE_PATTERN / REGION_PATTERN を載せ、tools/list で契約を見せる。
 */
 export declare const COMMON_INPUT_SHAPE: {
     profile: z.ZodOptional<z.ZodString>;
@@ -83,10 +76,7 @@ export interface ExecuteOptions {
     */
     readonly timeoutMs?: number;
     /**
-    許可リストの静的宣言だけでは表せない拒否条件（Athena の変更系クエリ、既存ファイルの上書き）。
-  
-    validateInput の直後・awscli の存在確認より前に評価する。存在確認を先にすると、
-    awscli 未導入の環境で「拒否されるはずの呼び出し」が awscli-missing に化ける。
+    静的宣言で表せない拒否条件。awscli 未導入で拒否が awscli-missing に化けないよう、存在確認より前に評価する。
     */
     readonly reject?: (arguments_: Readonly<Record<string, unknown>>) => PreExecutionRejection | undefined;
     /**
@@ -116,26 +106,15 @@ export interface AllowlistedToolSpec {
     readonly artifactsOf?: ExecuteOptions['artifactsOf'];
 }
 /**
-失敗種別と awscli の終了コードから応答の exitCode を決める。
-
-exitCode を持たない失敗（シグナル終了・awscli を起動していない SSO の状態遷移）は
-省略するか null で渡し、1 以上へ畳む。ok: false と exitCode 0 が同居しないようにする。
+失敗種別と awscli の終了コードから応答の exitCode を決める。exitCode を持たない失敗は 1 以上へ畳む。
 */
 export declare function resolveExitCode(category: FailureCategory, exitCode?: number | null): number;
 /**
-許可リストのエントリ 1 件を実行し、ExecutionResult を返す。
-
-検証で弾いた場合は awscli を起動しない（exitCode 2）。awscli の失敗は種別判定にかけ、
-応答へ載せる stdout / stderr は必ず秘匿化と上限を通す。
+許可リストのエントリ 1 件を実行し、ExecutionResult を返す。検証で弾けば awscli を起動せず（exitCode 2）、出力は秘匿化と上限を通す。
 */
 export declare function executeAllowlisted(entry: Readonly<AllowlistEntry>, arguments_: Readonly<Record<string, unknown>>, call: ToolCallContext, options?: Readonly<ExecuteOptions>): Promise<ExecutionResult>;
 /**
-許可リストのエントリ 1 件を MCP ツール定義にする。
-
-入力の検証は 2 段になる。
-inputSchema（型・列挙・書式）は SDK がハンドラ到達前に見て、入力検証エラーを返す。
-許可リスト側の規則（先頭 '-'・排他・shorthand の構成要素）は、executeAllowlisted が見て isError の応答にする。ハンドラで再度 zod parse はしない
-（SDK が既に未知キーの除去と default の適用を済ませている）。
+許可リストのエントリ 1 件を MCP ツール定義にする。zod の検証は SDK が済ませるので、ハンドラで再 parse しない。
 */
 export declare function allowlistedTool(spec: Readonly<AllowlistedToolSpec>, options?: Readonly<ToolOptions>): ToolDefinition;
 //# sourceMappingURL=_shared.d.ts.map

package/cli/dist/mcp/tools/_shared.js

@@ -1,10 +1,6 @@
 // 全ツール共通の入出力スキーマと、許可リストのエントリを 1 本の実行手順へ通す処理。
-//
-// 系統別のツール定義（`mcp/tools/{sts,lambda,logs,sqs,athena,s3}.ts`）が宣言するのは、使うエントリと入力スキーマだけ。
-// 検証 → 実行前拒否 → 引数組み立て → awscli 起動 → 失敗種別判定 → 秘匿化 → 切り詰め、という手順はここに 1 本だけ置く。
-// 手順をツール側へ複製すると、秘匿化や上限の適用を忘れるおそれがある。
-/* eslint-disable @typescript-eslint/prefer-readonly-parameter-types -- call.signal は mutable なメンバを持つ。
-   readonly 化すると、SDK 側の型と適合しなくなる。 */
+// 秘匿化と上限の掛け忘れを防ぐため、検証から切り詰めまでの手順はここに 1 本だけ置く。
+/* eslint-disable @typescript-eslint/prefer-readonly-parameter-types -- call.signal は mutable */
 import { z } from 'zod';
 import { PROFILE_PATTERN, REGION_PATTERN, } from '../../domain/allowlist.js';
 import { buildArguments, validateInput } from '../../domain/arguments.js';
@@ -35,77 +31,70 @@ export const COMMAND_NOT_FOUND_EXIT_CODE = 127;
 */
 export const UNKNOWN_FAILURE_EXIT_CODE = 1;
 /**
-`profile` だけの入力。
-
-SSO の 2 件は region を取らない（contracts/mcp-tools.md §SSO 認証）。
-そのため共通入力から profile だけを切り出し、両方が同じ書式・同じ説明文を公開できるようにする。
+`profile` だけの入力。SSO の 2 件は region を取らないので、共通入力から切り出す。
 */
 export const PROFILE_INPUT_SHAPE = {
     profile: z.string().regex(PROFILE_PATTERN).optional()
-        .describe('AWS プロファイル名。未指定なら awscli の既定解決に従う'),
+        .describe('AWS profile name. If omitted, the awscli default resolution applies'),
 };
 /**
-全ツール共通の任意入力。
-
-書式の定義は domain/allowlist.ts の PROFILE_PATTERN / REGION_PATTERN にある。
-ここはその定数をそのまま inputSchema へ載せる（契約書の共通規約を tools/list で見せるため）。
-値を書き写さないので、定義は 1 箇所のまま。書式違反はハンドラ到達前に入力検証エラーとなる。awscli は起動しない。
+全ツール共通の任意入力。書式は allowlist.ts の PROFILE_PATTERN / REGION_PATTERN を載せ、tools/list で契約を見せる。
 */
 export const COMMON_INPUT_SHAPE = {
     ...PROFILE_INPUT_SHAPE,
     region: z.string().regex(REGION_PATTERN).optional()
-        .describe('AWS リージョン（ap-northeast-1 等）。未指定なら awscli の既定解決に従う'),
+        .describe('AWS region (e.g. ap-northeast-1). If omitted, the awscli default resolution applies'),
 };
 /**
 クライアント側ページング（`--max-items` / `--starting-token`）を持つツールの入力。
 */
 export const MAX_ITEMS_PAGINATION_SHAPE = {
-    max_items: z.number().int().min(1).optional().describe('1 回の応答に含める最大件数'),
-    starting_token: z.string().optional().describe('前回応答の nextToken。続きを取得する'),
+    max_items: z.number().int().min(1).optional().describe('Maximum number of items in one response'),
+    starting_token: z.string().optional().describe('nextToken from the previous response. Fetches the next page'),
 };
 /**
 API 固有ページング（`logs get-log-events`）を持つツールの入力。
 */
 export const LIMIT_NEXT_TOKEN_PAGINATION_SHAPE = {
-    limit: z.number().int().min(1).max(10_000).optional().describe('取得するイベント数の上限（1〜10000）'),
-    next_token: z.string().optional().describe('前回応答の nextForwardToken / nextBackwardToken'),
-    start_from_head: z.boolean().default(false).describe('true なら古いイベントから返す'),
+    limit: z.number().int().min(1).max(10_000).optional().describe('Maximum number of events to return (1-10000)'),
+    next_token: z.string().optional().describe('nextForwardToken / nextBackwardToken from the previous response'),
+    start_from_head: z.boolean().default(false).describe('If true, returns the oldest events first'),
 };
 /**
 ExecutionResult と同形の outputSchema。全ツールで共有する。
 */
 export const TOOL_OUTPUT_SCHEMA = z.object({
-    ok: z.boolean().describe('awscli の実行が成功したか'),
-    exitCode: z.number().describe('終了コード (0 = success、実行前拒否 2、時間切れ 124、未導入 127)'),
-    category: z.string().optional().describe('失敗種別（成功時は省略）'),
-    data: z.record(z.string(), z.unknown()).describe('awscli の JSON 出力、または行配列'),
-    artifacts: z.array(z.string()).describe('書き出したローカルファイルの絶対パス'),
-    message: z.string().describe('呼び出し元エージェント向けの 1 行サマリ'),
-    stderr: z.string().optional().describe('秘匿化済みの awscli stderr（失敗時のみ）'),
+    ok: z.boolean().describe('Whether the awscli run succeeded'),
+    exitCode: z.number().describe('Exit code (0 = success, 2 = rejected before running, 124 = timeout, 127 = not installed)'),
+    category: z.string().optional().describe('Failure category (omitted on success)'),
+    data: z.record(z.string(), z.unknown()).describe('awscli JSON output, or an array of lines'),
+    artifacts: z.array(z.string()).describe('Absolute paths of the local files written'),
+    message: z.string().describe('One-line summary for the calling agent'),
+    stderr: z.string().optional().describe('Redacted awscli stderr (only on failure)'),
 });
 /**
 失敗種別ごとの再試行方法。message の後半に載せる。
 */
 const FAILURE_HINTS = {
-    'not-allowed': '許可されていない操作です。公開しているツールの範囲で実行してください',
-    'invalid-input': '入力を修正して再実行してください',
-    'awscli-missing': 'awscli v2 (2.22 以上) を導入して PATH を通してください',
-    'auth-missing': '認証設定がありません。aws_sso_login を実行するか profile を指定してください',
-    'auth-expired': '認証の有効期限が切れています。aws_sso_login で再認証してください',
-    'permission-denied': '権限が不足しています。profile / role を確認してください',
-    'resource-not-found': '対象が見つかりません。名前・リージョンを確認してください',
-    'timeout': '時間切れです。取得範囲を狭めて再実行してください',
-    'other': 'awscli が失敗しました。stderr を確認してください',
+    'not-allowed': 'Operation not allowed. Use only the exposed tools',
+    'invalid-input': 'Fix the input and run again',
+    'awscli-missing': 'Install awscli v2 (2.22 or later) and add it to PATH',
+    'auth-missing': 'Not authenticated. Run aws_sso_login or specify a profile',
+    'auth-expired': 'Authentication has expired. Run aws_sso_login to sign in again',
+    'permission-denied': 'Permission denied. Check the profile / role',
+    'resource-not-found': 'Resource not found. Check the name and region',
+    'timeout': 'Timed out. Narrow the range and run again',
+    'other': 'awscli failed. Check stderr',
 };
 /**
 出力が上限を超えたときの案内。
 */
-const TRUNCATION_MESSAGE = `出力が上限 ${String(OUTPUT_LIMIT_BYTES)} バイトを超えたため先頭のみ返しました。`
-    + 'max_items を減らすか starting_token で分割して再取得してください';
+const TRUNCATION_MESSAGE = `Output exceeded the limit of ${String(OUTPUT_LIMIT_BYTES)} bytes, so only the beginning is returned. `
+    + 'Reduce max_items or split the request with starting_token.';
 /**
 stderr が上限で切り詰められたときに message へ足す注記。
 */
-const STDERR_TRUNCATION_NOTE = '（stderr は上限を超えたため先頭のみ載せています）';
+const STDERR_TRUNCATION_NOTE = '(stderr exceeded the limit, so only the beginning is included)';
 function isRecord(value) {
     return value instanceof Object && !Array.isArray(value);
 }
@@ -132,10 +121,7 @@ function toLines(text) {
     return body === '' ? [] : body.split('\n');
 }
 /**
-失敗種別と awscli の終了コードから応答の exitCode を決める。
-
-exitCode を持たない失敗（シグナル終了・awscli を起動していない SSO の状態遷移）は
-省略するか null で渡し、1 以上へ畳む。ok: false と exitCode 0 が同居しないようにする。
+失敗種別と awscli の終了コードから応答の exitCode を決める。exitCode を持たない失敗は 1 以上へ畳む。
 */
 export function resolveExitCode(category, exitCode) {
     if (category === 'timeout')
@@ -146,7 +132,7 @@ export function resolveExitCode(category, exitCode) {
 }
 function failureMessage(toolName, category) {
     // eslint-disable-next-line security/detect-object-injection -- category は FailureCategory の列挙値
-    return `${toolName} が失敗しました (${category})。${FAILURE_HINTS[category]}`;
+    return `${toolName} failed (${category}). ${FAILURE_HINTS[category]}`;
 }
 /**
 成功時の data。JSON 出力はそのまま、非 JSON 出力は行配列にする。
@@ -159,10 +145,7 @@ function successData(entry, stdout) {
     return typeof nextToken === 'string' && entry.pagination === 'max-items' ? { ...parsed, nextToken } : parsed;
 }
 /**
-許可リストのエントリ 1 件を実行し、ExecutionResult を返す。
-
-検証で弾いた場合は awscli を起動しない（exitCode 2）。awscli の失敗は種別判定にかけ、
-応答へ載せる stdout / stderr は必ず秘匿化と上限を通す。
+許可リストのエントリ 1 件を実行し、ExecutionResult を返す。検証で弾けば awscli を起動せず（exitCode 2）、出力は秘匿化と上限を通す。
 */
 export async function executeAllowlisted(entry, arguments_, call, options = {}) {
     const invalid = validateInput(entry, arguments_);
@@ -241,18 +224,11 @@ export async function executeAllowlisted(entry, arguments_, call, options = {})
         exitCode: 0,
         data: successData(entry, limited.text),
         artifacts,
-        message: `${entry.toolName} が成功しました`,
+        message: `${entry.toolName} succeeded`,
     };
 }
 /**
-annotations を許可リストの kind から導く。
-
-契約表の「読取専用」列は read だけが true で、fetch（ローカルへ書き出す）と
-execute（Athena のクエリ起動）は false。destructiveHint は fetch だけ true にする:
-`overwrite: true` の呼び出しはローカルの既存ファイルを上書きして戻せない。
-openWorldHint は AWS API へ到達するので全件 true。
-
-契約書の共通規約も destructiveHint を fetch 2 件だけ true と定めており、ここはそれと一致する。
+annotations を許可リストの kind から導く。destructiveHint は fetch だけ true（`overwrite: true` で既存ファイルを上書きするため）。
 */
 function annotationsOf(entry) {
     return {
@@ -262,12 +238,7 @@ function annotationsOf(entry) {
     };
 }
 /**
-許可リストのエントリ 1 件を MCP ツール定義にする。
-
-入力の検証は 2 段になる。
-inputSchema（型・列挙・書式）は SDK がハンドラ到達前に見て、入力検証エラーを返す。
-許可リスト側の規則（先頭 '-'・排他・shorthand の構成要素）は、executeAllowlisted が見て isError の応答にする。ハンドラで再度 zod parse はしない
-（SDK が既に未知キーの除去と default の適用を済ませている）。
+許可リストのエントリ 1 件を MCP ツール定義にする。zod の検証は SDK が済ませるので、ハンドラで再 parse しない。
 */
 export function allowlistedTool(spec, options = {}) {
     const executeOptions = {