poi-plugin-nanodesu-mcp

一個 poi 插件，把 poi 當下的 KanColle 遊戲狀態 以 MCP 工具的形式開放給 MCP 客戶端（Claude Code，或任何說 MCP 的 agent）。 不必去撈 poi 的快取檔，也沒有過期問題：每一次呼叫讀的都是遊戲正在跑的那個 redux store。

功能特色

裝上之後，agent 可以回答這類問題：

• 艦隊現況——誰大破、誰快升級、哪些艦娘鎖了、資源和入渠時間還剩多少。

• 任務——目前接了什麼、哪些已達成待領獎；再配上完整的任務線圖， 可以往前推「這條任務線卡在哪一關」。

• 戰鬥歷史——什麼時候打了哪張圖、走哪條航路、拿什麼評價； 再往下拉出單場的完整編成、裝備、改修值。

• 圖鑑查詢——把遊戲回傳的 id 翻成艦名、裝備名、海域名。

• 存編成——把當下的艦隊（或一段貼進來的編成碼）存成一筆 編成日記記錄。

界線畫在遊戲那一側：對遊戲只讀不寫——不送任何遊戲請求、不碰 webview、 不代替你操作遊戲。寫進 poi 自己（或其他插件）的 state 則在界內， poi_hensei_save 正是如此：它把一筆編成記進編成日記，遊戲那頭什麼也沒發生。

它仍然是這裡唯一會寫的工具，而且只在真的寫得進去時才註冊——沒裝編成日記、 或它沒載入，這個工具根本不會出現，不需要任何設定。

Related MCP server: homelab-mcp

核心概念

這個插件的目的是把 poi 以及其他插件的 state 開放給 agent 查詢， 並且整合一部分並非 state、但同樣實用的資料。

所以可讀的東西分成三類：

第三類是刻意納入的：有些資料對 agent 極有價值，卻從來不進 redux——任務線圖 是插件 require() 進模組區域變數的靜態資產，戰鬥記錄則是一場一個 gz 檔寫在 磁碟上。單靠讀 store 永遠拿不到它們，所以這個插件把它們一併整合進來， 用同一套查詢介面提供。

整合僅止於「讓它可查」。這個插件不做推論、不產生衍生欄位、不做名稱解析—— 回傳的都是原始 kcsapi 資料；把任務線圖和你的進度接起來、或從編成回推任務 是否達成，都是 agent 的工作。

提供的工具

poi_get

以點分路徑讀取 store，例如 info.ships、info.fleets、info.resources。 可讀的根是 info、const、fcd、wctf、battle、sortie、timers、 misc，加上下面兩個：

• ext.<套件名>._——允許清單內的其他插件 state，一次讀一個（ext 整包 不可讀）。那層 _ 是 poi 自己包在每個插件 reducer 外面的。

• questline.quests——poi-plugin-quest-line 隨套件附帶的靜態任務線圖， 每個任務 id 對應到它的目錄條目，含 prereqIds／unlocks（圖的邊）與 名稱、分類、獎勵欄位。它是「遊戲裡存在哪些任務」的凍結目錄， 完全不反映你的進度。

集合（陣列，或以 id 為鍵的物件）支援 where 篩選、select 投影與 limit； 回應大小有上限，超過就截斷。完整的運算式語法寫在工具本身的說明裡， agent 呼叫時讀得到。

poi_battle

依戰鬥 id 讀取 poi-plugin-battle-detail 存下的完整記錄：fleet.main／ fleet.escort 每艘艦的 api_ship_id、api_lv、改修值與裝備，加上原始戰鬥 封包與結果。id 來自 ext.poi-plugin-battle-detail._.indexes，單次最多 50 個。

典型用法是先用索引框出時段，再把 id 丟進來查編成：

poi_get    path="ext.poi-plugin-battle-detail._.indexes" where="map = \"2-4\""
poi_battle ids=[...] select=["fleet.main[].api_ship_id"]

poi_lookup

把主資料的 id 解析成記錄——api_ship_id 變艦名、api_slotitem_id 變裝備名等。 涵蓋艦娘、裝備、艦種、海域、遠征、改修等資料表；單次最多 200 個 id （這些表很大，光 const.$ships 就約 1.6 MB，所以永遠不整包倒出來）。

poi_describe

在查詢之前先了解某個路徑上有什麼：種類、元素數量、鍵、以及取樣元素的欄位名。 不帶 path 呼叫則列出所有可讀的根。

少數幾條路徑的資料是位置式陣列，欄位名不在資料裡——info.resources 是八個 裸數字，航海日誌 EX 的每一列也是。這些路徑上 poi_describe 會回傳已查證的欄位 名（而不是 ["0","1",...]），poi_get 則把同一份對照放進 hint，因為最需要它 的正是沒先呼叫 poi_describe 的人。另有兩條路徑帶警語：info.repairs 的 api_ship_id 是 roster id（不是 master id），而 info.resources 的位置與 poi_lookup(kind="useitems") 的 id 空間無關。

欄位名是對別人的資料配置所做的宣告，所以每一張表都在原始碼裡註明出處 （src/fields.ts），而且只在實際形狀與表上的欄位數吻合時才輸出；對不上就改回 報「配置已變動」。寧可說「我不知道」，也不要把名字貼錯欄位——後者看起來完全 正常。

