Skip to main content
Glama
poi-plugin-mcp

poi-plugin-mcp

by minagi

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後の変更は次のとおりです。

  • 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へ保存されます。

項目

説明

Port

HTTP/MCPサービスの待受port。既定値は17777。通常は変更不要

Service

ローカルデータ連携サービスを開始・停止

WebView Input

認証済みクライアントからゲーム画面へ入力を送信。参照のみの利用では不要

操作記録

操作・画面・関連responseをローカルへ記録。入力の再生は行わない

Debug eval

ゲームWebViewで任意JavaScriptを実行する調査用機能。通常はOFFを推奨

航海日誌

航海日誌の資源履歴をread-onlyで利用。明示的にONにした場合だけ参照

航海日誌は必須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は次のとおりです。

Endpoint

内容

GET /health

bridgeのhealth check

GET /basic

提督基本情報

GET /fleets

艦隊

GET /ships

所持艦娘instance

GET /equipment

所持装備instance

GET /resources

現在資源のraw 8要素配列

GET /quests

受注任務と任務進捗record

GET /available-quests

全任務tabから取得したsnapshot。stdio内部でも使用

GET /airbase

基地航空隊

GET /names

艦娘・装備・遠征の名称map

GET /master

艦娘・装備・艦種・遠征などのmaster data

GET /event

event札定義と所持艦娘の出撃札

GET /planner

Ship Infoの配装計画data

GET /battle

観測した戦闘data、結果、簡易状態

GET /action-events

成功したゲームAPI操作event

GET /action-events/wait

新しい操作eventを待つlong-poll endpoint

GET /api-responses

完全一致pathで指定したKCSAPI response

GET /all

基本runtime dataのまとめ

POST /query

Bearer token必須の汎用read-only query

GET /debug/status

Bearer token必須のDebug eval状態確認

POST /debug/evaluate

明示的に有効化したDebug eval

POST /mcp

HTTP MCP JSON-RPC endpoint

MCP Tools

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

Tool

用途

get_fleet_status

fleetId 1~4の艦隊、艦娘、装備、補強増設、速力、士気、33式索敵、制空値を取得

search_ships

所持艦娘を名前、master ID、艦種、level、士気、lock、配属艦隊、出撃札などで検索

search_equipment

所持装備を名前、master/type ID、改修値、lock、装備中かどうかで検索・集計

get_resources

現在の8資材を名前付きfieldと元のraw配列で取得

get_resource_history

航海日誌の資源snapshotを期間集計し、純増減、日次換算、最小・最大、観測された増減などを取得

get_quests

Poi storeにある受注任務と進捗recordを取得

get_available_quests

「全任務」tabから最後に取得した新鮮な任務snapshotを検索・集計

get_airbase_status

Poi storeの基地航空隊配列を取得

get_all

基本account dataをまとめて取得。通常は目的別Toolを推奨

get_battle

現在または最後に観測した1件の戦闘状態を取得

get_action_events

成功したKCSAPI操作eventをgeneration順に取得

get_kcsapi_responses

完全一致apiPathについて、保持中のKCSAPI responseを取得

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

取り込んだ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を推測していません。

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables MCP clients to query homelab infrastructure such as Proxmox VE, NetBox, systemd services, Grafana, InfluxDB, AdGuard Home, ping logs, and configured HTTP JSON endpoints through read-only tools.
      AGPL 3.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables MCP clients to query a running KanColle game client's live state and integrated resources—fleets, quests, battle history, and id lookups—through read-only tools.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables MCP clients to read Sierra Chart study outputs, chart discovery, and study metadata/history via read-only tools over Streamable HTTP or stdio.
      MIT