接入 MCP 服务
从驱动 v0.0.14 开始，知言家 AI Coding 伴侣提供本地 MCP（Model Context Protocol）stdio 服务。支持本地 stdio MCP 的 AI 客户端，可以启动驱动随包安装的 hookbridge，让模型通过一个状态工具更新设备灯效。
已有 Hook（钩子）时优先使用 Hook
Codex、Claude Code、OpenCode、TRAE 和 Qoder 家族已有对应的 Hook 接入方案。Hook 由客户端生命周期事件自动触发，状态更及时、确定性更高。
MCP 更适合不支持 Hook、但支持 MCP 协议的客户端。
MCP 复用现有驱动，不用升级固件，也不需要 API Key 或网络服务。
复制给 AI 的接入包
如果由 AI 客户端代为配置，把下面整包复制给它即可，无需让它联网抓取本页。这份内容也可在 /docs/integrations/mcp.txt 直接获取，方便能联网的 AI 当作干净源读取。
点开复制 · 给 AI 的完整接入包
text
# 知言家 AI Coding 伴侣 · MCP 接入任务包
本包用于让 AI 客户端为本机配置知言家本地 MCP 服务和状态通知 Skill。复制本包全文发给 AI，即可按步骤执行，无需联网抓取网页。
注意：Codex、Claude Code、OpenCode、TRAE、Qoder 家族已支持 Hook，优先使用 Hook 方案（见 https://zyhome.run/docs/integrations/ ）。MCP 仅适用于不支持 Hook 但支持 MCP 协议的客户端。
## 背景
知言家驱动从 v0.0.14 起内置本地 stdio MCP 服务，只暴露一个工具 zy_vibe_set_task_status，参数只有 status 一个。AI 客户端通过本地 stdio 启动 hookbridge，调用该工具把任务状态同步到桌面设备灯效。无需 API Key、无需网络服务、无需升级固件。
## 前置确认
1. 驱动已安装并在系统托盘运行（知言家 logo）。
2. hookbridge 路径：%LOCALAPPDATA%\zy_home_vibe_coding_driver\bin\zy_home_vibe_coding_driver_hookbridge.exe
PowerShell 确认（应返回 True）：
$HookBridge = Join-Path $env:LOCALAPPDATA "zy_home_vibe_coding_driver\bin\zy_home_vibe_coding_driver_hookbridge.exe"
Test-Path -LiteralPath $HookBridge
返回 False 时重装或修复驱动，从安装目录取用。
## 第 1 步 · 添加本地 stdio MCP 服务
在客户端 MCP 配置文件中加入（QoderWork 路径 ~/.qoderworkcn/mcp.json）：
```json
{
"mcpServers": {
"zy_home_ai_coding_driver_mcp": {
"type": "stdio",
"command": "C:\\Users\\<用户名>\\AppData\\Local\\zy_home_vibe_coding_driver\\bin\\zy_home_vibe_coding_driver_hookbridge.exe",
"args": ["--mcp"]
}
}
}
```
要点：
- command 用绝对路径，把 <用户名> 替换为当前 Windows 用户名。
- --mcp 是独立参数，单独写在 args，不要拼到路径字符串。
- 传输类型选 stdio / local，不是 HTTP、SSE。
- 不需要 URL、Token、端口、工作目录或环境变量。
- 客户端不认 "type" 字段时，删掉该行，保留 command 和 args。
- QoderWork 改完 mcp.json 后若服务器显示未连接，到 设置 -> 连接器 把该服务器禁用再启用一次。
## 第 2 步 · 创建状态通知 Skill
在客户端技能目录新建 SKILL.md（QoderWork 路径 ~/.qoderworkcn/skills/zy-home-ai-coding-notify/SKILL.md），内容：
```markdown
---
name: zy-home-ai-coding-notify
description: "ALWAYS use this skill at the start and end of every user interaction. Sends hardware light notifications via the zy_home_ai_coding_driver_mcp MCP to indicate task lifecycle on the physical device. This skill applies to ALL tasks regardless of topic."
version: 2.0.0
---
# 硬件状态灯通知
每次用户交互必须调用 zy_home_ai_coding_driver_mcp MCP 的 `zy_vibe_set_task_status` 工具，参数只有 `status` 一个：
| 时机 | status |
| --- | --- |
| 任务开始（最先执行的工具调用之一） | `running` |
| 即将请求用户授权、批准或确认高风险操作 | `approval_required` |
| 因缺少信息必须向用户提问 | `input_required` |
| 用户响应后任务恢复 | `running` |
| 任务成功完成或被取消（最后的工具调用之一） | `completed` |
| 任务因错误无法继续 | `failed` |
- 开始时的 `running` 与结束时的 `completed`/`failed` 必须成对；漏调收尾会让硬件卡在“处理中”灯效。
- 只在状态变化时调用一次，不要在中间步骤重复调用。
- MCP 服务不可用（调用报错）时静默跳过，不要中断任务。
```
## 第 3 步 · 验证
1. 重载客户端，打开 MCP/Tools 面板，确认：
- 服务器名与配置键名一致（zy_home_ai_coding_driver_mcp）；
- 连接类型为本地 stdio；
- 工具列表中只有一个 zy_vibe_set_task_status（部分客户端会加前缀显示为 mcp__zy_home_ai_coding_driver_mcp__zy_vibe_set_task_status，以 zy_vibe_set_task_status 结尾即正确）。
2. 发送测试提示词：
```text
请使用 zy_home_ai_coding_driver_mcp MCP 完成一次设备状态测试：
先调用 zy_vibe_set_task_status，将 status 设置为 running；
回复“状态测试进行中”；
最后再次调用该工具，将 status 设置为 completed。
不要执行其他工具或命令。
```
3. 预期结果：驱动控制台出现 MCP 默认任务；running 后设备进入进行中灯效；completed 后任务自然收尾。
4. 首次工具调用可能触发客户端的工具信任确认，确认前核对工具名和本地可执行文件路径。
## 状态枚举（仅这五个英文值）
running / approval_required / input_required / completed / failed
不支持 waiting、idle、cancelled 或中文。任务被取消用 completed 收尾（取消不是错误）。
## 排查速查
- Executable not found / spawn failed：hookbridge 路径是否绝对、Test-Path 是否 True、JSON 反斜杠是否正确转义。
- Server 连接失败：是否选 stdio；--mcp 是否作为独立参数；驱动文件是否被安全软件隔离。
- 已连接但 0 个工具：完全重启客户端，确认启动的是当前安装目录的 hookbridge。
- 显示 1 个工具但设备无变化：查看本轮是否真有工具调用记录，而非只在文字里说“已更新”。
- 工具提示事件投递失败：驱动未运行，先打开驱动控制台再重试。
- 状态参数错误：只用五个英文枚举值，不要传任务名、摘要等附加字段。
- 一个任务显示两次：同一客户端可能同时开了 Hook 和 MCP，保留一条路线。
- 多个 MCP 客户端互相覆盖：这是单共享任务的设计，需要隔离时改用各客户端 Hook 路线。
## 查看驱动日志（必要时）
Get-Content -LiteralPath "$env:LOCALAPPDATA\zy_home_vibe_coding_driver\service.json"
Get-Content -Tail 100 -LiteralPath "$env:LOCALAPPDATA\zy_home_vibe_coding_driver\service.log"
service.json 中的 baseUrl 应指向本机回环地址，是本地投递用的，不要公开到局域网或互联网，也不是 MCP URL。驱动提供的 MCP 能力
| 项目 | 说明 |
|---|---|
| 传输方式 | 本地 stdio，由客户端启动 hookbridge.exe --mcp |
| MCP 能力 | Tools |
| 工具数量 | 1 个：zy_vibe_set_task_status |
| 工具参数 | 只使用 status；任务名、会话名等附加身份不会参与任务划分 |
| 可用状态 | running、approval_required、input_required、completed、failed |
| 任务身份 | 固定为 source=mcp、默认会话；所有 MCP 客户端共用一个设备任务 |
| 应用色 | 所有 MCP 客户端共用一个 MCP 应用色，可在驱动设置页修改 |
| 本地投递 | hookbridge 通过驱动发现文件，只向本机回环地址投递状态 |
| 固件要求 | 不需要为 MCP 单独升级设备固件 |
这台 MCP 服务器只暴露一个状态工具，并作为本地进程通过标准输入输出通信。客户端配置里选择 stdio / local process / command 即可；它不是 HTTP 服务，因此官网地址、驱动控制台地址和 /events 都不是 MCP Server URL。
配置成功不等于稳定触发
MCP 服务只把工具提供给模型。是否调用、何时调用以及传入哪个状态，都由模型决定。
Hook 与 MCP 怎么选
| 维度 | Hook 路线 | MCP 路线 |
|---|---|---|
| 触发方式 | 客户端生命周期事件自动触发 | 模型主动调用状态工具 |
| 触发确定性 | 高 | 受模型能力、上下文和工具策略影响 |
| 客户端要求 | 有对应 Hook 模板 | 能启动本地 stdio MCP |
| 设备任务 | 各客户端使用独立任务身份 | 所有 MCP 客户端共用一个默认任务 |
| 应用色 | 按客户端区分 | 共用 MCP 应用色 |
| 适用场景 | Codex、Claude Code、OpenCode、TRAE | 不支持 Hook、但支持 MCP 协议的客户端 |
同一个客户端不要重复接入
不同客户端可以分别用 Hook 或 MCP，但同一个客户端别同时开两条路线。两条来源会被驱动当成不同任务，出现重复灯效或状态互相覆盖。
一、检查驱动与 hookbridge
1. 确认驱动正在运行
查看系统托盘，应能看到知言家 logo并正常打开控制台。工具调用最终要投递给本机驱动，驱动没跑起来会返回投递失败。
2. 检查可执行文件
正式安装包的默认路径是：
text
%LOCALAPPDATA%\zy_home_vibe_coding_driver\bin\zy_home_vibe_coding_driver_hookbridge.exe在 PowerShell 中执行：
powershell
$HookBridge = Join-Path $env:LOCALAPPDATA "zy_home_vibe_coding_driver\bin\zy_home_vibe_coding_driver_hookbridge.exe"
Test-Path -LiteralPath $HookBridge
Get-Item -LiteralPath $HookBridge |
Select-Object FullName, Length, LastWriteTimeTest-Path 应返回 True。如果文件不存在，先重新安装或修复当前驱动版本，并从安装目录取用，避免使用其他来源的同名可执行文件。
在客户端 MCP 面板里确认连接
hookbridge.exe --mcp 由客户端通过 stdio 管理。手工双击会卡住等待输入、或因输入流关闭而退出，无法据此判断连接是否正常，请在客户端的 MCP 面板里确认。
二、按客户端添加本地 stdio 服务
不支持 Hook 的客户端，通常用 mcpServers 结构声明本地 stdio 服务。先查客户端文档确认字段名，再按下面的结构填。
通用 mcpServers 配置
按下面的结构填写（字段名以客户端文档为准）：
json
{
"mcpServers": {
"zy_home_ai_coding_driver_mcp": {
"type": "stdio",
"command": "C:\\Users\\<用户名>\\AppData\\Local\\zy_home_vibe_coding_driver\\bin\\zy_home_vibe_coding_driver_hookbridge.exe",
"args": ["--mcp"]
}
}
}部分客户端不接受 type 字段；此时只删除 "type": "stdio"，保留 command 和 args。同时注意：
command是hookbridge.exe的绝对路径；--mcp是独立参数，单独写在args里，不要拼接到路径字符串中；- 传输类型选择 stdio 或 local（而非 HTTP、SSE 或 Streamable HTTP）；
- 不需要配置 URL、Token、端口、工作目录或环境变量。
QoderWork 配置示例
QoderWork 已支持 Hook，优先使用 Hook 接入方案。以下 MCP 配置仅作为不支持 Hook 的客户端参考示例。
自定义 MCP 配置在 ~/.qoderworkcn/mcp.json（Windows 为 C:\Users\<用户名>\.qoderworkcn\mcp.json），加入下面的服务器：
json
{
"mcpServers": {
"zy_home_ai_coding_driver_mcp": {
"type": "stdio",
"command": "C:\\Users\\<用户名>\\AppData\\Local\\zy_home_vibe_coding_driver\\bin\\zy_home_vibe_coding_driver_hookbridge.exe",
"args": ["--mcp"]
}
}
}服务器名可以自由取，本例使用 zy_home_ai_coding_driver_mcp；如果之前用过自建的桥接 MCP，沿用旧名可以避免连带修改已有的配置和规则文件。
实际接入过程中验证过的几点经验：
- 改完
mcp.json后，QoderWork 能识别到新服务器，但可能不会立刻建立连接（状态显示 unknown）。到 设置 → 连接器 里找到该服务器，先禁用再启用一次即可完成连接，不用重启应用。 - 连接建立后核对工具发现：服务器工具列表里应只有一个
zy_vibe_set_task_status。QoderWork 会给工具名加上服务器名前缀，模型实际看到的是mcp__zy_home_ai_coding_driver_mcp__zy_vibe_set_task_status这样的长名字，以zy_vibe_set_task_status结尾即正确。 - 服务端严格校验参数，只接收
status一个字段；传任务名、摘要等附加字段会报错，不要额外添加。 - 最后按“做一次明确的两段状态测试”走一遍
running→completed，设备灯效全程响应，链路才算打通。
三、让模型正确调用状态工具
MCP 初始化时，驱动会向客户端返回工具说明，但不同模型对工具调用的积极程度不同。客户端支持自定义指令时，可以加入下面这段规则：
text
使用 zy_home_ai_coding_driver_mcp MCP 服务同步当前主任务状态：
1. 开始执行或从等待中恢复时，调用 zy_vibe_set_task_status，status=running。
2. 即将请求用户授权、批准执行或确认高风险操作前，调用它，status=approval_required。
3. 因缺少信息而必须向用户提问前，调用它，status=input_required。
4. 成功完成当前任务后，调用它，status=completed。
5. 当前任务因错误无法继续时，调用它，status=failed。
只在状态发生变化时调用一次；不要创建任务名或会话名参数。这段指令只是提高调用概率，MCP 不会因此变成确定性触发。
把调用规则封装成 Skill（推荐）
指令文本能不能被模型稳定遵守，取决于客户端怎么加载它。支持 Skill 机制的客户端（如 QoderWork）可以把上面这段规则封装成一个 skill，这一步对实际体验影响很大：
- Skill 在每轮会话开始时自动加载，规则持续在场。普通指令只出现一次，长对话、多轮工具调用之后很容易被模型"忘掉"，而 skill 不会。
- 状态工具最关键的约束是成对调用：任务开始调
running，结束必须补一次completed或failed。漏掉收尾调用，设备会一直停留在"处理中"灯效，用户无法判断任务到底完没完。skill 里把"每次交互必须成对调用、漏调会让硬件卡死"写成硬性规则，模型遵守率显著更高。 - Skill 还能固定降级行为：MCP 服务不可用时静默跳过，不让一个灯效通知阻断主任务。
简化样例（保存为客户端技能目录下的 SKILL.md；QoderWork 放在 ~/.qoderworkcn/skills/<名称>/SKILL.md，其他客户端按其要求调整存放位置）：
markdown
---
name: zy-home-ai-coding-notify
description: "ALWAYS use this skill at the start and end of every user interaction. Sends hardware light notifications via the zy_home_ai_coding_driver_mcp MCP to indicate task lifecycle on the physical device. This skill applies to ALL tasks regardless of topic."
version: 2.0.0
---
# 硬件状态灯通知
每次用户交互必须调用 zy_home_ai_coding_driver_mcp MCP 的 `zy_vibe_set_task_status` 工具，参数只有 `status` 一个：
| 时机 | status |
| --- | --- |
| 任务开始（最先执行的工具调用之一） | `running` |
| 即将请求用户授权、批准或确认高风险操作 | `approval_required` |
| 因缺少信息必须向用户提问 | `input_required` |
| 用户响应后任务恢复 | `running` |
| 任务成功完成或被取消（最后的工具调用之一） | `completed` |
| 任务因错误无法继续 | `failed` |
- 开始时的 `running` 与结束时的 `completed`/`failed` 必须成对；漏调收尾调用会让硬件卡在"处理中"灯效。
- 只在状态变化时调用一次，不要在中间步骤重复调用。
- MCP 服务不可用（调用报错）时静默跳过，不要中断任务。这段 skill 的关键在 description 里的 "ALWAYS use this skill at the start and end of every user interaction"——它决定 skill 是否每轮都被加载；正文则把状态映射表和成对约束写死，不给模型自由发挥的空间。
四、状态工具与设备含义
MCP Server 只公布一个工具：
text
zy_vibe_set_task_status工具名由驱动固定，与服务器名无关
zy_vibe_set_task_status 是驱动写死上报的工具名，客户端配置改不了、也去不掉；它和 mcpServers 里的服务器键名是两回事——键名可以自由取（本文示例用的 zy_home_ai_coding_driver_mcp），工具名不会跟着变。部分客户端展示工具时会拼上服务器名前缀（如 QoderWork 显示为 mcp__zy_home_ai_coding_driver_mcp__zy_vibe_set_task_status），看到带前缀的长名字不用意外，以 zy_vibe_set_task_status 结尾即正确。
参数是：
json
{
"status": "running"
}status | 何时调用 | 驱动处理 |
|---|---|---|
running | 任务开始或从等待中恢复 | 建立或刷新 MCP 默认任务，进入进行中 |
approval_required | 即将请求授权、批准执行或确认高风险操作 | 确保任务存在后进入设备五态中的“等待授权” |
input_required | 缺少信息，需要用户补充或回答问题 | 确保任务存在后进入设备五态中的“等待审批” |
completed | 当前任务成功结束 | 以成功结果完成默认任务 |
failed | 当前任务失败且本轮结束 | 以失败结果完成默认任务 |
只支持上表中的五个英文枚举值。waiting、idle、cancelled、中文状态或其他自定义值都不受支持；传入无效值时，工具会返回可见错误，改用五个有效值即可。
任务被取消时用 completed 收尾——取消不是错误，failed 只留给任务真正失败的情况。
失败不是第六种常驻设备状态
failed 记为失败结果后按“任务完成”收尾，不新增设备状态。
五、理解共享任务行为
所有 MCP 连接都归到同一个 source=mcp 默认任务，客户端传的服务器名、项目名、会话名都不会另开任务。
因此：
- 多个 MCP 客户端可以连接，但它们更新的是同一个任务；
- 两个客户端并发工作时，后到的状态会成为这个共享任务的当前状态；
- MCP 只能反映“当前那一个任务”，没法区分多个并行会话；
- 需要按客户端或会话独立展示时，应使用对应的 Hook 接入路线。
MCP 应用色可以在驱动设置页统一修改；默认安装配置使用紫色 #8B5CF6。
六、完成首次验证
1. 验证服务器和工具发现
重新加载客户端后，打开客户端的 MCP / Tools 面板，查看服务器列表，确认这三点：
- 服务器名称与你配置的键名一致（本文示例为
zy_home_ai_coding_driver_mcp）； - 连接类型为本地 stdio；
- 工具列表中只有一个
zy_vibe_set_task_status。
2. 做一次明确的两段状态测试
在客户端发送：
text
请使用 zy_home_ai_coding_driver_mcp MCP 完成一次设备状态测试：
先调用 zy_vibe_set_task_status，将 status 设置为 running；
回复“状态测试进行中”；
最后再次调用该工具，将 status 设置为 completed。
不要执行其他工具或命令。提示词里的服务器名以你配置的键名为准（本文示例为 zy_home_ai_coding_driver_mcp），不要照抄后与本地配置对不上。
观察结果：
- 驱动控制台出现 MCP 默认任务；
running后设备进入进行中灯效；completed后任务进入完成状态并自然收尾。
首次工具调用可能触发客户端的工具信任或执行确认。确认前请核对工具名和本地可执行文件路径。
如何判断问题在哪一层
控制台任务状态会变化但设备没有灯效，说明 MCP 已经到达驱动，应转去检查设备连接、电量和固件状态。
MCP 面板已连接但控制台没有任务，先确认模型确实调用了工具，而不是只在文字中描述“已经更新”。
七、常见问题排查
| 现象 | 重点检查 |
|---|---|
Executable not found、spawn failed | Test-Path $HookBridge 是否为 True；配置是否使用绝对路径；JSON/TOML 反斜杠是否正确转义 |
| Server 连接失败 | 是否选择 stdio；--mcp 是否作为独立参数；驱动安装文件是否被安全软件隔离 |
| Server 已连接但显示 0 个工具 | 客户端是否缓存了旧连接；完全重启客户端；确认启动的是当前安装目录中的 hookbridge |
| 显示 1 个工具但设备无变化 | 查看本轮是否真的出现工具调用记录；必要时使用上面的明确测试提示 |
| 工具提示事件投递失败 | 驱动未运行、发现文件失效或本机驱动正在重启；先打开驱动控制台再重试 |
| 工具返回状态参数错误 | 只使用五个英文枚举值，不要使用 waiting、idle 或中文 |
| 一个任务被显示两次 | 同一客户端可能同时启用了 Hook 与 MCP；保留其中一条路线 |
| 多个 MCP 客户端互相覆盖状态 | 这是单共享任务的设计结果；需要隔离时改用各客户端 Hook |
| 手工运行后一直没有输出 | stdio Server 正在等待客户端消息，属于正常现象；使用客户端 MCP 面板验证 |
工具名带 zy_vibe_ 前缀、和服务器名对不上 | 正常现象：工具名由驱动固定，与服务器键名无关，见第四节的提示 |
QoderWork 改完 mcp.json 后服务器显示未连接 | 到 设置 → 连接器 把该服务器禁用再启用一次；重命名键名等同新增服务器，同样处理 |
仍无法定位时，检查驱动发现文件和日志：
powershell
Get-Content -LiteralPath "$env:LOCALAPPDATA\zy_home_vibe_coding_driver\service.json"
Get-Content -Tail 100 -LiteralPath "$env:LOCALAPPDATA\zy_home_vibe_coding_driver\service.log"发现文件中的 baseUrl 应指向本机回环地址。它是本地投递用的，不要公开到局域网或互联网，也不是 MCP URL。
八、协议兼容信息（排查兼容性时再看）
点开查看协议细节
正常接入不需要关心这一节，仅在排查兼容性问题时参考。
- JSON-RPC：
2.0 - 传输：换行分帧的 stdio
- 支持的方法：
initialize、ping、tools/list、tools/call - 支持的 MCP 协议版本：
2024-11-05、2025-03-26、2025-06-18、2025-11-25。这些日期是 MCP 规范的修订版本，在initialize握手时协商：客户端上报的版本在清单内就原样确认；不在清单内时，服务器返回自己支持的最高版本（如实测上报2000-01-01会收到2025-11-25），再由客户端决定是否继续连接。 - 工具列表不会动态变化，
tools.listChanged=false - 单条 stdio 消息上限：1 MiB
能跑本地 stdio MCP 并完成工具发现的客户端，就不用为知言家添加私有协议。