# ppclock-mcp Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** 把 ppclock SDK 包装成单层部署的 MCP 服务器（stdio + streamable HTTP 双模），供各 agent 平台调用，Windows 蓝牙服务器先行实测。

**Architecture:** 新增三个模块（`device_manager.py` 连接管理 / `mcp_tools.py` 工具层 / `mcp_server.py` 装配入口），作为 SDK 的纯消费者；连接管理用方案 C（按需连接 + 空闲超时保持 + 全局串行锁 + 掉线重连重试一次）。

**Tech Stack:** Python ≥3.10、官方 `mcp` 包（FastMCP）、bleak（Windows=WinRT / Linux=BlueZ）、pytest + pytest-asyncio。

**Spec:** `docs/superpowers/specs/2026-07-30-ppclock-mcp-design.md`

## Global Constraints

- **SDK 零改动**：不改 `client.py`/`commands.py`/`protocol.py`/`image_pipeline.py`/`transports/*` 任何一行。
- `mcp>=1.10` 只能进 optional extra，基础 SDK 依赖（bleak、pillow）不变。
- 输出契约：成功 `{"ok": true, "tool": <name>, "data": {...}}`；失败 `{"ok": false, "tool": <name>, "error": {"code","message","hint"?}}`。
- 错误码仅：`INVALID_PARAM` / `DEVICE_NOT_FOUND` / `CONNECT_TIMEOUT` / `BLE_ERROR` / `DEVICE_DISCONNECTED` / `INTERNAL`。
- HTTP 默认 `--host 127.0.0.1 --port 8972`；绑非回环地址必须设环境变量 `PPCLOCK_MCP_TOKEN`。
- 代码注释/docstring 用中文，风格对齐现有源码；commit 前缀用 `feat:`/`test:`/`docs:`。
- 测试用 `@pytest.mark.asyncio`（对齐 tests/ 现有模式），FakeTransport 模式复用 tests/test_client.py。
- 全部测试命令用 `.venv/bin/python -m pytest tests/ -q`（仓库根目录）。

---

### Task 1: DeviceManager（连接管理器）

**Files:**
- Create: `src/ppclock/device_manager.py`
- Test: `tests/test_device_manager.py`

**Interfaces:**
- Consumes: `ppclock.client.PPClient`、`ppclock.transports.base.TransportError`
- Produces:
  - `DeviceManager(mac: str|None=None, connect_timeout: float=90.0, idle_timeout: float=300.0, client_factory: Callable[[str|None, float], PPClient]|None=None)`
  - `async manager.run(op) -> Any` — `op` 是 `async (PPClient) -> Any`；串行执行，掉线自动重连重试一次
  - `async manager.status() -> dict` — `{connected, mac, idle_seconds, connect_count, connect_timeout, idle_timeout, device_id?}`
  - `async manager.close() -> None`
  - `manager.connected: bool`（property）
- 下游（Task 2/3）只依赖以上名字与签名。

- [ ] **Step 1: 写失败测试**

```python
"""DeviceManager 测试：按需连接/串行/空闲超时/掉线重连。"""
import asyncio

import pytest

from ppclock.client import PPClient
from ppclock.device_manager import DeviceManager
from ppclock.transports.base import TransportError


class FakeTransport:
    def __init__(self):
        self.address = "AA:BB:CC:DD:EE:FF"
        self.enters = 0
        self.exits = 0
        self.rxtx_writes = []
        self.fail_next_write = False

    async def __aenter__(self):
        self.enters += 1
        return self

    async def __aexit__(self, *exc):
        self.exits += 1
        return False

    async def write_epd(self, data, response=True):
        pass

    async def write_rxtx(self, data, response=True):
        if self.fail_next_write:
            self.fail_next_write = False
            raise TransportError("connection lost")
        self.rxtx_writes.append(data)

    async def read_rxtx(self):
        return b"\x00"

    async def request_device_id(self, timeout=8.0):
        return "81233F3C267112"

    async def run_ota(self, image, on_progress=None):
        return {}

    async def delay(self, seconds):
        pass


def make_manager(transports, **kw):
    """client_factory 依次弹出预置 transport 包成 PPClient。"""
    def factory(mac, timeout):
        return PPClient(transports.pop(0))
    kw.setdefault("client_factory", factory)
    return DeviceManager(**kw)


class TestConnect:
    @pytest.mark.asyncio
    async def test_connect_on_demand_and_reuse(self):
        t = FakeTransport()
        m = make_manager([t])
        assert not m.connected
        await m.run(lambda dev: dev.set_mode("clock1"))
        await m.run(lambda dev: dev.set_mode("clock2"))
        assert t.enters == 1  # 第二次复用连接
        assert m.connected
        await m.close()

    @pytest.mark.asyncio
    async def test_remembers_address(self):
        t = FakeTransport()
        m = make_manager([t], mac=None)
        await m.run(lambda dev: dev.set_mode("clock1"))
        assert (await m.status())["mac"] == "AA:BB:CC:DD:EE:FF"
        await m.close()


class TestSerialization:
    @pytest.mark.asyncio
    async def test_ops_are_serialized(self):
        t = FakeTransport()
        m = make_manager([t])
        concurrent = 0
        peak = 0

        async def op(dev):
            nonlocal concurrent, peak
            concurrent += 1
            peak = max(peak, concurrent)
            await asyncio.sleep(0.02)
            concurrent -= 1
            return 1

        await asyncio.gather(*(m.run(op) for _ in range(5)))
        assert peak == 1
        await m.close()


class TestIdleTimeout:
    @pytest.mark.asyncio
    async def test_idle_disconnect(self):
        t = FakeTransport()
        m = make_manager([t], idle_timeout=0.05)
        await m.run(lambda dev: dev.set_mode("clock1"))
        assert m.connected
        await asyncio.sleep(0.15)
        assert not m.connected
        assert t.exits == 1

    @pytest.mark.asyncio
    async def test_activity_resets_idle(self):
        t = FakeTransport()
        m = make_manager([t], idle_timeout=0.1)
        await m.run(lambda dev: dev.set_mode("clock1"))
        await asyncio.sleep(0.06)
        await m.run(lambda dev: dev.set_mode("clock2"))
        await asyncio.sleep(0.06)
        assert m.connected  # 第二次活动续期
        await m.close()


class TestReconnect:
    @pytest.mark.asyncio
    async def test_reconnect_once_on_transport_error(self):
        t1, t2 = FakeTransport(), FakeTransport()
        t1.fail_next_write = True
        m = make_manager([t1, t2])
        await m.run(lambda dev: dev.set_mode("clock1"))
        assert t1.enters == 1 and t2.enters == 1  # 掉线重连一次并成功
        await m.close()

    @pytest.mark.asyncio
    async def test_retry_exhaustion_raises(self):
        t1, t2 = FakeTransport(), FakeTransport()
        t1.fail_next_write = True
        t2.fail_next_write = True
        m = make_manager([t1, t2])
        with pytest.raises(TransportError):
            await m.run(lambda dev: dev.set_mode("clock1"))
        await m.close()


class TestStatus:
    @pytest.mark.asyncio
    async def test_status_fields(self):
        t = FakeTransport()
        m = make_manager([t], connect_timeout=90.0, idle_timeout=300.0)
        s = await m.status()
        assert s["connected"] is True  # status 自身触发连接
        assert s["device_id"] == "81233F3C267112"
        assert s["connect_timeout"] == 90.0
        assert s["idle_timeout"] == 300.0
        assert isinstance(s["idle_seconds"], float)
        await m.close()
```

