QuickTVUI Debug MCP

独立的 MCP Server，基于 ESDebugServer 已有的 /ai/* 和 /ai/stream 暴露只读资源与工具。

能力

• resources
  • quicktvui-debug://targets
  • quicktvui-debug://stream/status
  • quicktvui-debug://targets/{clientId}/context
  • quicktvui-debug://targets/{clientId}/events/recent
  • quicktvui-debug://targets/{clientId}/events/live
  • quicktvui-debug://targets/{clientId}/native-logs/recent
  • quicktvui-debug://targets/{clientId}/screenshot/latest
• tools
  • list_targets
  • get_target_context
  • get_recent_events
  • get_recent_console_logs
  • get_recent_native_logs
  • get_latest_screenshot
  • get_live_events
  • get_stream_status

构建

npm run build:quicktvui-debug-mcp

测试

npm run test:quicktvui-debug-mcp

当前测试会起一个本地 mock ESDebugServer，覆盖：

• /ai/* 只读接口映射
• /ai/stream -> MCP resources/updated
• tools / resources / resource templates 的最小握手

运行

如果你是通过 Trae 或其他 MCP client 的 command + args 配置接入：

• 不需要手工执行下面的启动命令
• MCP 进程会由 Trae 或 MCP client 自动拉起
• 你只需要保证 ESDebugServer 本身已经启动，并且 --base-url 可访问

下面的命令主要用于命令行 smoke test 或排障：

npx -y @quicktvui/[email protected] --base-url http://127.0.0.1:38989

默认会连 ESDebugServer 的 /ai/stream，并把实时事件转成 MCP resources/updated 通知。

如果 /ai/stream 中途断开，当前实现会在重连后按 sinceSeq 调用 /ai/targets/:clientId/events 做一次回填，尽量补上断线窗口内漏掉的统一事件。

quicktvui-debug://targets/{clientId}/events/live 的资源列表会同时参考：

• 当前 /ai/targets
• 本地 stream cache 里已经见过的 clientId

所以它可以覆盖“只在流里先出现、但还没稳定进入 /ai/targets”的目标；但 context / events/recent / native-logs/recent / screenshot/latest 仍然只对 /ai/targets 中已知 target 暴露。

如果只想保留静态只读工具和资源，不连 SSE：

npx -y @quicktvui/[email protected] --base-url http://127.0.0.1:38989 --no-stream

使用文档

• 详细使用说明与验证步骤见 ./USAGE.md
• 发布到 npm 与 Trae 接入说明见 ../../doc/QUICKTVUI_DEBUG_MCP_TRAE_RELEASE_GUIDE.MD