poi-plugin-mcp (Minagi fork)

Poiで保持している艦隊・艦娘・装備・資源・任務などの情報を、ローカルHTTP APIと Model Context Protocol（MCP）経由で外部ツールから参照するためのPoiプラグインです。

サービスは既定で127.0.0.1:17777だけをlistenし、LANやインターネットへは公開しません。

このforkについて

このrepositoryは、npmで公開されたpoi-plugin-mcp 0.2.29を基にしたforkです。 取り込み時点の内容はtag upstream-0.2.29、 元READMEはdocs/UPSTREAM_README.mdで確認できます。

• Fork maintainer: Minagi Tohno

• Repository: minagi/poi-plugin-mcp

• Issues: GitHub Issues

主なfork後の変更は次のとおりです。

• MCP Toolを拡張し、艦隊状態、艦娘・装備検索、任務、戦闘、操作event、KCSAPI responseを取得可能にした

• 現在資源を名前付きfieldで返し、航海日誌の資源履歴を期間集計するget_resource_historyを追加した

• 設定UIを日本語化し、各機能の用途と安全上の注意を表示した

• 外部Poiプラグインとのread-only連携基盤を追加した

• 航海日誌（poi-plugin-akashic-records）を任意連携として検出し、Poi Redux extension state経由で資源履歴を参照できるようにした

• HTTP MCPとstdio MCPで同じTool定義・入力検証・結果形式を利用するよう整理した

Related MCP server: homelab-mcp

主な機能

• Poi storeにある艦隊、艦娘、装備、資源、任務、基地航空隊、master dataなどの参照

• 艦娘・装備の絞り込み、summary、keyset pagination

• 全任務tabから取得した任務snapshotの参照

• 現在または最後に観測した戦闘状態の参照

• 成功したゲームAPI操作eventと、完全一致pathで指定したKCSAPI responseの参照

• 航海日誌の資源snapshotを使った純増減、回復ペース、期間内の最小・最大、観測された増減の集計

• MCP Resources、HTTP MCP、stdio MCP、ローカルHTTP data endpoint

• 明示的に有効化した場合のみ利用できるWebView入力、調査用JavaScript実行、操作記録

インストール

このforkとnpm版poi-plugin-mcpは同じpackage名です。Poiのプラグイン検索から poi-plugin-mcpを通常installした場合は、npmで公開されているupstream版が対象となります。

このforkをGitHubからinstallする場合はPoiを完全に終了し、PowerShellで次を実行します。

cd "$env:APPDATA\poi\plugins"
npm install "git+https://github.com/minagi/poi-plugin-mcp.git#v0.2.30-minagi.1"

install後にPoiを再起動し、プラグイン一覧で「MCP連携」が有効になっていることを確認してください。

Poiは同名npm packageのlatestとlocal versionをSemVerで比較します。このforkはupstream 0.2.29より新しく、将来の正式版0.2.30よりは古くなるよう、0.2.30-minagi.1を使用します。 これによりupstream 0.2.29を誤ってupdateとして表示することを避けつつ、upstream 0.2.30 が公開された場合はupdate対象になります。update実行時はnpm registryの同名packageがinstall されるため、forkを継続利用する場合は更新元を確認してください。

stdio接続でpoi-mcpコマンドを利用する場合は、同じforkをglobal installできます。

npm install -g "git+https://github.com/minagi/poi-plugin-mcp.git#v0.2.30-minagi.1"
Get-Command poi-mcp

設定

設定は%USERPROFILE%\.poi-mcp\settings.jsonへ保存されます。

航海日誌は必須dependencyではありません。未install・無効・読込未完了の場合でも、 航海日誌連携以外の機能は利用できます。

操作記録の保存内容、上限、redactionについては操作記録の仕様を参照してください。

MCP接続

起動確認とport

既定portのhealth check:

Invoke-RestMethod http://127.0.0.1:17777/health

正常時は{"status":"ok"}を返します。実際に使用しているportは次のfileにも保存されます。

%USERPROFILE%\.poi-mcp\port

root path /の404は異常ではありません。/healthを使用してください。

HTTP MCP

Poiが起動している状態で、MCP clientから次のURLへ接続します。

http://127.0.0.1:17777/mcp

Codexの設定例:

[mcp_servers.poi]
url = "http://127.0.0.1:17777/mcp"

一般的なJSON設定例:

{
  "mcpServers": {
    "poi": {
      "url": "http://127.0.0.1:17777/mcp"
    }
  }
}

stdio MCP

poi-mcpは対話型commandではなく、MCP clientが起動するstdio serverです。 Poi内の既存HTTP /mcpへ委譲するため、Poiと本プラグインが起動している必要があります。

[mcp_servers.poi]
command = "poi-mcp"
args = []

commandが見つからない場合はGet-Command poi-mcpで得た完全pathを指定してください。

MCP Resources

resources/listとresources/readでは次のURIを利用できます。

poi://basic
poi://fleets
poi://ships
poi://equipment
poi://resources
poi://quests
poi://airbase
poi://names
poi://master
poi://event
poi://planner
poi://all