注：`status()` 在设备 ID 读取上复用已建立连接；实现上 status 在连接时顺手 `get_device_id()`。`test_status_fields` 假定 status 会确保连接（见实现）。

- [ ] **Step 2: 跑测试确认失败**

Run: `.venv/bin/python -m pytest tests/test_device_manager.py -q`
Expected: FAIL（`ModuleNotFoundError: No module named 'ppclock.device_manager'`）

- [ ] **Step 3: 实现 device_manager.py**

```python
"""设备连接管理器（方案 C：按需连接 + 空闲保持，全操作串行）。

- 一把 asyncio.Lock 串行所有设备操作（BLE 适配器独占）
- 首次操作守候连接（connect_timeout 应覆盖设备 30-60s 广播窗口）
- 操作后保持连接；空闲 idle_timeout 秒自动断开让设备睡眠
- 操作中 TransportError（连接丢失）→ 重连并重试一次，再失败向上抛
"""
from __future__ import annotations

import asyncio
import time

from .client import PPClient
from .transports.base import TransportError


class DeviceManager:
    def __init__(self, mac: str | None = None, connect_timeout: float = 90.0,
                 idle_timeout: float = 300.0, client_factory=None):
        self._mac = mac
        self._connect_timeout = connect_timeout
        self._idle_timeout = idle_timeout
        self._factory = client_factory or (
            lambda mac, timeout: PPClient.via_local(mac=mac, timeout=timeout))
        self._client = None
        self._lock = asyncio.Lock()
        self._last_activity: float | None = None
        self._idle_task: asyncio.Task | None = None
        self._connect_count = 0

    @property
    def connected(self) -> bool:
        return self._client is not None

    async def run(self, op):
        """串行执行 op(client)；掉线重连重试一次。"""
        async with self._lock:
            try:
                return await self._run_with_retry(op)
            finally:
                self._touch()

    async def status(self) -> dict:
        async with self._lock:
            await self._ensure_connected()
            self._touch()
            info = {
                "connected": self.connected,
                "mac": self._mac,
                "idle_seconds": None if self._last_activity is None
                else round(time.monotonic() - self._last_activity, 1),
                "connect_count": self._connect_count,
                "connect_timeout": self._connect_timeout,
                "idle_timeout": self._idle_timeout,
            }
            try:
                info["device_id"] = await self._client.get_device_id()
            except Exception:  # noqa: BLE001 - 状态查询尽力而为
                pass
            return info

    async def close(self) -> None:
        if self._idle_task is not None:
            self._idle_task.cancel()
        async with self._lock:
            await self._drop()

    # ---------- 内部 ----------

    async def _run_with_retry(self, op):
        await self._ensure_connected()
        try:
            return await op(self._client)
        except TransportError:
            await self._drop()
            await self._ensure_connected()
            return await op(self._client)

    async def _ensure_connected(self):
        if self._client is not None:
            return
        client = self._factory(self._mac, self._connect_timeout)
        await client.__aenter__()
        self._client = client
        self._connect_count += 1
        if self._mac is None:  # 自动扫描后记住实际地址
            self._mac = getattr(client._t, "address", None)

    async def _drop(self):
        client, self._client = self._client, None
        if client is not None:
            try:
                await client.__aexit__(None, None, None)
            except Exception:  # noqa: BLE001 - 断开失败不影响状态
                pass

    def _touch(self):
        self._last_activity = time.monotonic()
        if self._idle_task is not None:
            self._idle_task.cancel()
            self._idle_task = None
        if self.connected:
            self._idle_task = asyncio.create_task(self._idle_watch())

    async def _idle_watch(self):
        try:
            await asyncio.sleep(self._idle_timeout)
            async with self._lock:
                if (self._last_activity is not None
                        and time.monotonic() - self._last_activity >= self._idle_timeout):
                    await self._drop()
        except asyncio.CancelledError:
            pass
```

