poker-mcp 1.8.3 → 1.9.9

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Yoshihiro Hirao
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -4,14 +4,82 @@ YAML-based input file management tool for radiation-shielding calculation code P
 
 ## 📋 クイック情報
 
-- **バージョン**: 1.6.0
+- **バージョン**: 1.9.9
+- **ツール数**: 36メソッド
 - **プロトコル**: 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.8.0〜1.8.1の新機能
+## 🐛 バージョン1.9.9の修正
+
+npm で入れた環境（`npx poker-mcp`）でだけ現れる不具合と、失敗の伝え方の不具合を
+直しました。まっさらな Windows に npm パッケージから入れた環境で、CAD 連携を含む
+計算結果がリポジトリ上の実行と全行一致することを確認しています。
+
+### `poker_generateInput` が npm 版で動かなかった
+
+`tools/gen_input.py` と、それが読み込む `tools/scatter.py` が `package.json` の
+`files` から漏れていました。リポジトリから動かすと問題なく、npm から入れた環境で
+だけ `No module named 'gen_input'` で失敗していました。
+
+### 失敗が成功として返っていた
+
+CAD 系などのハンドラが返す `{ content, isError }` を、共通の処理がもう一度包んで
+いたため、`isError: true` が本文の中に埋もれ、MCP の上では成功として伝わって
+いました。AI クライアントは失敗に気づかないまま次の手順へ進みます。
+
+すでに MCP の応答形式になっている戻り値はそのまま返し、`{ success: false, ... }`
+を返すハンドラには `isError: true` を付けるようにしました。立体・ゾーン・線源など
+の検証エラーも、MCP の上で失敗として伝わります。
+
+### 計算エラーの処理そのものが落ちていた
+
+`poker_executeCalculation` が計算エラーを返す途中で
+`Cannot read properties of undefined (reading '_isRecoverableError')` になり、
+本来のエラー内容が隠れていました。ハンドラがオブジェクトから切り離して呼ばれる
+ため `this` が未定義になっていたのが原因です。
+
+## 🆕 バージョン1.9.8の新機能
+
+### 📜 `poker_getSchema` — ファイル書式を JSON Schema で取得
+
+POKER が扱う4種類のファイルの書式を、機械可読な形で取得できます。
+
+```javascript
+poker_getSchema()                   // 入力 YAML
+poker_getSchema({ kind: "paths" })  // CAD から抽出した経路ファイル
+poker_getSchema({ kind: "summary" })
+poker_getSchema({ kind: "dose" })
+```
+
+スキーマは静的なファイルではなく、`poker_cui --schema` をその場で呼んで
+生成します。そのため実行環境の POKER の版と材料ライブラリに必ず一致し、
+`lib_material.dat` に材料を追加していれば、その材料も材料名の一覧
+（`$defs` の `x-poker-names`）に現れます。
+
+規定するのは書式・型・値域までです。参照の解決（`zone.body_name` が
+`body` に在るか）や名前の存在確認は従来どおり `poker_cui --validate`
+（`poker_executeCalculation` が内部で実施）の担当で、両者で役割が分かれます。
+
+`.dose` のスキーマには、YAML の頭部に続く数値表の読み方
+（ブロックの区切り・列の索引 `[dose, ray, energy]`・行の索引
+`i + j*number_i + k*number_i*number_j`）が `x-poker-data-layout` として
+書かれています。
+
+### 🐛 `poker_getDoseMap` が線量種別の増加に追随
+
+`.dose` の列構成を、線量種別3種・線種4種と決め打ちしていました。線量種別は
+ライブラリ設定で増えるため（`E(PA)` や空気カーマを足した場合）、その環境では
+誤った列を読むか、集計ブロックを見つけられず失敗していました。
+
+冒頭の `information` から `dose_type` / `ray_type` / 線源ごとの `energy_bin` を
+数えて列構成を決めるようにしました。1D/2D/3D 検出器の全評価点について、
+`.summary` の `statistics_total`（min/max）と一致することを
+`npm run test:schema` で検証しています。
+
+## 🆕 バージョン1.8.0〜1.8.3の新機能
 
 ### 📐 CAD連携が MCP だけで完結
 従来、CAD からの経路抽出は MCP を経由せず、FreeCAD を手で起動する必要が
