@pecot/visual-mcp 0.0.0-stage → 1.0.0

package/cli/dist/mcp/result.js

@@ -0,0 +1,201 @@
+// MCP ツールの結果表現と、SDK の CallToolResult への変換。
+//
+// pecotv の各ツールは「既存 CLI コマンドの実処理を呼び、その成否・生成物・出力を一様な形で返す」構造になる。
+// そのためコマンド固有の戻り値ではなく ToolResult に正規化してからプロトコル表現へ変換する。加えて parsePathArguments が、引数の parse とパス引数への
+// Windows 形式パス変換 (windows-path.ts) をまとめて担う。
+import path from 'node:path';
+import { Writable } from 'node:stream';
+import { toPosixPath } from './windows-path.js';
+/**
+解決できないパス (相対パス / 変換できない Windows 形式) を受け取ったときの exit code (UsageError 相当)。
+*/
+const USAGE_ERROR_EXIT_CODE = 2;
+/**
+1 本の捕捉で保持する出力の上限 (バイト)。
+
+捕捉した出力は ToolResult に載って MCP クライアントのコンテキストへ入る。
+長時間ツール (slide_convert 等) の進捗ログが際限なく積み上がると、メモリとクライアント側コンテキストを圧迫する。超過分は「新しい方を残す」= 先頭を捨てる:
+失敗の直接原因は末尾に出るため、切り詰めるなら古い側から捨てるのが妥当。
+*/
+const OUTPUT_CAPTURE_LIMIT_BYTES = 64 * 1024;
+/**
+切り詰めが起きたことを text() の先頭に 1 行で明示するマーカー。
+*/
+const TRUNCATION_MARKER = `[pecotv] 出力が上限 ${String(OUTPUT_CAPTURE_LIMIT_BYTES)} バイトを超えたため、先頭を切り詰めました\n`;
+/**
+ToolResult を MCP の CallToolResult へ変換する。
+
+content には structuredContent と同じ内容の JSON テキストを載せる。structuredContent を
+読めないクライアントでもツール結果を解釈できるようにするための二重化で、
+MCP 仕様が推奨する形。
+
+引数は deep readonly だが、戻り値は SDK 側の mutable 型のまま返す。
+SDK が readonly 型を公開していないため、この非対称は境界として許容する。
+*/
+export function toCallToolResult(result) {
+    const structuredContent = toStructuredContent(result);
+    return {
+        content: [{ type: 'text', text: JSON.stringify(structuredContent) }],
+        structuredContent,
+        // exactOptionalPropertyTypes 下で「成功時は isError キー自体を持たない」を表現する。
+        ...(!result.ok && { isError: true }),
+    };
+}
+function toStructuredContent(result) {
+    return {
+        ok: result.ok,
+        exitCode: result.exitCode,
+        artifacts: [...result.artifacts],
+        data: { ...result.data },
+        message: result.message,
+        ...(result.stdout !== undefined && { stdout: result.stdout }),
+        ...(result.stderr !== undefined && { stderr: result.stderr }),
+    };
+}
+/**
+引数の parse と、パスパラメータ群の変換・絶対パス確認 (FR-011) をまとめて行う。
+
+受理したときは変換済みの値を載せた同型オブジェクトを返す。ハンドラ側に未変換の束縛を残さないための形にしている。
+パスを下流へ渡すルートが 1 箇所でも取りこぼすと、Windows のクライアントには「変換されたりされなかったり」に見える。
+そのため確認と変換を別々の関数に割らない。
+
+拒否するのは (1) Windows 形式だが POSIX パスへ畳めないもの (他 distro の UNC 等) と
+(2) 変換後も絶対パスにならないものの 2 つ。両方が同じ呼び出しに含まれるときは、
+一方を返して他方を隠すと利用者が取りこぼすため invalidPaths に両方を列挙する。
+message は解決不能側 (1) を主文にする。cwd 依存の曖昧さより「渡した値をそもそも
+解釈できない」方が原因の特定に時間がかかるため。MCP クライアントの cwd はサーバ
+プロセスの cwd と一致する保証が無いため、相対パスは解決せず即座に弾く。invalidPaths
+には利用者が渡した元の値を載せる (変換後の値だけを見せると、渡した引数との対応が取れない)。
+
+見るのは「cwd 非依存で一意に解決できるか」だけで、`/a/../etc/passwd` のような
+`..` を含む絶対パスは通す。FR-011 は cwd の曖昧さを排除する規約で、
+サンドボックス境界ではない。アクセス範囲の制限は本関数の責務ではない。
+*/
+export function parsePathArguments(
+// zod のスキーマはメソッドを持つクラス型で、readonly 化すると parse を呼べない。
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+schema, arguments_, keys) {
+    const parsed = schema.parse(arguments_);
+    const draft = { ...parsed };
+    /**
+    パラメータ名 → 変換内容。拒否結果に載せて「どう解釈したか」を利用者に見せる。
+    */
+    const converted = {};
+    const unsupportedPaths = [];
+    const unsupportedDetails = [];
+    const relativePaths = [];
+    for (const key of keys) {
+        // eslint-disable-next-line security/detect-object-injection -- key は各ツールが定数で渡すパス引数名
+        const value = parsed[key];
+        // 省略された任意パラメータは素通しする (undefined 以外が来ることは inputSchema が防ぐ)。
+        if (typeof value !== 'string')
+            continue;
+        const conversion = toPosixPath(value);
+        if (conversion.kind === 'unsupported') {
+            unsupportedPaths.push(`${key}=${value}`);
+            unsupportedDetails.push(`${key}=${value} (${conversion.reason})`);
+            continue;
+        }
+        if (conversion.kind === 'converted') {
+            // eslint-disable-next-line security/detect-object-injection -- key は各ツールが定数で渡すパス引数名
+            converted[key] = { from: value, to: conversion.path };
+            // eslint-disable-next-line security/detect-object-injection -- key は各ツールが定数で渡すパス引数名
+            draft[key] = conversion.path;
+            continue;
+        }
+        if (!path.isAbsolute(value))
+            relativePaths.push(`${key}=${value}`);
+    }
+    const convertedPart = Object.keys(converted).length === 0 ? {} : { convertedPaths: converted };
+    const invalidPaths = [...unsupportedPaths, ...relativePaths];
+    if (invalidPaths.length > 0) {
+        const messages = [
+            ...(unsupportedDetails.length > 0 ? [`Windows 形式のパスを解決できません: ${unsupportedDetails.join(' / ')}`] : []),
+            ...(relativePaths.length > 0 ? [`パスは絶対パスで指定してください: ${relativePaths.join(', ')}`] : []),
+        ];
+        return {
+            rejected: {
+                ok: false,
+                exitCode: USAGE_ERROR_EXIT_CODE,
+                artifacts: [],
+                data: { invalidPaths, ...convertedPart },
+                message: messages.join(' / '),
+            },
+        };
+    }
+    // 変換が 1 件も無ければ parse 済みの値をそのまま返す。変換があれば、
+    // draft は parsed のキー集合と型をそのまま保ち、パス引数の値だけを toPosixPath が返した
+    // 文字列へ差し替えている (schema の他フィールドには一切触れない)。差し替え後の値も
+    // string で schema 側の型と矛盾しないため、再 parse せず Output として返す。
+    // eslint-disable-next-line no-restricted-syntax -- 上記の理由により draft は Output と同型 (unknown 経由の narrowing)
+    return ({ input: Object.keys(converted).length === 0 ? parsed : draft });
+}
+/**
+既に文字列として手元にある出力を、出力捕捉と同じ上限・同じマーカーで切り詰める。
+
+子プロセスの結果 (SpawnResult) のように Writable を経由しない出力にも同じ上限を働かせる
+ためのエントリ。上限を超える出力をそのまま ToolResult に載せると、エージェントのコンテキストを
+際限なく食う (`playwright install` は非 TTY でも進捗を stdout へ書く)。
+*/
+export function truncateCapturedText(text) {
+    const buffer = Buffer.from(text, 'utf8');
+    // createOutputCapture と同じく新しい方 (末尾) を残す。失敗の直接原因は末尾に出る。
+    return buffer.length <= OUTPUT_CAPTURE_LIMIT_BYTES
+        ? text
+        : TRUNCATION_MARKER + buffer.subarray(buffer.length - OUTPUT_CAPTURE_LIMIT_BYTES).toString('utf8');
+}
+/**
+メモリ上に蓄積する Writable を作る。
+
+MCP サーバのプロセス stdout は JSON-RPC 専有なので、既存コマンドの stdout / stderr は
+これに差し替えて捕捉し、ToolResult へ転写する。
+
+蓄積量は OUTPUT_CAPTURE_LIMIT_BYTES で頭打ちにし、超えた分は先頭から捨てる。
+*/
+export function createOutputCapture() {
+    // Buffer のまま溜めて取り出し時に一括デコードする。chunk 単位でデコードすると
+    // マルチバイト文字が chunk 境界で破損しうる。
+    // decodeStrings は既定 true なので、文字列を write しても _write には Buffer で届く。
+    const chunks = [];
+    let retainedBytes = 0;
+    let isTruncated = false;
+    /**
+    保持量が上限に収まるまで先頭から捨てる。境界にかかる chunk は途中から切り出す。
+    */
+    const dropOverflow = () => {
+        while (retainedBytes > OUTPUT_CAPTURE_LIMIT_BYTES) {
+            const head = chunks[0];
+            /* c8 ignore next -- retainedBytes > 0 なら chunks は非空なので到達不能、防御網のみ */
+            if (head === undefined)
+                return;
+            isTruncated = true;
+            const excess = retainedBytes - OUTPUT_CAPTURE_LIMIT_BYTES;
+            if (head.length <= excess) {
+                chunks.shift();
+                retainedBytes -= head.length;
+            }
+            else {
+                chunks[0] = head.subarray(excess);
+                retainedBytes -= excess;
+            }
+        }
+    };
+    const stream = new Writable({
+        // Node stream の _write シグネチャに揃える必要があり、readonly 化できない。
+        // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+        write(chunk, _encoding, callback) {
+            const buffered = Buffer.from(chunk);
+            chunks.push(buffered);
+            retainedBytes += buffered.length;
+            dropOverflow();
+            callback();
+        },
+    });
+    return {
+        stream,
+        // 切り詰めた場合、残った先頭は多バイト文字の途中から始まりうる (その 1 文字だけが
+        // U+FFFD になる)。バイト数で頭打ちにする以上避けられないので、マーカーで明示する。
+        text: () => (isTruncated ? TRUNCATION_MARKER : '') + Buffer.concat(chunks).toString('utf8'),
+    };
+}
+//# sourceMappingURL=result.js.map

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