注：`client._t` 是同包内访问 PPClient 持有的传输层（Transport 协议公开 `address` 属性），SDK 无公开访问器，此处为有意为之的包内约定。

- [ ] **Step 4: 跑测试确认通过**

Run: `.venv/bin/python -m pytest tests/test_device_manager.py -q`
Expected: 9 passed

- [ ] **Step 5: 回归 + 提交**

Run: `.venv/bin/python -m pytest tests/ -q`
Expected: 165 + 9 全绿

```bash
git add src/ppclock/device_manager.py tests/test_device_manager.py
git commit -m "feat(mcp): DeviceManager——按需连接+空闲保持+串行锁+掉线重连（方案 C）"
```

---

### Task 2: mcp_tools（工具层：图源解码 + 错误契约 + 13 工具）

**Files:**
- Create: `src/ppclock/mcp_tools.py`
- Test: `tests/test_mcp_tools.py`

**Interfaces:**
- Consumes: Task 1 的 `DeviceManager.run(op)` / `DeviceManager.status()`；SDK `PPClient` 全部高层方法
- Produces:
  - `decode_image_source(source: str) -> PIL.Image.Image` — 路径或 base64（可带 `data:*;base64,` 前缀）；非法输入抛 `ValueError`
  - `register_tools(mcp, manager) -> None` — 把 13 个工具注册到 FastMCP 实例
  - 工具名（Task 3 与文档依赖，逐字）：`scan_devices / device_status / set_time / set_mode / toggle / upload_image / render_template / countdown / countdown_off / calendar_text / set_sleep / clear_screen / raw_send`

- [ ] **Step 1: 写失败测试**

```python
"""mcp_tools 测试：图源解码 + 工具契约（内存 MCP 会话端到端）。"""
import base64
import io
import json

import pytest
from mcp.server.fastmcp import FastMCP
from mcp.shared.memory import create_connected_server_and_client_session
from PIL import Image

from ppclock.client import PPClient
from ppclock.mcp_tools import decode_image_source, register_tools
from ppclock.transports.base import TransportError


class FakeTransport:
    def __init__(self):
        self.address = "AA:BB:CC:DD:EE:FF"
        self.epd_writes = []
        self.rxtx_writes = []

    async def __aenter__(self):
        return self

    async def __aexit__(self, *exc):
        return False

    async def write_epd(self, data, response=True):
        self.epd_writes.append(data)

    async def write_rxtx(self, data, response=True):
        self.rxtx_writes.append(data)

    async def read_rxtx(self):
        return b"\x00"

    async def request_device_id(self, timeout=8.0):
        return "81233F3C267112"

    async def run_ota(self, image, on_progress=None):
        return {}

    async def delay(self, seconds):
        pass


class FakeManager:
    """模拟 DeviceManager：直接对 fake client 执行 op，或抛预置错误。"""

    def __init__(self, error=None):
        self.client = PPClient(FakeTransport())
        self.error = error
        self.ops = 0

    async def run(self, op):
        self.ops += 1
        if self.error is not None:
            raise self.error
        return await op(self.client)

    async def status(self):
        return {"connected": True, "mac": "AA:BB:CC:DD:EE:FF",
                "idle_seconds": 0.0, "connect_count": 1,
                "connect_timeout": 90.0, "idle_timeout": 300.0,
                "device_id": "81233F3C267112"}


def make_session_coro(manager):
    mcp = FastMCP("ppclock-test")
    register_tools(mcp, manager)
    return mcp


async def call(mcp, tool, args=None):
    async with create_connected_server_and_client_session(mcp._mcp_server) as s:
        result = await s.call_tool(tool, args or {})
        assert not result.isError, result.content
        return json.loads(result.content[0].text)


def png_b64() -> str:
    buf = io.BytesIO()
    Image.new("RGB", (400, 300), "white").save(buf, "PNG")
    return base64.b64encode(buf.getvalue()).decode()


class TestDecodeImageSource:
    def test_path(self, tmp_path):
        p = tmp_path / "a.png"
        Image.new("RGB", (10, 10)).save(p)
        assert decode_image_source(str(p)).size == (10, 10)

    def test_base64(self):
        assert decode_image_source(png_b64()).size == (400, 300)

    def test_data_uri(self):
        src = "data:image/png;base64," + png_b64()
        assert decode_image_source(src).size == (400, 300)

    def test_garbage(self):
        with pytest.raises(ValueError):
            decode_image_source("!!!not-base64!!!")


class TestTools:
    @pytest.mark.asyncio
    async def test_set_time_ok(self):
        r = await call(make_session_coro(FakeManager()), "set_time", {"tz": 8.0})
        assert r["ok"] is True and r["tool"] == "set_time"

    @pytest.mark.asyncio
    async def test_upload_image_base64(self):
        r = await call(make_session_coro(FakeManager()), "upload_image",
                       {"source": png_b64(), "slot": 0})
        assert r["ok"] is True
        assert r["data"]["bytes_bw"] == 15000
        assert r["data"]["slot"] == 0

    @pytest.mark.asyncio
    async def test_set_mode_invalid_param(self):
        r = await call(make_session_coro(FakeManager()), "set_mode",
                       {"mode": "nonsense"})
        assert r["ok"] is False
        assert r["error"]["code"] == "INVALID_PARAM"

    @pytest.mark.asyncio
    async def test_transport_error_mapped(self):
        m = FakeManager(error=TransportError("Connection timed out"))
        r = await call(make_session_coro(m), "set_time", {})
        assert r["ok"] is False
        assert r["error"]["code"] == "CONNECT_TIMEOUT"
        assert "hint" in r["error"]

    @pytest.mark.asyncio
    async def test_device_status(self):
        r = await call(make_session_coro(FakeManager()), "device_status", {})
        assert r["ok"] is True
        assert r["data"]["device_id"] == "81233F3C267112"

    @pytest.mark.asyncio
    async def test_raw_send(self):
        r = await call(make_session_coro(FakeManager()), "raw_send",
                       {"data_hex": "e201", "channel": "alt"})
        assert r["ok"] is True

    @pytest.mark.asyncio
    async def test_raw_send_bad_hex(self):
        r = await call(make_session_coro(FakeManager()), "raw_send",
                       {"data_hex": "zz", "channel": "alt"})
        assert r["ok"] is False
        assert r["error"]["code"] == "INVALID_PARAM"

    @pytest.mark.asyncio
    async def test_render_template(self):
        r = await call(make_session_coro(FakeManager()), "render_template",
                       {"name": "custom", "payload": {"text": "你好"}, "slot": 0})
        assert r["ok"] is True
        assert r["data"]["template"] == "custom"

    @pytest.mark.asyncio
    async def test_countdown(self):
        r = await call(make_session_coro(FakeManager()), "countdown",
                       {"date": "2026-12-31", "mode": "clock", "prefix": "目标"})
        assert r["ok"] is True

    @pytest.mark.asyncio
    async def test_scan_devices(self, monkeypatch):
        async def fake_scan(uri="local", timeout=5.0):
            return [{"name": "NRF-5DBF28", "address": "18:BC:5A:5D:BF:28",
                     "rssi": -60}]
        monkeypatch.setattr(PPClient, "scan_devices", staticmethod(fake_scan))
        r = await call(make_session_coro(FakeManager()), "scan_devices", {})
        assert r["ok"] is True
        assert r["data"]["devices"][0]["address"] == "18:BC:5A:5D:BF:28"
```

