poi-plugin-mcp 0.2.12 → 0.2.14

package/README.md

@@ -1,144 +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 数据端点。
+
+## 安装与重启
+
+在 Poi 插件管理器中安装 npm 包：
 
-```text
+```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.
+安装或更新后完整退出并重新启动 Poi。在插件设置中确认“`MCP 数据桥`”已启用，
+然后进入游戏；需要读取账号数据的端点要等 Poi store 初始化完成。
+
+如果 MCP 客户端要使用 stdio 方式，可另外全局安装同一个 npm 包，使
+`poi-mcp` 命令进入 `PATH`：
+
+```powershell
+npm install -g poi-plugin-mcp
+Get-Command poi-mcp
+```
 
-## Development Install
+## 健康检查与端口发现
 
-When working from this repository, install from the repo root:
+默认端口的检查命令：
 
 ```powershell
-npm install
-npm run install:poi
+Invoke-RestMethod http://127.0.0.1:17777/health
 ```
 
-Then restart Poi and enable `MCP Data Bridge` if needed.
+正常响应：
+
+```json
+{"status":"ok"}
+```
 
-The installer creates:
+插件启动后会把实际端口写入：
 
-```text
-%APPDATA%\poi\plugins\node_modules\poi-plugin-mcp -> <repo>\packages\poi-plugin-mcp
+```none
+%USERPROFILE%\.poi-mcp\port
 ```
 
-## Settings
+修改过端口时，应以该文件为准：
 
-The Poi plugin settings panel supports:
+```powershell
+$port = (Get-Content "$HOME\.poi-mcp\port" -Raw).Trim()
+Invoke-RestMethod "http://127.0.0.1:$port/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
+根路径 `/` 返回 404 不代表服务故障，请使用 `/health`。
 
-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.
+## MCP 接入
 
-## HTTP Endpoints
+插件提供两种 MCP 连接方式：
 
-| 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 |
-| `/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` | 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}`. `POST /input`
-requires `Authorization: Bearer <token>`, accepts at most 64 KiB of JSON, and
-works only while WebView input is enabled in the plugin settings. Both routes
-disable CORS and return `Cache-Control: no-store`.
-
-Each POST accepts exactly one operation:
+- **HTTP MCP**：客户端直接连接 Poi 内的 `POST /mcp`。
+- **stdio MCP**：客户端启动 npm 安装的 `poi-mcp` 命令；该命令读取端口文件，
+  再访问 Poi 的本地数据 API。
 
-```json
-{"operation":"click","x":600,"y":360,"button":"left"}
+两种方式都要求 Poi 正在运行且插件已加载。
+
+### HTTP MCP
+
+MCP URL：
+
+```none
+http://127.0.0.1:17777/mcp
 ```
 
