@pecot/visual-mcp 0.0.0-stage → 1.0.0

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

@@ -0,0 +1,314 @@
+// setup ツール。実行時依存 (永続層) と Playwright Chromium を明示的に取得する。
+//
+// `pecotv mcp` は MCP クライアントの接続タイムアウト (Claude Code の MCP_TIMEOUT は既定
+// 30000ms) に収めるため、起動時に何も取得しない。また、モデルが呼ぶツールの側から 120MB 級の
+// ダウンロードを通知なしに始めることも避けている。
+// そのぶん「取得する」という操作を明示的に呼べる口として本ツールを置く。
+//
+// 取得対象は 2 つある。
+// - 実行時依存 (@slidev/cli / dom-to-pptx / @slidev/parser と、実行時依存の manifest が
+//   宣言するテーマの peer)。単体配布ルートでは npx が起動のたびに node_modules を作り直すため、
+//   これらを起動層に載せられない。データ置き場の `mcp-dist/` へ置いて永続させる。
+//   置き場は `PLUGIN_DATA` で選べる。
+//   既定は `$XDG_DATA_HOME/pecot/pecot-visual/mcp-dist`、無ければ `~/.local/share/pecot/pecot-visual/mcp-dist`。
+//   プラグインルートでは同梱されているので取得済み判定で通過する。
+// - Playwright Chromium。従来どおり `~/.cache/ms-playwright` へ置く。
+//   取得後に、起動に要る OS のライブラリを確かめ、足りなければ入れる。
+//   参照: #1217、infra/playwright/host-dependencies.ts。bin/pecotv の bootstrap と同じルート。
+//
+// 実行時依存を先に取るのは、取得ロックの置き場所 (installLockPath) が依存ルートの
+// node_modules だからで、先に作っておくと chromium 側もロック付きで走れる。
+//
+// 対応する CLI サブコマンドは持たない。
+// CLI 側の chromium 取得ルートは bin/pecotv の bootstrap (`pecotv drawio url` 等の初回実行) と setup.sh にある。
+// そちらは #543 の設計どおり、同期取得・失敗時 fatal のまま変えていない。
+//
+// 取得中の無音対策は不要。
+// progress ハートビートは createMcpServer が全ツール一律で送っている (src/mcp/server.ts の startProgressHeartbeat)。
+// そのため本ツールが長時間動いている間、クライアントの idle timer はリセットされ続ける。
+import { z } from 'zod';
+import { LOCK_CONFLICT_EXIT_CODE, LOCK_WAIT_SECONDS } from '../../infra/_shared/flock.js';
+import { ensureChromiumHostDependencies, hostDependenciesDefaultDependencies, } from '../../infra/playwright/host-dependencies.js';
+import { toCallToolResult } from '../result.js';
+import { CHROMIUM_UNAVAILABLE_EXIT_CODE, chromiumDefaultDependencies, chromiumInstallFailureDetail, runtimeDefaultDependencies, RUNTIME_UNAVAILABLE_EXIT_CODE, spawnOutputPart, tlsCertificateHint, TOOL_OUTPUT_SCHEMA, } from './_shared.js';
+/**
+実行時依存を取得する。
+
+chromium と違い、取得済みなら実行そのものを飛ばす。`playwright install` は取得済みなら
+1 spawn で skip して返るが、npm install は 600MB 級の依存解決を毎回やり直すため、
+呼ぶだけで数十秒かかる。取得済み判定は「必要なパッケージが全て解決できるか」で、
+途中で失敗した中途半端な状態では false に倒れるので、再入すればやり直しになる。
+*/
+async function runRuntimeStage(dependencies, 
+// AbortSignal は EventTarget で addEventListener を呼ぶため readonly 化できない。
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+signal) {
+    const location = dependencies.root();
+    if (dependencies.isInstalled()) {
+        return { installed: true, downloaded: false, durationMs: 0, location, detail: undefined, spawned: undefined };
+    }
+    const startedAt = Date.now();
+    const spawned = await dependencies.install(signal);
+    const durationMs = Date.now() - startedAt;
+    // exit 0 でも実体が置かれたかは改めて確認する (解決できなければ取得できていない)。
+    const isInstalled = spawned.exitCode === 0 && dependencies.isInstalled();
+    const detail = isInstalled
+        ? undefined
+        : (spawned.exitCode === 0
+            ? `取得コマンドは成功しましたが ${location ?? '永続層'} から実行時依存を解決できません。`
+            : runtimeInstallFailureDetail(spawned));
+    return { installed: isInstalled, downloaded: isInstalled, durationMs, location, detail, spawned };
+}
+/**
+実行時依存の取得が失敗したときに載せる理由 (chromiumInstallFailureDetail と同じ流儀)。
+stderr が TLS の証明書検証の失敗を示すなら、chromium 側と同じ誘導を同じ条件で足す。
+*/
+function runtimeInstallFailureDetail(result) {
+    return `${runtimeFailureReason(result)}${tlsCertificateHint(result)}`;
+}
+/**
+失敗の種類ごとの理由 (誘導を足す前の本文)。
+*/
+function runtimeFailureReason(result) {
+    if (result.exitCode === LOCK_CONFLICT_EXIT_CODE) {
+        return `別のプロセスが実行時依存を取得中です (ロック待ちが ${String(LOCK_WAIT_SECONDS)} 秒を超えました)。`
+            + '取得の完了を待ってから再実行してください。';
+    }
+    if (result.timedOut) {
+        return '取得がタイムアウトしました。ネットワーク到達性 / プロキシ設定を確認のうえ再実行してください。';
+    }
+    if (result.exitCode === null) {
+        return result.signal === null
+            ? 'npm を起動できませんでした (理由は stderr を参照)。'
+            : `取得コマンドが ${result.signal} で中断されました。取得が外部から打ち切られています。`;
+    }
+    return `npm install が exit ${String(result.exitCode)} で終了しました (理由は stderr を参照)。`;
+}
+/**
+Chromium を取得する。取得済みでも Playwright 側が冪等に skip するため常に実行する。
+*/
+async function runChromiumStage(dependencies, 
+// AbortSignal は EventTarget で addEventListener を呼ぶため readonly 化できない。
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+signal) {
+    const location = dependencies.browsersRoot();
+    const isInstalledBefore = await dependencies.isInstalled();
+    const startedAt = Date.now();
+    // call.signal を接続する。クライアントがリクエストを打ち切ったら取得も止める
+    // (接続しないと子プロセスが孤児として動き続け、取得ロックを保持したままになる)。
+    const spawned = await dependencies.install(signal);
+    const durationMs = Date.now() - startedAt;
+    // exit 0 でも実体が置かれたかは改めて確認する (skip を成功と取り違えないため)。
+    const isInstalled = spawned.exitCode === 0 && await dependencies.isInstalled();
+    const detail = isInstalled
+        ? undefined
+        : (spawned.exitCode === 0
+            ? `取得コマンドは成功しましたが ${location ?? 'browsers ディレクトリ'} に chromium がありません。`
+            : chromiumInstallFailureDetail(spawned));
+    return { installed: isInstalled, downloaded: isInstalled && !isInstalledBefore, durationMs, location, detail, spawned };
+}
+/**
+Chromium が起動するのに要る OS のライブラリを確認し、足りなければ入れる (#1217)。
+
+実行ファイルの取得 (runChromiumStage) では OS のライブラリは入らない。本体は
+infra/playwright/host-dependencies.ts で、bin/pecotv の bootstrap と同じ判定・導入を通る。
+結果は bootstrap と同じ印に記録する (失敗も期限付きで記録し、毎回の確認を避ける)。
+MCP は stdout を JSON-RPC に使うため、apt-get 開始前の通知 (deps.notify) は既定のまま何も出さない。
+*/
+async function runHostDependenciesStage(dependencies, 
+// AbortSignal は EventTarget で addEventListener を呼ぶため readonly 化できない。
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+signal) {
+    const startedAt = Date.now();
+    const outcome = await ensureChromiumHostDependencies(dependencies, signal);
+    const durationMs = Date.now() - startedAt;
+    const base = { durationMs, location: undefined, spawned: undefined };
+    switch (outcome.status) {
+        case 'ok': {
+            dependencies.record('ok');
+            return { ...base, installed: true, downloaded: false, detail: undefined };
+        }
+        case 'installed': {
+            dependencies.record('ok');
+            return { ...base, installed: true, downloaded: true, detail: `入れたパッケージ: ${outcome.packages.join(' ')}` };
+        }
+        case 'missing': {
+            dependencies.record('missing');
+            return { ...base, installed: false, downloaded: false, detail: outcome.detail };
+        }
+        case 'launch-failed': {
+            // OS のライブラリ以外の原因 (実行ファイルの欠け等) は本段の担当外。
+            // 実行ファイルは runChromiumStage が揃えており、起動の失敗は各ツールが案内付きで返す。
+            // そのためここでは理由を残して通す (bin/pecotv の `pecotv chromium host-deps` と同じ扱い)。
+            dependencies.record('launch-failed');
+            return { ...base, installed: true, downloaded: false, detail: `Chromium を起動できませんでした (OS のライブラリ以外の原因): ${outcome.detail}` };
+        }
+    }
+}
+/**
+ToolResult の data へ載せる 1 系統ぶんの要約。
+*/
+function stageData(outcome) {
+    return {
+        installed: outcome.installed,
+        downloaded: outcome.downloaded,
+        durationMs: outcome.durationMs,
+        ...(outcome.location !== undefined && { location: outcome.location }),
+        ...(outcome.detail !== undefined && { detail: outcome.detail }),
+    };
+}
+/**
+取得した実体の置き場所だけを artifacts に載せる。何も取得していなければ空。
+*/
+function artifactsOf(stages) {
+    return stages
+        .filter(stage => stage.downloaded)
+        .map(stage => stage.location)
+        .filter((location) => location !== undefined);
+}
+function successMessage(runtime, chromium, hostDependencies) {
+    const parts = [
+        runtime.downloaded
+            ? `実行時依存を取得しました (${String(Math.round(runtime.durationMs / 1000))}s)`
+            : '実行時依存は取得済みです',
+        chromium.downloaded
+            ? `Playwright Chromium を取得しました (${String(Math.round(chromium.durationMs / 1000))}s)`
+            : 'Playwright Chromium は取得済みです',
+        ...(hostDependencies.downloaded ? [`Chromium の起動に要る OS のライブラリを入れました (${hostDependencies.detail ?? ''})`] : []),
+        // 起動できなかったが OS のライブラリ以外が原因 (launch-failed)。成功のまま理由を伝える。
+        ...(hostDependencies.downloaded || hostDependencies.detail === undefined ? [] : [hostDependencies.detail]),
+    ];
+    return parts.join(' / ');
+}
+/**
+`setup` を公開する。
+
+引数は取らない。chromium 側は取得済みかを見て早期 return はしない。
+判定が「取得済み」になる状態でも、実体が欠けていることがある。
+例はダウンロード途中、必要リビジョンの未取得、headless shell の欠落。
+早期 return は、取得と案内のどちらも行われない行き止まりを作る。
+`playwright install chromium` 自体が冪等で、取得済みなら Playwright 側が skip するので、
+常に実行してよい (代償は 1 spawn)。`downloaded` は実行前後の判定差で決める。
+
+実行時依存側は取得済みなら飛ばす (runRuntimeStage のコメントを参照)。
+
+片方が失敗しても他方は実行する。npm が破損している環境で chromium の取得まで巻き添えに
+しないため。ok は両方が揃ったときだけ true になる。
+*/
+export function setupTool(buildDependencies = chromiumDefaultDependencies, buildRuntimeDependencies = runtimeDefaultDependencies, buildHostDependencies = hostDependenciesDefaultDependencies) {
+    const handler = async (_arguments, 
+    // ToolCallContext.signal (AbortSignal は EventTarget で addEventListener を呼ぶため readonly 化できない)。
+    // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+    call) => {
+        const runtime = await runRuntimeStage(buildRuntimeDependencies(), call.signal);
+        const chromium = await runChromiumStage(buildDependencies(), call.signal);
+        // OS のライブラリは実行ファイルが揃ってからでないと起動で確かめられない。
+        const hostDependencies = chromium.installed ? await runHostDependenciesStage(buildHostDependencies(), call.signal) : undefined;
+        const artifacts = artifactsOf([runtime, chromium]);
+        const data = {
+            runtime: stageData(runtime),
+            chromium: stageData(chromium),
+            ...(hostDependencies !== undefined && { hostDeps: stageData(hostDependencies) }),
+        };
+        if (runtime.installed && chromium.installed && hostDependencies?.installed === true) {
+            const result = {
+                ok: true,
+                exitCode: 0,
+                // ダウンロードした実体の置き場所を成果物として返す。取得済みなら何も置いていない。
+                artifacts,
+                data: {
+                    event: runtime.downloaded || chromium.downloaded || hostDependencies.downloaded ? 'setup.done' : 'setup.skipped',
+                    ...data,
+                },
+                message: successMessage(runtime, chromium, hostDependencies),
+                ...spawnOutputPart(chromium.spawned ?? emptySpawn()),
+            };
+            return toCallToolResult(result);
+        }
+        // 両系統が失敗することもある (ネットワーク断・プロキシ誤設定では両方が落ちる)。
+        // 片方だけを見ると、もう片方の理由が data.<系統>.detail にしか残らず message から
+        // 消えるため、失敗した系統を全て畳んで載せる。
+        const failures = [
+            ...(runtime.installed ? [] : [{ label: '実行時依存', reason: 'runtime-install-failed', stage: runtime }]),
+            ...(chromium.installed ? [] : [{ label: 'Playwright Chromium', reason: 'chromium-install-failed', stage: chromium }]),
+            ...(hostDependencies === undefined || hostDependencies.installed
+                ? []
+                : [{ label: 'Chromium の OS ライブラリ', reason: 'chromium-host-deps-missing', stage: hostDependencies }]),
+        ];
+        const detail = failures.map(failure => `${failure.label}: ${failure.stage.detail ?? ''}`).join(' / ');
+        // OS ライブラリの失敗は「取得」ではなく「足りない」ことを案内するため、取得の失敗と分ける。
+        // その detail は足りないライブラリと入れるコマンドまで書いた文なので、前置きを付けずに載せる。
+        const acquisitionFailures = failures.filter(failure => failure.reason !== 'chromium-host-deps-missing');
+        const hostDependenciesDetail = failures.find(failure => failure.reason === 'chromium-host-deps-missing')?.stage.detail;
+        const message = [
+            ...(acquisitionFailures.length === 0
+                ? []
+                : [`${acquisitionFailures.map(failure => failure.label).join(' / ')} の取得に失敗しました: `
+                        + acquisitionFailures.map(failure => `${failure.label}: ${failure.stage.detail ?? ''}`).join(' / ')]),
+            ...(hostDependenciesDetail === undefined ? [] : [hostDependenciesDetail]),
+        ].join(' / ');
+        const result = {
+            ok: false,
+            exitCode: runtime.installed ? CHROMIUM_UNAVAILABLE_EXIT_CODE : RUNTIME_UNAVAILABLE_EXIT_CODE,
+            artifacts,
+            data: {
+                event: 'setup.error',
+                reason: failures.map(failure => failure.reason).join(','),
+                detail,
+                ...data,
+            },
+            message,
+            ...spawnOutputPart(mergeSpawned(failures.map(failure => failure.stage.spawned))),
+        };
+        return toCallToolResult(result);
+    };
+    return {
+        name: 'setup',
+        config: {
+            title: '実行環境の準備 (実行時依存 / Chromium 取得と OS ライブラリ)',
+            description: 'pecotv が使う実行時依存 (@slidev/cli / dom-to-pptx / @slidev/parser 等) と Playwright Chromium をダウンロードする。'
+                + 'slide_create / slide_convert / slide_sync が「実行時依存が未取得」で失敗したとき、'
+                + 'また drawio_export / slide_convert / drawio_create の PNG 出力が「Chromium が未取得」で失敗したときに呼ぶ。'
+                + '初回は実行時依存 約 600MB と Chromium 約 120MB をダウンロードするため完了まで数十秒かかる。'
+                + 'Chromium の起動に要る OS のライブラリが足りなければ、sudo を使える環境では apt-get で入れ、'
+                + '使えない環境では入れるコマンドを返す。'
+                + '取得済みなら skip するため短時間で終わる (何度呼んでも安全)。',
+            // 引数を取らないツールは空の z.object を渡す (src/mcp/server.ts の ToolConfig)。
+            inputSchema: z.object({}),
+            outputSchema: TOOL_OUTPUT_SCHEMA,
+            // Claude Code は annotations から自動承認の可否を組み立てるため、既定値と同じでも
+            // 明示する。ダウンロードでファイルシステムを書き換え (destructive)、外部ホストへ
+            // 到達する (openWorld)。読み取り専用ではないので readOnlyHint は立てない。
+            // 取得済みなら skip するため、何度呼んでも状態は変わらない (idempotent)。
+            annotations: { destructiveHint: true, idempotentHint: true, openWorldHint: true },
+        },
+        handler,
+    };
+}
+/**
+取得を飛ばした系統には子プロセスが無い。stdout / stderr のキーは契約どおり残す。
+*/
+function emptySpawn() {
+    // eslint-disable-next-line unicorn/no-null -- SpawnResult は起動なしを exitCode: null で表す
+    return { exitCode: null, signal: null, stdout: '', stderr: '', timedOut: false };
+}
+/**
+失敗した系統の出力を 1 つに畳む。
+
+ToolResult の stdout / stderr は 1 組しか持てないため、両系統が失敗したときは
+どちらの出力も落とさずに連結する (原因が stdout 側にあることもある)。
+*/
+function mergeSpawned(spawned) {
+    const present = spawned.filter((result) => result !== undefined);
+    if (present.length === 0)
+        return emptySpawn();
+    const first = present[0] ?? emptySpawn();
+    if (present.length === 1)
+        return first;
+    return {
+        ...first,
+        stdout: present.map(result => result.stdout).filter(text => text !== '').join('\n'),
+        stderr: present.map(result => result.stderr).filter(text => text !== '').join('\n'),
+    };
+}
+//# sourceMappingURL=setup.js.map