時區：store 裡混著三種時鐘，而且字串都不帶標記——遊戲自己的 api_*_time_str 是 JST（UTC+9），某些插件（如 battle-detail 的 time）用主機時區格式化， timeRange 的 from／to 則是 UTC。所以要比較、要排序，一律用 epoch 數值 （api_*_time、time_、min／max），不要用字串。遊戲的每日邊界（例如任務 05:00 重置）同樣在 JST 上。相關路徑讀取時會附警語。

對於每列帶時間戳的日誌（航海日誌 EX 各表、ext.poi-plugin-battle-detail._.indexes）， poi_describe 還會回傳 timeRange——該分支實際涵蓋的最舊與最新時刻，同時給 原始毫秒值（可直接拿去 where 比較）與 ISO 字串。這是資料視界：where 篩不到 東西，在範圍內代表「沒發生」，在範圍外只代表「日誌沒回溯到那麼早」，兩者必須分得 開。範圍是掃過每一列算出來的，不靠列的排序——實測航海日誌 EX 是新到舊，但那 是對某張表的觀察，不是插件的保證。

poi_hensei_save

把一筆編成存進 poi-plugin-hensei-nikki（編成日記）。這是這裡唯一會寫的 工具，寫的是 poi 的 state、不是遊戲——它不會替你動遊戲裡的任何一艘船。 傳 decks（poi 裡的艦隊編號，例如 [1]，聯合艦隊就 [1, 2]）存下當前 的艦隊，或傳 code 匯入一段編成——deckbuilder v4 物件、poi-h-v1 記錄、或 編成日記自己的舊編碼都吃。title 同時是記錄的鍵，note 可以附一段文字。

寫入走的是編成日記自己的 @@HENSEI_SAVE_DATA action——poi 的 redux store 是 所有插件共用的，這跟按下它自己的「新增」按鈕是同一條路。存檔也是它自己做的： 它的 observer 一看到 state 變了就寫 <APPDATA>/hensei-nikki/<memberId>.json，所以 dispatch 出去就等於落地了， 這個插件不碰那個檔案。

刻意只做「新增」，沒有刪除和改名。標題撞名預設直接拒絕，因為對方的 reducer 是 整筆蓋掉 data[title]、舊的編成救不回來；真的要覆蓋得明講 overwrite: true。 現有的記錄可以從 ext.poi-plugin-hensei-nikki._.henseiData.data 讀，存之前 確認標題、存完確認有沒有寫進去，都靠它。

安裝

把這個 repo 用 symlink 掛進 poi 的插件目錄（沒有發佈到 npm）：

ln -s /path/to/poi-plugin-nanodesu-mcp \
  "$HOME/Library/Application Support/poi/plugins/node_modules/poi-plugin-nanodesu-mcp"

然後在 poi 裡重載插件（或重啟 poi）。本專案以原始 TypeScript 發佈、沒有建置 步驟——poi 會在 require() 時即時轉譯 .ts。

伺服器只在 poi 的主視窗啟動。狀態（listening／stopped／error、端點網址、 請求計數）會顯示在 poi 的插件面板。開始監聽後（預設 http://127.0.0.1:12450/mcp）接上 agent：

claude mcp add poi --transport http http://127.0.0.1:12450/mcp

實際綁定的連接埠也會寫到 ~/.poi-nanodesu-mcp/port，方便需要以程式探索的情境。

插件的 UI 字串透過 poi 自己的 i18n 機制翻譯（見 i18n/*.json），已包含繁體 中文；其他語系會回退到英文原文。

插件依賴

除了 poi 本身，這個插件會讀取其他幾個 poi 插件的資料。全部都是選用的： 沒安裝不會出錯，只是該分支不會出現在 poi_describe 的根列表，而直接去讀會 得到一則指名該套件的「未安裝」訊息。

有三個套件各出現兩次，因為它們是用兩種不同機制被依賴的：最有價值的（或 根本做不出來的）東西不進 redux，所以 state 讀一半、磁碟讀另一半。編成日記是 同樣的情況——記錄本身在 store 裡，但把遊戲狀態轉成 poi-h-v1 的那段邏輯只在 它的套件裡，與其照抄一份等著走鐘，不如直接載它的。

讀磁碟這半的耦合度明顯較高，它依賴對方私有的檔案配置：

<APPDATA>/plugins/node_modules/poi-plugin-quest-line/assets/quests.json
<APPDATA>/plugins/node_modules/poi-plugin-hensei-nikki/utils/calc.js
<APPDATA>/battle-detail/<id>.json.gz

對方改版搬動檔案，這幾條就會失效。目前的處理是安靜降級——載不到就當作沒有， 絕不讓插件啟動失敗或讓工具呼叫爆掉——但它不會主動告訴你「這條以前是通的， 現在壞了」。這是已知的取捨。

編成日記那條的降級方式不太一樣：calc.js 載不到，poi_hensei_save 就整個不註冊， 所以看得出來它不在（工具列表裡沒有），而不是呼叫了才發現沒效果。

開發

npm test           # node:test，跑 test/*.test.ts
npm run typecheck  # tsc --noEmit

scripts/live-check.ts 會對真正在跑的 poi 實例執行這些工具，而不是測試替身。 原始碼結構與在 poi renderer 裡執行時那些不直觀的限制，見 CLAUDE.md； 完整設計說明見 docs/superpowers/specs/2026-08-09-poi-plugin-chinjufu-mcp-design.md。

授權

MIT