-Click coordinates use a canonical 1200x720 layout and are scaled to Poi's
-current game WebView. Supported buttons are `left`, `middle`, and `right`.
+这是 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` 替换为端口文件中的值。
 
-## MCP Endpoint
+### stdio CLI
 
-The same local server also exposes a JSON-RPC MCP endpoint:
+`poi-mcp` 是 MCP stdio 服务命令，不是交互式终端程序。MCP 客户端应负责启动
+并通过标准输入输出与它通信。
 
-```text
-POST http://127.0.0.1:17777/mcp
+Codex 配置示例：
+
+```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,7 +7,9 @@ const controller = createBridgeController({
   getQuestList: telemetry.getQuestList,
   getQuestAction: telemetry.getQuestAction,
   getEquipmentAction: telemetry.getEquipmentAction,
+  getUnsetSlot: telemetry.getUnsetSlot,
   getFleetAction: telemetry.getFleetAction,
+  getActionEvents: telemetry.getActionEvents,
   getBattleTelemetry: telemetry.getBattleTelemetry,
 })
 const settingsClass = createSettingsClass(controller)

package/lib/bridge-controller.js

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

package/lib/poi-action-events.js

@@ -0,0 +1,290 @@
+const crypto = require('node:crypto')
+
+const DEFAULT_CAPACITY = 256
+const DEFAULT_LIMIT = 64
+const MAX_CAPACITY = 256
+const MAX_OBJECT_KEYS = 32
+const MAX_ARRAY_ITEMS = 16
+const MAX_STRING_LENGTH = 256
+const MAX_RESPONSE_DEPTH = 4
+
+const EXACT_PATHS = new Set([
+  '/kcsapi/api_start2/getData',
+  '/kcsapi/api_port/port',
+  '/kcsapi/api_get_member/base_air_corps',
+  '/kcsapi/api_get_member/deck',
+  '/kcsapi/api_get_member/kdock',
+  '/kcsapi/api_get_member/mapinfo',
+  '/kcsapi/api_get_member/material',
+  '/kcsapi/api_get_member/ndock',
+  '/kcsapi/api_get_member/practice',
+  '/kcsapi/api_get_member/questlist',
+  '/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',
+  '/kcsapi/api_req_air_corps/supply',
+  '/kcsapi/api_req_battle_midnight/battle',
+  '/kcsapi/api_req_battle_midnight/sp_midnight',
+  '/kcsapi/api_req_hensei/change',
+  '/kcsapi/api_req_hensei/combined',
+  '/kcsapi/api_req_hensei/preset_select',
+  '/kcsapi/api_req_hokyu/charge',
+  '/kcsapi/api_req_kaisou/powerup',
+  '/kcsapi/api_req_kaisou/slot_deprive',
+  '/kcsapi/api_req_kaisou/slotset',
+  '/kcsapi/api_req_kaisou/slotset_ex',
+  '/kcsapi/api_req_kaisou/unsetslot_all',
+  '/kcsapi/api_req_kousyou/createitem',
+  '/kcsapi/api_req_kousyou/createship',
+  '/kcsapi/api_req_kousyou/createship_speedchange',
+  '/kcsapi/api_req_kousyou/destroyitem2',
+  '/kcsapi/api_req_kousyou/destroyship',
+  '/kcsapi/api_req_kousyou/getship',
+  '/kcsapi/api_req_kousyou/remodel_slot',
+  '/kcsapi/api_req_map/next',
+  '/kcsapi/api_req_map/select_eventmap_rank',
+  '/kcsapi/api_req_map/start',
+  '/kcsapi/api_req_member/get_practice_enemyinfo',
+  '/kcsapi/api_req_mission/result',
+  '/kcsapi/api_req_mission/start',
+  '/kcsapi/api_req_nyukyo/speedchange',
+  '/kcsapi/api_req_nyukyo/start',
+  '/kcsapi/api_req_practice/battle',
+  '/kcsapi/api_req_practice/battle_result',
+  '/kcsapi/api_req_practice/midnight_battle',
+  '/kcsapi/api_req_quest/clearitemget',
+  '/kcsapi/api_req_quest/start',
+  '/kcsapi/api_req_quest/stop',
+])
+
+const ALLOWED_PREFIXES = [
+  '/kcsapi/api_req_sortie/',
+  '/kcsapi/api_req_combined_battle/',
+]
+
+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',
+  '/kcsapi/api_req_kaisou/slotset_ex',
+  '/kcsapi/api_req_kaisou/slot_deprive',
+  '/kcsapi/api_req_kaisou/unsetslot_all',
+  '/kcsapi/api_req_hensei/change',
+])
+
+function createPoiActionEvents(options = {}) {
+  const now = options.now || (() => new Date())
+  const inferredNow = options.inferredNow || (() => new Date())
+  const sessionId = boundedId(options.sessionId || crypto.randomUUID(), 'sessionId')
+  const capacity = boundedInteger(
+    options.capacity == null ? DEFAULT_CAPACITY : options.capacity,
+    1,
+    MAX_CAPACITY,
+    'capacity',
+  )
+  const events = []
+  let latestGeneration = 0
+
+  function capture(detail) {
+    if (!isCapturableDetail(detail)) return null
+    const explicitApiResult = readApiResult(detail)
+    const apiResult = explicitApiResult == null && hasUnwrappedResponseBody(detail)
+      ? 1
+      : explicitApiResult
+    if (apiResult !== 1) return null
+
+    latestGeneration += 1
+    const eventNow = explicitApiResult != null ||
+      SHARED_TELEMETRY_TIMESTAMP_PATHS.has(detail.path)
+      ? now
+      : inferredNow
+    const event = Object.freeze({
+      generation: latestGeneration,
+      capturedAt: timestamp(eventNow()),
+      path: detail.path,
+      apiResult,
+      postBody: sanitizePostBody(detail.postBody),
+      responseSummary: sanitizeResponse(detail.body),
+    })
+    events.push(event)
+    if (events.length > capacity) events.splice(0, events.length - capacity)
+    return event
+  }
+
+  function read(options = {}) {
+    const after = boundedInteger(
+      options.after == null ? 0 : options.after,
+      0,
+      Number.MAX_SAFE_INTEGER,
+      'after',
+    )
+    const limit = boundedInteger(
+      options.limit == null ? DEFAULT_LIMIT : options.limit,
+      1,
+      MAX_CAPACITY,
+      'limit',
+    )
+    return {
+      available: true,
+      sessionId,
+      latestGeneration,
+      events: events
+        .filter((event) => event.generation > after)
+        .slice(0, limit),
+    }
+  }
+
+  return Object.freeze({ capture, read })
+}
+
+function isCapturableDetail(detail) {
+  return Boolean(
+    detail &&
+    typeof detail === 'object' &&
+    !Array.isArray(detail) &&
+    typeof detail.path === 'string' &&
+    (
+      EXACT_PATHS.has(detail.path) ||
+      ALLOWED_PREFIXES.some((prefix) => detail.path.startsWith(prefix))
+    ),
+  )
+}
+
+function readApiResult(detail) {
+  const candidates = [
+    detail.apiResult,
+    detail.api_result,
+    detail.result,
+    detail.body && detail.body.api_result,
+  ]
+  for (const candidate of candidates) {
+    if (candidate == null || candidate === '') continue
+    const parsed = Number(candidate)
+    return Number.isInteger(parsed) ? parsed : null
+  }
+  return null
+}
+
+function hasUnwrappedResponseBody(detail) {
+  if (!Object.prototype.hasOwnProperty.call(detail, 'body')) return false
+  const body = detail.body
+  if (!isPlainObject(body) && !Array.isArray(body)) return false
+  return !(
+    isPlainObject(body) &&
+    (
+      Object.prototype.hasOwnProperty.call(body, 'api_result') ||
+      Object.prototype.hasOwnProperty.call(body, 'api_data')
+    )
+  )
+}
+
+function sanitizePostBody(value) {
+  if (!isPlainObject(value)) return {}
+  const output = {}
+  for (const [key, item] of Object.entries(value).slice(0, MAX_OBJECT_KEYS)) {
+    if (!safeKey(key)) continue
+    const scalar = sanitizeScalar(item)
+    if (scalar !== undefined) {
+      output[key] = scalar
+      continue
+    }
+    if (
+      Array.isArray(item) &&
+      item.length <= MAX_ARRAY_ITEMS
+    ) {
+      const array = item.map(sanitizeScalar)
+      if (array.every((entry) => entry !== undefined)) output[key] = array
+    }
+  }
+  return output
+}
+
+function sanitizeResponse(value) {
+  const sanitized = sanitizeNested(value, 0)
+  return isPlainObject(sanitized) ? sanitized : {}
+}
+
+function sanitizeNested(value, depth) {
+  const scalar = sanitizeScalar(value)
+  if (scalar !== undefined) return scalar
+  if (depth >= MAX_RESPONSE_DEPTH) return undefined
+  if (Array.isArray(value)) {
+    return value
+      .slice(0, MAX_ARRAY_ITEMS)
+      .map((item) => sanitizeNested(item, depth + 1))
+      .filter((item) => item !== undefined)
+  }
+  if (!isPlainObject(value)) return undefined
+  const output = {}
+  for (const [key, item] of Object.entries(value).slice(0, MAX_OBJECT_KEYS)) {
+    if (!safeKey(key)) continue
+    const sanitized = sanitizeNested(item, depth + 1)
+    if (sanitized !== undefined) output[key] = sanitized
+  }
+  return output
+}
+
+function sanitizeScalar(value) {
+  if (
+    value === null ||
+    typeof value === 'boolean' ||
+    (typeof value === 'number' && Number.isFinite(value))
+  ) {
+    return value
+  }
+  if (typeof value === 'string') return value.slice(0, MAX_STRING_LENGTH)
+  return undefined
+}
+
+function safeKey(key) {
+  return (
+    typeof key === 'string' &&
+    key.length > 0 &&
+    key.length <= 64 &&
+    !/(authorization|cookie|header|password|secret|token)/i.test(key)
+  )
+}
+
+function timestamp(value) {
+  const date = value instanceof Date ? value : new Date(value)
+  if (!Number.isFinite(date.getTime())) throw new Error('now must return a valid date')
+  return date.toISOString()
+}
+
+function boundedId(value, name) {
+  if (typeof value !== 'string' || value.length === 0 || value.length > 256) {
+    throw new Error(`${name} must be a non-empty bounded string`)
+  }
+  return value
+}
+
+function boundedInteger(value, minimum, maximum, name) {
+  if (
+    !Number.isSafeInteger(value) ||
+    value < minimum ||
+    value > maximum
+  ) {
+    throw new Error(
+      `${name} must be an integer from ${minimum} through ${maximum}`,
+    )
+  }
+  return value
+}
+
+function isPlainObject(value) {
+  return Boolean(
+    value &&
+    typeof value === 'object' &&
+    !Array.isArray(value),
+  )
+}
+
+module.exports = {
+  createPoiActionEvents,
+}