- [ ] **Step 2: 装依赖 + 跑测试确认失败**

Run: `.venv/bin/pip install "mcp>=1.10" -q && .venv/bin/python -m pytest tests/test_mcp_tools.py -q`
Expected: FAIL（`ModuleNotFoundError: No module named 'ppclock.mcp_tools'`）

- [ ] **Step 3: 实现 mcp_tools.py**

```python
"""MCP 工具层：13 个高层工具，统一输出契约（与 CLI --json 同构）。

成功 {"ok": true, "tool": name, "data": {...}}
失败 {"ok": false, "tool": name, "error": {"code", "message", "hint"?}}
"""
from __future__ import annotations

import base64
import binascii
import datetime
import io
import os

from PIL import Image

from .client import PPClient
from .transports.base import TransportError

_TIMEOUT_HINT = "设备长睡眠、广播窗口 30-60s；调大 --connect-timeout 或稍后重试"
_NOTFOUND_HINT = "未发现 NRF- 前缀设备；确认设备在位且未处于深睡"


def decode_image_source(source: str) -> Image.Image:
    """source = 服务器本地路径，或 base64（可带 data URI 前缀）。"""
    if os.path.exists(source):
        return Image.open(source)
    data = source
    if data.startswith("data:"):
        if "," not in data:
            raise ValueError("data URI 缺少 ',' 分隔")
        data = data.split(",", 1)[1]
    try:
        raw = base64.b64decode(data, validate=True)
    except (binascii.Error, ValueError):
        raise ValueError("source 既不是存在的文件路径，也不是合法 base64") from None
    return Image.open(io.BytesIO(raw))


def _err(tool: str, code: str, message: str, hint: str | None = None) -> dict:
    error = {"code": code, "message": message}
    if hint:
        error["hint"] = hint
    return {"ok": False, "tool": tool, "error": error}


def _map_transport_error(tool: str, exc: TransportError) -> dict:
    msg = str(exc)
    low = msg.lower()
    if "timeout" in low or "timed out" in low:
        return _err(tool, "CONNECT_TIMEOUT", msg, _TIMEOUT_HINT)
    if "not found" in low or "no device" in low:
        return _err(tool, "DEVICE_NOT_FOUND", msg, _NOTFOUND_HINT)
    return _err(tool, "BLE_ERROR", msg)


def register_tools(mcp, manager) -> None:
    """把 13 个工具注册到 FastMCP 实例；manager 为 DeviceManager（测试可注入 fake）。"""

    async def _call(tool: str, op) -> dict:
        try:
            data = await manager.run(op)
            return {"ok": True, "tool": tool, "data": data if data is not None else {}}
        except TransportError as exc:
            return _map_transport_error(tool, exc)
        except ValueError as exc:
            return _err(tool, "INVALID_PARAM", str(exc))
        except Exception as exc:  # noqa: BLE001 - 工具层兜底，错误须回 agent 而非炸会话
            return _err(tool, "INTERNAL", f"{type(exc).__name__}: {exc}")

    @mcp.tool()
    async def scan_devices(timeout: float = 5.0) -> dict:
        """扫描附近 NRF- 前缀墨水屏设备，返回 [{name,address,rssi}]。"""
        try:
            devices = await PPClient.scan_devices("local", timeout=timeout)
            return {"ok": True, "tool": "scan_devices", "data": {"devices": devices}}
        except TransportError as exc:
            return _map_transport_error("scan_devices", exc)
        except Exception as exc:  # noqa: BLE001
            return _err("scan_devices", "INTERNAL", f"{type(exc).__name__}: {exc}")

    @mcp.tool()
    async def device_status() -> dict:
        """查询连接状态/绑定 MAC/设备 ID/空闲秒数。"""
        try:
            return {"ok": True, "tool": "device_status", "data": await manager.status()}
        except Exception as exc:  # noqa: BLE001
            return _err("device_status", "INTERNAL", f"{type(exc).__name__}: {exc}")

    @mcp.tool()
    async def set_time(tz: float = 8.0) -> dict:
        """对时；tz 为时区偏移（默认 8=北京时间）。"""
        return await _call("set_time", lambda dev: dev.set_time(tz=tz))

    @mcp.tool()
    async def set_mode(mode: str) -> dict:
        """切换显示模式：clock1-3/calendar1-3/image0-3/tricolor/mono。"""
        return await _call("set_mode", lambda dev: dev.set_mode(mode))

    @mcp.tool()
    async def toggle(name: str) -> dict:
        """单字节切换：invert/font/rotate180/hour_format/clock_color。"""
        return await _call("toggle", lambda dev: dev.toggle(name))

    @mcp.tool()
    async def upload_image(source: str, slot: int = 0, algo: str = "atkinson",
                           mono: bool = False,
                           threshold: float | None = None,
                           diffusion: float | None = None,
                           brightness: float | None = None,
                           contrast: float | None = None,
                           saturation: float | None = None,
                           rotate: float | None = None) -> dict:
        """传图到指定槽位。source=服务器路径或 base64；algo∈
        none/floydsteinberg/atkinson/bayer/stucki/jarvis。"""
        adjust = {k: v for k, v in {
            "threshold": threshold, "diffusion": diffusion,
            "brightness": brightness, "contrast": contrast,
            "saturation": saturation, "rotate": rotate}.items() if v is not None}
        img = decode_image_source(source)
        return await _call("upload_image", lambda dev: dev.upload_image(
            img, slot=slot, algo=algo, mono=mono, **adjust))

    @mcp.tool()
    async def render_template(name: str, payload: dict | None = None,
                              slot: int = 0, algo: str = "atkinson") -> dict:
        """本地渲染模板并上传：schedule/businesscard/memo/course/qrcode/custom。"""
        return await _call("render_template", lambda dev: dev.render_template(
            name, payload, slot=slot, algo=algo))

    @mcp.tool()
    async def countdown(date: str, mode: str = "clock",
                        prefix: str | None = None) -> dict:
        """倒计时；date 为 ISO YYYY-MM-DD；mode=clock/calendar。"""
        d = datetime.date.fromisoformat(date)
        return await _call("countdown", lambda dev: dev.countdown(
            d, mode=mode, prefix=prefix))

    @mcp.tool()
    async def countdown_off() -> dict:
        """关闭倒计时。"""
        return await _call("countdown_off", lambda dev: dev.countdown_off())

    @mcp.tool()
    async def calendar_text(text: str) -> dict:
        """设置日历中文文字并切到日历模式一。"""
        return await _call("calendar_text", lambda dev: dev.calendar_text(text))

    @mcp.tool()
    async def set_sleep(on: bool, start_h: int, end_h: int) -> dict:
        """设置休眠时段（0-23 时）。"""
        return await _call("set_sleep", lambda dev: dev.sleep(on, start_h, end_h))

    @mcp.tool()
    async def clear_screen() -> dict:
        """刷屏（EPD 清屏）。"""
        return await _call("clear_screen", lambda dev: dev.clear())

    @mcp.tool()
    async def raw_send(data_hex: str, channel: str = "alt") -> dict:
        """逃生舱：直发十六进制字节串；channel=rxtx/epd/alt。"""
        data = bytes.fromhex(data_hex)
        return await _call("raw_send", lambda dev: dev.raw(data, channel))
```

