poi-plugin-mcp 0.2.3 → 0.2.9

package/README.md

@@ -1,6 +1,8 @@
 # poi-plugin-mcp
 
-Poi plugin that starts a local HTTP/MCP bridge inside Poi so CLI/MCP agents can read current KanColle data.
+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.
 
 ## Install
 
@@ -42,8 +44,11 @@ The Poi plugin settings panel supports:
 
 - 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`.
+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.
 
 ## HTTP Endpoints
 
@@ -62,6 +67,8 @@ The default port is `17777`.
 | `/event` | Event ship tag definitions plus owned ships' current sally area |
 | `/planner` | Ship Info deck planner areas and ship assignments |
 | `/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
@@ -70,6 +77,39 @@ 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:
+
+```json
+{"operation":"click","x":600,"y":360,"button":"left"}
+```
+
+Click coordinates use a canonical 1200x720 layout and are scaled to Poi's
+current game WebView. Supported buttons are `left`, `middle`, and `right`.
+
+```json
+{"operation":"key","event":"keyDown","key":"Enter"}
+```
+
+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
+{"operation":"text","text":"literal text"}
+```
+
+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.
+
 ## MCP Endpoint
 
 The same local server also exposes a JSON-RPC MCP endpoint:

package/index.js

@@ -1,16 +1,28 @@
 const { createBridgeController } = require('./lib/bridge-controller')
+const { createPoiTelemetry } = require('./lib/poi-telemetry')
 const { createSettingsClass } = require('./lib/settings-view')
 
-const controller = createBridgeController()
+const telemetry = createPoiTelemetry()
+const controller = createBridgeController({
+  getQuestList: telemetry.getQuestList,
+  getQuestAction: telemetry.getQuestAction,
+  getBattleTelemetry: telemetry.getBattleTelemetry,
+})
 const settingsClass = createSettingsClass(controller)
 
 function pluginDidLoad() {
+  if (typeof window !== 'undefined') {
+    window.addEventListener('game.response', telemetry.handleGameResponse)
+  }
   controller.load().catch((error) => {
     console.error('[poi-plugin-mcp] Failed to start:', error.message)
   })
 }
 
 function pluginWillUnload() {
+  if (typeof window !== 'undefined') {
+    window.removeEventListener('game.response', telemetry.handleGameResponse)
+  }
   controller.unload().catch((error) => {
     console.error('[poi-plugin-mcp] Failed to stop:', error.message)
   })

package/lib/bridge-controller.js

@@ -1,4 +1,5 @@
 const { createPoiDataBridge } = require('./poi-http-bridge')
+const { loadOrCreateInputToken } = require('./input-token')
 const {
   DEFAULT_SETTINGS_FILE,
   loadSettings,
@@ -13,6 +14,7 @@ function createBridgeController(options = {}) {
 
   let settings = loadSettings(settingsPath)
   let bridge = null
+  let inputToken = options.inputToken || null
   let pending = Promise.resolve()
 
   function enqueue(action) {
@@ -21,9 +23,18 @@ function createBridgeController(options = {}) {
   }
 
   function createCurrentBridge() {
+    if (!inputToken) {
+      inputToken = loadOrCreateInputToken(options.inputTokenFile)
+    }
     return createBridge({
       getStore: options.getStore,
       captureScreenshot: options.captureScreenshot,
+      performInput: options.performInput,
+      getQuestList: options.getQuestList,
+      getQuestAction: options.getQuestAction,
+      getBattleTelemetry: options.getBattleTelemetry,
+      inputEnabled: settings.inputEnabled,
+      inputToken,
       port: settings.port,
       portFile: options.portFile,
       logger,
@@ -83,6 +94,7 @@ function createBridgeController(options = {}) {
         const normalized = normalizeSettings({ ...settings, ...nextSettings })
         const portChanged = normalized.port !== settings.port
         const enabledChanged = normalized.enabled !== settings.enabled
+        const inputEnabledChanged = normalized.inputEnabled !== settings.inputEnabled
 
         persist(normalized)
 
@@ -91,7 +103,7 @@ function createBridgeController(options = {}) {
           return
         }
 
-        if (portChanged || enabledChanged || !bridge) {
+        if (portChanged || enabledChanged || inputEnabledChanged || !bridge) {
           await stopCurrentBridge()
           await ensureStarted()
         }
@@ -109,6 +121,7 @@ function createBridgeController(options = {}) {
         running: actualPort > 0,
         port: settings.port,
         actualPort,
+        inputEnabled: settings.inputEnabled,
       }
     },
   }

package/lib/input-token.js

@@ -0,0 +1,63 @@
+const crypto = require('crypto')
+const fs = require('fs')
+const os = require('os')
+const path = require('path')
+
+const DEFAULT_INPUT_TOKEN_FILE = path.join(os.homedir(), '.poi-mcp', 'input-token')
+const TOKEN_PATTERN = /^[a-f0-9]{64}$/
+
+function loadOrCreateInputToken(tokenFile = DEFAULT_INPUT_TOKEN_FILE) {
+  const existing = readValidToken(tokenFile)
+  if (existing) {
+    restrictPermissions(tokenFile)
+    return existing
+  }
+
+  const directory = path.dirname(tokenFile)
+  fs.mkdirSync(directory, { recursive: true, mode: 0o700 })
+  restrictPermissions(directory, 0o700)
+
+  const token = crypto.randomBytes(32).toString('hex')
+  try {
+    fs.writeFileSync(tokenFile, `${token}\n`, {
+      encoding: 'utf8',
+      flag: 'wx',
+      mode: 0o600,
+    })
+  } catch (error) {
+    if (error.code !== 'EEXIST') throw error
+
+    const concurrent = readValidToken(tokenFile)
+    if (concurrent) {
+      restrictPermissions(tokenFile)
+      return concurrent
+    }
+    fs.writeFileSync(tokenFile, `${token}\n`, {
+      encoding: 'utf8',
+      mode: 0o600,
+    })
+  }
+
+  restrictPermissions(tokenFile)
+  return token
+}
+
+function readValidToken(tokenFile) {
+  try {
+    const token = fs.readFileSync(tokenFile, 'utf8').trim()
+    return TOKEN_PATTERN.test(token) ? token : null
+  } catch (_) {
+    return null
+  }
+}
+
+function restrictPermissions(target, mode = 0o600) {
+  try {
+    fs.chmodSync(target, mode)
+  } catch (_) {}
+}
+
+module.exports = {
+  DEFAULT_INPUT_TOKEN_FILE,
+  loadOrCreateInputToken,
+}

package/lib/poi-http-bridge.js

@@ -1,8 +1,11 @@
 const fs = require('fs')
 const http = require('http')
+const crypto = require('crypto')
 const os = require('os')
 const path = require('path')
 const packageJson = require('../package.json')
+const { loadOrCreateInputToken } = require('./input-token')
+const { createPoiInputProvider } = require('./poi-input')
 const { createPoiScreenshotProvider } = require('./poi-screenshot')
 
 const DEFAULT_PORT = 17777
@@ -14,6 +17,7 @@ const DEFAULT_PLANNER_FILE = path.join(
 )
 const JSONRPC_VERSION = '2.0'
 const MCP_PROTOCOL_VERSION = '2024-11-05'
+const INPUT_BODY_LIMIT = 64 * 1024
 
 function createPoiDataBridge(options = {}) {
   const getStore = options.getStore || defaultGetStore
@@ -21,10 +25,21 @@ function createPoiDataBridge(options = {}) {
   const portFile = options.portFile || DEFAULT_PORT_FILE
   const plannerFile = options.plannerFile || DEFAULT_PLANNER_FILE
   const logger = options.logger || console
+  const getQuestList = options.getQuestList || (() => ({ available: false, generation: 0 }))
+  const getQuestAction = options.getQuestAction || (() => ({ available: false, generation: 0 }))
+  const getBattleTelemetry = options.getBattleTelemetry ||
+    (() => ({ available: false, generation: 0 }))
+  const inputEnabled = options.inputEnabled === true
+  const inputToken = options.inputToken || (
+    inputEnabled ? loadOrCreateInputToken(options.inputTokenFile) : null
+  )
   let captureScreenshot = options.captureScreenshot || null
+  let performInput = options.performInput || null
 
   let server = null
   let actualPort = 0
+  let inputPending = Promise.resolve()
+  let inputSequence = 0
 
   function readStore() {
     const store = getStore()
@@ -44,10 +59,82 @@ function createPoiDataBridge(options = {}) {
     if (options.noStore) {
       headers['Cache-Control'] = 'no-store'
     }
+    Object.assign(headers, options.headers)
     res.writeHead(statusCode, headers)
     res.end(JSON.stringify(data))
   }
 
+  function sendInputJson(res, statusCode, data, options = {}) {
+    sendJson(res, statusCode, data, {
+      allowCors: false,
+      noStore: true,
+      ...options,
+    })
+  }
+
+  function enqueueInput(operation) {
+    const execute = async () => {
+      if (!performInput) {
+        performInput = createPoiInputProvider({ getStore })
+      }
+      const operationName = await performInput(operation)
+      inputSequence += 1
+      return {
+        ok: true,
+        operation: operationName,
+        sequence: inputSequence,
+      }
+    }
+    const result = inputPending.then(execute, execute)
+    inputPending = result.catch(() => {})
+    return result
+  }
+
+  async function handleInputRequest(req, res) {
+    if (req.method !== 'POST') {
+      drainRequest(req)
+      sendInputJson(res, 405, { error: 'Input endpoint only accepts POST requests.' })
+      return
+    }
+    if (!hasValidBearerToken(req.headers.authorization, inputToken)) {
+      drainRequest(req)
+      sendInputJson(
+        res,
+        401,
+        { error: 'A valid Bearer token is required.' },
+        { headers: { 'WWW-Authenticate': 'Bearer' } },
+      )
+      return
+    }
+    if (requestContentLength(req) > INPUT_BODY_LIMIT) {
+      drainRequest(req)
+      sendInputJson(res, 413, { error: 'Input request body exceeds 64KB.' })
+      return
+    }
+    if (!inputEnabled) {
+      drainRequest(req)
+      sendInputJson(res, 403, { error: 'WebView input is disabled.' })
+      return
+    }
+
+    try {
+      const body = await readRequestBody(
+        req,
+        INPUT_BODY_LIMIT,
+        'Input request body exceeds 64KB.',
+      )
+      const operation = JSON.parse(body || '{}')
+      sendInputJson(res, 200, await enqueueInput(operation))
+    } catch (error) {
+      const statusCode = error.code === 'BODY_TOO_LARGE'
+        ? 413
+        : /WebView|dimensions/.test(error.message)
+          ? 503
+          : 400
+      sendInputJson(res, statusCode, { error: error.message })
+    }
+  }
+
   function handleMcpRequest(req, res) {
     if (req.method !== 'POST') {
       sendJson(res, 405, { error: 'MCP endpoint only accepts POST requests.' })
@@ -126,6 +213,35 @@ function createPoiDataBridge(options = {}) {
         return
       }
 
+      if (endpoint === '/input/status') {
+        if (req.method !== 'GET') {
+          drainRequest(req)
+          sendInputJson(
+            res,
+            405,
+            { error: 'Input status endpoint only accepts GET requests.' },
+          )
+          return
+        }
+        sendInputJson(res, 200, { enabled: inputEnabled })
+        return
+      }
+
+      if (endpoint === '/input') {
+        await handleInputRequest(req, res)
+        return
+      }
+
+      if (endpoint === '/quest-list') {
+        sendJson(res, 200, getQuestList())
+        return
+      }
+
+      if (endpoint === '/quest-action') {
+        sendJson(res, 200, getQuestAction())
+        return
+      }
+
       const store = readStore()
       const info = store.info
 
@@ -166,6 +282,12 @@ function createPoiDataBridge(options = {}) {
         case '/planner':
           sendJson(res, 200, extractPlannerData(store, plannerFile))
           break
+        case '/battle':
+          sendJson(res, 200, combineBattleTelemetry(
+            getBattleTelemetry(),
+            extractProphetBattle(store),
+          ))
+          break
         case '/all':
           sendJson(res, 200, {
             basic: info.basic || {},
@@ -241,22 +363,64 @@ function createPoiDataBridge(options = {}) {
   }
 }
 
-function readRequestBody(req) {
+function readRequestBody(
+  req,
+  maxBytes = 1024 * 1024,
+  tooLargeMessage = 'MCP request body is too large.',
+) {
   return new Promise((resolve, reject) => {
     let body = ''
+    let bodyBytes = 0
+    let tooLarge = false
     req.setEncoding('utf8')
     req.on('data', (chunk) => {
+      if (tooLarge) return
+      bodyBytes += Buffer.byteLength(chunk)
+      if (bodyBytes > maxBytes) {
+        tooLarge = true
+        body = ''
+        return
+      }
       body += chunk
-      if (body.length > 1024 * 1024) {
-        reject(new Error('MCP request body is too large.'))
-        req.destroy()
+    })
+    req.on('end', () => {
+      if (tooLarge) {
+        const error = new Error(tooLargeMessage)
+        error.code = 'BODY_TOO_LARGE'
+        reject(error)
+      } else {
+        resolve(body)
       }
     })
-    req.on('end', () => resolve(body))
     req.on('error', reject)
   })
 }
 
+function requestContentLength(req) {
+  const value = req.headers['content-length']
+  if (value == null) return 0
+  const length = Number(value)
+  return Number.isSafeInteger(length) && length >= 0 ? length : Infinity
+}
+
+function drainRequest(req) {
+  req.resume()
+}
+
+function hasValidBearerToken(authorization, expectedToken) {
+  if (
+    typeof authorization !== 'string' ||
+    typeof expectedToken !== 'string' ||
+    !authorization.startsWith('Bearer ')
+  ) {
+    return false
+  }
+
+  const supplied = Buffer.from(authorization.slice('Bearer '.length), 'utf8')
+  const expected = Buffer.from(expectedToken, 'utf8')
+  return supplied.length === expected.length && crypto.timingSafeEqual(supplied, expected)
+}
+
 function handleMcpMessage(message, readStore, plannerFile) {
   const { id, method, params } = message || {}
 
@@ -565,13 +729,146 @@ function jsonRpcError(id, code, message) {
   return { jsonrpc: JSONRPC_VERSION, id, error: { code, message } }
 }
 
-function defaultGetStore() {
+function defaultGetStore(storePath) {
   if (typeof window !== 'undefined' && typeof window.getStore === 'function') {
-    return window.getStore()
+    return window.getStore(storePath)
   }
   return null
 }
 
+function extractProphetBattle(store) {
+  const battle = store &&
+    store.ext &&
+    store.ext['poi-plugin-prophet'] &&
+    store.ext['poi-plugin-prophet']._ &&
+    store.ext['poi-plugin-prophet']._.battle
+  if (!battle || typeof battle !== 'object') {
+    return {
+      available: false,
+      source: 'poi-plugin-prophet',
+      engine: 'poi-lib-battle',
+      engineVersion: '3.0.5',
+    }
+  }
+
+  const fleets = {
+    main: compactBattleFleet(battle.mainFleet),
+    escort: compactBattleFleet(battle.escortFleet),
+    enemy: compactBattleFleet(battle.enemyFleet),
+    enemyEscort: compactBattleFleet(battle.enemyEscort),
+  }
+  const result = compactBattleResult(battle.result)
+  return {
+    available: true,
+    source: 'poi-plugin-prophet',
+    engine: 'poi-lib-battle',
+    engineVersion: '3.0.5',
+    sortieState: finiteNumber(battle.sortieState, 0),
+    sortieStateName: sortieStateName(battle.sortieState),
+    mapAreaId: finiteNumber(battle.mapAreaId, 0),
+    eventId: finiteNumber(battle.eventId, 0),
+    eventKind: finiteNumber(battle.eventKind, 0),
+    airControl: stringValue(battle.airControl),
+    battleForm: stringValue(battle.battleForm),
+    enemyFormation: stringValue(battle.eFormation),
+    rank: typeof result.rank === 'string' ? result.rank : null,
+    mvpIndex0Based: compactMvp(result.mvp),
+    heavilyDamaged: findHeavilyDamaged(fleets),
+    fleets,
+  }
+}
+
+function combineBattleTelemetry(telemetry, predicted) {
+  const current = telemetry && typeof telemetry === 'object'
+    ? telemetry
+    : { available: false, generation: 0 }
+  return {
+    available: current.available === true || predicted.available === true,
+    generation: finiteNumber(current.generation, 0),
+    status: typeof current.status === 'string' ? current.status : 'unavailable',
+    observed: current.observed || null,
+    predicted,
+    official: current.official || null,
+  }
+}
+
+function compactBattleResult(result) {
+  if (!result || typeof result !== 'object') return {}
+  return Object.fromEntries(
+    ['rank', 'mvp', 'getShip', 'getItem']
+      .filter((key) => result[key] !== undefined)
+      .map((key) => [key, result[key]]),
+  )
+}
+
+function compactMvp(value) {
+  const values = Array.isArray(value) ? value : [value, null]
+  return {
+    main: Number.isInteger(values[0]) && values[0] >= 0 ? values[0] : null,
+    escort: Number.isInteger(values[1]) && values[1] >= 0 ? values[1] : null,
+  }
+}
+
+function findHeavilyDamaged(fleets) {
+  return ['main', 'escort'].flatMap((fleetName) =>
+    fleets[fleetName].flatMap((ship) => {
+      if (
+        !Number.isFinite(ship.currentHp) ||
+        !Number.isFinite(ship.maxHp) ||
+        ship.maxHp <= 0 ||
+        ship.currentHp > ship.maxHp * 0.25
+      ) {
+        return []
+      }
+      return [{
+        fleet: fleetName,
+        position: ship.position,
+        instanceId: ship.instanceId,
+        currentHp: ship.currentHp,
+        maxHp: ship.maxHp,
+      }]
+    }),
+  )
+}
+
+function compactBattleFleet(fleet) {
+  if (!Array.isArray(fleet)) return []
+  return fleet.flatMap((ship) => {
+    if (!ship || typeof ship !== 'object') return []
+    const raw = ship.raw && typeof ship.raw === 'object' ? ship.raw : {}
+    return [{
+      id: nullableNumber(ship.id),
+      owner: nullableNumber(ship.owner),
+      position: nullableNumber(ship.pos),
+      maxHp: nullableNumber(ship.maxHP),
+      initialHp: nullableNumber(ship.initHP),
+      currentHp: nullableNumber(ship.nowHP),
+      lostHp: nullableNumber(ship.lostHP),
+      damage: nullableNumber(ship.damage),
+      items: Array.isArray(ship.items) ? [...ship.items] : [],
+      useItem: ship.useItem == null ? null : ship.useItem,
+      instanceId: Number.isInteger(raw.api_id) ? raw.api_id : null,
+      masterId: Number.isInteger(raw.api_ship_id) ? raw.api_ship_id : null,
+    }]
+  })
+}
+
+function sortieStateName(value) {
+  return ['in_port', 'navigation', 'battle', 'practice'][value] || 'unknown'
+}
+
+function finiteNumber(value, fallback) {
+  return Number.isFinite(value) ? value : fallback
+}
+
+function nullableNumber(value) {
+  return Number.isFinite(value) ? value : null
+}
+
+function stringValue(value) {
+  return typeof value === 'string' ? value : ''
+}
+
 function cleanupPortFile(portFile) {
   try {
     fs.unlinkSync(portFile)
@@ -753,6 +1050,7 @@ module.exports = {
   DEFAULT_PORT,
   DEFAULT_PORT_FILE,
   DEFAULT_PLANNER_FILE,
+  INPUT_BODY_LIMIT,
   extractEventData,
   extractMasterData,
   extractPlannerData,

package/lib/poi-input.js

@@ -0,0 +1,205 @@
+const CANONICAL_WIDTH = 1200
+const CANONICAL_HEIGHT = 720
+const DEFAULT_CLICK_DELAY_MS = 10
+const MAX_TEXT_LENGTH = 256
+
+const SUPPORTED_BUTTONS = new Set(['left', 'middle', 'right'])
+const SUPPORTED_KEY_EVENTS = new Set(['keyDown', 'keyUp'])
+const SUPPORTED_KEYS = new Set([
+  'Backspace',
+  'Delete',
+  'End',
+  'Enter',
+  'Escape',
+  'Home',
+  'PageDown',
+  'PageUp',
+  'Space',
+  'Tab',
+  'ArrowDown',
+  'ArrowLeft',
+  'ArrowRight',
+  'ArrowUp',
+])
+
+function createPoiInputProvider(options = {}) {
+  const getStore = options.getStore || defaultGetStore
+  const resolveWebContents =
+    options.resolveWebContents || defaultResolveWebContents
+  const delay = options.delay || defaultDelay
+  const clickDelayMs = options.clickDelayMs == null
+    ? DEFAULT_CLICK_DELAY_MS
+    : options.clickDelayMs
+
+  if (
+    !Number.isInteger(clickDelayMs) ||
+    clickDelayMs < 1 ||
+    clickDelayMs > 100
+  ) {
+    throw new Error('clickDelayMs must be an integer from 1 to 100')
+  }
+
+  return async function performPoiInput(operation) {
+    validateOperationObject(operation)
+    const layout = readLayout(getStore, resolveWebContents)
+
+    switch (operation.operation) {
+      case 'click':
+        validateClick(operation)
+        await sendClick(layout, operation, delay, clickDelayMs)
+        return 'click'
+      case 'key':
+        validateKey(operation)
+        await layout.webContents.sendInputEvent({
+          type: operation.event,
+          keyCode: operation.key,
+        })
+        return 'key'
+      case 'text':
+        validateText(operation)
+        for (const character of operation.text) {
+          await layout.webContents.sendInputEvent({
+            type: 'char',
+            keyCode: character,
+          })
+        }
+        return 'text'
+      default:
+        throw new Error(`Unsupported input operation: ${String(operation.operation)}`)
+    }
+  }
+}
+
+function validateOperationObject(operation) {
+  if (
+    !operation ||
+    typeof operation !== 'object' ||
+    Array.isArray(operation)
+  ) {
+    throw new Error('Input must be one operation object')
+  }
+}
+
+function readLayout(getStore, resolveWebContents) {
+  const layout = getStore('layout.webview')
+  if (!layout || !layout.ref) {
+    throw new Error('Poi game WebView is not ready')
+  }
+  if (
+    !Number.isFinite(layout.width) ||
+    layout.width <= 0 ||
+    !Number.isFinite(layout.height) ||
+    layout.height <= 0
+  ) {
+    throw new Error('Poi game WebView dimensions must be positive finite numbers')
+  }
+  let webContents
+  if (typeof layout.ref.getWebContents === 'function') {
+    webContents = layout.ref.getWebContents()
+  } else if (typeof layout.ref.getWebContentsId === 'function') {
+    const webContentsId = layout.ref.getWebContentsId()
+    if (!Number.isInteger(webContentsId) || webContentsId <= 0) {
+      throw new Error('Poi game WebContents id is invalid')
+    }
+    webContents = resolveWebContents(webContentsId)
+  } else {
+    throw new Error('Poi game WebView is not ready')
+  }
+  if (!webContents || typeof webContents.sendInputEvent !== 'function') {
+    throw new Error('Poi game WebContents is not ready')
+  }
+  return { ...layout, webContents }
+}
+
+function validateClick(operation) {
+  assertExactFields(operation, ['operation', 'x', 'y', 'button'])
+  if (!Number.isFinite(operation.x) || !Number.isFinite(operation.y)) {
+    throw new Error('Click coordinates must be finite numbers')
+  }
+  if (
+    operation.x < 0 ||
+    operation.x >= CANONICAL_WIDTH ||
+    operation.y < 0 ||
+    operation.y >= CANONICAL_HEIGHT
+  ) {
+    throw new Error('Click coordinates must be within canonical bounds')
+  }
+  if (!SUPPORTED_BUTTONS.has(operation.button)) {
+    throw new Error(`Unsupported mouse button: ${String(operation.button)}`)
+  }
+}
+
+function validateKey(operation) {
+  assertExactFields(operation, ['operation', 'event', 'key'])
+  if (!SUPPORTED_KEY_EVENTS.has(operation.event)) {
+    throw new Error(`Unsupported key event: ${String(operation.event)}`)
+  }
+  if (!SUPPORTED_KEYS.has(operation.key)) {
+    throw new Error(`Unsupported key: ${String(operation.key)}`)
+  }
+}
+
+function validateText(operation) {
+  assertExactFields(operation, ['operation', 'text'])
+  if (
+    typeof operation.text !== 'string' ||
+    operation.text.length === 0 ||
+    operation.text.length > MAX_TEXT_LENGTH
+  ) {
+    throw new Error('Literal text must contain 1 to 256 characters')
+  }
+  if (/[\u0000-\u001f\u007f-\u009f]/u.test(operation.text)) {
+    throw new Error('Literal text must contain printable characters only')
+  }
+}
+
+function assertExactFields(operation, allowedFields) {
+  const allowed = new Set(allowedFields)
+  const unexpected = Object.keys(operation).find((field) => !allowed.has(field))
+  if (unexpected) {
+    throw new Error(`Unexpected field for ${operation.operation}: ${unexpected}`)
+  }
+  const missing = allowedFields.find((field) => !Object.hasOwn(operation, field))
+  if (missing) {
+    throw new Error(`Missing field for ${operation.operation}: ${missing}`)
+  }
+}
+
+async function sendClick(layout, operation, delay, clickDelayMs) {
+  const event = {
+    x: Math.floor((operation.x * layout.width) / CANONICAL_WIDTH),
+    y: Math.floor((operation.y * layout.height) / CANONICAL_HEIGHT),
+    button: operation.button,
+    clickCount: 1,
+  }
+
+  await layout.webContents.sendInputEvent({ type: 'mouseDown', ...event })
+  try {
+    await delay(clickDelayMs)
+  } finally {
+    await layout.webContents.sendInputEvent({ type: 'mouseUp', ...event })
+  }
+}
+
+function defaultDelay(milliseconds) {
+  return new Promise((resolve) => setTimeout(resolve, milliseconds))
+}
+
+function defaultGetStore(path) {
+  if (typeof window !== 'undefined' && typeof window.getStore === 'function') {
+    return window.getStore(path)
+  }
+  return null
+}
+
+function defaultResolveWebContents(webContentsId) {
+  const { webContents } = require('@electron/remote')
+  return webContents.fromId(webContentsId)
+}
+
+module.exports = {
+  CANONICAL_HEIGHT,
+  CANONICAL_WIDTH,
+  MAX_TEXT_LENGTH,
+  createPoiInputProvider,
+}

package/lib/poi-telemetry.js

@@ -0,0 +1,215 @@
+const QUEST_LIST_PATH = '/kcsapi/api_get_member/questlist'
+const QUEST_ACTION_PATHS = new Set([
+  '/kcsapi/api_req_quest/start',
+  '/kcsapi/api_req_quest/stop',
+])
+const BATTLE_RESULT_PATHS = new Set([
+  '/kcsapi/api_req_practice/battle_result',
+  '/kcsapi/api_req_sortie/battleresult',
+  '/kcsapi/api_req_combined_battle/battleresult',
+])
+const BATTLE_PATHS = new Set([
+  '/kcsapi/api_req_practice/battle',
+  '/kcsapi/api_req_practice/midnight_battle',
+  '/kcsapi/api_req_sortie/battle',
+  '/kcsapi/api_req_sortie/airbattle',
+  '/kcsapi/api_req_sortie/ld_airbattle',
+  '/kcsapi/api_req_sortie/ld_shooting',
+  '/kcsapi/api_req_battle_midnight/battle',
+  '/kcsapi/api_req_battle_midnight/sp_midnight',
+  '/kcsapi/api_req_combined_battle/battle',
+  '/kcsapi/api_req_combined_battle/battle_water',
+  '/kcsapi/api_req_combined_battle/airbattle',
+  '/kcsapi/api_req_combined_battle/ld_airbattle',
+  '/kcsapi/api_req_combined_battle/ld_shooting',
+  '/kcsapi/api_req_combined_battle/ec_battle',
+  '/kcsapi/api_req_combined_battle/each_battle',
+  '/kcsapi/api_req_combined_battle/each_battle_water',
+  '/kcsapi/api_req_combined_battle/midnight_battle',
+  '/kcsapi/api_req_combined_battle/sp_midnight',
+  '/kcsapi/api_req_combined_battle/ec_midnight_battle',
+  '/kcsapi/api_req_combined_battle/ec_night_to_day',
+])
+
+function createPoiTelemetry(options = {}) {
+  const now = options.now || (() => new Date())
+  let questGeneration = 0
+  let questList = null
+  let questActionGeneration = 0
+  let questAction = null
+  let battleGeneration = 0
+  let battleTelemetry = null
+
+  function handleGameResponse(event) {
+    const detail = event && event.detail
+    if (!detail || typeof detail.path !== 'string') return
+
+    if (detail.path === QUEST_LIST_PATH) {
+      captureQuestList(detail)
+      return
+    }
+    if (QUEST_ACTION_PATHS.has(detail.path)) {
+      captureQuestAction(detail)
+      return
+    }
+    if (BATTLE_RESULT_PATHS.has(detail.path)) {
+      captureBattleResult(detail)
+      return
+    }
+    if (BATTLE_PATHS.has(detail.path)) {
+      captureBattlePacket(detail)
+    }
+  }
+
+  function captureQuestList(detail) {
+    const body = detail.body
+    const postBody = detail.postBody
+    const tabId = toInteger(postBody && postBody.api_tab_id)
+    if (
+      !body ||
+      !Array.isArray(body.api_list) ||
+      tabId == null ||
+      tabId < 0 ||
+      tabId > 9
+    ) {
+      return
+    }
+
+    const quests = body.api_list.flatMap((quest, index) => {
+      if (!quest || typeof quest !== 'object' || !Number.isInteger(quest.api_no)) {
+        return []
+      }
+      return [{ ...quest, pageRow: index + 1 }]
+    })
+
+    questGeneration += 1
+    questList = {
+      available: true,
+      generation: questGeneration,
+      capturedAt: now().toISOString(),
+      tabId,
+      pageNo: nonNegativeInteger(body.api_disp_page),
+      pageCount: nonNegativeInteger(body.api_page_count),
+      count: nonNegativeInteger(body.api_count),
+      execCount: nonNegativeInteger(body.api_exec_count),
+      execType: nonNegativeInteger(body.api_exec_type),
+      quests,
+    }
+  }
+
+  function captureQuestAction(detail) {
+    const postBody = detail.postBody
+    const questId = toInteger(postBody && postBody.api_quest_id)
+    if (questId == null || questId <= 0) return
+
+    questActionGeneration += 1
+    questAction = {
+      available: true,
+      generation: questActionGeneration,
+      capturedAt: now().toISOString(),
+      path: detail.path,
+      questId,
+      flag: toInteger(postBody && postBody.api_quest_flag),
+    }
+  }
+
+  function captureBattlePacket(detail) {
+    if (!battleTelemetry || battleTelemetry.status === 'settled') {
+      battleGeneration += 1
+    }
+    battleTelemetry = {
+      available: true,
+      generation: battleGeneration,
+      status: 'in_progress',
+      observed: {
+        capturedAt: now().toISOString(),
+        path: detail.path,
+        time: finiteOrNull(detail.time),
+        phaseStartHp: {
+          friendlyMain: numberArray(detail.body && detail.body.api_f_nowhps),
+          friendlyEscort: numberArray(
+            detail.body && detail.body.api_f_nowhps_combined,
+          ),
+          enemyMain: numberArray(detail.body && detail.body.api_e_nowhps),
+          enemyEscort: numberArray(
+            detail.body && detail.body.api_e_nowhps_combined,
+          ),
+        },
+      },
+      official: null,
+    }
+  }
+
+  function captureBattleResult(detail) {
+    if (!battleTelemetry) battleGeneration += 1
+    const body = detail.body && typeof detail.body === 'object'
+      ? detail.body
+      : {}
+    battleTelemetry = {
+      available: true,
+      generation: battleGeneration,
+      status: 'settled',
+      observed: battleTelemetry ? battleTelemetry.observed : null,
+      official: {
+        capturedAt: now().toISOString(),
+        path: detail.path,
+        time: finiteOrNull(detail.time),
+        rank: typeof body.api_win_rank === 'string' ? body.api_win_rank : null,
+        mvpPosition: {
+          main: positiveIntegerOrNull(body.api_mvp),
+          escort: positiveIntegerOrNull(body.api_mvp_combined),
+        },
+        drop: {
+          ship: objectOrNull(body.api_get_ship),
+          useItem: objectOrNull(body.api_get_useitem),
+        },
+      },
+    }
+  }
+
+  return {
+    handleGameResponse,
+    getQuestList() {
+      return questList || { available: false, generation: 0 }
+    },
+    getQuestAction() {
+      return questAction || { available: false, generation: 0 }
+    },
+    getBattleTelemetry() {
+      return battleTelemetry || { available: false, generation: 0 }
+    },
+  }
+}
+
+function toInteger(value, fallback = null) {
+  if (value == null || value === '') return fallback
+  const parsed = Number(value)
+  return Number.isInteger(parsed) ? parsed : null
+}
+
+function nonNegativeInteger(value) {
+  const parsed = toInteger(value, 0)
+  return parsed != null && parsed >= 0 ? parsed : 0
+}
+
+function positiveIntegerOrNull(value) {
+  const parsed = toInteger(value)
+  return parsed != null && parsed > 0 ? parsed : null
+}
+
+function finiteOrNull(value) {
+  return Number.isFinite(value) ? value : null
+}
+
+function numberArray(value) {
+  if (!Array.isArray(value)) return []
+  return value.map((item) => finiteOrNull(item))
+}
+
+function objectOrNull(value) {
+  return value && typeof value === 'object' ? { ...value } : null
+}
+
+module.exports = {
+  createPoiTelemetry,
+}

package/lib/settings-view.js

@@ -54,9 +54,20 @@ function renderStatefulSettings(React, controller) {
     validPort,
     onPortChange: (event) => setPortText(event.target.value),
     onApply: () => run(
-      () => controller.applySettings({ port, enabled: status.enabled }),
+      () => controller.applySettings({
+        port,
+        enabled: status.enabled,
+        inputEnabled: status.inputEnabled,
+      }),
       'Port saved',
     ),
+    onInputToggle: (event) => {
+      const inputEnabled = event.target.checked
+      return run(
+        () => controller.applySettings({ inputEnabled }),
+        inputEnabled ? 'WebView input enabled' : 'WebView input disabled',
+      )
+    },
     onToggle: () => run(
       () => (status.running ? controller.stopBridge() : controller.startBridge()),
       status.running ? 'Stopped' : 'Started',
@@ -79,8 +90,17 @@ function renderStaticSettings(e, controller) {
     onApply: async () => {
       const input = typeof document !== 'undefined' ? document.getElementById('poi-mcp-port') : null
       const nextPort = input ? Number(input.value) : port
-      await controller.applySettings({ port: nextPort, enabled: status.enabled })
+      await controller.applySettings({
+        port: nextPort,
+        enabled: status.enabled,
+        inputEnabled: status.inputEnabled,
+      })
     },
+    onInputToggle: (event) => controller.applySettings({
+      port,
+      enabled: status.enabled,
+      inputEnabled: event.target.checked,
+    }),
     onToggle: () => (status.running ? controller.stopBridge() : controller.startBridge()),
   })
 }
@@ -121,6 +141,20 @@ function renderSettings(e, props) {
       }, props.status.running ? 'Stop' : 'Start'),
       e('span', { style: styles.status }, statusText),
     ),
+    e('div', { style: styles.row },
+      e('label', { style: styles.label, htmlFor: 'poi-mcp-input-enabled' }, 'WebView input'),
+      e('input', {
+        id: 'poi-mcp-input-enabled',
+        type: 'checkbox',
+        checked: props.onPortChange ? props.status.inputEnabled : undefined,
+        defaultChecked: props.onPortChange ? undefined : props.status.inputEnabled,
+        disabled: props.busy,
+        onChange: props.onInputToggle,
+      }),
+      e('span', { style: styles.status },
+        props.status.inputEnabled ? 'Enabled' : 'Disabled',
+      ),
+    ),
     e('div', { style: styles.note },
       'Pi extension defaults to 127.0.0.1:17777; keep this port unless you also update Pi.',
     ),

package/lib/settings.js

@@ -5,6 +5,7 @@ const path = require('path')
 const DEFAULT_SETTINGS = Object.freeze({
   port: 17777,
   enabled: true,
+  inputEnabled: false,
 })
 
 const DEFAULT_SETTINGS_FILE = path.join(os.homedir(), '.poi-mcp', 'settings.json')
@@ -14,6 +15,9 @@ function normalizeSettings(input = {}) {
   return {
     port: port == null ? DEFAULT_SETTINGS.port : port,
     enabled: typeof input.enabled === 'boolean' ? input.enabled : DEFAULT_SETTINGS.enabled,
+    inputEnabled: typeof input.inputEnabled === 'boolean'
+      ? input.inputEnabled
+      : DEFAULT_SETTINGS.inputEnabled,
   }
 }
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "poi-plugin-mcp",
-  "version": "0.2.3",
-  "description": "Poi read-only data and game WebView capture bridge for local KanColle tools.",
+  "version": "0.2.9",
+  "description": "Poi data, WebView capture, and opt-in authenticated input bridge for local KanColle tools.",
   "main": "index.js",
   "keywords": [
     "poi-plugin",
@@ -24,7 +24,7 @@
   "poiPlugin": {
     "title": "MCP 数据桥",
     "id": "mcp_data_bridge",
-    "description": "Expose Poi state and in-memory game WebView captures on a local read-only bridge.",
+    "description": "Expose Poi state, in-memory game WebView captures, and opt-in authenticated input on a local bridge.",
     "icon": "fa/database",
     "priority": 53
   },