ローカルHTTP endpoint

主なread endpointは次のとおりです。

MCP Tools

現在は12個のToolを公開します。

search_shipsとsearch_equipmentは最大200件のkeyset paginationに対応します。 装備のsummary:trueはpagination前の全一致対象を集計し、limit省略時はinstance一覧を 返さないため、MCP clientのcontext消費を抑えられます。equipped判定は艦娘の通常slotと 補強増設を対象とし、基地航空隊は対象外です。

get_available_questsは正常なapi_tab_id=0 responseだけを単一snapshotとして保持します。 snapshotは取得から5分、または次の05:00 JSTの早い方で失効し、任務操作や bootstrap/reconnectを観測した場合もstaleになります。更新するにはゲームで「全任務」tabを 開くか再表示してください。Tool自身が任務を受注・解除することはありません。

get_battleは戦闘履歴ではありません。in_progressのまま残っていても古い可能性があります。 poi-plugin-prophetによる予測は任意で、未installでもエラーにはなりません。

get_action_eventsとget_kcsapi_responsesはin-memory ring bufferを参照します。 Poi再起動や保持上限超過はsessionChanged / cursorLost等で判別できます。 get_kcsapi_responsesは完全一致pathだけを受け付け、requestのpostBodyは返しません。 response bodyとTool結果にはsize上限があり、省略時はmetadataで判別できます。

航海日誌連携

get_resource_historyは航海日誌（poi-plugin-akashic-records）を任意のdata sourceとして 利用します。利用には次の条件がすべて必要です。

• 設定画面で航海日誌連携をONにしている

• 航海日誌がinstall・有効化され、Poiで正常に読込済み

• pluginがbrokenまたはrollback待ちではない

本プラグインは航海日誌の保存fileを直接読みません。航海日誌がPoiのRedux extension stateへ 読み込んだresource.dataをread-onlyで参照し、名前付きの内部形式へ正規化します。 航海日誌側のstate、file、設定を変更する処理はありません。

資源snapshotは固定timerで毎時必ず作られるものではありません。 航海日誌が/kcsapi/api_port/portを観測し、前回記録した時間帯から変わっている場合に、 1時間帯あたり最大1件保存されます。母港情報を取得しない時間帯は欠測し得ます。

get_resource_historyは期間内の最古・最新snapshot、純増減、実観測期間による日次換算、 最小・最大、開始値からの最大減少、隣接snapshot間で観測された増加・減少を返します。 これはtransaction logではないため、observedIncrease / observedDecreaseを実際の総収入・ 総消費と解釈しないでください。返却されるsampling gap情報で長時間の欠測も確認できます。

資源回復、event期間、戦果稼ぎ期間、運用変更前後などの事実確認に利用できますが、 おすすめ遠征、予測、資源優先順位などの判断はTool側では行いません。

セキュリティ上の注意

通常のread-only利用では、艦隊・艦娘・装備・資源・任務等の参照と、明示的にONにした 航海日誌連携を利用します。これらの結果にはaccount固有のinstance IDや進行状況が含まれる 場合があるため、信頼できるローカルclientだけから接続してください。

次の機能は通常の参照には不要で、設定画面から明示的に有効化する必要があります。

• WebView Input: ゲーム画面へ入力を送信する。Bearer tokenによる認証を使用

• Debug eval: ゲームWebViewで任意JavaScriptを実行する。token参照、game API呼出し、 page変更等が可能なため、調査時だけONにし、終了後はOFFへ戻すことを推奨

• 操作記録: mouse操作、画面、関連response、選択したPoi stateをlocal diskへ保存。 再生機能ではなく、保存容量と記録内容を確認したうえで利用

/query、/debug/status、/debug/evaluateはCORSを公開せず、 %USERPROFILE%\.poi-mcp\input-tokenのBearer tokenを要求します。

開発・テスト

source checkoutで次を実行します。

npm install
npm test
npm pack --dry-run --ignore-scripts

JavaScriptの構文確認例:

$files = @(rg --files -g '*.js')
foreach ($file in $files) { node --check $file }

Upstream

• 取り込み元: npm版poi-plugin-mcp 0.2.29

• Snapshot tag: upstream-0.2.29

• Upstream README保存版: docs/UPSTREAM_README.md

取り込んだsnapshotにはupstream repository URL、author、copyright holderを確実に特定できる 情報が含まれていません。そのため、npm publisher名やGitHub usernameから推測した作者・ 著作権者は記載していません。

License

package.jsonのlicenseは、upstream 0.2.29と同じMITを維持しています。 LICENSEはMinagi forkで追加・変更した部分についてのcopyright noticeを伴う、 標準MIT License本文です。

upstream snapshotもpackage.jsonでMITを宣言していますが、snapshot内にLICENSE fileや copyright holder・yearの明記はありませんでした。確認できた事実とfork側noticeの範囲は NOTICE.mdへ分離しています。元の著作権者をMinagi Tohnoとして扱うものではなく、 このrepositoryでは不明なupstream holderを推測していません。