注：`upload_image`/`countdown`/`raw_send` 在进入 `_call` 前的本地解析（decode/fromisoformat/fromhex）抛 `ValueError`——需被工具级兜底捕获。处理方式：这些工具体外不包 try 的话异常会炸 MCP 会话。把 `_call` 的 try 改为包住整个 lambda 构造不可行（解析发生在 `_call` 之外）。**实现时**把这三个工具改为：

```python
    @mcp.tool()
    async def upload_image(source: str, slot: int = 0, algo: str = "atkinson",
                           mono: bool = False, **kw) -> dict:
        """..."""
        try:
            adjust = {k: v for k, v in kw.items() if v is not None}
            img = decode_image_source(source)
        except ValueError as exc:
            return _err("upload_image", "INVALID_PARAM", str(exc))
        return await _call("upload_image", lambda dev: dev.upload_image(
            img, slot=slot, algo=algo, mono=mono, **adjust))
```

`countdown`/`raw_send` 同理包 try（fromisoformat/fromhex 的 ValueError → INVALID_PARAM）。其余工具参数无需预解析，直接 `_call`。

⚠ `upload_image` 用 `**kw` 收 adjust 参数时，FastMCP 会从签名生成 schema——`**kw` 不进 schema。为保持 schema 显式，**保留显式参数签名**（threshold/diffusion/brightness/contrast/saturation/rotate 六个 `float | None = None`），仅把解析段包 try。以显式签名为准。