package/cli/dist/mcp/tools/slide-dev.d.ts

@@ -0,0 +1,17 @@
+import { type EnsureThemeLinkedResult, type ThemeLinkContext } from '../../commands/slidev-project/linked-theme.js';
+import { type DevServerRegistry } from '../dev-server-registry.js';
+import type { ToolDefinition } from '../server.js';
+import { type RuntimeDependencies } from './_shared.js';
+/**
+テーマを今の値で張る port。dev は、テーマを参照しない talk-dir を `theme-none` で止める。
+*/
+export type EnsureThemeLinked = (talkDirectory: string, context: ThemeLinkContext) => Promise<EnsureThemeLinkedResult>;
+/**
+`slide_dev` を公開する。
+
+起動は「ポートを決めて slidev を子プロセスで起こし、127.0.0.1 へ GET 200 が通ったら
+URL を返す」だけで、終了は待たない。ready までは計測で約 1 秒、その間は直列キュー
+(src/mcp/queue.ts) を占有する。
+*/
+export declare function slideDevTool(buildRegistry?: () => DevServerRegistry, buildRuntimeDependencies?: () => RuntimeDependencies, buildEnsureThemeLinked?: () => EnsureThemeLinked): ToolDefinition;
+//# sourceMappingURL=slide-dev.d.ts.map

