poi-plugin-mcp 0.2.13 → 0.2.15

package/README.md

@@ -1,151 +1,201 @@
 # poi-plugin-mcp
 
-Poi plugin that starts a loopback HTTP/MCP bridge inside Poi so local tools can
-read current KanColle data, capture the game WebView, and use explicitly enabled
-authenticated input.
+`poi-plugin-mcp` 是运行在 Poi 内的本地数据桥。它把当前舰队、舰娘、装备、
+资源、任务、陆航和相关主数据通过本机 HTTP 与 MCP 提供给本机工具。
 
-## Install
+默认监听：
 
-Install it from Poi's plugin manager as:
+```none
+http://127.0.0.1:17777
+```
+
+服务只绑定本机回环地址 `127.0.0.1`，不对局域网或公网监听。本文介绍用于
+读取 Poi 状态的 MCP 工具、MCP 资源和 HTTP 数据端点。
+
+## 安装与重启
 
-```text
+在 Poi 插件管理器中安装 npm 包：
+
+```none
 poi-plugin-mcp
 ```
 
-Or install it into Poi's plugin directory with npm:
+也可以完全退出 Poi 后，在 Poi 插件目录中手动安装：
 
 ```powershell
 cd "$env:APPDATA\poi\plugins"
 npm install poi-plugin-mcp
 ```
 
-Then restart Poi and enable `MCP Data Bridge` if needed.
-
-## Development Install
+安装或更新后完整退出并重新启动 Poi。在插件设置中确认“`MCP 数据桥`”已启用，
+然后进入游戏；需要读取账号数据的端点要等 Poi store 初始化完成。
 
-When working from this repository, verify the package from the repo root:
+如果 MCP 客户端要使用 stdio 方式，可另外全局安装同一个 npm 包，使
+`poi-mcp` 命令进入 `PATH`：
 
 ```powershell