@@ -19,6 +87,7 @@ YAML-based input file management tool for radiation-shielding calculation code P
 スクリプトを渡す。3 手順すべてが手作業でした。
 
 ```javascript
+poker_generateInput({ fcstd: "C:/path/to/model.FCStd" })   // YAML を生成
 poker_generatePaths({ fcstd: "C:/path/to/model.FCStd" })
 poker_executeCalculation({ yaml_file: "poker.yaml", path_input: "poker.paths" })
 ```
@@ -43,6 +112,15 @@ FreeCAD の場所を、環境変数 → PATH → 既定のインストール先
 解決されていました。MCP サーバの起動場所によっては別の場所を指します。
 
 
+### 📦 CAD連携ツールを npm パッケージに同梱（v1.8.2）
+`poker_generatePaths` が使う Python スクリプトが `files` に含まれておらず、
+GitHub から clone した環境でしか動きませんでした。`npm install` / `npx` でも
+使えるようにしています。
+
+### 🐛 サマリーの衝突を修正（v1.8.3）
+`generatePaths` が `-p` 付きで作ったサマリーを `executeCalculation` が上書きし、
+次に `generatePaths` を呼ぶと失敗していました。専用ファイルに分離しています。
+
 ## 🆕 バージョン1.7.0〜1.7.2の新機能
 
 ### 📉 サマリー出力量の制御（ThinnedIndices 操作系 3メソッド）
@@ -50,6 +128,9 @@ FreeCAD の場所を、環境変数 → PATH → 既定のインストール先
 線源分割点と検出器評価点が必要ですが、既定では間引かれるため手で書き足す
 必要がありました。
 
+**`poker_generatePaths` が自動で合わせる**ので、通常は意識する必要はありません。
+手で設定したい場合はこうします。
+
 ```javascript
 poker_updateThinnedIndices({ fit_for_paths: true })
 // → 入力の分割定義と検出器グリッドから必要数を計算して設定
@@ -104,16 +185,18 @@ poker_getThinnedIndices()
 
 ### 📡 CAD連携レイトレース
 FreeCAD のソリッドモデルを、STEP のような中間フォーマットを介さず、CSG で
-表現し直す作業も無しに遮蔽体系として扱えます。**MCP の 2 呼び出しで完結**します。
+表現し直す作業も無しに遮蔽体系として扱えます。**MCP の 3 呼び出しで完結**します。
 
 ```javascript
