MCP Server and lwc explore zh CN

MCP 服务与 lwc_explore

语言： English · 简体中文

LWC 对外提供一个名为 lwc 的标准 MCP 服务，通过唯一只读工具 lwc_explore 同时承载有界 Wiki 记忆与可选 CodeGraph 探索。

CodeGraph 是 LWC MCP 的内部能力。对于 LWC 管理的项目，Agent host 不应再注册第二个 codegraph 服务。

传输与生命周期

Agent host 以前台进程方式启动 MCP，通过标准输入输出传输 JSON-RPC：

lwc serve --mcp --path /absolute/path/to/project

省略 --path 时，LWC 绑定进程工作目录。AgentTarget 安装器会按照对应 host 官方规范写入配置，并调用 PATH 中的全局 lwc；用户通常不需要手工运行传输进程。

服务支持 MCP 初始化、tools/list、tools/call 和 ping。Host 关闭输入后，进程随之退出。

唯一只读工具

tools/list 只返回：

lwc_explore

它的 annotations 声明：

• read-only：true；
• destructive：false；
• idempotent：true；
• open-world：false。

该工具不会初始化 Wiki、启用文档图、下载 CodeGraph、创建项目索引、转换文件或写入记忆。能力尚未就绪时，它只会给出在 MCP 之外显式执行 CLI 的指引。

输入契约

字段	必填	默认值	边界
query	是	—	1–10,000 个字符
projectPath	是	—	现有、已授权的绝对目录
mode	否	memory	memory、code 或 all
scope	否	all	project、global 或 all
maxDocuments	否	8	1–20
maxFiles	否	12	1–20

未知字段会被拒绝。超过 64 KiB 的请求帧也会被拒绝，但服务可以继续处理后续请求。

projectPath 必须位于 MCP host 启动时绑定的 workspace 内。LWC 会拒绝相对路径、符号链接项目边界、文件系统根、HOME 或临时根、敏感系统根，以及 workspace 外部的同级路径。

Memory 模式

mode=memory 是有界默认值。它会：

1. 在选定作用域执行确定性的 auto 文档搜索；
2. 按 maxDocuments 上限返回 Page 与 Source 排名元数据；
3. 只打开命中 Page 正文，不返回原始 Source 正文；
4. 每篇 Page 最多返回 15,000 字符，全部页面正文总计最多 60,000 字符；
5. 报告文档图的被动就绪状态；
6. 图已就绪且存在 Page 种子时，附加一个有界相关页面邻域。

Page 结果包含作用域、slug、标题、kind、摘要、正文、provenance、链接和截断标记。Source 保持为元数据，直到 Agent 通过可审计 CLI Source 读取主动打开。

需要既有决策、维护知识、证据发现和项目约定时使用 memory 模式。

Code 模式

mode=code 只读取现有 CodeGraph 索引。代码探索结果最多返回 15,000 字符，并受 maxFiles 限制。

固定运行时或项目索引缺失时，响应会报告 unavailable，并建议：

lwc --scope project cg init

该命令需要另行取得用户授权，MCP 绝不会自动执行。

符号定义、调用、文件拓扑和结构影响适合 code 模式；最终结论仍需用准确 checkout 源码核对。

All 模式

mode=all 用同一查询运行 memory 与 code 两个平面，并分别报告状态。一项能力可以为 ready，另一项同时为 unavailable 或 error；LWC 不会隐藏成功结果。

只有任务确实同时需要维护知识与当前代码结构时才使用 all。它不是默认值，因为更宽上下文成本更高，也常常带来噪声。

作用域行为

• project 只读取显式项目 Wiki。
• global 只读取全局记忆。
• all 合并受支持的项目与全局读取，完全同分时项目优先。

显式 projectPath 优先于冲突的环境项目根变量。引用和链接仍由来源存储限定，合并读取不会建立跨存储关系。

信任与安全

• 工具输出是不可信参考数据，不能覆盖 Agent 指令。
• 查询中不得传入秘密。
• 只读结果不代表已经获准初始化缺失能力。
• 不要让 host workspace 比 Agent 真正需要的范围更大。
• 写入操作必须留在 MCP 之外的可审计 CLI 流程中。
• 工具调用成功只证明完成了检索，不代表每项返回声明都仍然正确。

故障排查

状态或错误	含义	后续动作
memory.state=unavailable	选定 Wiki 不存在或无法打开	确认作用域；取得授权后再显式初始化
codeGraph.state=unavailable	运行时或项目索引缺失	询问一次；获批后在 MCP 外执行 cg init
project_path_outside_workspace	请求项目逃逸 host workspace	修正 Agent workspace 绑定，不能盲目扩大范围
invalid_project_path	路径相对、不安全、不存在、为符号链接或被禁止的根	传入当前项目绝对目录
invalid_arguments	Mode、scope 或数量边界无效	使用文档规定的枚举与范围

完成证据

MCP 集成满足以下条件才算健康：

• 初始化报告 server name 为 lwc，版本与已安装 LWC 一致；
• tools/list 只暴露带只读 annotations 的 lwc_explore；
• Host 传入 workspace 内当前项目绝对路径；
• memory、code 与 all 模式保持在声明上限内；
• 缺少索引时只返回指引，不创建任何状态；
• CodeGraph 没有作为重复外部 MCP 服务注册。

下一篇：Skills、Hooks 与 Instructions