- [ ] **Step 4: 跑测试确认通过**

Run: `.venv/bin/python -m pytest tests/test_mcp_tools.py -q`
Expected: 14 passed

- [ ] **Step 5: 回归 + 提交**

Run: `.venv/bin/python -m pytest tests/ -q`
Expected: 全绿

```bash
git add src/ppclock/mcp_tools.py tests/test_mcp_tools.py
git commit -m "feat(mcp): 13 个高层 MCP 工具 + 图源解码 + 统一输出契约"
```

---

### Task 3: mcp_server（装配入口 + HTTP token 鉴权 + 打包）

**Files:**
- Create: `src/ppclock/mcp_server.py`
- Modify: `pyproject.toml`（extra + entry point）
- Test: `tests/test_mcp_server.py`

**Interfaces:**
- Consumes: Task 1 `DeviceManager`、Task 2 `register_tools`
- Produces:
  - `build_server(manager) -> FastMCP`
  - `parse_args(argv=None) -> argparse.Namespace`（字段：`transport/host/port/mac/connect_timeout/idle_timeout`）
  - `TokenAuthMiddleware(app, token)`（ASGI）
  - `main(argv=None) -> None`（`ppclock-mcp` 入口）
  - `TOKEN_ENV = "PPCLOCK_MCP_TOKEN"`

- [ ] **Step 1: 写失败测试**

```python
"""mcp_server 测试：参数解析 + 非回环强制 token + ASGI 鉴权中间件。"""
import asyncio

import pytest

from ppclock.mcp_server import (TOKEN_ENV, TokenAuthMiddleware,
                                parse_args)


class TestParseArgs:
    def test_defaults(self):
        a = parse_args([])
        assert a.transport == "stdio"
        assert a.host == "127.0.0.1"
        assert a.port == 8972
        assert a.mac is None
        assert a.connect_timeout == 90.0
        assert a.idle_timeout == 300.0

    def test_http_flags(self):
        a = parse_args(["--transport", "http", "--host", "0.0.0.0",
                        "--port", "9000", "--mac", "AA:BB:CC:DD:EE:FF",
                        "--connect-timeout", "120", "--idle-timeout", "60"])
        assert a.transport == "http" and a.host == "0.0.0.0"
        assert a.port == 9000 and a.mac == "AA:BB:CC:DD:EE:FF"
        assert a.connect_timeout == 120.0 and a.idle_timeout == 60.0


def run_middleware(token_set, auth_header):
    """驱动 TokenAuthMiddleware，返回 (status, app_called)。"""
    captured = {}

    async def app(scope, receive, send):
        captured["called"] = True
        await send({"type": "http.response.start", "status": 200, "headers": []})
        await send({"type": "http.response.body", "body": b"ok"})

    sent = []

    async def send(msg):
        sent.append(msg)

    headers = []
    if auth_header is not None:
        headers.append((b"authorization", auth_header.encode()))
    scope = {"type": "http", "headers": headers}
    mw = TokenAuthMiddleware(app, token_set)
    asyncio.run(mw(scope, None, send))
    status = next(m["status"] for m in sent if m["type"] == "http.response.start")
    return status, captured.get("called", False)


class TestTokenAuth:
    def test_no_header_401(self):
        status, called = run_middleware("secret", None)
        assert status == 401 and called is False

    def test_wrong_token_401(self):
        status, called = run_middleware("secret", "Bearer nope")
        assert status == 401 and called is False

    def test_right_token_passes(self):
        status, called = run_middleware("secret", "Bearer secret")
        assert status == 200 and called is True


class TestBindGuard:
    def test_non_loopback_requires_token(self, monkeypatch):
        from ppclock.mcp_server import main
        monkeypatch.delenv(TOKEN_ENV, raising=False)
        with pytest.raises(SystemExit):
            main(["--transport", "http", "--host", "0.0.0.0"])
```

- [ ] **Step 2: 跑测试确认失败**

Run: `.venv/bin/python -m pytest tests/test_mcp_server.py -q`
Expected: FAIL（`ModuleNotFoundError: No module named 'ppclock.mcp_server'`）

- [ ] **Step 3: 实现 mcp_server.py + pyproject 打包**