package/cli/dist/mcp/tools/slide-dev.js

@@ -0,0 +1,237 @@
+// slide_dev ツール。talk-dir の Slidev dev サーバを起動し、ブラウザで開ける URL を返す。
+//
+// 対応する CLI サブコマンドは持たない (`setup` と同じ MCP 専用ツール)。dev サーバの寿命は
+// MCP サーバプロセスに紐づくため、CLI から起動しても呼び出しの終了と同時に落ちるだけで
+// 意味を持たない。プレビュールートを MCP 一本に絞る #1023 の決定にも沿う。
+//
+// 実処理は src/mcp/dev-server-registry.ts が持つ。ここに置くのは引数の写像・実行前ガード・
+// ToolResult への正規化だけで、他のツールが commands/ の execute<Cmd>() を呼ぶ位置に
+// レジストリが入る形になる。
+// 参照するのは引数で受けた talk-dir と、その直下の固定名 (slides.md / node_modules) のみ。
+/* eslint-disable security/detect-non-literal-fs-filename */
+import { existsSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { z } from 'zod';
+import { errorToReason as slideCreateErrorToReason } from '../../commands/slidev-project/create.js';
+import { ensureTalkThemeLinked, linkedThemeDefaultDependencies, } from '../../commands/slidev-project/linked-theme.js';
+import { pluginDependencyRoot } from '../../infra/_shared/dependency-root.js';
+import { resolvePluginRoot } from '../../infra/_shared/plugin-root.js';
+import { devServerRegistry } from '../dev-server-registry.js';
+import { parsePathArguments, toCallToolResult } from '../result.js';
+import { ensureRuntimeDependencies, runtimeDefaultDependencies, TOOL_OUTPUT_SCHEMA, WINDOWS_PATH_NOTE, } from './_shared.js';
+/**
+dev サーバを起動できなかったときの exit code (各コマンドの RuntimeError と同じ 1)。
+*/
+const DEV_SERVER_EXIT_CODE = 1;
+/**
+子プロセスを起こす前に諦めたルートの出力。
+
+ToolResult の stdout / stderr が省略されるのは「捕捉していない」ときで、捕捉した結果が
+空であることとは意味が違う (tools/_shared.ts)。実行前ガードでも捕捉相当のキーは残す。
+*/
+const NO_OUTPUT = { stdout: '', stderr: '' };
+// context に AbortSignal を持つため readonly にできない。
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+function ensureThemeLinkedWithDefaults(directory, context) {
+    return ensureTalkThemeLinked(directory, linkedThemeDefaultDependencies(pluginDependencyRoot() ?? resolvePluginRoot(), context), { requireTheme: true });
+}
+function defaultEnsureThemeLinked() {
+    return ensureThemeLinkedWithDefaults;
+}
+const slideDevInput = z.object({
+    dir: z.string()
+        .describe('Slidev dev サーバを起動する talk-dir の絶対パス。相対パスは受け付けない。'
+        + WINDOWS_PATH_NOTE),
+    port: z.number().int().min(1).max(65_535).optional()
+        .describe('起動するポート。使用中なら別のポートへは移らず失敗する。'
+        + '省略時は 3030 から 3034 までを小さい順に試し、最初に空いていたポートで起動する。'
+        + '起動済みの talk-dir に別のポートを指定すると、そのポートで開き直す'),
+    stop: z.boolean().default(false)
+        .describe('true で該当 talk-dir の dev サーバを停止する (停止時は dir 以外の引数は意味を持たない)'),
+});
+/**
+spawn する前に talk-dir の体裁を確認する。続行してよければ undefined。
+
+実在しない cwd への spawn は 'error' イベントになり、これを spawn 後に扱うと失敗の理由が
+プロセス起動エラーに化ける。node_modules の確認は、テーマの張り直しの後に行う (inspectNodeModules)。
+*/
+function inspectTalkDirectory(directory) {
+    let isDirectory = false;
+    try {
+        isDirectory = statSync(directory).isDirectory();
+    }
+    catch {
+        // 不在。下の分岐で理由を組み立てる。
+    }
+    if (!isDirectory) {
+        return {
+            reason: 'talk-dir-not-found',
+            detail: `talk-dir がありません: ${directory}。`
+                + '`slide_create` で生成したディレクトリの絶対パスを指定してください。',
+        };
+    }
+    if (!existsSync(path.join(directory, 'slides.md'))) {
+        return {
+            reason: 'slides-md-not-found',
+            detail: `${directory} に slides.md がありません。Slidev プロジェクトのルートを指定してください。`,
+        };
+    }
+    return undefined;
+}
+/**
+テーマを張った後の node_modules を確認する。続行してよければ undefined。
+テーマの張り直しで復旧できる状態を、復旧の前に拒まないよう、張り直しの後に呼ぶ。
+*/
+function inspectNodeModules(directory) {
+    // existsSync は symlink を辿るため、dangling symlink もここで false になる。
+    if (!existsSync(path.join(directory, 'node_modules'))) {
+        return {
+            reason: 'node-modules-unresolved',
+            detail: `${directory}/node_modules を解決できません (symlink が切れている可能性があります)。`
+                + `\`slide_sync\` (dir: ${directory}) を実行してから再試行してください。`,
+        };
+    }
+    return undefined;
+}
+/**
+実行前ガードで諦めたときの ToolResult。
+*/
+function guardFailure(defect, directory, warnings = []) {
+    return {
+        ok: false,
+        exitCode: DEV_SERVER_EXIT_CODE,
+        artifacts: [],
+        data: {
+            event: 'slide.dev.error',
+            reason: defect.reason,
+            detail: defect.detail,
+            dir: directory,
+            ...(warnings.length > 0 && { warnings }),
+        },
+        message: defect.detail,
+        ...NO_OUTPUT,
+    };
+}
+/**
+`slide_dev` を公開する。
+
+起動は「ポートを決めて slidev を子プロセスで起こし、127.0.0.1 へ GET 200 が通ったら
+URL を返す」だけで、終了は待たない。ready までは計測で約 1 秒、その間は直列キュー
+(src/mcp/queue.ts) を占有する。
+*/
+export function slideDevTool(buildRegistry = devServerRegistry, buildRuntimeDependencies = runtimeDefaultDependencies, buildEnsureThemeLinked = defaultEnsureThemeLinked) {
+    const handler = async (arguments_, 
+    // ToolCallContext.signal (AbortSignal は EventTarget で addEventListener を呼ぶため readonly 化できない)。
+    // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+    call) => {
+        const validated = parsePathArguments(slideDevInput, arguments_, ['dir']);
+        if (validated.rejected !== undefined)
+            return toCallToolResult(validated.rejected);
+        const input = validated.input;
+        // 停止は実行時依存の確認より前に置く。止めるのに @slidev/cli は要らず、後ろに置くと
+        // 起動後に依存を失った環境で「動いているサーバを止められない」行き止まりになる。
+        if (input.stop) {
+            const stopped = buildRegistry().stop(input.dir);
+            return toCallToolResult({
+                ok: true,
+                exitCode: 0,
+                artifacts: [],
+                data: {
+                    event: 'slide.dev.stopped',
+                    dir: input.dir,
+                    stopped: stopped.stopped,
+                    ...(stopped.port !== undefined && { port: stopped.port }),
+                },
+                // 動いていないサーバへの停止要求は失敗にしない (呼び出しの目的は達成されている)。
+                message: stopped.stopped
+                    ? `slide dev: 停止しました (${input.dir})`
+                    : `slide dev: 起動中のサーバはありません (${input.dir})`,
+                ...NO_OUTPUT,
+            });
+        }
+        // 起動には @slidev/cli の bin が要る。未取得のときの失敗の型は
+        // slide_create / slide_convert / slide_sync と揃える。
+        const missingRuntime = ensureRuntimeDependencies('slide_dev', buildRuntimeDependencies());
+        if (missingRuntime !== undefined)
+            return toCallToolResult(missingRuntime);
+        const defect = inspectTalkDirectory(input.dir);
+        if (defect !== undefined)
+            return toCallToolResult(guardFailure(defect, input.dir));
+        // テーマを今の値で張る。取得済みなら stamp を比べるだけで、ネットワークには出ない。
+        // 取得中の警告は応答の data.warnings に載せ、MCP のキャンセルは取得 (git) まで届ける。
+        const warnings = [];
+        let ensured;
+        const context = {
+            signal: call.signal,
+            warn: (message) => {
+                warnings.push(message);
+            },
+        };
+        try {
+            ensured = await buildEnsureThemeLinked()(input.dir, context);
+        }
+        catch (error) {
+            return toCallToolResult(guardFailure({
+                reason: slideCreateErrorToReason(error),
+                detail: error instanceof Error ? error.message : String(error),
+            }, input.dir, warnings));
+        }
+        const nodeModulesDefect = inspectNodeModules(input.dir);
+        if (nodeModulesDefect !== undefined)
+            return toCallToolResult(guardFailure(nodeModulesDefect, input.dir, warnings));
+        // 起動済みのサーバは、稼働中の vite が旧い module graph のままになる。張り直すか、生成ファイルを書き直したら止めて起動し直す。
+        // 旧プロセスがポートを手放すまで待つ。待たないと、port 明示の呼び出しが「使用中」で失敗しうる。
+        if (ensured.relinked || ensured.regenerated)
+            await buildRegistry().stopAndWait(input.dir);
+        const started = await buildRegistry().start(input.dir, { port: input.port, signal: call.signal });
+        if (!started.ok) {
+            return toCallToolResult({
+                ok: false,
+                exitCode: DEV_SERVER_EXIT_CODE,
+                artifacts: [],
+                data: { event: 'slide.dev.error', reason: started.reason, detail: started.detail, dir: input.dir },
+                message: started.detail,
+                stdout: started.stdout,
+                stderr: started.stderr,
+            });
+        }
+        return toCallToolResult({
+            ok: true,
+            exitCode: 0,
+            artifacts: [],
+            data: {
+                event: started.reused ? 'slide.dev.reused' : 'slide.dev.started',
+                dir: input.dir,
+                url: started.url,
+                port: started.port,
+                reused: started.reused,
+                // MCP サーバが異常終了して dev サーバだけ残ったときの、手動回収の逃がし先。
+                ...(started.pid !== undefined && { pid: started.pid }),
+                ...(warnings.length > 0 && { warnings }),
+            },
+            message: started.reused
+                ? `slide dev: 起動済みのサーバを再利用します ${started.url}`
+                : `slide dev: 起動しました ${started.url}`,
+            ...NO_OUTPUT,
+        });
+    };
+    return {
+        name: 'slide_dev',
+        config: {
+            title: 'Slidev プレビュー起動',
+            description: 'talk-dir の Slidev dev サーバを起動し、ブラウザで開ける URL (data.url) を返す。'
+                + 'ポートは port で指定でき、省略時は 3030 から 3034 までの空きを使う。'
+                + '同じ talk-dir を再度呼ぶと起動済みのサーバをそのまま返す (data.reused: true)。'
+                + 'stop: true で停止する。'
+                + 'サーバは MCP サーバプロセスが生きている間だけ動き、セッションが終わるとプレビューも切れる。',
+            inputSchema: slideDevInput,
+            outputSchema: TOOL_OUTPUT_SCHEMA,
+            // annotations は明示しない。
+            // `--remote` で全インタフェースに LISTEN するため、openWorldHint: false の明示基準に反する。
+            // その基準は、ネットワークに到達しないことが確定していること。
+            // 子プロセスを起こす以上、readOnlyHint も立てられない。
+        },
+        handler,
+    };
+}
+//# sourceMappingURL=slide-dev.js.map

package/cli/dist/mcp/tools/slide-page.d.ts

@@ -0,0 +1,26 @@
+import type { ToolDefinition } from '../server.js';
+type PageFileName = {
+    readonly ok: true;
+    readonly filename: string;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+    readonly detail: string;
+};
+/**
+`file` を pages/ 直下のファイル名へ正規化する。
+
+拒否するのは次の 3 つ。
+(1) パス区切りを含む名前 = pages/ の外や下位ディレクトリを指すもの。
+(2) 名前として成立しない stem = 空・記号始まりなど。
+(3) 数字始まりの stem = lint の no-numeric-filename-prefix 違反になるもの。
+(3) を生成時に弾くのは、書けてしまうと直後の lint で必ず落ちてリネームのやり直しになるため。
+*/
+export declare function normalizePageFileName(file: string): PageFileName;
+type ReferenceReader = (file: string) => Promise<string>;
+/**
+`slide_page` のツール定義。
+*/
+export declare function slidePageTool(readReferenceText?: ReferenceReader): ToolDefinition;
+export {};
+//# sourceMappingURL=slide-page.d.ts.map