poker-mcp 1.9.9 → 1.10.0

package/README.md

@@ -4,14 +4,92 @@ YAML-based input file management tool for radiation-shielding calculation code P
 
 ## 📋 クイック情報
 
-- **バージョン**: 1.9.9
-- **ツール数**: 36メソッド
+- **バージョン**: 1.10.0
+- **ツール数**: 36メソッド（非同期ジョブを有効にすると 39、GUI を外すと 1 減る）
 - **プロトコル**: MCP (Model Context Protocol) 1.0.0 完全準拠
 - **メインサーバー**: `src/mcp_server_stdio_v4.js`
 - **データ保存**: `~/.poker-mcp/`（`POKER_MCP_HOME`環境変数で変更可）
 - **核種データ**: `${POKER_INSTALL_PATH}/LIB/ICRP-07.NDX` を直接参照
 - **実行方式**: STDIO通信（MCPプロトコル標準）
 
+## 🆕 バージョン1.10.0の新機能
+
+### ⏳ 計算の非同期実行（既定では無効）
+
+時間のかかる計算を「投入して、あとで結果を取りに行く」形で扱えるようにしました。
+1 回のツール呼び出しは数秒で終わるので、MCP クライアントの待ち時間の上限や、
+リモート公開時の中継（Cloudflare Tunnel の約 100 秒など）に切られずに、
+何時間かかる計算でも扱えます。
+
+```javascript
+poker_submitCalculation({ yaml_file: "poker.yaml" })   // → { job_id: "20261013-053012-a1b2c3", status: "queued" }
+poker_getJobStatus({ job_id: "20261013-053012-a1b2c3" }) // → queued / running / succeeded / failed
+poker_getJobResult({ job_id: "20261013-053012-a1b2c3" }) // → executeCalculation と同じ形式の結果
+poker_getDoseMap({ detector_name: "D_map", job_id: "20261013-053012-a1b2c3" })
+```
+
+**既定では無効です。** 環境変数 `POKER_MCP_ASYNC=1` を設定したときだけ、上の 3 ツールが
+現れ、`poker_getDoseMap` に `job_id` 引数が付きます。設定しなければ、ツール一覧も動作も
+v1.9.9 と同じです。主にリモート公開したサーバで使うことを想定しています。
+
+```json
+"env": {
+  "POKER_MCP_HOME": "C:\\Users\\<username>\\poker_mcp_workspace",
+  "POKER_INSTALL_PATH": "C:/Poker",
+  "POKER_MCP_ASYNC": "1"
+}
+```
+
+| 環境変数 | 既定 | 内容 |
+|---|---|---|
+| `POKER_MCP_ASYNC` | 無効 | `1` で非同期ジョブを有効にする |
+| `POKER_MCP_ASYNC_CONCURRENCY` | 1 | 同時に実行する計算の数 |
+| `POKER_MCP_JOB_RETENTION_DAYS` | 7 | 終わったジョブを残す日数 |
+| `POKER_MCP_JOB_TIMEOUT_MIN` | 1440 | 1 件の計算の打ち切り時間 [分] |
+
+**計算の中身は同期と同じです。** ジョブも `poker_executeCalculation` と同じ処理で POKER を
+呼びます。`npm run test:jobs` で、同期と非同期の `.summary`・`.dose`・線量マップが
+全行一致することを確認しています（生成日時・計算時間・入力ファイルのパスの行を除く）。
+
+**投入した時点の入力で計算します。** YAML（と `.paths`）を
+`POKER_MCP_HOME/jobs/<ジョブID>/` にコピーしてから計算し、出力もそこに書きます。
+投入後に作業中の YAML を編集しても、投入済みのジョブには混ざらず、
+作業フォルダの `poker.yaml.summary` なども上書きしません。保留中の変更は含まれないので、
+必要なら先に `poker_applyChanges` で確定してください。
+
+**サーバを再起動してもジョブは残ります。** 状態は `job.json` に保存しています。
+実行中に再起動した場合、その計算は失われているため `failed`（`INTERRUPTED_BY_RESTART`）
+になります。待機中だったジョブは再び並び、実行されます。
+
+### 🖥️ GUI（poker_openGui）を使える環境でだけ登録
+
+`poker_openGui` は、MCP サーバが動いている機械の画面に POKER.exe を開きます。次のどれかに
+当たるときは、ツール一覧から外し、処理も登録しません（名前で直接呼ばれても実行しません）。
+
+| 条件 | 想定する場面 |
+|---|---|
+| `POKER_MCP_GUI=0` | **リモート公開したサーバ。** サーバに POKER が入っていても、GUI は利用者の手元ではなくサーバの画面に開き、利用者からは見えないため |
+| Windows 以外 | POKER.exe は Windows 専用 |
+| `POKER_INSTALL_PATH` に POKER.exe が無い | POKER の GUI を入れていない環境 |
+
+手元の Windows に POKER を入れて Claude Desktop から使う普段の環境では、従来どおり
+36 ツールが登録されます。判定はサーバの起動時に 1 回だけ行い、結果は起動ログに
+`poker_openGui: 有効（…）` / `無効（…）` と理由付きで出ます。
+
+GUI を外しても、計算（POKER_CUI.exe）・検証・CAD 連携・非同期ジョブには影響しません。
+POKER.exe を使うのは `poker_openGui` だけです。
+
+リモート公開するサーバの設定例（非同期ジョブを有効にし、GUI を外す）:
+
+```json
+"env": {
+  "POKER_MCP_HOME": "C:\\poker_mcp_workspace",
+  "POKER_INSTALL_PATH": "C:/Poker",
+  "POKER_MCP_ASYNC": "1",
+  "POKER_MCP_GUI": "0"
+}
+```
+
 ## 🐛 バージョン1.9.9の修正
 
 npm で入れた環境（`npx poker-mcp`）でだけ現れる不具合と、失敗の伝え方の不具合を
@@ -406,10 +484,27 @@ npx poker-mcp
 POKERのインストールディレクトリを指定します。以下の2つの用途で参照されます。
 
 - **ICRP-07.NDX の参照先**: `{POKER_INSTALL_PATH}/LIB/ICRP-07.NDX` を直接参照（v1.4.0以降、コピーなし）
-- **POKER.exe の場所**: `{POKER_INSTALL_PATH}/POKER.exe`（`poker_openGui` 使用時）
+- **POKER.exe の場所**: `{POKER_INSTALL_PATH}/POKER.exe`（`poker_openGui` 使用時）。
+  POKER.exe が見つからなければ `poker_openGui` は登録されません（v1.10.0）
 
 **デフォルト値**: `C:/Poker`（未設定時は `C:/Poker` を使用）
 