-npm install
-npm test
-npm pack --dry-run --ignore-scripts
+npm install -g poi-plugin-mcp
+Get-Command poi-mcp
 ```
 
-Publish or install the generated package through Poi's plugin manager. Fully
-exit Poi before a manual npm installation into its plugin directory.
+## 健康检查与端口发现
 
-## Settings
+默认端口的检查命令：
 
-The Poi plugin settings panel supports:
+```powershell
+Invoke-RestMethod http://127.0.0.1:17777/health
+```
 
-- changing the HTTP port, saved in `~/.poi-mcp/settings.json`
-- manually starting and stopping the local bridge
-- enabling WebView input, which defaults to off
+正常响应：
 
-The default port is `17777`. A random 32-byte hex input token is generated at
-`~/.poi-mcp/input-token` with restrictive best-effort file permissions. The
-token is never returned by an HTTP endpoint.
+```json
+{"status":"ok"}
+```
 
-## HTTP Endpoints
+插件启动后会把实际端口写入：
 
-| Endpoint | Data |
-|---|---|
-| `/health` | Bridge status |
-| `/basic` | Admiral profile |
-| `/fleets` | Raw Poi fleet data |
-| `/ships` | Raw owned ship instance data |
-| `/equipment` | Raw owned equipment instance data |
-| `/resources` | Resource array |
-| `/quests` | Active quests and quest records |
-| `/quest-list` | Latest complete quest-page telemetry |
-| `/quest-action` | Latest successful quest start or stop request |
-| `/equipment-action` | Latest successful equipment mutation request |
-| `/fleet-action` | Latest successful fleet-position mutation request |
-| `/action-events` | Bounded generic KanColle API action-event stream |
-| `/airbase` | Land base air squadron data |
-| `/names` | Ship, equipment, and mission name maps |
-| `/master` | Master ship, equipment, ship type, equipment type, mission, and bounded equipment compatibility data |
-| `/event` | Event ship tag definitions plus owned ships' current sally area |
-| `/planner` | Ship Info deck planner areas and ship assignments |
-| `/battle` | Observed battle packets, official settlement, and compact Prophet state |
-| `/screenshot` | In-memory PNG capture of the game WebView |
-| `/input/status` | Whether authenticated WebView input is enabled |
-| `/input/lease/*` | Acquire, renew, release, inspect, or revoke the one input lease |
-| `/input` | Authenticated, serialized WebView input |
-| `/all` | Combined basic runtime data |
-
-`/screenshot` accepts `GET` only. It uses Poi's existing
-`screenshot::get` WebContents capture path and returns PNG base64 in JSON. It
-does not save a file, write the clipboard, capture the desktop, or appear in
-MCP resources and tools. Its response disables CORS and uses
-`Cache-Control: no-store`.
-
-### WebView Input
-
-`GET /input/status` returns only `{"enabled":true|false}`. Input requires both
-`Authorization: Bearer <token>` and one active expiring lease. A static token
-alone cannot authorize `POST /input`. Requests accept at most 64 KiB of JSON
-and work only while WebView input is enabled in the plugin settings. Input
-routes disable CORS and return `Cache-Control: no-store`.
-
-Each POST accepts exactly one operation:
+```none
+%USERPROFILE%\.poi-mcp\port
+```
 
-```json
-{"operation":"click","x":600,"y":360,"button":"left"}
+修改过端口时，应以该文件为准：
+
+```powershell
+$port = (Get-Content "$HOME\.poi-mcp\port" -Raw).Trim()
+Invoke-RestMethod "http://127.0.0.1:$port/health"
 ```
 
-Click coordinates use a canonical 1200x720 layout and are scaled to Poi's
-current game WebView. Supported buttons are `left`, `middle`, and `right`.
+根路径 `/` 返回 404 不代表服务故障，请使用 `/health`。
 
-```json
-{"operation":"drag","fromX":247,"fromY":178,"toX":202,"toY":178,"durationMs":400,"button":"left"}
+## MCP 接入
+
+插件提供两种 MCP 连接方式：
+
+- **HTTP MCP**：客户端直接连接 Poi 内的 `POST /mcp`。
+- **stdio MCP**：客户端启动 npm 安装的 `poi-mcp` 命令；该命令读取端口文件，
+  再访问 Poi 的本地数据 API。
+
+两种方式都要求 Poi 正在运行且插件已加载。
+
+### HTTP MCP
+
+MCP URL：
+
+```none
+http://127.0.0.1:17777/mcp
 ```
 
-Drag endpoints use the same canonical layout. Duration must be from 50 through
-2000 milliseconds.
+这是 JSON-RPC over HTTP 端点，请由 MCP 客户端向它发送 `POST` 请求。Codex
+配置示例：
 
-```json
-{"operation":"key","event":"keyDown","key":"Enter"}
+```toml
+[mcp_servers.poi]
+url = "http://127.0.0.1:17777/mcp"
 ```
 
-Key events are `keyDown` or `keyUp`. Supported keys are `Backspace`, `Delete`,
-`End`, `Enter`, `Escape`, `Home`, `PageDown`, `PageUp`, `Space`, `Tab`, and the
-four arrow keys.
+使用 JSON 配置的 MCP 客户端可采用：
 
 ```json
-{"operation":"text","text":"literal text"}
+{
+  "mcpServers": {
+    "poi": {
+      "url": "http://127.0.0.1:17777/mcp"
+    }
+  }
+}
 ```
 
-Literal text must contain 1-256 printable characters. Successful requests
-return a bounded response such as
-`{"ok":true,"operation":"text","sequence":1}`. Complete operations execute in
-sequence, so concurrent requests cannot interleave their WebView events.
+若修改过端口，请把 URL 中的 `17777` 替换为端口文件中的值。
+
+### stdio CLI
 
-## MCP Endpoint
+`poi-mcp` 是 MCP stdio 服务命令，不是交互式终端程序。MCP 客户端应负责启动
+并通过标准输入输出与它通信。
 
-The same local server also exposes a JSON-RPC MCP endpoint:
+Codex 配置示例：
 
-```text
-POST http://127.0.0.1:17777/mcp
+```toml
+[mcp_servers.poi]
+command = "poi-mcp"
+args = []
 ```
 
-It supports `initialize`, `ping`, `resources/list`, `resources/read`,
-`tools/list`, and `tools/call`. Resource URIs mirror the HTTP endpoints,
-including `poi://ships`, `poi://equipment`, `poi://resources`, `poi://master`,
-`poi://event`, and `poi://planner`.
+通用 JSON 配置示例：
 
-Available tools:
+```json
+{
+  "mcpServers": {
+    "poi": {
+      "command": "poi-mcp",
+      "args": []
+    }
+  }
+}
+```
 
-- `get_fleet_status`
-- `search_ships`
-- `search_equipment`
-- `get_resources`
-- `get_all`
+如果桌面客户端找不到 npm 的全局命令，请先运行 `Get-Command poi-mcp`，再把
+配置中的 `command` 改为返回的完整可执行文件路径。
 
-## Verification
+## MCP 工具
 
-From the repo root:
+| 工具 | 用途 |
+|---|---|
+| `get_fleet_status` | 按 `fleetId`（1-4）读取一支舰队及舰娘、装备实例 |
+| `search_ships` | 按可选的 `minLevel`、`maxLevel`、`minMorale` 筛选持有舰娘 |
+| `search_equipment` | 按可选的 `minLevel` 筛选持有装备 |
+| `get_resources` | 读取当前资源数组 |
+| `get_all` | 读取基础汇总；`include` 可选 `master`、`event`、`planner` |
+
+## MCP 资源
+
+可通过 `resources/list` 和 `resources/read` 读取：
+
+```none
+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 数据查询端点：
+
+| 端点 | 内容 |
+|---|---|
+| `GET /health` | bridge 健康状态 |
+| `GET /basic` | 提督基础信息 |
+| `GET /fleets` | 舰队数据 |
+| `GET /ships` | 持有舰娘实例 |
+| `GET /equipment` | 持有装备实例 |
+| `GET /resources` | 当前资源 |
+| `GET /quests` | 当前任务与任务记录 |
+| `GET /airbase` | 基地航空队 |
+| `GET /names` | 舰娘、装备和远征名称映射 |
+| `GET /master` | 舰娘、装备、类型、远征等主数据 |
+| `GET /event` | 活动标签定义与持有舰娘出击标签 |
+| `GET /planner` | Ship Info 配装规划数据 |
+| `GET /battle` | 已观测战斗数据、结算与简化战斗状态 |
+| `GET /all` | 基础运行数据汇总 |
+| `POST /mcp` | HTTP MCP JSON-RPC 入口 |
+
+## 开发验证
+
+在源码目录执行：
 
 ```powershell
-npm run test:plugin
+npm install
+npm test
+npm pack --dry-run --ignore-scripts
 ```
+
+`npm test` 应运行 `node --test test/*.test.js`；打包预览应包含
+`index.js`、`lib`、`mcp-server.js` 和本 README。

package/index.js

@@ -7,6 +7,7 @@ const controller = createBridgeController({
   getQuestList: telemetry.getQuestList,
   getQuestAction: telemetry.getQuestAction,
   getEquipmentAction: telemetry.getEquipmentAction,
+  getUnsetSlot: telemetry.getUnsetSlot,
   getFleetAction: telemetry.getFleetAction,
   getActionEvents: telemetry.getActionEvents,
   getBattleTelemetry: telemetry.getBattleTelemetry,

package/lib/bridge-controller.js

@@ -33,6 +33,7 @@ function createBridgeController(options = {}) {
       getQuestList: options.getQuestList,
       getQuestAction: options.getQuestAction,
       getEquipmentAction: options.getEquipmentAction,
+      getUnsetSlot: options.getUnsetSlot,
       getFleetAction: options.getFleetAction,
       getActionEvents: options.getActionEvents,
       getBattleTelemetry: options.getBattleTelemetry,

package/lib/poi-action-events.js

@@ -22,6 +22,7 @@ const EXACT_PATHS = new Set([
   '/kcsapi/api_get_member/ship2',
   '/kcsapi/api_get_member/ship3',
   '/kcsapi/api_get_member/slot_item',
+  '/kcsapi/api_get_member/unsetslot',
   '/kcsapi/api_get_member/useitem',
   '/kcsapi/api_req_air_corps/set_action',
   '/kcsapi/api_req_air_corps/set_plane',
@@ -33,6 +34,7 @@ const EXACT_PATHS = new Set([
   '/kcsapi/api_req_hensei/preset_select',
   '/kcsapi/api_req_hokyu/charge',
   '/kcsapi/api_req_kaisou/powerup',
+  '/kcsapi/api_req_kaisou/slot_select',
   '/kcsapi/api_req_kaisou/slot_deprive',
   '/kcsapi/api_req_kaisou/slotset',
   '/kcsapi/api_req_kaisou/slotset_ex',
@@ -67,6 +69,7 @@ const ALLOWED_PREFIXES = [
 
 const SHARED_TELEMETRY_TIMESTAMP_PATHS = new Set([
   '/kcsapi/api_get_member/questlist',
+  '/kcsapi/api_get_member/unsetslot',
   '/kcsapi/api_req_quest/start',
   '/kcsapi/api_req_quest/stop',
   '/kcsapi/api_req_kaisou/slotset',

package/lib/poi-http-bridge.js

@@ -40,6 +40,8 @@ function createPoiDataBridge(options = {}) {
   const getQuestAction = options.getQuestAction || (() => ({ available: false, generation: 0 }))
   const getEquipmentAction = options.getEquipmentAction ||
     (() => ({ available: false, generation: 0 }))
+  const getUnsetSlot = options.getUnsetSlot ||
+    (() => ({ available: false, generation: 0 }))
   const getFleetAction = options.getFleetAction ||
     (() => ({ available: false, generation: 0 }))
   const getActionEvents = options.getActionEvents ||
@@ -367,6 +369,11 @@ function createPoiDataBridge(options = {}) {
         return
       }
 
+      if (endpoint === '/unsetslot') {
+        sendJson(res, 200, getUnsetSlot())
+        return
+      }
+
       if (endpoint === '/fleet-action') {
         sendJson(res, 200, getFleetAction())
         return

package/lib/poi-telemetry.js

@@ -1,6 +1,7 @@
 const { createPoiActionEvents } = require('./poi-action-events')
 
 const QUEST_LIST_PATH = '/kcsapi/api_get_member/questlist'
+const UNSET_SLOT_PATH = '/kcsapi/api_get_member/unsetslot'
 const QUEST_ACTION_PATHS = new Set([
   '/kcsapi/api_req_quest/start',
   '/kcsapi/api_req_quest/stop',
@@ -49,6 +50,8 @@ function createPoiTelemetry(options = {}) {
   let questAction = null
   let equipmentActionGeneration = 0
   let equipmentAction = null
+  let unsetSlotGeneration = 0
+  let unsetSlot = null
   let fleetActionGeneration = 0
   let fleetAction = null
   let battleGeneration = 0
@@ -63,6 +66,10 @@ function createPoiTelemetry(options = {}) {
       captureQuestList(detail, actionEvent)
       return
     }
+    if (detail.path === UNSET_SLOT_PATH) {
+      captureUnsetSlot(detail, actionEvent)
+      return
+    }
     if (QUEST_ACTION_PATHS.has(detail.path)) {
       captureQuestAction(detail, actionEvent)
       return
@@ -166,6 +173,24 @@ function createPoiTelemetry(options = {}) {
     }
   }
 
+  function captureUnsetSlot(detail, actionEvent) {
+    const bySlotType = normalizeUnsetSlotBody(detail.body)
+    if (bySlotType == null) return
+
+    unsetSlotGeneration += 1
+    unsetSlot = {
+      available: true,
+      generation: unsetSlotGeneration,
+      capturedAt: actionEvent
+        ? actionEvent.capturedAt
+        : now().toISOString(),
+      bySlotType,
+      equipmentIds: Object.values(bySlotType)
+        .flatMap((groups) => Object.values(groups))
+        .flat(),
+    }
+  }
+
   function captureFleetAction(detail, actionEvent) {
     const apiResult = actionEvent
       ? actionEvent.apiResult
@@ -252,6 +277,9 @@ function createPoiTelemetry(options = {}) {
     getEquipmentAction() {
       return equipmentAction || { available: false, generation: 0 }
     },
+    getUnsetSlot() {
+      return unsetSlot || { available: false, generation: 0 }
+    },
     getFleetAction() {
       return fleetAction || { available: false, generation: 0 }
     },
@@ -264,6 +292,36 @@ function createPoiTelemetry(options = {}) {
   }
 }
 
+function normalizeUnsetSlotBody(body) {
+  if (!body || typeof body !== 'object' || Array.isArray(body)) return null
+  const source = body.api_data &&
+    typeof body.api_data === 'object' &&
+    !Array.isArray(body.api_data)
+    ? body.api_data
+    : body
+  const output = {}
+  let totalIds = 0
+
+  for (const [slotType, groups] of Object.entries(source)) {
+    if (!/^api_slottype\d+$/.test(slotType)) continue
+    if (!groups || typeof groups !== 'object' || Array.isArray(groups)) continue
+    const normalizedGroups = {}
+    for (const [groupId, ids] of Object.entries(groups)) {
+      if (!/^\d+$/.test(groupId) || !Array.isArray(ids)) continue
+      const normalizedIds = ids
+        .map(positiveIntegerOrNull)
+        .filter((id) => id != null)
+      totalIds += normalizedIds.length
+      if (totalIds > 10000) return null
+      normalizedGroups[groupId] = normalizedIds
+    }
+    if (Object.keys(normalizedGroups).length > 0) {
+      output[slotType] = normalizedGroups
+    }
+  }
+  return Object.keys(output).length > 0 ? output : null
+}
+
 function normalizeFleetPostBody(postBody) {
   if (!postBody || typeof postBody !== 'object') return null
   const fleetId = boundedInteger(postBody.api_id, 1, 4)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "poi-plugin-mcp",
-  "version": "0.2.13",
+  "version": "0.2.15",
   "description": "Poi data, WebView capture, and opt-in authenticated input bridge for local KanColle tools.",
   "main": "index.js",
   "keywords": [