@pecot/tools-mcp 0.0.0-stage → 1.0.0

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

@@ -0,0 +1,70 @@
+import type { Readable } from 'node:stream';
+import { Writable } from 'node:stream';
+import type { McpServer, Transport } from '@modelcontextprotocol/server';
+import { type StdioServerHandle } from '@modelcontextprotocol/server/stdio';
+/**
+process.stdout / process.stderr のうち、ガードが必要とする最小の書き込み面。
+*/
+export interface WritableTarget {
+    write(chunk: string | Uint8Array, callback?: (error?: Error | null) => void): boolean;
+}
+/**
+stdio の stdout を JSON-RPC 専有にするガードを張る。
+
+返した Writable だけが本物の stdout へ届き、それ以外の stdout 書き込み
+(console.log・依存ライブラリの進捗表示など) は stderr へ逃がす。
+
+「process.stdout.write を差し替えるだけ」では、transport 自身の JSON-RPC 応答まで stderr に流れる。
+するとクライアントが無応答になる。
+そのため、差し替え前に束縛した元の write を使う専用 Writable を transport へ渡す、という二段構えが必須になる。
+
+同じ stdout に対しては冪等で、2 回目以降は初回に作った Writable を返す。
+*/
+export declare function installStdoutGuard(stdout: WritableTarget, stderr: WritableTarget): Writable;
+/**
+SIGTERM / SIGINT / 'exit' の配線先。既定は process 本体で、テストはフェイクを渡す。
+*/
+export interface ProcessSignals {
+    on(event: 'SIGTERM' | 'SIGINT' | 'exit', listener: () => void): void;
+    exit(code: number): void;
+}
+export interface McpServeDependencies {
+    readonly createServer: () => McpServer;
+    readonly createTransport: (stdin: Readable, stdout: Writable) => Transport;
+    /**
+    stdout ガードを張り、JSON-RPC 専用の Writable を返す。
+    */
+    readonly installStdoutGuard: () => Writable;
+    readonly stdin: Readable;
+    readonly stderr: WritableTarget;
+    /**
+    終了時に呼ぶ後始末。
+  
+    実行中の awscli 子プロセスのように「子プロセスを持つ機能」がここへ登録する。
+    子を kill しない限り親は終了できない (子の stdio パイプが Node のイベントループを
+    保持するため、stdin の EOF で server.close() を呼んでも待ち続ける)。
+    */
+    readonly onShutdown: readonly (() => void)[];
+    readonly signals: ProcessSignals;
+}
+/**
+MCP サーバを stdio で待ち受ける。
+
+serveStdio が接続ごとに 2025 系と 2026-07-28 系のどちらかを選び、factory のインスタンスを
+1 つ固定して配る。factory は 1 接続で複数回呼ばれ得る (2026-07-28 は探査用インスタンスを捨てることがある)。
+そのため createServer() と onerror の設定以外の副作用は持たせない。
+後始末の配線 (signals / stdin) は factory の外で 1 回だけ行う。
+
+接続が完了しても待ち受けは続く。クライアントが stdin を閉じたら子プロセスを落として
+接続を閉じ、SIGTERM を待たずにプロセスが自力で終了できるようにする。
+*/
+export declare function runMcpServe(dependencies: Readonly<McpServeDependencies>): StdioServerHandle;
+/**
+`pecot-tools mcp` の action 本体。
+
+program.parse は action の Promise を await しない。
+そのため例外はここで捕まえて、process.exitCode へ反映する (unhandled rejection にしない)。
+*/
+export declare function executeMcpServe(buildDependencies: () => McpServeDependencies): void;
+export declare function mcpServeDefaultDependencies(): McpServeDependencies;
+//# sourceMappingURL=serve.d.ts.map

package/cli/dist/mcp/serve.js