+#### `POKER_MCP_ASYNC` ほか（オプション、v1.10.0）
+計算の非同期実行（`poker_submitCalculation` など）を有効にします。既定では無効で、設定しなければ
+ツール一覧も動作も変わりません。詳しくは「[バージョン1.10.0の新機能](#-バージョン1100の新機能)」。
+
+| 変数 | 既定 | 内容 |
+|---|---|---|
+| `POKER_MCP_ASYNC` | 無効 | `1` で非同期ジョブを有効にする |
+| `POKER_MCP_ASYNC_CONCURRENCY` | 1 | 同時に実行する計算の数 |
+| `POKER_MCP_JOB_RETENTION_DAYS` | 7 | 終わったジョブを残す日数 |
+| `POKER_MCP_JOB_TIMEOUT_MIN` | 1440 | 1 件の計算の打ち切り時間 [分] |
+
+#### `POKER_MCP_GUI`（オプション、v1.10.0）
+`0` を設定すると `poker_openGui` を登録しません。リモート公開するサーバで使います
+（GUI がサーバの画面に開き、利用者からは見えないため）。Windows 以外の環境や、
+POKER.exe が見つからない環境では、設定しなくても登録されません。計算には影響しません。
+
 ```bash
 # Windows（コマンドプロンプト）
 set POKER_MCP_HOME=C:\Users\yoshi\poker_mcp_workspace
@@ -431,6 +526,7 @@ POKER_MCP_HOME/          # デフォルト: ~/.poker-mcp/
   ├── backups/           # 自動バックアップ（最大10世代）
   ├── data/              # ICRP-07.NDX 核種データベース
   ├── logs/              # error.log, combined.log
+  ├── jobs/              # 非同期ジョブ（POKER_MCP_ASYNC=1 のときだけ。既定 7 日で自動削除）
   └── config.json        # ユーザー設定（任意）
 ```
 
@@ -466,6 +562,13 @@ POKER_MCP_HOME/          # デフォルト: ~/.poker-mcp/
    > **⚠️ 注意:** `cwd`（作業ディレクトリ）の指定は不要です。`POKER_MCP_HOME`
    > 環境変数で管理するため、`cwd` を設定すると v1.2.5 以前の問題が再発します。
 
+   > **版の固定:** `npx` は一度取得した版を使い続けることがあります。確実に特定の版を
+   > 使うには `"args": ["poker-mcp@1.9.9"]` のように版を書きます。v1.9.8 以前の npm 版では
+   > `poker_generateInput` が動きません（v1.9.9 で修正）。
+
+   リモート公開するサーバ向けの設定（非同期ジョブを有効にし、GUI を外す）は
+   「[バージョン1.10.0の新機能](#-バージョン1100の新機能)」を参照してください。
+
 3. **Claude Desktopを再起動** してMCPサーバーを有効化
 
 ### 4. 動作確認
@@ -485,7 +588,9 @@ Claude Desktopで以下のようにテストできます：
 ## 🏆 主要機能
 
 ### ✅ **MCP完全対応**
-- **36メソッド完全実装**: 全ての放射線遮蔽計算入力管理機能
+- **36メソッド完全実装**: 全ての放射線遮蔽計算入力管理機能（非同期ジョブ有効時は 39）
+- **失敗の通知**: ツールが処理の結果として失敗（`success: false`）を返すと、MCP の `isError: true` が付く（v1.9.9）
+- **計算の非同期実行**: 長い計算を投入して後から結果を取得（`POKER_MCP_ASYNC=1`、v1.10.0）
 - **JSON-RPC 2.0準拠**: 標準プロトコル完全対応
 - **STDIO通信**: MCPクライアントとの標準通信方式
 - **自動バックアップ・ロールバック**: 企業品質のデータ保護
@@ -519,6 +624,10 @@ Claude Desktopで以下のようにテストできます：
 | **📐 CAD** | 2個 | CAD から入力と経路を生成 | generateInput・generatePaths |
 | **⚙️ System** | 6個 | システム制御 | applyChanges・executeCalculation・resetYaml・confirmDaughterNuclides・openGui・getDoseMap |
 | **📜 Schema** | 1個 | ファイル書式の取得 | getSchema |
+| **⏳ Job**（`POKER_MCP_ASYNC=1` のときだけ） | 3個 | 計算の非同期実行 | submitCalculation・getJobStatus・getJobResult |
+
+- `poker_openGui` は、Windows で POKER.exe が見つかり、`POKER_MCP_GUI=0` でないときだけ登録されます。
+- 非同期ジョブを有効にすると、`poker_getDoseMap` にジョブを指定する `job_id` 引数が付きます。
 
 ### 📋 **全36メソッド一覧**
 ```
@@ -537,6 +646,9 @@ CAD系 (2):           poker_generateInput, poker_generatePaths
 System系 (6):        poker_applyChanges, poker_executeCalculation, poker_resetYaml,
                      poker_confirmDaughterNuclides, poker_openGui, poker_getDoseMap
 Schema系 (1):        poker_getSchema
+
+（POKER_MCP_ASYNC=1 のとき追加）
+Job系 (3):           poker_submitCalculation, poker_getJobStatus, poker_getJobResult
 ```
 
 ## 📁 プロジェクト構造
@@ -571,6 +683,8 @@ POKER_MCP_HOME/
 ├── 📁 logs/                         # 📝 ログファイル
 │   ├── error.log
 │   └── combined.log
+├── 📁 jobs/                         # ⏳ 非同期ジョブ（POKER_MCP_ASYNC=1 のときだけ）
+│   └── <ジョブID>/                  # job.json・入力のコピー・.summary・.dose・stdout/stderr
 └── config.json                      # ユーザー設定（任意）
 ```
 
@@ -664,6 +778,22 @@ POKER_MCP_HOME/
 - **メモリ**: 512MB以上推奨（大規模検出器使用時は1GB以上）
 - **POKER 本体**: v2.1.5 以降（`POKER_INSTALL_PATH` で場所を指定）
 - **FreeCAD**: 1.0 以降（CAD連携を使う場合。`FREECAD_PATH`、未設定なら自動探索）
+- **POKER の GUI（POKER.exe）**: `poker_openGui` を使う場合のみ。Windows 専用
+
+## 🧪 開発者向けの確認
+
+リポジトリで次を実行します。`check:manifest` 以外は POKER 本体が必要です（`POKER_INSTALL_PATH` 既定 `C:/Poker`）。
+
+| コマンド | 内容 |
+|---|---|
+| `npm run check:manifest` | ツール定義とマニフェストの整合。既定・非同期有効・非同期有効かつ GUI 無効の 3 通り |
+| `npm run test:jobs` | 非同期ジョブ。同期との全行一致、投入後の編集が混ざらないこと、待ち行列、再起動後の復元 |
+| `npm run test:gui` | `poker_openGui` の登録条件（`POKER_MCP_GUI=0` で外れ、計算は従来どおり動く） |
+| `npm run test:schema` | `poker_getSchema` と `.dose` の読み取り |
+| `npm run test:pending` | 保留中の変更の表示 |
+| `npm run test:cad-validate` など | CAD 連携（FreeCAD が必要） |
+
+`test:jobs` と `test:gui` は、失敗があれば終了コード 1 で終わります。
 
 ## 🎯 実際の使用ワークフロー
 
@@ -688,6 +818,12 @@ POKER_MCP_HOME/
 
 ## 📝 更新履歴
 
+### v1.10.0 (2026-10)
+- ✨ 計算の非同期実行（`poker_submitCalculation` / `poker_getJobStatus` / `poker_getJobResult`、`poker_getDoseMap` の `job_id`）。`POKER_MCP_ASYNC=1` のときだけ有効
+- ✨ `poker_openGui` を GUI が使える環境でだけ登録（`POKER_MCP_GUI=0`、Windows 以外、POKER.exe なしで外す）
+- ✅ `npm run test:jobs`（同期との全行一致、入力のスナップショット、再起動後の復元）と `npm run test:gui` を追加
+- 🔧 `npm run check:manifest` が非同期ジョブ有効時・GUI 無効時のツール定義も照合
+
 ### v1.9.9 (2026-10)
 - 🐛 `tools/gen_input.py` と `tools/scatter.py` を npm パッケージに同梱（`poker_generateInput` が npm 版で動かなかった）
 - 🐛 ツールの失敗が `isError: true` として伝わるよう修正（応答の二重包みを解消、`success: false` に `isError` を付与）
@@ -783,6 +919,6 @@ obtained separately and licensed separately. poker-mcp は `poker_cui` を外部
 
 ---
 
-**🎯 Poker MCP Server v1.9.9**  
+**🎯 Poker MCP Server v1.10.0**  
 **プロトコル**: MCP 1.0.0 完全準拠  
 **作者**: Yoshihiro Hirao | **ライセンス**: MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "poker-mcp",
-  "version": "1.9.9",
+  "version": "1.10.0",
   "description": "YAML-based input file management tool for radiation shielding calculation code POKER with MCP support - Enhanced with collision detection, daughter nuclide auto-completion, and environment variable support",
   "main": "src/mcp_server_stdio_v4.js",
   "type": "module",
@@ -11,7 +11,9 @@
     "start": "node src/mcp_server_stdio_v4.js",
     "dev": "nodemon src/mcp_server_stdio_v4.js",
     "prepare": "echo 'NPX ready: npx poker-mcp'",
-    "check:manifest": "node scripts/check-manifest-sync.mjs",
+    "check:manifest": "node scripts/check-manifest-sync.mjs && node scripts/check-manifest-sync.mjs --async && node scripts/check-manifest-sync.mjs --async --no-gui",
+    "test:jobs": "node tests/async-jobs.test.mjs",
+    "test:gui": "node tests/gui-switch.test.mjs",
     "test:pending": "node tests/pending-view.test.mjs",
     "test:cad": "node tests/cad-e2e.test.mjs",
     "test:cad-full": "node tests/cad-full.test.mjs",

package/src/mcp/handlers/calculationHandlers.js

@@ -7,7 +7,7 @@ import { TASKS_DIR } from '../../utils/paths.js';
 import { parseDoseSummary } from '../../utils/summaryParser.js';
 import { parseDoseMap } from '../../utils/doseMapParser.js';
 
-export function createCalculationHandlers(taskManager) {
+export function createCalculationHandlers(taskManager, { jobManager = null } = {}) {
   const calculationService = new CalculationService();
 
   // server.js はハンドラを handler(args) の形でオブジェクトから切り離して呼ぶため、
@@ -18,10 +18,26 @@ export function createCalculationHandlers(taskManager) {
         if (!args.detector_name) {
           throw new ValidationError('detector_name is required', 'detector_name', args.detector_name);
         }
-        const yamlFile = args.yaml_file || 'poker.yaml';
-        const absolutePathPattern = /^([a-zA-Z]:[\\\/]|\/)/;
-        const resolvedYamlFile = absolutePathPattern.test(yamlFile) ? yamlFile : path.join(TASKS_DIR, yamlFile);
-        const dosePath = resolvedYamlFile + '.dose';
+        let dosePath;
+        if (args.job_id) {
+          // 非同期ジョブの結果を読む（ジョブ専用フォルダの .dose）
+          if (!jobManager) {
+            return { success: false, error: 'job_id は非同期ジョブが有効なとき（POKER_MCP_ASYNC=1）だけ使えます' };
+          }
+          const job = jobManager.get(args.job_id);
+          if (!job) {
+            return { success: false, error: `ジョブが見つかりません: ${args.job_id}`, error_type: 'JOB_NOT_FOUND' };
+          }
+          if (job.status !== 'succeeded') {
+            return { success: false, error: `ジョブ ${args.job_id} は完了していません（status: ${job.status}）`, status: job.status };
+          }
+          dosePath = job.outputs.dose_file;
+        } else {
+          const yamlFile = args.yaml_file || 'poker.yaml';
+          const absolutePathPattern = /^([a-zA-Z]:[\\\/]|\/)/;
+          const resolvedYamlFile = absolutePathPattern.test(yamlFile) ? yamlFile : path.join(TASKS_DIR, yamlFile);
+          dosePath = resolvedYamlFile + '.dose';
+        }
         // .dose は poker_cui 完了直後に書き込まれるが、完了検知からディスク反映までに数秒の
         // ばらつきがある。実運用（executeCalculation とは別コール）では準備済みだが、直後呼び出しに
         // 備え、準備できるまで最大約10秒リトライする（未準備時のみ待機）。

package/src/mcp/handlers/index.js

@@ -5,16 +5,25 @@ import { createTransformHandlers } from './transformHandlers.js';
 import { createBuildupFactorHandlers } from './buildupFactorHandlers.js';
 import { createSourceHandlers } from './sourceHandlers.js';
 import { createDetectorHandlers } from './detectorHandlers.js';
-import { createUnitHandlers } from './unitHandlers.js';
-import { createThinnedIndicesHandlers } from './thinnedIndicesHandlers.js';
+import { createUnitHandlers } from './unitHandlers.js';
+import { createThinnedIndicesHandlers } from './thinnedIndicesHandlers.js';
 import { createCadHandlers } from './cadHandlers.js';
 import { createCalculationHandlers } from './calculationHandlers.js';
 import { resetHandlers } from './resetHandlers.js';
 import { createDaughterNuclideHandler } from './daughterNuclideHandler.js';
-import { createGuiHandlers } from './guiHandlers.js';
+import { createGuiHandlers } from './guiHandlers.js';
 import { createSchemaHandlers } from './schemaHandlers.js';
+import { createJobHandlers } from './jobHandlers.js';
 
-export function createAllHandlers(taskManager) {
+/**
+ * @param {Object} taskManager
+ * @param {Object} [opts]
+ * @param {import('../../services/JobManager.js').JobManager|null} [opts.jobManager]
+ *   非同期ジョブが有効なときだけ渡される。null ならジョブ系のハンドラは登録しない。
+ * @param {boolean} [opts.guiEnabled=true]
+ *   false なら poker_openGui のハンドラを登録しない（ツール名で直接呼ばれても実行しない）。
+ */
+export function createAllHandlers(taskManager, { jobManager = null, guiEnabled = true } = {}) {
   return {
     // 立体操作
     ...createBodyHandlers(taskManager),
@@ -35,12 +44,15 @@ export function createAllHandlers(taskManager) {
     ...createDetectorHandlers(taskManager),
     
     // 単位操作
-    ...createUnitHandlers(taskManager),
-    ...createThinnedIndicesHandlers(taskManager),
+    ...createUnitHandlers(taskManager),
+    ...createThinnedIndicesHandlers(taskManager),
     ...createCadHandlers(taskManager),
     
     // 計算操作
-    ...createCalculationHandlers(taskManager),
+    ...createCalculationHandlers(taskManager, { jobManager }),
+
+    // 非同期ジョブ（POKER_MCP_ASYNC=1 のときだけ）
+    ...(jobManager ? createJobHandlers(taskManager, jobManager) : {}),
 
     // 子孫核種確認操作
     confirmDaughterNuclides: createDaughterNuclideHandler(taskManager),
@@ -48,10 +60,10 @@ export function createAllHandlers(taskManager) {
     // リセット操作
     resetYaml: resetHandlers.resetYaml(taskManager),
 
-    // GUI表示操作
-    ...createGuiHandlers(taskManager),
-
-    // スキーマ取得（poker_cui --schema）
+    // GUI表示操作（Windows で POKER.exe があり、POKER_MCP_GUI=0 でないときだけ）
+    ...(guiEnabled ? createGuiHandlers(taskManager) : {}),
+
+    // スキーマ取得（poker_cui --schema）
     ...createSchemaHandlers(),
     
     // 共通操作

package/src/mcp/handlers/jobHandlers.js

@@ -0,0 +1,183 @@
+// mcp/handlers/jobHandlers.js - 計算の非同期実行のハンドラ
+import fs from 'fs';
+import path from 'path';
+import { ValidationError } from '../../utils/errors.js';
+import { logger } from '../../utils/logger.js';
+import { TASKS_DIR } from '../../utils/paths.js';
+import { parseDoseSummary } from '../../utils/summaryParser.js';
+import { TERMINAL_STATUSES } from '../../services/JobManager.js';
+
+const ABSOLUTE = /^([a-zA-Z]:[\\\/]|\/)/;
+const resolveTaskPath = (p) => (ABSOLUTE.test(p) ? p : path.join(TASKS_DIR, p));
+
+export function createJobHandlers(taskManager, jobManager) {
+  const statusView = (job) => {
+    const now = Date.now();
+    const start = job.started_at ? Date.parse(job.started_at) : null;
+    const end = job.finished_at ? Date.parse(job.finished_at) : null;
+    return {
+      job_id: job.id,
+      status: job.status,
+      submitted_at: job.submitted_at,
+      started_at: job.started_at,
+      finished_at: job.finished_at,
+      queue_position: jobManager.queuePosition(job.id),
+      running_seconds: start ? Math.round(((end || now) - start) / 1000) : null,
+      input_file: job.input.yaml_source,
+      path_input: job.input.path_input_source,
+      ...(job.status === 'failed' ? { error: job.error } : {})
+    };
+  };
+
+  return {
+    async submitCalculation(args) {
+      if (!args.yaml_file) {
+        throw new ValidationError('YAML file is required', 'yaml_file', args.yaml_file);
+      }
+      const yamlFile = resolveTaskPath(args.yaml_file);
+      if (!/\.(yaml|yml)$/i.test(yamlFile)) {
+        throw new ValidationError('YAML file must have .yaml or .yml extension', 'yaml_file', args.yaml_file);
+      }
+      if (!fs.existsSync(yamlFile)) {
+        throw new ValidationError(`YAML file not found: ${yamlFile}`, 'yaml_file', args.yaml_file);
+      }
+      let pathInput = null;
+      if (args.path_input) {
+        pathInput = resolveTaskPath(args.path_input);
+        if (!fs.existsSync(pathInput)) {
+          throw new ValidationError(`path_input not found: ${pathInput}`, 'path_input', args.path_input);
+        }
+      }
+      const outputFiles = args.output_files || {};
+      for (const [key, name] of Object.entries(outputFiles)) {
+        if (name && !/^[a-zA-Z0-9_\-\.]+\.(yaml|yml)$/.test(name)) {
+          throw new ValidationError(`Output file ${key} must be a file name ending with .yaml or .yml`, `output_files.${key}`, name);
+        }
+      }
+
+      // 同期の executeCalculation と同じ事前検証を、投入の時点で行う。
+      // 重大エラー（立体干渉を除く）があれば受け付けない。
+      if (taskManager?.dataManager) {
+        const v = await taskManager.dataManager.performPreCalculationValidation();
+        const critical = (v.criticalErrors || []).filter((e) => e.type !== 'collision_detected');
+        if (critical.length > 0) {
+          return {
+            success: false,
+            error: 'CRITICAL_VALIDATION_ERRORS',
+            error_type: 'PRE_VALIDATION_FAILED',
+            message: '計算実行前に解決が必要な重大エラーがあるため、ジョブを受け付けませんでした',
+            critical_errors: critical
+          };
+        }
+      }
+
+      const job = await jobManager.submit({
+        yamlFile,
+        pathInput,
+        summaryOptions: args.summary_options || {},
+        outputFiles
+      });
+
+      return {
+        success: true,
+        message: '計算を受け付けました。poker_getJobStatus で進み具合を確認し、終わったら poker_getJobResult で結果を取得してください。',
+        job_id: job.id,
+        status: job.status,
+        queue_position: jobManager.queuePosition(job.id),
+        input: {
+          yaml_file: yamlFile,
+          yaml_sha256: job.input.yaml_sha256,
+          path_input: pathInput
+        }
+      };
+    },
+
+    async getJobStatus(args = {}) {
+      if (!args.job_id) {
+        const jobs = jobManager.list(20).map(statusView);
+        return {
+          success: true,
+          running: jobManager.running.size,
+          queued: jobManager.queue.length,
+          concurrency: jobManager.concurrency,
+          jobs
+        };
+      }
+      const job = jobManager.get(args.job_id);
+      if (!job) {
+        return { success: false, error: `ジョブが見つかりません: ${args.job_id}`, error_type: 'JOB_NOT_FOUND' };
+      }
+      return { success: true, ...statusView(job) };
+    },
+
+    async getJobResult(args) {
+      const job = jobManager.get(args.job_id);
+      if (!job) {
+        return { success: false, error: `ジョブが見つかりません: ${args.job_id}`, error_type: 'JOB_NOT_FOUND' };
+      }
+      if (!TERMINAL_STATUSES.has(job.status)) {
+        return {
+          success: true,
+          ready: false,
+          ...statusView(job),
+          message: 'まだ終わっていません。しばらくおいて poker_getJobStatus で確認してください。'
+        };
+      }
+      if (job.status === 'failed') {
+        return {
+          success: false,
+          ready: true,
+          ...statusView(job),
+          error: job.error?.message,
+          error_type: job.error?.code || 'JOB_FAILED',
+          details: job.error
+        };
+      }
+
+      const files = {};
+      for (const [key, p] of Object.entries(job.outputs)) {
+        try {
+          const st = fs.statSync(p);
+          files[key] = { exists: true, size: st.size, path: p };
+        } catch (e) {
+          files[key] = { exists: false, path: p };
+        }
+      }
+      const stdout = jobManager.readOutput(job.id, 'stdout.txt');
+      const stderr = jobManager.readOutput(job.id, 'stderr.txt');
+
+      const response = {
+        success: true,
+        ready: true,
+        ...statusView(job),
+        message: 'Radiation shielding calculation completed successfully',
+        calculation: {
+          input_file: job.input.yaml_source,
+          snapshot_file: job.input.yaml_file,
+          yaml_sha256: job.input.yaml_sha256,
+          execution_time_ms: job.execution_time_ms,
+          options: job.summary_options
+        },
+        outputs: {
+          console: { stdout_length: stdout.length, stderr_length: stderr.length },
+          files
+        },
+        details: { stdout, stderr }
+      };
+
+      try {
+        const parsed = parseDoseSummary(job.outputs.summary_file);
+        if (parsed) {
+          response.result_total = parsed.result_total;
+          response.dose_columns = parsed.columns;
+          if (parsed.notes && parsed.notes.length) response.calculation_notes = parsed.notes;
+          if (parsed.elapsed_time) response.calculation.elapsed_time = parsed.elapsed_time;
+          if (parsed.warnings && parsed.warnings.length) response.calculation_warnings = parsed.warnings;
+        }
+      } catch (e) {
+        logger.warn('summary 構造化パースをスキップ', { job: job.id, error: e.message });
+      }
+      return response;
+    }
+  };
+}

package/src/mcp/server.js

@@ -8,6 +8,9 @@ import { createAllHandlers } from './handlers/index.js';
 import { safeExecute } from './middleware/errorHandler.js';
 import { logger } from '../utils/logger.js';
 import { YAML_FILE, PENDING_FILE } from '../utils/paths.js';
+import { isAsyncEnabled, getAsyncConfig } from '../utils/asyncConfig.js';
+import { JobManager } from '../services/JobManager.js';
+import { getGuiStatus } from '../utils/guiConfig.js';
 import { readFileSync } from 'fs';
 
 // initialize の serverInfo で返す版。クライアント（Claude Desktop 等）が
@@ -39,6 +42,7 @@ export class PokerMcpServer {
     
     this.taskManager = new TaskManager(yamlFile, pendingFile);
     this.handlers = null;
+    this.jobManager = null;
   }
 
   async initialize() {
@@ -46,8 +50,21 @@ export class PokerMcpServer {
       // TaskManager初期化
       await this.taskManager.initialize();
       
+      // 非同期ジョブ（POKER_MCP_ASYNC=1 のときだけ）
+      if (isAsyncEnabled()) {
+        this.jobManager = new JobManager(getAsyncConfig());
+        await this.jobManager.init();
+      }
+
+      // POKER の GUI（poker_openGui）を使えるか
+      const gui = getGuiStatus();
+      logger.info(`poker_openGui: ${gui.enabled ? '有効' : '無効'}（${gui.reason}）`);
+
       // ハンドラー作成
-      this.handlers = createAllHandlers(this.taskManager);
+      this.handlers = createAllHandlers(this.taskManager, {
+        jobManager: this.jobManager,
+        guiEnabled: gui.enabled
+      });
       
       // ツール一覧ハンドラー
       this.server.setRequestHandler(ListToolsRequestSchema, async () => {

package/src/mcp/tools/index.js

@@ -14,8 +14,15 @@ import { resetTools } from './resetTools.js';
 import { daughterNuclideTools } from './daughterNuclideTools.js';
 import { guiTools } from './guiTools.js';
 import { schemaTools } from './schemaTools.js';
+import { jobTools, withJobIdParam } from './jobTools.js';
+import { isAsyncEnabled } from '../../utils/asyncConfig.js';
+import { isGuiEnabled } from '../../utils/guiConfig.js';
 
-export const allTools = [
+// poker_openGui は、Windows で POKER.exe が見つかり、POKER_MCP_GUI=0 でないときだけ載せる
+// （utils/guiConfig.js）。手元の Windows で POKER を入れている普段の環境では従来どおり載る。
+const guiAvailable = isGuiEnabled();
+
+const baseTools = [
   ...bodyTools,
   ...zoneTools,
   ...transformTools,
@@ -29,11 +36,19 @@ export const allTools = [
   ...calculationTools,
   ...resetTools,
   ...daughterNuclideTools,
-  ...guiTools,
+  ...(guiAvailable ? guiTools : []),
   ...schemaTools
 ];
 
+// 非同期ジョブ（POKER_MCP_ASYNC=1）が有効なときだけ、ジョブ系の 3 ツールを加え、
+// poker_getDoseMap に job_id 引数を足す。無効なときは baseTools をそのまま使い、
+// ツール一覧は非同期ジョブを持たない版と変わらない。
+export const allTools = isAsyncEnabled()
+  ? [...baseTools.map((t) => (t.name === 'poker_getDoseMap' ? withJobIdParam(t) : t)), ...jobTools]
+  : baseTools;
+
 export {
+  jobTools,
   bodyTools,
   zoneTools,
   transformTools,

package/src/mcp/tools/jobTools.js

@@ -0,0 +1,98 @@
+// mcp/tools/jobTools.js - 計算の非同期実行（POKER_MCP_ASYNC=1 のときだけ登録される）
+//
+// 長い計算を 1 回のツール呼び出しで待つと、MCP クライアントの待ち時間の上限や、
+// 途中の中継（Cloudflare Tunnel など）の上限で切られる。投入・状態確認・結果取得に
+// 分ければ、1 回の呼び出しは数秒で終わり、何時間かかる計算でも扱える。
+
+const summaryOptionsSchema = {
+  type: 'object',
+  description: 'サマリー出力オプション（poker_executeCalculation と同じ）',
+  properties: {
+    show_parameters: { type: 'boolean', description: '入力パラメータをサマリーに表示（-p）', default: false },
+    show_source_data: { type: 'boolean', description: '各線源による計算データ及び線量を表示（-s）', default: true },
+    show_total_dose: { type: 'boolean', description: '各検出器に対する全線源からの総和線量を表示（-t）', default: true }
+  },
+  additionalProperties: false
+};
+
+export const jobTools = [
+  {
+    name: 'poker_submitCalculation',
+    description:
+      '時間のかかる遮蔽計算を非同期で投入し、すぐにジョブ ID を返します。数十秒で終わる計算は ' +
+      'poker_executeCalculation を使ってください。投入した時点の YAML（と .paths）をジョブ専用の' +
+      'フォルダにコピーして計算するため、投入後に YAML を編集しても実行中の計算には影響しません。' +
+      '保留中の変更は含まれないので、必要なら先に poker_applyChanges で確定してください。' +
+      '進み具合は poker_getJobStatus、結果は poker_getJobResult で取得します。',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        yaml_file: {
+          type: 'string',
+          description: '計算に使う YAML ファイル名（例: poker.yaml）。ファイル名のみなら POKER_MCP_HOME/tasks/ 配下を参照。絶対パスも可。',
+          pattern: '^([a-zA-Z0-9_\\-\\.]+\\.(yaml|yml)|([a-zA-Z]:[\\\\\/]|\\/)[^\\\\]+\\.(yaml|yml))$'
+        },
+        path_input: {
+          type: 'string',
+          description: 'CAD から抽出した経路ファイル（.paths）。poker_executeCalculation の path_input と同じ。'
+        },
+        summary_options: summaryOptionsSchema,
+        output_files: {
+          type: 'object',
+          description: '出力ファイル名（ジョブ専用フォルダに置かれる）。省略時は <YAML名>.summary / <YAML名>.dose。',
+          properties: {
+            summary_file: { type: 'string', pattern: '^[a-zA-Z0-9_\\-\\.]+\\.(yaml|yml)$' },
+            dose_file: { type: 'string', pattern: '^[a-zA-Z0-9_\\-\\.]+\\.(yaml|yml)$' }
+          },
+          additionalProperties: false
+        }
+      },
+      required: ['yaml_file'],
+      additionalProperties: false
+    }
+  },
+  {
+    name: 'poker_getJobStatus',
+    description:
+      '非同期ジョブの状態を返します（queued: 待機中 / running: 実行中 / succeeded: 完了 / failed: 失敗）。' +
+      'job_id を省略すると最近のジョブの一覧を返します。終わっていなければ、数秒〜数十秒おいて再度確認してください。',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        job_id: { type: 'string', description: 'poker_submitCalculation が返したジョブ ID' }
+      },
+      additionalProperties: false
+    }
+  },
+  {
+    name: 'poker_getJobResult',
+    description:
+      '終わったジョブの結果を返します。内容は poker_executeCalculation の応答と同じ形式です' +
+      '（検出器ごとの result_total、dose_columns、calculation_warnings など）。' +
+      'まだ終わっていなければ ready: false を返します。グリッド検出器の線量マップは ' +
+      'poker_getDoseMap に job_id を指定して取得します。',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        job_id: { type: 'string', description: 'poker_submitCalculation が返したジョブ ID' }
+      },
+      required: ['job_id'],
+      additionalProperties: false
+    }
+  }
+];
+
+/** 非同期有効時に poker_getDoseMap へ job_id 引数を足した定義を返す（元の定義は変更しない） */
+export function withJobIdParam(tool) {
+  return {
+    ...tool,
+    description: tool.description + ' 非同期ジョブの結果は job_id で指定します。',
+    inputSchema: {
+      ...tool.inputSchema,
+      properties: {
+        ...tool.inputSchema.properties,
+        job_id: { type: 'string', description: '非同期ジョブ ID。指定するとそのジョブの .dose を読みます（yaml_file は無視）。' }
+      }
+    }
+  };
+}

package/src/services/JobManager.js

@@ -0,0 +1,254 @@
+// services/JobManager.js - 計算の非同期実行（ジョブ）の管理
+//
+// 方針
+//  - 計算そのものは同期の executeCalculation と同じ CalculationService.executeCalculation
+//    を呼ぶ。計算の中身を二通りに持たない。
+//  - 投入した時点の入力（YAML と .paths）をジョブ専用フォルダにコピーし、それで計算する。
+//    投入後に作業中の YAML を編集しても、実行中・待機中のジョブには混ざらない。
+//  - 出力もジョブ専用フォルダに書く。作業フォルダの poker.yaml.summary 等は上書きしない。
+//  - ジョブの状態は job.json に保存する。サーバを再起動しても消えない。
+//    実行中に再起動した場合、その計算プロセスは失われているので failed にする。
+//    待機中だったものは再び並べる（入力は既にコピー済みなので、そのまま実行できる）。
+//  - 終わったジョブは retentionDays を過ぎたら削除する。
+
+import fs from 'fs';
+import fsp from 'fs/promises';
+import path from 'path';
+import crypto from 'crypto';
+import { logger } from '../utils/logger.js';
+import { CalculationService } from './CalculationService.js';
+
+export const TERMINAL_STATUSES = new Set(['succeeded', 'failed']);
+
+export class JobManager {
+  constructor({ jobsDir, concurrency = 1, retentionDays = 7, timeoutMs = 24 * 3600 * 1000, calculationService } = {}) {
+    if (!jobsDir) throw new Error('JobManager: jobsDir is required');
+    this.jobsDir = jobsDir;
+    this.concurrency = concurrency;
+    this.retentionDays = retentionDays;
+    this.timeoutMs = timeoutMs;
+    this.calculationService = calculationService || new CalculationService();
+    this.jobs = new Map();       // id -> job
+    this.queue = [];             // 待機中のジョブ ID（投入順）
+    this.running = new Set();    // 実行中のジョブ ID
+    this.waiters = new Map();    // id -> [resolve]（テスト・内部用の完了待ち）
+  }
+
+  async init() {
+    await fsp.mkdir(this.jobsDir, { recursive: true });
+    const entries = await fsp.readdir(this.jobsDir, { withFileTypes: true });
+    const requeue = [];
+    for (const e of entries) {
+      if (!e.isDirectory()) continue;
+      const file = path.join(this.jobsDir, e.name, 'job.json');
+      let job;
+      try {
+        job = JSON.parse(await fsp.readFile(file, 'utf8'));
+      } catch {
+        continue; // 作成途中で落ちたフォルダなど。触らない
+      }
+      if (job.status === 'running') {
+        job.status = 'failed';
+        job.finished_at = new Date().toISOString();
+        job.error = {
+          message: '計算の実行中にサーバが再起動したため、計算は完了していません。投入し直してください。',
+          code: 'INTERRUPTED_BY_RESTART'
+        };
+        await this._save(job);
+      } else if (job.status === 'queued') {
+        requeue.push(job);
+      }
+      this.jobs.set(job.id, job);
+    }
+    requeue.sort((a, b) => a.submitted_at.localeCompare(b.submitted_at));
+    for (const job of requeue) this.queue.push(job.id);
+    await this.cleanup();
+    logger.info('JobManager 初期化', {
+      jobsDir: this.jobsDir, jobs: this.jobs.size, requeued: requeue.length,
+      concurrency: this.concurrency, retentionDays: this.retentionDays
+    });
+    this._pump();
+  }
+
+  /** 保存期間を過ぎた、終わったジョブを削除する */
+  async cleanup(now = Date.now()) {
+    const limit = this.retentionDays * 24 * 3600 * 1000;
+    for (const job of [...this.jobs.values()]) {
+      if (!TERMINAL_STATUSES.has(job.status) || !job.finished_at) continue;
+      if (now - Date.parse(job.finished_at) <= limit) continue;
+      try {
+        await fsp.rm(this._dir(job.id), { recursive: true, force: true });
+        this.jobs.delete(job.id);
+        logger.info('期限切れのジョブを削除', { id: job.id });
+      } catch (e) {
+        logger.warn('ジョブの削除に失敗', { id: job.id, error: e.message });
+      }
+    }
+  }
+
+  /**
+   * 計算を投入する。入力をジョブ専用フォルダへコピーしてから待ち行列に並べる。
+   * @param {Object} p
+   * @param {string} p.yamlFile    入力 YAML（絶対パス）
+   * @param {string|null} p.pathInput  .paths（絶対パス）または null
+   * @param {Object} p.summaryOptions
+   * @param {Object} p.outputFiles  { summary_file?, dose_file? }（ファイル名のみ）
+   */
+  async submit({ yamlFile, pathInput = null, summaryOptions = {}, outputFiles = {} }) {
+    const id = this._newId();
+    const dir = this._dir(id);
+    await fsp.mkdir(dir, { recursive: true });
+
+    const yamlName = path.basename(yamlFile);
+    const jobYaml = path.join(dir, yamlName);
+    await fsp.copyFile(yamlFile, jobYaml);
+
+    let jobPaths = null;
+    if (pathInput) {
+      jobPaths = path.join(dir, path.basename(pathInput));
+      await fsp.copyFile(pathInput, jobPaths);
+    }
+
+    const job = {
+      id,
+      status: 'queued',
+      submitted_at: new Date().toISOString(),
+      started_at: null,
+      finished_at: null,
+      input: {
+        yaml_source: yamlFile,
+        yaml_file: jobYaml,
+        yaml_sha256: await sha256(jobYaml),
+        path_input_source: pathInput,
+        path_input: jobPaths,
+        path_input_sha256: jobPaths ? await sha256(jobPaths) : null
+      },
+      summary_options: summaryOptions,
+      outputs: {
+        summary_file: path.join(dir, outputFiles.summary_file || `${yamlName}.summary`),
+        dose_file: path.join(dir, outputFiles.dose_file || `${yamlName}.dose`)
+      },
+      timeout_ms: this.timeoutMs,
+      execution_time_ms: null,
+      error: null
+    };
+
+    await this._save(job);
+    this.jobs.set(id, job);
+    this.queue.push(id);
+    logger.info('ジョブを受け付けました', { id, yaml: yamlFile, pathInput });
+    this._pump();
+    return job;
+  }
+
+  get(id) {
+    return this.jobs.get(id) || null;
+  }
+
+  /** 新しい順に返す */
+  list(limit = 20) {
+    return [...this.jobs.values()]
+      .sort((a, b) => b.submitted_at.localeCompare(a.submitted_at))
+      .slice(0, limit);
+  }
+
+  /** 待機中なら 1 始まりの順番、それ以外は null */
+  queuePosition(id) {
+    const i = this.queue.indexOf(id);
+    return i < 0 ? null : i + 1;
+  }
+
+  /** ジョブが終わるまで待つ（テストと内部用） */
+  waitFor(id, timeoutMs = 600000) {
+    const job = this.get(id);
+    if (!job) return Promise.reject(new Error(`job not found: ${id}`));
+    if (TERMINAL_STATUSES.has(job.status)) return Promise.resolve(job);
+    return new Promise((resolve, reject) => {
+      const t = setTimeout(() => reject(new Error(`timeout waiting for job ${id}`)), timeoutMs);
+      const list = this.waiters.get(id) || [];
+      list.push((j) => { clearTimeout(t); resolve(j); });
+      this.waiters.set(id, list);
+    });
+  }
+
+  readOutput(id, name) {
+    const file = path.join(this._dir(id), name);
+    try { return fs.readFileSync(file, 'utf8'); } catch { return ''; }
+  }
+
+  // ---------------------------------------------------------------- 内部
+
+  _pump() {
+    while (this.running.size < this.concurrency && this.queue.length > 0) {
+      const id = this.queue.shift();
+      this._run(id).catch((e) => logger.error('ジョブ実行の内部エラー', { id, error: e.message }));
+    }
+  }
+
+  async _run(id) {
+    const job = this.jobs.get(id);
+    if (!job) return;
+    this.running.add(id);
+    job.status = 'running';
+    job.started_at = new Date().toISOString();
+    await this._save(job);
+    logger.info('ジョブ開始', { id });
+
+    try {
+      const r = await this.calculationService.executeCalculation(
+        job.input.yaml_file,
+        job.summary_options,
+        job.outputs,
+        job.timeout_ms,
+        job.input.path_input
+      );
+      await fsp.writeFile(path.join(this._dir(id), 'stdout.txt'), r.outputs?.stdout || '', 'utf8');
+      await fsp.writeFile(path.join(this._dir(id), 'stderr.txt'), r.outputs?.stderr || '', 'utf8');
+      job.status = 'succeeded';
+      job.execution_time_ms = r.executionTime ?? null;
+    } catch (e) {
+      const ctx = e.context || {};
+      job.status = 'failed';
+      job.error = {
+        message: e.message,
+        code: e.code || null,
+        exit_code: ctx.exitCode ?? null,
+        stderr: ctx.stderr || null,
+        stdout: ctx.stdout || null
+      };
+      if (ctx.stderr) await fsp.writeFile(path.join(this._dir(id), 'stderr.txt'), ctx.stderr, 'utf8').catch(() => {});
+      logger.warn('ジョブ失敗', { id, error: e.message });
+    } finally {
+      job.finished_at = new Date().toISOString();
+      await this._save(job).catch((e) => logger.error('job.json の保存に失敗', { id, error: e.message }));
+      this.running.delete(id);
+      logger.info('ジョブ終了', { id, status: job.status });
+      for (const resolve of this.waiters.get(id) || []) resolve(job);
+      this.waiters.delete(id);
+      this._pump();
+      this.cleanup().catch(() => {});
+    }
+  }
+
+  _dir(id) {
+    return path.join(this.jobsDir, id);
+  }
+
+  _newId() {
+    // 例: 20261013-053012-a1b2c3（UTC）。並べると投入順になる
+    const s = new Date().toISOString().replace(/[-:]/g, '').replace('T', '-').slice(0, 15);
+    return `${s}-${crypto.randomBytes(3).toString('hex')}`;
+  }
+
+  async _save(job) {
+    const file = path.join(this._dir(job.id), 'job.json');
+    const tmp = `${file}.tmp`;
+    await fsp.writeFile(tmp, JSON.stringify(job, null, 2), 'utf8');
+    await fsp.rename(tmp, file);
+  }
+}
+
+async function sha256(file) {
+  const buf = await fsp.readFile(file);
+  return crypto.createHash('sha256').update(buf).digest('hex');
+}

package/src/utils/asyncConfig.js

@@ -0,0 +1,34 @@
+// utils/asyncConfig.js - 非同期ジョブ（submitCalculation など）の設定
+//
+// 非同期ジョブは既定で無効。環境変数 POKER_MCP_ASYNC=1 のときだけ有効になり、
+// ツール一覧に poker_submitCalculation / poker_getJobStatus / poker_getJobResult が
+// 加わる。無効のときのツール一覧と動作は、非同期ジョブを持たない版と同じ。
+//
+//   POKER_MCP_ASYNC               1 / true / yes / on で有効（既定: 無効）
+//   POKER_MCP_ASYNC_CONCURRENCY   同時に実行する計算の数（既定: 1）
+//   POKER_MCP_JOB_RETENTION_DAYS  終わったジョブを残す日数（既定: 7）
+//   POKER_MCP_JOB_TIMEOUT_MIN     1 件の計算の打ち切り時間 [分]（既定: 1440 = 24 時間）
+//
+// ジョブは POKER_MCP_HOME/jobs/<ジョブID>/ に置く。
+
+import path from 'path';
+import { BASE_DIR } from './paths.js';
+
+export function isAsyncEnabled() {
+  const v = String(process.env.POKER_MCP_ASYNC || '').trim().toLowerCase();
+  return ['1', 'true', 'yes', 'on'].includes(v);
+}
+
+function positive(value, fallback) {
+  const n = Number(value);
+  return Number.isFinite(n) && n > 0 ? n : fallback;
+}
+
+export function getAsyncConfig() {
+  return {
+    jobsDir: path.join(BASE_DIR, 'jobs'),
+    concurrency: Math.max(1, Math.floor(positive(process.env.POKER_MCP_ASYNC_CONCURRENCY, 1))),
+    retentionDays: positive(process.env.POKER_MCP_JOB_RETENTION_DAYS, 7),
+    timeoutMs: positive(process.env.POKER_MCP_JOB_TIMEOUT_MIN, 1440) * 60 * 1000
+  };
+}

package/src/utils/guiConfig.js

@@ -0,0 +1,40 @@
+// utils/guiConfig.js - POKER の GUI（poker_openGui）を登録するかどうか
+//
+// poker_openGui は POKER.exe（GUI）を、MCP サーバが動いている機械の画面に開く。
+// 次のどれかに当たるときは、ツール一覧から外し、処理も登録しない。
+//
+//   1. POKER_MCP_GUI が 0 / false / no / off
+//        リモート公開したサーバで使う。サーバに POKER が入っていても、GUI は
+//        利用者の手元ではなくサーバの画面に開き、利用者からは見えないため。
+//   2. Windows 以外で動いている（POKER.exe は Windows 専用）
+//   3. POKER_INSTALL_PATH（既定 C:/Poker）に POKER.exe が無い
+//
+// 判定はサーバの起動時に 1 回だけ行う。後から POKER を入れた場合はサーバを再起動する。
+// GUI を外しても、計算（POKER_CUI.exe）を使うツールには影響しない。
+
+import fs from 'fs';
+import path from 'path';
+
+export function resolvePokerExePath() {
+  const installPath = process.env.POKER_INSTALL_PATH || 'C:/Poker';
+  return path.win32.join(installPath.replace(/\//g, '\\'), 'POKER.exe');
+}
+
+export function getGuiStatus() {
+  const v = String(process.env.POKER_MCP_GUI ?? '').trim().toLowerCase();
+  if (['0', 'false', 'no', 'off'].includes(v)) {
+    return { enabled: false, reason: 'POKER_MCP_GUI=0 により無効' };
+  }
+  if (process.platform !== 'win32') {
+    return { enabled: false, reason: `Windows 以外のため無効（${process.platform}）` };
+  }
+  const exe = resolvePokerExePath();
+  if (!fs.existsSync(exe)) {
+    return { enabled: false, reason: `POKER.exe が見つからないため無効: ${exe}` };
+  }
+  return { enabled: true, reason: `POKER.exe: ${exe}` };
+}
+
+export function isGuiEnabled() {
+  return getGuiStatus().enabled;
+}