@@ -0,0 +1,65 @@
+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;
+    /**
+    起動中の Slidev dev サーバ (slide_dev) を全て停止する。
+    */
+    readonly shutdownDevServers: () => void;
+    readonly signals: ProcessSignals;
+}
+/**
+MCP サーバを stdio transport で公開する。
+
+serveStdio は 2025 系と 2026-07-28 系の両方に応答する。接続ごとに factory から
+インスタンスを作り、最初のメッセージで版を決める (factory は 1 接続で 2 回呼ばれ得る)。
+transport は従来どおり stdout ガード越しに作って渡すため、JSON-RPC 以外は stdout に載らない。
+
+クライアントが stdin を閉じたら dev サーバを止め、接続を閉じて自力で終了できるようにする。
+v2 の StdioServerTransport は EOF で自分も閉じるが、dev サーバの後始末は本層の責務。
+*/
+export declare function runMcpServe(dependencies: Readonly<McpServeDependencies>): StdioServerHandle;
+/**
+`pecotv 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,187 @@
+// `pecotv mcp` — MCP サーバとして stdio で待ち受ける実装。
+//
+// 配置が src/commands/ ではなく src/mcp/ なのは ESLint の依存方向制約
+// (commands → mcp の import 禁止) による。cli.ts はどの zone の target でもないため、
+// ここから直接呼べる。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 { devServerRegistry } from './dev-server-registry.js';
+import { createMcpServer } from './server.js';
+import { allTools } from './tools/index.js';
+import { ignoreRejection } from '../domain/_shared/ignore-rejection.js';
+/**
+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 と callback は省略できる)。
+        // encoding は意図的に捨てる: 逃がす先の stderr は既定の utf8 で解釈すればよく、
+        // ここで扱うのは console 系が書く utf8 文字列か Buffer に限られる。encoding を
+        // 引き回すと BufferEncoding への narrowing のために型アサーションが必要になる。
+        const done = typeof encodingOrCallback === 'function' ? encodingOrCallback : callback;
+        const isWritten = stderr.write(chunk);
+        done?.();
+        return isWritten;
+    };
+    // 代入ではなく defineProperty を使うのは、オーバーロード付きの write に単一シグネチャの
+    // 関数を代入する際の `as` キャストを避けるため。
+    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(`pecotv mcp: stdout への書き込みに失敗しました: ${error.message}\n`);
+        process.exitCode = 1;
+    });
+    installedGuards.set(stdout, protocolStdout);
+    return protocolStdout;
+}
+/**
+dev サーバの後始末を終了ルートへ接続する。
+
+子を kill しない限り親は終了できない。stdio パイプを持つ子プロセスハンドルが Node の
+イベントループを保持するため、stdin の EOF で server.close() を呼んでも `pecotv mcp` が
+残り続ける。接続は「孤児を残さないため」だけでなく「親が終われるようにするため」にも要る。
+
+SIGTERM / SIGINT はハンドラを登録した時点で既定の即終了が無効になるので、明示的に exit する。
+'exit' は最後の網で、同期処理しか動かないため kill だけを撃つ。
+
+どのルートでも撃てるのは SIGTERM までで、レジストリが持つ SIGKILL エスカレーション
+(dev-server-registry.ts の kill) は届かない。親が先に exit すると保留中のタイマは
+実行されないためで、エスカレーションが働くのは MCP サーバが生き続ける `stop` 呼び出しに限る。
+*/
+function installShutdownHandlers(dependencies) {
+    dependencies.signals.on('SIGTERM', () => {
+        dependencies.shutdownDevServers();
+        dependencies.signals.exit(SIGTERM_EXIT_CODE);
+    });
+    dependencies.signals.on('SIGINT', () => {
+        dependencies.shutdownDevServers();
+        dependencies.signals.exit(SIGINT_EXIT_CODE);
+    });
+    dependencies.signals.on('exit', () => {
+        dependencies.shutdownDevServers();
+    });
+}
+/**
+MCP サーバを stdio transport で公開する。
+
+serveStdio は 2025 系と 2026-07-28 系の両方に応答する。接続ごとに factory から
+インスタンスを作り、最初のメッセージで版を決める (factory は 1 接続で 2 回呼ばれ得る)。
+transport は従来どおり stdout ガード越しに作って渡すため、JSON-RPC 以外は stdout に載らない。
+
+クライアントが stdin を閉じたら dev サーバを止め、接続を閉じて自力で終了できるようにする。
+v2 の StdioServerTransport は EOF で自分も閉じるが、dev サーバの後始末は本層の責務。
+*/
+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 行流す。エントリ・transport の異常
+    // (serveStdio の onerror) とインスタンス内部の異常 (server.server.onerror) に同じ報告を張る。
+    // serveStdio は接続確定後の異常を options.onerror とインスタンスの onerror の両方へ流すため、
+    // 同じ Error を 2 回報告しないよう報告済みを覚えておく。
+    const reported = new WeakSet();
+    const report = (error) => {
+        if (reported.has(error))
+            return;
+        reported.add(error);
+        dependencies.stderr.write(`pecotv mcp: ${error.message}\n`);
+    };
+    const handle = serveStdio(() => {
+        // factory に持たせる副作用は、インスタンスの生成と onerror の設定だけにする。
+        try {
+            const server = dependencies.createServer();
+            // SDK の Protocol は EventTarget ではなく onerror プロパティで通知する。
+            // eslint-disable-next-line unicorn/prefer-add-event-listener
+            server.server.onerror = report;
+            return server;
+        }
+        catch (error) {
+            // 起動失敗は exit 1 の契約。報告は serveStdio が onerror へ流すので、ここでは終了コードと後始末だけ行う。
+            process.exitCode = 1;
+            // 終了処理中の close 失敗は報告先が無いため捨てる。
+            void ignoreRejection(handle.close());
+            throw error;
+        }
+    }, { transport, onerror: report });
+    dependencies.stdin.once('end', () => {
+        // dev サーバを先に落とす。子の stdio パイプがイベントループを保持するため、
+        // 残したままだと接続を閉じるだけでは自力終了できない。
+        dependencies.shutdownDevServers();
+        /* c8 ignore next 3 -- close() が reject するルートは StdioServerTransport には無く、防御網のみ */
+        // 終了処理中の close 失敗は報告先が無いため握り潰す。
+        void ignoreRejection(handle.close());
+    });
+    return handle;
+}
+/**
+`pecotv 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(`pecotv mcp: ${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,
+        shutdownDevServers: () => {
+            devServerRegistry().shutdown();
+        },
+        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,81 @@
+import { McpServer } from '@modelcontextprotocol/server';
+import type { CallToolResult, ToolAnnotations } from '@modelcontextprotocol/server';
+import type { z } from 'zod';
+/**
+MCP サーバ名。plugins/pecot-visual/.mcp.json の mcpServers のキーと一致させる。
+*/
+export declare const MCP_SERVER_NAME = "pecot-visual";
+/**
+registerTool に渡すツールのメタ情報。
+
+inputSchema / outputSchema は自前の zod で組み立てた object スキーマ (`z.object({ ... })`)。
+SDK は渡されたスキーマ自身で JSON Schema を作るため、ツール定義側の zod と 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 のコンテキスト型に縛られないよう、使うものだけを渡す。
+progress の送出はハートビートが担うため、ツール側は signal (キャンセル) だけを見る。
+*/
+export interface ToolCallContext {
+    /**
+    クライアントが tools/call をキャンセルしたとき、または接続が閉じたときに abort される。
+    */
+    readonly signal: AbortSignal;
+}
+/**
+createMcpServer がハンドラへ渡す、サーバ側の機能への入り口。
+*/
+export interface ToolContext {
+    /**
+    以降の progress 通知の文言を差し替え、その場で 1 発送る。長時間ツールが工程や件数を
+    利用者へ見せるために使う。progressToken の無い呼び出しでは何もしない。
+    */
+    readonly reportProgress: (message: string) => void;
+}
+/**
+tools/call のハンドラ。arguments_ は inputSchema で検証済みの値。
+context は createMcpServer 経由の呼び出しで必ず渡る（ハンドラを直接呼ぶテストでは省略できる）。
+*/
+export type ToolHandler = (arguments_: Readonly<Record<string, unknown>>, call: ToolCallContext, context?: ToolContext) => 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 が並行に届いても実行は 1 件ずつになる
+(直列化はここで構造的に保証し、ツール実装側には依存しない)。キューは再入を禁止するので、
+ハンドラ内から同じキューへ積み直すと ReentrantEnqueueError で失敗する。
+
+あわせて 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,126 @@
+// MCP サーバのファクトリ。ツール登録シームと逐次実行キューの所有をここで持つ。
+//
+// ツール 1 件以上のときは McpServer.registerTool だけを使う。
+// 低レベルの setRequestHandler('tools/list', ...) で一覧ハンドラを先に張る場合を考える。
+// 後から registerTool したときに SDK が「handler already exists」で throw する。
+// 一方でツール 0 件の McpServer は tools capability と一覧ハンドラを持たず、tools/list に -32601 を返す。
+// そのため 0 件のときだけ明示登録する。両者は排他。
+// ツールハンドラの第 2 引数 (SDK の ServerContext) は mcpReq.signal / notify 等の mutable なメンバを持つ。
+// readonly 化すると registerTool のコールバック型と適合しなくなる。
+/* eslint-disable @typescript-eslint/prefer-readonly-parameter-types */
+import { McpServer } from '@modelcontextprotocol/server';
+import { readVersion } from '../version.js';
+import { createExecutionQueue } from './queue.js';
+import { ignoreRejection } from '../domain/_shared/ignore-rejection.js';
+/**
+progress ハートビートの送出周期 (ms)。
+
+守る相手は MCP クライアントの「無音タイムアウト」で、Claude Code の計測は 30 分の
+idle watchdog (progress 受信でリセット・判定周期 30s)。10s はそこから十分な余裕があり、
+かつ長時間ツール 1 件で通知が積み上がりすぎない粒度になる。
+*/
+const PROGRESS_HEARTBEAT_INTERVAL_MS = 10_000;
+/**
+MCP サーバ名。plugins/pecot-visual/.mcp.json の mcpServers のキーと一致させる。
+*/
+export const MCP_SERVER_NAME = 'pecot-visual';
+/**
+tools/call 1 件分の progress 通知を開始し、即座に 1 発目 (キュー待機中) を送る。
+
+MCP では progressToken を伴わないリクエストに notifications/progress を返せない。
+そのためクライアントが token を付けてこなかった場合は何も送らず undefined を返す。
+判定は SDK 公式のパターンに従い、`context.mcpReq._meta` の progressToken の有無で行う。
+
+送出は enqueue の前から始める。守りたいのは実行中だけでなく「直列キューで順番待ちしている
+間も無音時計が進む」区間で、ハンドラ内に置くラッパーではデキュー前を守れない。
+
+クライアントがキャンセル (notifications/cancelled) した後は、周期送出と reportProgress のどちらからも
+送らない。キャンセル済みのリクエストへ通知を返し続けると、クライアント側の onerror に
+未知トークン宛の通知が積み上がる。
+*/
+function startProgressHeartbeat(toolName, context, intervalMs) {
+    const progressToken = context.mcpReq._meta?.progressToken;
+    if (progressToken === undefined)
+        return undefined;
+    const { signal } = context.mcpReq;
+    let progress = 0;
+    let phase = 'キュー待機中';
+    let isStopped = false;
+    // 周期送出と reportProgress のどちらも通る関門。停止後・キャンセル後は何も送らない。
+    const send = () => {
+        if (isStopped)
+            return;
+        progress += 1;
+        // 通知はベストエフォート。クライアント切断後の reject を await ルートに乗せると
+        // ハンドラの例外に化けて ok: false になるため、ここで握り潰す。
+        void ignoreRejection(context.mcpReq.notify({
+            method: 'notifications/progress',
+            params: { progressToken, progress, message: `${toolName}: ${phase}` },
+        }));
+    };
+    const timer = setInterval(send, intervalMs);
+    const stop = () => {
+        isStopped = true;
+        clearInterval(timer);
+        signal.removeEventListener('abort', stop);
+    };
+    if (signal.aborted) {
+        stop();
+    }
+    else {
+        send();
+        signal.addEventListener('abort', stop, { once: true });
+    }
+    return {
+        markRunning: () => { phase = '実行中'; },
+        report: (message) => {
+            phase = message;
+            send();
+        },
+        stop,
+    };
+}
+/**
+MCP サーバを生成し、渡されたツール定義を登録する。
+
+各ハンドラは登録時にキューで包むため、tools/call が並行に届いても実行は 1 件ずつになる
+(直列化はここで構造的に保証し、ツール実装側には依存しない)。キューは再入を禁止するので、
+ハンドラ内から同じキューへ積み直すと ReentrantEnqueueError で失敗する。
+
+あわせて progress ハートビートもここで包む。全ツールに一律で働き、ツール実装側の
+適用判断が要らなくなる。
+
+呼び出しごとに新しい McpServer とキューを生成する (singleton にしない)。
+*/
+export function createMcpServer(tools = [], options = {}) {
+    // サーバ名は .mcp.json のキーと揃える (initialize の serverInfo.name として返る値)。
+    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 queue = createExecutionQueue();
+    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);
+            const context = {
+                reportProgress: (message) => { heartbeat?.report(message); },
+            };
+            try {
+                return await queue.enqueue(() => {
+                    heartbeat?.markRunning();
+                    return tool.handler(arguments_, { signal: serverContext.mcpReq.signal }, context);
+                });
+            }
+            finally {
+                heartbeat?.stop();
+            }
+        });
+    }
+    return server;
+}
+//# sourceMappingURL=server.js.map