@@ -0,0 +1,185 @@
+// `pecot-tools mcp` — MCP サーバとして stdio で待ち受ける実装。
+//
+// cli.ts は薄い Command だけを持つ。
+// 本モジュールは action 内の dynamic import で初めて読み込まれる (MCP SDK の読み込みを mcp 実行時に限定するため)。
+//
+// exit code 規約:
+//   0 = 正常終了 (クライアントが stdin を閉じるまで待ち受ける)
+//   1 = 起動失敗 (transport 接続エラー等) / stdout への書き込み失敗
+import { Writable } from 'node:stream';
+import { serveStdio, StdioServerTransport } from '@modelcontextprotocol/server/stdio';
+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 オブジェクトなので、テストごとに別のフェイクを使っても混入しない。
+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 を返す。
+*/
+export function installStdoutGuard(stdout, stderr) {
+    const installed = installedGuards.get(stdout);
+    if (installed !== undefined)
+        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 に限られる。
+        const done = typeof encodingOrCallback === 'function' ? encodingOrCallback : callback;
+        const isWritten = stderr.write(chunk);
+        done?.();
+        return isWritten;
+    };
+    // 代入ではなく defineProperty を使うのは、オーバーロード付きの write に単一シグネチャの
+    // 関数を代入する際の型アサーションを避けるため。
+    Object.defineProperty(stdout, 'write', {
+        value: isForwardToStderr,
+        writable: true,
+        configurable: true,
+    });
+    const protocolStdout = new Writable({
+        write(chunk, _encoding, callback) {
+            isOriginalWrite(chunk, callback);
+        },
+    });
+    // stdout の相手が消えた後の書き込み (EPIPE) は Writable の 'error' として上がる。
+    // 拾わないと uncaught 例外でスタックトレースごと落ちるため、1 行報告して終了コードを立てる。
+    protocolStdout.on('error', (error) => {
+        stderr.write(`${LOG_PREFIX} stdout への書き込みに失敗しました: ${error.message}\n`);
+        process.exitCode = 1;
+    });
+    installedGuards.set(stdout, protocolStdout);
+    return protocolStdout;
+}
+function runShutdown(dependencies) {
+    for (const hook of dependencies.onShutdown)
+        hook();
+}
+/**
+後始末を終了処理へ配線する。
+
+SIGTERM / SIGINT はハンドラを登録した時点で既定の即終了が無効になるので、明示的に exit する。
+'exit' は最後の網で、同期処理しか実行されないため後始末だけを呼ぶ。
+*/
+function installShutdownHandlers(dependencies) {
+    dependencies.signals.on('SIGTERM', () => {
+        runShutdown(dependencies);
+        dependencies.signals.exit(SIGTERM_EXIT_CODE);
+    });
+    dependencies.signals.on('SIGINT', () => {
+        runShutdown(dependencies);
+        dependencies.signals.exit(SIGINT_EXIT_CODE);
+    });
+    dependencies.signals.on('exit', () => {
+        runShutdown(dependencies);
+    });
+}
+/**
+MCP サーバを stdio で待ち受ける。
+
+serveStdio が接続ごとに 2025 系と 2026-07-28 系のどちらかを選び、factory のインスタンスを
+1 つ固定して配る。factory は 1 接続で複数回呼ばれ得る (2026-07-28 は探査用インスタンスを捨てることがある)。
+そのため createServer() と onerror の設定以外の副作用は持たせない。
+後始末の配線 (signals / stdin) は factory の外で 1 回だけ行う。
+
+接続が完了しても待ち受けは続く。クライアントが stdin を閉じたら子プロセスを落として
+接続を閉じ、SIGTERM を待たずにプロセスが自力で終了できるようにする。
+*/
+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 回だけ報告する。
+    const reported = new WeakSet();
+    const report = (error) => {
+        if (reported.has(error))
+            return;
+        reported.add(error);
+        dependencies.stderr.write(`${LOG_PREFIX} ${error.message}\n`);
+    };
+    const handle = serveStdio(() => {
+        try {
+            const server = dependencies.createServer();
+            // eslint-disable-next-line unicorn/prefer-add-event-listener -- SDK の Protocol は onerror 経由で通知
+            server.server.onerror = report;
+            return server;
+        }
+        catch (error) {
+            // factory の失敗は serveStdio が onerror (report) へ流して接続側へ内部エラーを返す。
+            // 起動に失敗したプロセスは待ち受けを続けても役に立たないため、終了コードを立てて閉じる。
+            process.exitCode = 1;
+            // 終了処理中の close 失敗は報告先が無いため握り潰す。
+            void ignoreRejection(handle.close());
+            throw error;
+        }
+    }, { transport, onerror: report });
+    dependencies.stdin.once('end', () => {
+        // 子プロセスを先に落とす。子の stdio パイプがイベントループを保持するため、
+        // 残したままだと接続を閉じるだけでは自力終了できない。
+        runShutdown(dependencies);
+        // 終了処理中の close 失敗は報告先が無いため握り潰す。
+        void ignoreRejection(handle.close());
+    });
+    return handle;
+}
+/**
+`pecot-tools mcp` の action 本体。
+
+program.parse は action の Promise を await しない。
+そのため例外はここで捕まえて、process.exitCode へ反映する (unhandled rejection にしない)。
+*/
+export function executeMcpServe(buildDependencies) {
+    const dependencies = buildDependencies();
+    try {
+        runMcpServe(dependencies);
+    }
+    catch (error) {
+        dependencies.stderr.write(`${LOG_PREFIX} ${formatError(error)}\n`);
+        process.exitCode = 1;
+    }
+}
+export function mcpServeDefaultDependencies() {
+    return {
+        createServer: () => createMcpServer(allTools()),
+        createTransport: (stdin, stdout) => new StdioServerTransport(stdin, stdout),
+        /* c8 ignore next 2 -- 実 process.stdout を差し替えるため単体テストからは起動できない (installStdoutGuard 本体はフェイク stream で検証) */
+        installStdoutGuard: () => installStdoutGuard(process.stdout, process.stderr),
+        stdin: process.stdin,
+        stderr: process.stderr,
+        // tools/call 実行中の awscli 子プロセスと、SSO ログインで待機中の子プロセスを落とす。
+        // 親が先に消えると、子は PPID 1 へ再親付けされる。
+        // timeout を張っていた親が居なくなるので、打ち切りも働かなくなる（SSO は最長 10 分待つ）。
+        onShutdown: [killRunningAwscli, shutdownLoginRegistry],
+        signals: process,
+    };
+}
+function formatError(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=serve.js.map

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

@@ -0,0 +1,69 @@
+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_<サーバ名>__*`）が噛み合わなくなる。
+*/
+export declare const MCP_SERVER_NAME = "pecot-tools";
+/**
+registerTool に渡すツールのメタ情報。
+
+inputSchema / outputSchema は自前の zod の `z.object()` で書く。SDK は渡されたスキーマ自身から JSON Schema を作る。
+そのため SDK 同梱の zod と混在しない。引数を取らないツールは inputSchema に
+`z.object({})` を渡す。
+*/
+export interface ToolConfig {
+    readonly title?: string;
+    readonly description?: string;
+    readonly inputSchema: z.ZodObject;
+    /**
+    指定すると SDK が structuredContent をこのスキーマで検証する。
+    */
+    readonly outputSchema?: z.ZodObject;
+    /**
+    readOnlyHint / destructiveHint 等、クライアントの実行判断に使われるヒント。
+    */
+    readonly annotations?: ToolAnnotations;
+}
+/**
+tools/call ハンドラの第 2 引数。ハンドラが使う面だけを SDK の ServerContext から切り出す。
+
+signal はクライアントのキャンセル (notifications/cancelled) と stdin の EOF で abort される。
+SDK の型を直接渡さないのは、ツール側とテストのフェイクを SDK の型から切り離すため。
+*/
+export interface ToolCallContext {
+    readonly signal: AbortSignal;
+}
+/**
+tools/call のハンドラ。arguments_ は inputSchema で検証済みの値。
+*/
+export type ToolHandler = (arguments_: Readonly<Record<string, unknown>>, call: ToolCallContext) => Promise<CallToolResult>;
+/**
+サーバへ登録するツール 1 件の定義。
+*/
+export interface ToolDefinition {
+    readonly name: string;
+    readonly config: ToolConfig;
+    readonly handler: ToolHandler;
+}
+interface McpServerOptions {
+    /**
+    progress ハートビートの送出周期 (ms)。既定は PROGRESS_HEARTBEAT_INTERVAL_MS で、テストが短縮する。
+    */
+    readonly progressIntervalMs?: number;
+}
+/**
+MCP サーバを生成し、渡されたツール定義を登録する。
+
+各ハンドラは登録時に実行器で包む。tools/call が並行に届いても、同時に実行されるのは 4 件までになる
+(上限はここで構造的に保証し、ツール実装側には依存しない)。
+あわせて progress ハートビートもここで包む。全ツールに一律で適用され、ツール実装側の適用判断が要らなくなる。
+
+呼び出しごとに新しい McpServer と実行器を生成する (singleton にしない)。
+*/
+export declare function createMcpServer(tools?: readonly ToolDefinition[], options?: McpServerOptions): McpServer;
+export {};
+//# sourceMappingURL=server.d.ts.map

package/cli/dist/mcp/server.js

@@ -0,0 +1,115 @@
+// 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 のコールバック型と適合しなくなる。 */
+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 件で通知が積み上がりすぎない粒度になる。
+*/
+const PROGRESS_HEARTBEAT_INTERVAL_MS = 10_000;
+/**
+tools/call の同時実行数の上限 (research R9)。
+*/
+const CONCURRENCY_LIMIT = 4;
+/**
+MCP サーバ名。initialize の serverInfo.name として返る値。
+
+`.mcp.json` の `mcpServers` の登録キーと必ず揃える。食い違うとクライアント側の表示と
+ツール名の名前空間（`mcp__plugin_pecot-t_<サーバ名>__*`）が噛み合わなくなる。
+*/
+export const MCP_SERVER_NAME = 'pecot-tools';
+/**
+tools/call 1 件分の progress 通知を開始し、即座に 1 発目 (順番待ち中) を送る。
+
+MCP では progressToken を伴わないリクエストに notifications/progress を返せない。
+そのためクライアントが token を付けてこなかった場合は、何も送らず undefined を返す。
+
+送出は run() の前から始める。守りたいのは実行中だけでなく「上限に掛かって順番待ちしている
+間も無音時計が進む」区間で、ハンドラ内に置くラッパーでは待機中を守れない。
+*/
+function startProgressHeartbeat(toolName, serverContext, intervalMs) {
+    const { signal } = serverContext.mcpReq;
+    const progressToken = serverContext.mcpReq._meta?.progressToken;
+    if (progressToken === undefined)
+        return undefined;
+    let progress = 0;
+    let phase = '順番待ち中';
+    const send = () => {
+        progress += 1;
+        // 通知はベストエフォート。クライアント切断後の reject を await の流れに乗せると、
+        // ハンドラの例外に化けて ok: false になる。そのため、ここで握り潰す。
+        void ignoreRejection(serverContext.mcpReq.notify({
+            method: 'notifications/progress',
+            params: { progressToken, progress, message: `${toolName}: ${phase}` },
+        }));
+    };
+    const timer = setInterval(send, intervalMs);
+    // キャンセル済みの呼び出しへ通知を送ると、クライアントは破棄済みのトークン宛の progress を
+    // 受けて onerror に落とす。abort した時点で周期送出を止める。
+    const stop = () => {
+        clearInterval(timer);
+        signal.removeEventListener('abort', stop);
+    };
+    if (signal.aborted) {
+        stop();
+    }
+    else {
+        signal.addEventListener('abort', stop, { once: true });
+        send();
+    }
+    return {
+        markRunning: () => { phase = '実行中'; },
+        stop,
+    };
+}
+/**
+MCP サーバを生成し、渡されたツール定義を登録する。
+
+各ハンドラは登録時に実行器で包む。tools/call が並行に届いても、同時に実行されるのは 4 件までになる
+(上限はここで構造的に保証し、ツール実装側には依存しない)。
+あわせて progress ハートビートもここで包む。全ツールに一律で適用され、ツール実装側の適用判断が要らなくなる。
+
+呼び出しごとに新しい McpServer と実行器を生成する (singleton にしない)。
+*/
+export function createMcpServer(tools = [], options = {}) {
+    const server = new McpServer({ name: MCP_SERVER_NAME, version: readVersion() });
+    if (tools.length === 0) {
+        // registerTool を 1 件もしないと tools capability 自体が宣言されないため、明示的に張る。
+        // コンストラクタの capabilities で宣言すると listChanged: true が付くので使わない。
+        server.server.registerCapabilities({ tools: {} });
+        server.server.setRequestHandler('tools/list', () => ({ tools: [] }));
+        return server;
+    }
+    const executor = createBoundedExecutor(CONCURRENCY_LIMIT);
+    const intervalMs = options.progressIntervalMs ?? PROGRESS_HEARTBEAT_INTERVAL_MS;
+    for (const tool of tools) {
+        server.registerTool(tool.name, tool.config, async (arguments_, serverContext) => {
+            const heartbeat = startProgressHeartbeat(tool.name, serverContext, intervalMs);
+            try {
+                return await executor.run(() => {
+                    heartbeat?.markRunning();
+                    return tool.handler(arguments_, { signal: serverContext.mcpReq.signal });
+                });
+            }
+            finally {
+                heartbeat?.stop();
+            }
+        });
+    }
+    return server;
+}
+//# sourceMappingURL=server.js.map

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

@@ -0,0 +1,141 @@
+import { z } from 'zod';
+import { type AllowlistEntry, type FailureCategory } from '../../domain/allowlist.js';
+import type { LoginRegistry } from '../../infra/sso/login-registry.js';
+import { type ExecutionResult } from '../result.js';
+import type { ToolCallContext, ToolDefinition } from '../server.js';
+/**
+1 回の awscli 呼び出しに与える既定の制限時間。
+*/
+export declare const TOOL_TIMEOUT_MS = 120000;
+/**
+awscli を起動せずに拒否したときの終了コード（UsageError 相当）。
+*/
+export declare const PRE_EXECUTION_EXIT_CODE = 2;
+/**
+時間切れの終了コード（coreutils timeout の慣習）。
+*/
+export declare const TIMEOUT_EXIT_CODE = 124;
+/**
+コマンドが見つからないときの終了コード（シェルの慣習）。
+*/
+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 だけを切り出し、両方が同じ書式・同じ説明文を公開できるようにする。
+*/
+export declare const PROFILE_INPUT_SHAPE: {
+    profile: z.ZodOptional<z.ZodString>;
+};
+/**
+全ツール共通の任意入力。
+
+書式の定義は domain/allowlist.ts の PROFILE_PATTERN / REGION_PATTERN にある。
+ここはその定数をそのまま inputSchema へ載せる（契約書の共通規約を tools/list で見せるため）。
+値を書き写さないので、定義は 1 箇所のまま。書式違反はハンドラ到達前に入力検証エラーとなる。awscli は起動しない。
+*/
+export declare const COMMON_INPUT_SHAPE: {
+    profile: z.ZodOptional<z.ZodString>;
+    region: z.ZodOptional<z.ZodString>;
+};
+/**
+クライアント側ページング（`--max-items` / `--starting-token`）を持つツールの入力。
+*/
+export declare const MAX_ITEMS_PAGINATION_SHAPE: {
+    max_items: z.ZodOptional<z.ZodNumber>;
+    starting_token: z.ZodOptional<z.ZodString>;
+};
+/**
+API 固有ページング（`logs get-log-events`）を持つツールの入力。
+*/
+export declare const LIMIT_NEXT_TOKEN_PAGINATION_SHAPE: {
+    limit: z.ZodOptional<z.ZodNumber>;
+    next_token: z.ZodOptional<z.ZodString>;
+    start_from_head: z.ZodDefault<z.ZodBoolean>;
+};
+/**
+ExecutionResult と同形の outputSchema。全ツールで共有する。
+*/
+export declare const TOOL_OUTPUT_SCHEMA: z.ZodObject<{
+    ok: z.ZodBoolean;
+    exitCode: z.ZodNumber;
+    category: z.ZodOptional<z.ZodString>;
+    data: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    artifacts: z.ZodArray<z.ZodString>;
+    message: z.ZodString;
+    stderr: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+実行前に拒否したときの理由。awscli は起動しない。
+*/
+export interface PreExecutionRejection {
+    readonly category: 'not-allowed' | 'invalid-input';
+    readonly message: string;
+}
+export interface ExecuteOptions {
+    /**
+    既定は TOOL_TIMEOUT_MS。
+    */
+    readonly timeoutMs?: number;
+    /**
+    許可リストの静的宣言だけでは表せない拒否条件（Athena の変更系クエリ、既存ファイルの上書き）。
+  
+    validateInput の直後・awscli の存在確認より前に評価する。存在確認を先にすると、
+    awscli 未導入の環境で「拒否されるはずの呼び出し」が awscli-missing に化ける。
+    */
+    readonly reject?: (arguments_: Readonly<Record<string, unknown>>) => PreExecutionRejection | undefined;
+    /**
+    成功時に artifacts へ載せる書き出し先。切り詰めの有無に依らず適用する。
+    */
+    readonly artifactsOf?: (arguments_: Readonly<Record<string, unknown>>) => readonly string[];
+}
+/**
+ツール定義を組み立てるときの調整点。テストが timeoutMs を短縮する。
+*/
+export interface ToolOptions {
+    readonly timeoutMs?: number;
+    /**
+    SSO の 2 件が使うログインレジストリ。既定はプロセス共有のインスタンス。
+    */
+    readonly loginRegistry?: LoginRegistry;
+}
+/**
+allowlistedTool へ渡すツール 1 件の宣言。
+*/
+export interface AllowlistedToolSpec {
+    readonly entry: AllowlistEntry;
+    readonly title: string;
+    readonly description: string;
+    readonly inputSchema: z.ZodObject;
+    readonly reject?: ExecuteOptions['reject'];
+    readonly artifactsOf?: ExecuteOptions['artifactsOf'];
+}
+/**
+失敗種別と awscli の終了コードから応答の exitCode を決める。
+
+exitCode を持たない失敗（シグナル終了・awscli を起動していない SSO の状態遷移）は
+省略するか null で渡し、1 以上へ畳む。ok: false と exitCode 0 が同居しないようにする。
+*/
+export declare function resolveExitCode(category: FailureCategory, exitCode?: number | null): number;
+/**
+許可リストのエントリ 1 件を実行し、ExecutionResult を返す。
+
+検証で弾いた場合は awscli を起動しない（exitCode 2）。awscli の失敗は種別判定にかけ、
+応答へ載せる stdout / stderr は必ず秘匿化と上限を通す。
+*/
+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 の適用を済ませている）。
+*/
+export declare function allowlistedTool(spec: Readonly<AllowlistedToolSpec>, options?: Readonly<ToolOptions>): ToolDefinition;
+//# sourceMappingURL=_shared.d.ts.map