+poker_generateInput({ fcstd: "C:/path/to/model.FCStd" })
 poker_generatePaths({ fcstd: "C:/path/to/model.FCStd" })
 poker_executeCalculation({ yaml_file: "poker.yaml", path_input: "poker.paths" })
 ```
 
+CAD が正本です。**YAML を手で書く必要はありません。** ソリッドに材質・線源・
+検出器をカスタムプロパティで設定しておけば、そこから入力が生成されます。
 線源点→検出器の直線を FreeCAD 側で追跡し、通過した材質と厚さを `.paths` に
-記録して POKER に渡します。分割点の取得、グリッド検出器の展開、ビルドアップ
-等価材料の解決はすべて自動です。
+記録して POKER に渡します。
 
 CSG 経由と一致することを平板・円筒・球の 5 体系で確認済みです。フィレットや
 自由曲面のように CSG で表現できない形状も扱えます。**複数線源・グリッド検出器・
@@ -156,6 +239,7 @@ numpy はレイトレーサが使いますが、FreeCAD に同梱されている
 他の CAD で作ったモデルを STEP で読み込んだ場合、材質情報は失われるので
 FreeCAD 上で設定してください。一度設定すれば `.FCStd` に保存されます。
 
+まずは [CAD_QUICKSTART.md](./docs/manuals/CAD_QUICKSTART.md)（最短手順と実例）を、
 詳細は [CAD_RAYTRACE.md](./docs/manuals/CAD_RAYTRACE.md)、フォーマットは
 [PATHS_FORMAT.md](./docs/manuals/PATHS_FORMAT.md)。
 
@@ -401,14 +485,14 @@ Claude Desktopで以下のようにテストできます：
 ## 🏆 主要機能
 
 ### ✅ **MCP完全対応**
-- **34メソッド完全実装**: 全ての放射線遮蔽計算入力管理機能
+- **36メソッド完全実装**: 全ての放射線遮蔽計算入力管理機能
 - **JSON-RPC 2.0準拠**: 標準プロトコル完全対応
 - **STDIO通信**: MCPクライアントとの標準通信方式
 - **自動バックアップ・ロールバック**: 企業品質のデータ保護
 
 ### ✅ **放射線遮蔽計算専用設計**
 - **10種類の立体形状**: SPH, RCC, RPP, BOX, CMB, TOR, ELL, REC, TRC, WED
-- **14種類の材料**: コンクリート、鉛、鉄、VOID等標準遮蔽材料
+- **23種類の材料**: 鉄・鉛・コンクリート（普通/重量3種）・SUS・ポリエチレン等（`lib_material.dat` から読み込み）
 - **複数線源対応**: 点・体積線源の完全管理
 - **検出器配置**: 0D/1D/2D/3D検出器の柔軟な配置
 
@@ -420,7 +504,7 @@ Claude Desktopで以下のようにテストできます：
 
 ## 🎯 API構成
 
-### 🔧 **34メソッド完全実装**
+### 🔧 **36メソッド完全実装**
 
 | **カテゴリ** | **メソッド数** | **機能** | **主要操作** |
 |-------------|---------------|----------|-------------|
@@ -431,9 +515,12 @@ Claude Desktopで以下のようにテストできます：
 | **📡 Source** | 3個 | 線源管理 | propose・update・delete |
 | **🎯 Detector** | 3個 | 検出器管理 | propose・update・delete |
 | **📏 Unit** | 5個 | 単位設定管理 | propose・get・update・validateIntegrity・analyzeConversion |
-| **⚙️ System** | 6個 | システム制御 | applyChanges・executeCalculation・resetYaml・confirmDaughterNuclides・openGui・各種検証 |
+| **📉 ThinnedIndices** | 3個 | サマリー出力量の制御 | propose・get・update |
+| **📐 CAD** | 2個 | CAD から入力と経路を生成 | generateInput・generatePaths |
+| **⚙️ System** | 6個 | システム制御 | applyChanges・executeCalculation・resetYaml・confirmDaughterNuclides・openGui・getDoseMap |
+| **📜 Schema** | 1個 | ファイル書式の取得 | getSchema |
 
-### 📋 **全34メソッド一覧**
+### 📋 **全36メソッド一覧**
 ```
 Body系 (3):          poker_proposeBody, poker_updateBody, poker_deleteBody
 Zone系 (3):          poker_proposeZone, poker_updateZone, poker_deleteZone  
@@ -444,8 +531,12 @@ Source系 (3):        poker_proposeSource, poker_updateSource, poker_deleteSourc
 Detector系 (3):      poker_proposeDetector, poker_updateDetector, poker_deleteDetector
 Unit系 (5):          poker_proposeUnit, poker_getUnit, poker_updateUnit,
                      poker_validateUnitIntegrity, poker_analyzeUnitConversion
+ThinnedIndices系 (3): poker_proposeThinnedIndices, poker_getThinnedIndices,
+                     poker_updateThinnedIndices
+CAD系 (2):           poker_generateInput, poker_generatePaths
 System系 (6):        poker_applyChanges, poker_executeCalculation, poker_resetYaml,
