@quicktvui/ai-mcp

QuickTVUI 的 MCP 本地服务，提供文档检索、源码定位、doctor/validate 以及运行流程工具。

能力概览

• 通过 MCP tools 暴露 QuickTVUI 本地文档检索能力
• 在本地 rules 源码中定位 QuickTVUI 实现
• 返回结构化的 doctor / validate 结果
• 通过 MCP 调用 run-dev / run-esapp / run-to-tv
• 提供设备与 runtime 状态检查能力
• 支持日志采集与常见问题模式分析
• 支持项目脚手架与 issue 报告模板准备
• 内置 QuickTVUI Debug 能力（/ai/* + /ai/stream）
• 内置插件服务能力（/api/v1/*，支持 hello/status/upload）
• 内置 Android 插件脚手架能力（工程 / 模块 / 组件创建与打包）
• 提供适配 Trae 等客户端的 stdio 传输

Tools

• quicktvui_docs_search
• quicktvui_docs_open
• quicktvui_source_locate
• quicktvui_source_open
• quicktvui_doctor
• quicktvui_validate_project
• quicktvui_run_to_tv
• quicktvui_run_dev
• quicktvui_run_esapp
• quicktvui_devices_list
• quicktvui_runtime_check
• quicktvui_runtime_install
• quicktvui_logs_collect
• quicktvui_logs_analyze
• quicktvui_project_scaffold
• quicktvui_issue_report_prepare
• plugin_server_check
• plugin_server_hello
• plugin_server_status
• plugin_upload_so
• plugin_upload_plugin
• plugin_project_create
• plugin_project_build
• plugin_module_create
• plugin_component_create
• 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

Resources

• quicktvui://server/info
• quicktvui://rules/docs-root
• quicktvui://rules/source-root
• quicktvui://docs/index
• quicktvui://trae/readme
• quicktvui://docs/file/{path}
• quicktvui://source/file/{path}
• 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

Prompts

• quicktvui_lookup
• quicktvui_run_to_tv

安装

项目侧规则依赖

在你的 QuickTVUI 业务项目里安装：

npm install @quicktvui/ai --save-dev

命令侧运行依赖

用于全局命令或 MCP 启动：

npm install -g @quicktvui/ai-cli @quicktvui/ai-skills @quicktvui/ai-mcp

启动方式

如果环境可以直接使用发布包：

npx @quicktvui/ai-mcp

全局安装后也可以直接执行：

quicktvui-ai-mcp

Debug 参数

现在同一个 quicktvui-ai-mcp 进程已内置运行时调试能力，可直接通过参数配置：

quicktvui-ai-mcp --debug-base-url http://127.0.0.1:38989

支持参数：

• --debug-base-url
• --debug-hash
• --debug-stream / --no-debug-stream
• --debug-stream-reconnect-delay-ms
• --debug-max-live-events-per-client
• --plugin-base-url

插件服务

插件服务工具对应 docs/plugin/plugin-server-api.md 中定义的 /api/v1/* 接口。

这些接口都要求使用 POST。同路径 GET 在实测设备上可能返回 404。

不显式传 baseUrl 时，MCP 会按下面顺序解析插件服务地址：

1. 优先尝试 adb 已连接设备的插件服务地址
2. 如果无法从目标设备推断 host，则自动使用 adb 端口转发并回落到 http://127.0.0.1:36366
3. 如果同时有多台 adb 设备，需显式传 device 或 baseUrl
4. 如果没有 adb 已连接设备，需由用户提供服务 IP / baseUrl

abi 只在 plugin_upload_so 时才需要。如果这里未显式传 abi，MCP 会尝试从当前插件服务对应的 adb 目标读取 ro.product.cpu.abi 并按需补齐；其他插件服务工具不会主动查询 ABI。

如果电视端服务只监听设备本地回环地址，仍可以使用 adb 端口转发：

adb -s <device-serial> forward tcp:36366 tcp:36366
quicktvui-ai-mcp --plugin-base-url http://127.0.0.1:36366

不要把某个开发者自己的电视 IP 固定写进共享 MCP 配置。更推荐：

1. 共享配置里只保留 quicktvui-ai-mcp
2. 在具体工具调用时按需显式传 baseUrl=http://<tv-ip>:36366
3. 或由开发者在本机通过环境变量 / 本地配置自行覆盖

推荐先做一次连通性检查：

只调用 plugin_server_check，参数：
baseUrl=http://127.0.0.1:36366
也可以改成 baseUrl=http://<tv-ip>:36366
仅返回 structuredContent。

插件脚手架

这组工具用于创建 / 更新 / 打包 Android 插件工程，并生成原生模块、原生组件骨架，避免 AI 逐个手写文件。

推荐映射：

1. plugin_project_create：克隆或更新插件模板、改包名、写 .kyy-plugin-project.json、注入 build:android-plugin
2. plugin_project_build：按固定优先级打包插件 build:android-plugin -> build:plugin -> build -> ./gradlew assembleGeneralDebug
3. plugin_module_create：生成实现 com.quicktvui.sdk.base.module.IEsModule 的无界面原生模块
4. plugin_component_create：生成实现 com.quicktvui.sdk.base.component.IEsComponent / IEsComponentView 的原生 UI 组件，并补 docs/component/<kebab-name>.md

推荐优先查阅包内文档：

• node_modules/@quicktvui/ai/rules/.docs/zh-CN/tool/cli/plugin-create-project.md
• node_modules/@quicktvui/ai/rules/.docs/zh-CN/tool/cli/plugin-create-module.md
• node_modules/@quicktvui/ai/rules/.docs/zh-CN/tool/cli/plugin-create-component.md
• node_modules/@quicktvui/ai/rules/.docs/zh-CN/tool/api/plugin-scaffold-mcp.md

Trae 配置

可使用如下 stdio MCP 配置：

{
  "mcpServers": {
    "quicktvui": {
      "command": "npx",
      "args": ["@quicktvui/ai-mcp"],
      "cwd": "/ABS/PATH/TO/YOUR/QUICKTVUI/PROJECT"
    }
  }
}

若已全局安装，也可以配置为：

{
  "mcpServers": {
    "quicktvui": {
      "command": "quicktvui-ai-mcp",
      "args": [],
      "cwd": "/ABS/PATH/TO/YOUR/QUICKTVUI/PROJECT"
    }
  }
}

cwd 必须指向目标 QuickTVUI 业务项目根目录，MCP 才能优先使用项目内 @quicktvui/ai/rules 进行文档和源码解析。

cwd 是什么

cwd 是 MCP 进程启动时的工作目录（Current Working Directory）。

对 @quicktvui/ai-mcp 来说，它应该是你的 QuickTVUI 业务项目根目录（包含业务 package.json 的目录），而不是 quicktvui-ai 工具仓库目录。

macOS 示例：

{
  "mcpServers": {
    "quicktvui": {
      "command": "npx",
      "args": ["@quicktvui/ai-mcp"],
      "cwd": "/Users/yourname/workspace/my-tv-app"
    }
  }
}

Windows 示例：

{
  "mcpServers": {
    "quicktvui": {
      "command": "npx",
      "args": ["@quicktvui/ai-mcp"],
      "cwd": "C:\\workspace\\my-tv-app"
    }
  }
}

如何验证 MCP 集成成功

在 Trae 里配置完成后，按下面顺序验证：

1. 在 MCP 面板确认 quicktvui 状态为已连接。
2. 调用 quicktvui_doctor 做工具链路校验。
3. 调用 quicktvui_docs_search 做文档检索校验。
4. 调用 quicktvui_validate_project 做项目状态校验。

可直接复制到 Trae 的提示词：

工具链路校验：

只调用 quicktvui_doctor，参数：
projectRoot=/ABS/PATH/TO/YOUR/QUICKTVUI/PROJECT
仅返回 structuredContent。

文档检索校验：

只调用 quicktvui_docs_search，参数：
projectRoot=/ABS/PATH/TO/YOUR/QUICKTVUI/PROJECT
query=qt-image
limit=3
仅返回 structuredContent。

项目校验：

只调用 quicktvui_validate_project，参数：
projectRoot=/ABS/PATH/TO/YOUR/QUICKTVUI/PROJECT
仅返回 structuredContent。

runtime 校验：

只调用 quicktvui_runtime_check，参数：
device=<ADB_SERIAL>
runtimePackage=com.extscreen.runtime
仅返回 structuredContent。

设备列表校验：

只调用 quicktvui_devices_list，参数：
仅返回 structuredContent。

预期结果：

• quicktvui_doctor 能返回 hasRulesRoot、hasDocs、hasSource 等字段。
• quicktvui_docs_search 对常见组件关键词应返回 total > 0。
• quicktvui_validate_project 应返回 valid: true（或明确的缺失项列表）。
• quicktvui_runtime_check 在 runtime 准备完成时应返回 installed: true。
• quicktvui_devices_list 在 adb 可用且有设备时应返回至少一个 serial。

若校验失败，优先检查：

• cwd 是否指向业务项目根目录。
• 项目是否安装了 @quicktvui/ai。
• MCP 配置中的 command / args 在本机是否可执行。

两种使用方式：自动调用 vs 强制调用

方式 A：AI 自动调用 MCP（省事）

说明：你不指定工具名，AI 会根据任务自动判断是否调用 MCP。

示例：

我想确认 qt-image 支持哪些能力。你可以自动调用 QuickTVUI MCP 工具后再回答。

帮我排查 run-dev 为什么没启动起来，必要时请自动调用设备、runtime 和日志相关 MCP 工具。

适用场景：

1. 问题比较泛，不确定先用哪个工具。
2. 你只关心最终结论，不关心中间调用过程。

注意：

1. 自动模式不保证每次都命中你期望的工具。
2. 代码生成、运行排障这类任务建议使用“强制调用”。

方式 B：强制 AI 调用 MCP（稳定，推荐开发使用）

建议把提示词写成“工具名 + 明确参数 + 返回格式”，优先拿 structuredContent。

模板 1：单工具调用

只调用 <tool_name>，参数：
key1=value1
key2=value2
仅返回 structuredContent。

示例：

只调用 quicktvui_doctor，参数：
projectRoot=/ABS/PATH/TO/YOUR/QUICKTVUI/PROJECT
仅返回 structuredContent。

模板 2：写代码前先查能力

按顺序调用以下工具，并在最后输出结论：
1) quicktvui_docs_search(query=<关键词>, projectRoot=<项目根>, limit=5)
2) quicktvui_docs_open(打开第1步最相关文档)
3) quicktvui_source_locate(query=<组件或API>, projectRoot=<项目根>, limit=3)
只基于工具返回回答，不要臆测未检索到的能力。

示例：

按顺序调用以下工具，并输出结论：
1) quicktvui_docs_search，参数：
projectRoot=/ABS/PATH/TO/YOUR/QUICKTVUI/PROJECT
query=qt-image
limit=3
2) quicktvui_docs_open，打开第1步最相关文档
3) quicktvui_source_locate，参数：
projectRoot=/ABS/PATH/TO/YOUR/QUICKTVUI/PROJECT
query=qt-image
limit=2
仅返回 structuredContent 和最终结论。

模板 3：运行问题排查

按顺序调用并汇总问题：
1) quicktvui_devices_list
2) quicktvui_runtime_check(device=<ADB_SERIAL>, runtimePackage=com.extscreen.runtime)
3) quicktvui_logs_collect(device=<ADB_SERIAL>, lines=300)
4) quicktvui_logs_analyze(使用第3步日志)
输出每一步 structuredContent，并给出下一步建议。

提示词速查表（按场景）

下面 5 条可直接复制。

1. 查组件能力

按顺序调用以下工具并输出结论：
1) quicktvui_docs_search(projectRoot=/ABS/PATH/TO/YOUR/QUICKTVUI/PROJECT, query=qt-image, limit=5)
2) quicktvui_docs_open(打开第1步最相关文档)
仅返回 structuredContent 和最终结论。

2. 写代码前校验能力（docs + source）

按顺序调用以下工具：
1) quicktvui_docs_search(projectRoot=/ABS/PATH/TO/YOUR/QUICKTVUI/PROJECT, query=qt-waterfall, limit=5)
2) quicktvui_source_locate(projectRoot=/ABS/PATH/TO/YOUR/QUICKTVUI/PROJECT, query=FastListViewController, limit=3)
只基于工具结果输出“可用能力 + 约束 + 示例写法”。

3. 一键跑到 TV

只调用 quicktvui_run_to_tv，参数：
projectRoot=/ABS/PATH/TO/YOUR/QUICKTVUI/PROJECT
仅返回 structuredContent。

4. 运行失败排查

按顺序调用并汇总问题：
1) quicktvui_devices_list
2) quicktvui_runtime_check(device=<ADB_SERIAL>, runtimePackage=com.extscreen.runtime)
3) quicktvui_logs_collect(device=<ADB_SERIAL>, lines=400)
4) quicktvui_logs_analyze(使用第3步日志)
输出每一步 structuredContent，并给出下一步操作。

5. 准备 issue 报告

只调用 quicktvui_issue_report_prepare，参数：
projectRoot=/ABS/PATH/TO/YOUR/QUICKTVUI/PROJECT
summary=请概述问题
actualBehavior=请描述实际表现
expectedBehavior=请描述预期表现
logText=粘贴日志
仅返回 structuredContent。

零基础建议

1. 先跑“只调用 quicktvui_doctor”确认 MCP 可用。
2. 开发阶段默认用“强制调用”模板，减少幻觉。
3. 需要快速探索时再用“自动调用”。
4. 路径和设备都显式传参（projectRoot、device）。

失败分流图（排障流程）

按顺序执行，命中哪条先处理哪条：

1. quicktvui_doctor/quicktvui_validate_project 失败
   先安装 @quicktvui/ai，并检查 projectRoot、cwd 是否指向业务项目根目录。

2. quicktvui_devices_list 无设备
   先处理 adb 连接；多设备时显式传 device。

3. quicktvui_runtime_check.installed=false 或 launchCapability.ok=false
   先执行 quicktvui_runtime_install，再复查 quicktvui_runtime_check。

4. quicktvui_run_to_tv 阶段失败
   根据 stage 字段定位在 setup-vue-env、setup-android-env 还是 run-dev。

5. run-dev 仍失败
   执行 quicktvui_logs_collect + quicktvui_logs_analyze，按 issues[].suggestion 处理。

6. 多次修复仍失败
   执行 quicktvui_issue_report_prepare 生成脱敏报告再上报。

说明

• 服务端基于官方 @modelcontextprotocol/sdk 架构（stdio）
• 传输层同时兼容 ndjson 与 Content-Length JSON-RPC 帧
• 可选环境变量：QUICKTVUI_MCP_STDIO_MODE=auto|line|content-length（默认 auto）
• quicktvui_run_dev 默认 detached 启动
• quicktvui_run_to_tv 会按顺序执行 doctor -> setup-vue-env -> setup-android-env -> run-dev
• 文档/源码解析优先项目内 node_modules/@quicktvui/ai/rules，其次回退到仓库本地布局
• 建议与 @quicktvui/ai、@quicktvui/ai-cli 配合使用

文档

• https://quicktvui.com