```python
"""ppclock-mcp —— MCP 服务器入口（stdio / streamable HTTP 双模）。

stdio：本机 agent 直挂（Claude Code/Desktop 等）。
http ：局域网 agent 平台远程调用；绑非回环地址必须设 PPCLOCK_MCP_TOKEN。
"""
from __future__ import annotations

import argparse
import asyncio
import os

from mcp.server.fastmcp import FastMCP

from .device_manager import DeviceManager
from .mcp_tools import register_tools

TOKEN_ENV = "PPCLOCK_MCP_TOKEN"


def build_server(manager: DeviceManager) -> FastMCP:
    mcp = FastMCP("ppclock", stateless_http=True)
    register_tools(mcp, manager)
    return mcp


def parse_args(argv=None) -> argparse.Namespace:
    p = argparse.ArgumentParser(prog="ppclock-mcp",
                                description="ppclock 墨水屏 MCP 服务器")
    p.add_argument("--transport", choices=["stdio", "http"], default="stdio")
    p.add_argument("--host", default="127.0.0.1")
    p.add_argument("--port", type=int, default=8972)
    p.add_argument("--mac", default=None, help="设备 MAC；缺省自动扫描 NRF- 前缀")
    p.add_argument("--connect-timeout", type=float, default=90.0,
                   help="守候连接秒数（覆盖设备 30-60s 广播窗口）")
    p.add_argument("--idle-timeout", type=float, default=300.0,
                   help="空闲断开秒数；0=每次调用独立连接")
    return p.parse_args(argv)


class TokenAuthMiddleware:
    """纯 ASGI 中间件：校验 Authorization: Bearer <token>，不符 401。"""

    def __init__(self, app, token: str):
        self.app = app
        self.token = token

    async def __call__(self, scope, receive, send):
        if scope["type"] == "http":
            headers = dict(scope.get("headers") or [])
            auth = headers.get(b"authorization", b"").decode("latin1")
            if auth != f"Bearer {self.token}":
                await send({"type": "http.response.start", "status": 401,
                            "headers": [(b"content-type", b"text/plain")]})
                await send({"type": "http.response.body",
                            "body": b"unauthorized"})
                return
        await self.app(scope, receive, send)


async def _run_http(mcp: FastMCP, host: str, port: int, token: str | None):
    import uvicorn
    app = mcp.streamable_http_app()
    if token:
        app = TokenAuthMiddleware(app, token)
    config = uvicorn.Config(app, host=host, port=port, log_level="info")
    await uvicorn.Server(config).serve()


def main(argv=None) -> None:
    args = parse_args(argv)
    manager = DeviceManager(mac=args.mac,
                            connect_timeout=args.connect_timeout,
                            idle_timeout=args.idle_timeout)
    mcp = build_server(manager)
    if args.transport == "stdio":
        try:
            mcp.run(transport="stdio")
        finally:
            asyncio.run(manager.close())
        return
    token = os.environ.get(TOKEN_ENV)
    loopback = args.host in ("127.0.0.1", "localhost", "::1")
    if not loopback and not token:
        raise SystemExit(f"绑定非回环地址 {args.host} 必须设置 {TOKEN_ENV}")
    try:
        asyncio.run(_run_http(mcp, args.host, args.port, token))
    finally:
        asyncio.run(manager.close())
```

pyproject.toml 修改（三处）：

```toml
# [project.optional-dependencies] 下追加：
mcp = ["mcp>=1.10"]

# [project.scripts] 下追加：
ppclock-mcp = "ppclock.mcp_server:main"
```

- [ ] **Step 4: 跑测试确认通过**

Run: `.venv/bin/pip install -e ".[mcp]" -q && .venv/bin/python -m pytest tests/test_mcp_server.py -q`
Expected: 6 passed

- [ ] **Step 5: stdio 冒烟（真实 MCP 握手，无硬件）**

Run（应输出工具清单 JSON 后退出）:

```bash
.venv/bin/python - <<'EOF'
import anyio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def main():
    params = StdioServerParameters(command=".venv/bin/python",
        args=["-m", "ppclock.mcp_server"])
    async with stdio_client(params) as (r, w):
        async with ClientSession(r, w) as s:
            await s.initialize()
            tools = await s.list_tools()
            names = sorted(t.name for t in tools.tools)
            assert len(names) == 13, names
            print(names)

anyio.run(main)
EOF
```

Expected: 打印 13 个工具名。若无 `python -m` 入口（模块无 `__main__` 守卫），改用 `args=["-c", "from ppclock.mcp_server import main; main()"]` 并设 `env` 使 `PYTHONPATH=src`，或以 console script `.venv/bin/ppclock-mcp` 为 command。

- [ ] **Step 6: 回归 + 提交**

Run: `.venv/bin/python -m pytest tests/ -q`
Expected: 全绿

```bash
git add src/ppclock/mcp_server.py tests/test_mcp_server.py pyproject.toml
git commit -m "feat(mcp): ppclock-mcp 入口——stdio/HTTP 双模 + token 鉴权 + 非回环守卫"
```

---

### Task 4: 文档与 0.2.0

**Files:**
- Create: `docs/sdk/MCP.md`
- Modify: `src/ppclock/__init__.py`（`__version__`）、`pyproject.toml`（version）、`CHANGELOG.md`、`README.md`、`llms.txt`、`docs/sdk/API.md`

**Interfaces:**
- Consumes: Task 1-3 全部公开名
- Produces: 文档与版本号；无新代码接口

- [ ] **Step 1: docs/sdk/MCP.md（工具参考 + agent 挂载示例）**

内容骨架（逐项写全，勿留 TODO）：

1. 一句话：ppclock-mcp 是跑在蓝牙所在机器上的单层 MCP 服务器，13 个工具覆盖对时/模式/传图/模板/倒计时/休眠等。
2. 安装：`pip install -e ".[mcp]"`；要求 Python ≥3.10、本机蓝牙。
3. 启动：stdio（`ppclock-mcp --mac XX`）与 http（`PPCLOCK_MCP_TOKEN=... ppclock-mcp --transport http --host 0.0.0.0 --port 8972`）双例。
4. agent 挂载示例：Claude Code `claude mcp add ppclock -- ppclock-mcp --mac XX`（stdio）；streamable HTTP 端点 `http://<host>:8972/mcp` + Bearer token。
5. 13 工具参考表（名字/参数/返回，逐字对齐 mcp_tools.py docstring 与签名；`upload_image` 列出 6 个可选 adjust 参数）。
6. 输出契约与错误码表（6 码 + hint 语义）。
7. 连接行为说明：守候窗口/空闲超时/串行/重连一次（对应 `--connect-timeout`/`--idle-timeout`）。
8. Windows 部署节：venv → `pip install -e ".[mcp]"` → 环境变量 → 启动 → 防火墙放行 8972（仅局域网）→ 不动 8971 bridge 与既有服务。
9. 不暴露能力清单（OTA/激活/LUT/WiFi/轮播）及原因一句。