-                     poker_confirmDaughterNuclides, poker_openGui, 内部検証メソッド群
+                     poker_confirmDaughterNuclides, poker_openGui, poker_getDoseMap
+Schema系 (1):        poker_getSchema
 ```
 
 ## 📁 プロジェクト構造
@@ -462,9 +553,10 @@ poker_mcp/
 │   │   ├── logger.js                # ログ出力（絶対パス）
 │   │   └── ...
 │   └── 📁 config/                   # 設定管理
+├── 📁 tools/                        # 🔧 CAD連携（レイトレーサ・経路生成）
 ├── 📁 docs/                         # 📚 完全ドキュメント
 ├── .mcp.json                        # MCPクライアント接続設定
-├── package.json                     # パッケージ定義（v1.2.6）
+├── package.json                     # パッケージ定義
 └── README.md                        # このファイル
 
 # 実行時に自動作成されるディレクトリ（POKER_MCP_HOME配下）
@@ -542,7 +634,7 @@ POKER_MCP_HOME/
 
 ### **✅ 放射線遮蔽計算特化**
 - **物理的妥当性**: 全パラメータの物理検証
-- **材料データベース**: 標準遮蔽材料14種完備
+- **材料データベース**: 標準遮蔽材料23種（lib_material.dat 準拠）
 - **単位系管理**: 4キー完全性保証（長さ・角度・密度・放射能）
 - **計算品質保証**: 自動整合性チェック
 
@@ -562,6 +654,7 @@ POKER_MCP_HOME/
 
 - **POKER**: 放射線遮蔽計算メインコード
 - **poker_cui**: コマンドライン実行インターフェース
+- **FreeCAD**: CAD連携レイトレース（`poker_generatePaths` を使う場合のみ）
 
 ## 🔗 システム要件
 
@@ -569,6 +662,8 @@ POKER_MCP_HOME/
 - **OS**: Windows, macOS, Linux
 - **MCP Client**: Claude Desktop (推奨)、その他MCPクライアント
 - **メモリ**: 512MB以上推奨（大規模検出器使用時は1GB以上）
+- **POKER 本体**: v2.1.5 以降（`POKER_INSTALL_PATH` で場所を指定）
+- **FreeCAD**: 1.0 以降（CAD連携を使う場合。`FREECAD_PATH`、未設定なら自動探索）
 
 ## 🎯 実際の使用ワークフロー
 
@@ -593,6 +688,46 @@ POKER_MCP_HOME/
 
 ## 📝 更新履歴
 
+### v1.9.9 (2026-10)
+- 🐛 `tools/gen_input.py` と `tools/scatter.py` を npm パッケージに同梱（`poker_generateInput` が npm 版で動かなかった）
+- 🐛 ツールの失敗が `isError: true` として伝わるよう修正（応答の二重包みを解消、`success: false` に `isError` を付与）
+- 🐛 `poker_executeCalculation` の計算エラー処理が `this` 未定義で落ちていた問題を修正
+
+### v1.9.8 (2026-10)
+- ✨ `poker_getSchema`（入力YAML・`.paths`・`.summary`・`.dose` の書式を JSON Schema で取得）
+- 🐛 `poker_getDoseMap` が `.dose` の列構成を `information` から読むようになり、線量種別の増加に追随
+- ✅ `npm run test:schema` を追加
+
+### v1.9.0〜v1.9.7 (2026-09)
+- ✨ `poker_generateInput`（CAD から入力 YAML を生成）
+- ✨ `generatePaths` が `thinnedindices` を `.paths` 生成に必要な値へ自動調整
+- ✨ `.paths` の座標・個数照合を強化
+
+### v1.8.0〜v1.8.3 (2026-09)
+- ✨ CAD連携が MCP だけで完結（`poker_generatePaths` と `path_input`）
+- ✨ `FREECAD_PATH` 環境変数（未設定なら PATH と既定の場所を自動探索）
+- 🐛 相対パスの解決をプロセスのカレントから `TASKS_DIR` 基準に修正
+- 🐛 `generatePaths` と `executeCalculation` のサマリー衝突を修正
+
+### v1.7.0〜v1.7.2 (2026-09)
+- ✨ ThinnedIndices 操作系 3メソッド（サマリー出力量の制御）
+- ✨ `get` 系が保留中の変更を `pending` として併記
+- ✨ `.paths` の座標照合（検出器を動かして再生成し忘れた場合を検出）
+
+### v1.6.0 (2026-09)
+- ✨ CAD連携レイトレースのツール群と `.paths` フォーマット
+- ✨ 材料システムを `lib_material.dat` 準拠に
+
+### v1.5.0 (2026-08)
+- ✨ `poker_openGui` で POKER を閉じずに表示を切り替え（POKER 2.1.1 以降）
+- 🐛 起動失敗時の偽の成功報告を修正
+
+### v1.4.0 (2026-07)
+- ✨ 子孫核種の自動管理（ICRP-07 準拠）
+
+### v1.3.0 (2026-06)
+- ✨ `poker_getDoseMap`（グリッド検出器の線量マップ取得）
+
 ### v1.2.8 (2026-05-16)
 - ✨ `poker_openGui` メソッドを新設（POKER.exe でGUI確認）
 - ✨ 起動前に `applyChanges` を自動実行
@@ -628,6 +763,16 @@ POKER_MCP_HOME/
 - 初期リリース
 - YAML管理基本機能
 
+## 📜 ライセンス
+
+**MIT License** — 著作権 (c) 2025-2026 Yoshihiro Hirao。全文は
+[LICENSE](LICENSE) を参照してください。
+
+このライセンスが及ぶのは本リポジトリの内容（poker-mcp）だけです。POKER itself is
+obtained separately and licensed separately. poker-mcp は `poker_cui` を外部
+プロセスとして起動するだけなので、POKER 本体の許諾には影響しません。FreeCAD も
+別途入手が必要で、それぞれのライセンスに従います。
+
 ## 📞 サポート・詳細情報
 
 - **📖 詳細README**: [docs/README.md](docs/README.md)
@@ -638,6 +783,6 @@ POKER_MCP_HOME/
 
 ---
 
-**🎯 Poker MCP Server v1.4.0**  
+**🎯 Poker MCP Server v1.9.9**  
 **プロトコル**: MCP 1.0.0 完全準拠  
-**作者**: Yoshihiro Hirao | **ライセンス**: ISC
+**作者**: Yoshihiro Hirao | **ライセンス**: MIT

package/package.json

@@ -1,62 +1,70 @@
-{
-  "name": "poker-mcp",
-  "version": "1.8.3",
-  "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",
-  "bin": {
-    "poker-mcp": "src/mcp_server_stdio_v4.js"
-  },
-  "scripts": {
-    "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",
-    "test:pending": "node tests/pending-view.test.mjs",
-    "test:cad": "node tests/cad-e2e.test.mjs"
-  },
-  "keywords": [
-    "mcp",
-    "model-context-protocol",
-    "yaml",
-    "radiation",
-    "shielding",
-    "nuclear",
-    "radioisotope",
-    "medical",
-    "accelerator",
-    "POKER",
-    "physics",
-    "validation",
-    "npx",
-    "point-kernel",
-    "collision-detection",
-    "daughter-nuclide"
-  ],
-  "author": "Yoshihiro Hirao <tora@pointkernel.com>",
-  "license": "ISC",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/Hirao-Y/poker_mcp.git"
-  },
-  "homepage": "https://github.com/Hirao-Y/poker_mcp#readme",
-  "engines": {
-    "node": ">=18.0.0"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.29.0",
-    "js-yaml": "^4.1.0",
-    "winston": "^3.17.0",
-    "zod": "^3.24.2"
-  },
-  "files": [
-    "src/",
-    "tools/gen_paths.py",
-    "tools/ray_trace_tri.py",
-    "tools/poker_lib.py",
-    "tools/audit_mfp.py",
-    "tools/compare_poker_trace.py",
-    "README.md",
-    ".mcp.json"
-  ]
-}
+{
+  "name": "poker-mcp",
+  "version": "1.9.9",
+  "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",
+  "bin": {
+    "poker-mcp": "src/mcp_server_stdio_v4.js"
+  },
+  "scripts": {
+    "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",
+    "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",
+    "test:cad-validate": "node tests/cad-validate.test.mjs",
+    "test:cad-pipe": "node tests/cad-pipe.test.mjs",
+    "test:cad-thinned": "node tests/cad-thinned-fit.test.mjs",
+    "test:schema": "node tests/schema-dose.test.mjs"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "yaml",
+    "radiation",
+    "shielding",
+    "nuclear",
+    "radioisotope",
+    "medical",
+    "accelerator",
+    "POKER",
+    "physics",
+    "validation",
+    "npx",
+    "point-kernel",
+    "collision-detection",
+    "daughter-nuclide"
+  ],
+  "author": "Yoshihiro Hirao <tora@pointkernel.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Hirao-Y/poker_mcp.git"
+  },
+  "homepage": "https://github.com/Hirao-Y/poker_mcp#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "js-yaml": "^4.1.0",
+    "winston": "^3.17.0",
+    "zod": "^3.24.2"
+  },
+  "files": [
+    "src/",
+    "tools/gen_input.py",
+    "tools/gen_paths.py",
+    "tools/scatter.py",
+    "tools/ray_trace_tri.py",
+    "tools/poker_lib.py",
+    "tools/audit_mfp.py",
+    "tools/compare_poker_trace.py",
+    "README.md",
+    "LICENSE",
+    ".mcp.json"
+  ]
+}