- [ ] **Step 2: 版本与既有文档同步**

- `src/ppclock/__init__.py`：`__version__ = "0.2.0"`
- `pyproject.toml`：`version = "0.2.0"`
- `CHANGELOG.md`：新增 `## 0.2.0（2026-07-30）`——ppclock-mcp（13 工具/双模/鉴权/方案 C 连接管理）、DeviceManager 公开为子包能力。
- `README.md`：SDK 用法后追加「MCP 服务器」小节（启动双例 + 指向 docs/sdk/MCP.md）。
- `llms.txt`：目录行加 `ppclock-mcp`（mcp_server/device_manager/mcp_tools）；快速示例后加 MCP 挂载一句。
- `docs/sdk/API.md`：子包速查表加三行（`ppclock.mcp_server`/`ppclock.device_manager`/`ppclock.mcp_tools`）。

- [ ] **Step 3: 回归 + 提交**

Run: `.venv/bin/python -m pytest tests/ -q`
Expected: 全绿

```bash
git add -A
git commit -m "docs+release: MCP.md 工具参考与部署指南；0.2.0"
```

---

### Task 5: Windows 部署包与熠管家协作

**Files:**
- Create: `tools/mcp_windows_deploy.md`（熠管家执行清单）
- 外发：Worker Bridge `assist.requested`

**Interfaces:**
- Consumes: Task 4 的 docs/sdk/MCP.md §Windows 部署
- Produces: 可执行部署清单 + 熠管家 assist 请求记录

- [ ] **Step 1: 写 tools/mcp_windows_deploy.md**

清单（每步含验证命令与预期输出）：

1. 前置：Windows 机 Python ≥3.10（`python --version`）、蓝牙适配器在位、设备 NRF- 在附近。
2. 取码：`git clone`（或压缩包拷贝）到 `C:\ppclock`；`cd C:\ppclock`。
3. 环境：`python -m venv .venv; .venv\Scripts\pip install -e ".[mcp]"`。
4. 冒烟（无设备）：`.venv\Scripts\ppclock-mcp --help` 打全参数表。
5. stdio 实测：`claude mcp add ppclock -- C:\ppclock\.venv\Scripts\ppclock-mcp.exe --mac <MAC>` → 调 `scan_devices`/`set_time`/`upload_image`/`set_mode image0` 目视上屏。
6. HTTP 实测：设 `PPCLOCK_MCP_TOKEN` → 启动 → 另一终端 `curl -H "Authorization: Bearer <token>" http://127.0.0.1:8972/mcp` 初始化握手；无 token 请求预期 401。
7. 约束核对：8971 bridge 与既有服务进程不动；8972 防火墙仅局域网放行。
8. 回报格式：每步截图/文本输出 + 目视结果。

- [ ] **Step 2: 经 Worker Bridge 请求熠管家协助**

```bash
W="$HOME/.local/bin/yi-worker-claude-current"
"$W" task.init ppclock-mcp-deploy '{"title":"ppclock-mcp Windows 部署实测","request_summary":"把 ppclock-mcp 部署到蓝牙所在 Windows 服务器并跑通 stdio+HTTP 实测（清单 tools/mcp_windows_deploy.md）","workspace":"/mnt/documents/Works/Eink/qianbian","native_session_id":"HOOK_INJECTED_EXACT_ID"}'
"$W" assist.requested ppclock-mcp-deploy '{"category":"action","question":"请按 tools/mcp_windows_deploy.md 在 Windows 服务器执行部署与实测，或给我该机的访问方式；约束：不动 8971 bridge 与既有服务","attempted":["本机 Linux 单元/协议测试全绿"],"needed":"Windows 执行环境或访问凭据","priority":"action_required"}'
```

（`native_session_id` 用 Hook 注入的原值；以上命令在 Task 5 执行时原样跑。）

- [ ] **Step 3: 提交清单**

```bash
git add tools/mcp_windows_deploy.md
git commit -m "docs: Windows 部署执行清单（熠管家协作）"
```

- [ ] **Step 4: 等复并执行联调**

inbox 回复到达后按回复执行（拿到访问方式则远程部署；熠管家代办则核对回报与验证清单）。每条事件处理后 `event.ack`。此步产出实测记录追加到 `docs/superpowers/specs/2026-07-30-ppclock-mcp-design.md` 末尾「实测记录」节。

---

## Self-Review 记录

- Spec 覆盖：13 工具 ✅（Task 2）、双模+鉴权 ✅（Task 3）、方案 C ✅（Task 1）、打包 extra ✅（Task 3）、文档/版本 ✅（Task 4）、Windows+熠管家 ✅（Task 5）、Linux 兼容（bleak 抽象，无平台分支代码）✅。
- 类型一致性：`DeviceManager.run(op)`/`status()` 签名在 Task 1 定义、Task 2 FakeManager 镜像；工具名 13 个 Task 2/3/4 一致；`TOKEN_ENV` Task 3 定义使用一致。
- 已知风险（执行时验证）：FastMCP `stateless_http`/`streamable_http_app` 存在于 mcp≥1.10——Task 3 Step 2 失败则 `.venv/bin/pip install -U mcp` 并按实际 API 调整；`create_connected_server_and_client_session` 路径若变更，以 `python -c "import mcp.shared.memory; help(...)"` 为准。