Flutter Engine 官方 MCP 服务器解析：用 Gemini CLI 通过 MCP 驱动引擎构建与 GN 目标查询

本指南围绕 engine/src/flutter/tools/mcp/README.md 展开，系统介绍 Flutter Engine 仓库自带的 MCP（Model Context Protocol）服务器：它通过标准输入输出（stdio）以 JSON-RPC 2.0 暴露 engine_build、engine_list_targets、engine_build_help 三个工具，使 Gemini CLI 等 AI Agent 可以直接查询与构建 engine 目标。读完本文，你将掌握该服务器的设计动机、协议交互方式、工具清单与手工测试方法，并能结合 server.dart 与 server_test.dart 从源码层面理解其实现与测试策略。

一、背景：为什么 Engine 需要一个专用 MCP 服务器

MCP 是用于连接 AI Agent（如 Gemini CLI）与外部数据、工具的开放协议。Flutter Engine 的代码规模庞大，AI Agent 若要在其中完成"列出某 config 下有哪些构建目标""执行一次引擎构建"这类任务，必须知道如何调用仓库自带的构建工具链。与其把构建脚本的调用细节写进 Agent 的提示词，不如将它封装成一个标准化的 MCP 服务器——Agent 只需询问"这个仓库提供了哪些工具"，再按工具名与参数调用即可。

EngineServer 的类注释点明了它的定位："An [MCPServer] that provides tools an agent would need to develop the Flutter engine."（一个向 Agent 提供 Flutter engine 开发所需工具的 MCP 服务器）。当前实现信息量虽小，但契约清晰：

• 进程间通信基于 stdout（标准输出），属于典型的 stdio 型 MCP 服务器；
• 工作目录（CWD）被假定为 //engine/src/flutter，这与"从该目录启动 Gemini CLI"时的 CWD 一致；
• 该目录归属较新、仍标记为 WIP（见 CODEOWNERS，由 @gaaclarke 负责），README 也坦言自动化测试有待整合进 dart workspace 后补全。

说明：文中 //engine/src/flutter 是 Flutter 仓库内部对 engine 源码根的惯用写法，对应本仓库实际路径 engine/src/flutter。下面统一按仓库根目录相对路径引用。

二、服务器定义与依赖（pubspec）

engine/src/flutter/tools/mcp/pubspec.yaml 揭示了实现它的技术选型：

name: engine_mcp
publish_to: none
environment:
  sdk: ^3.11.0-0
resolution: workspace
dependencies:
  async: any
  dart_mcp: any
  process: any
  process_runner: any
  stream_channel: any
dev_dependencies:
  process_fakes: any
  test: any

要点：

• 包名 engine_mcp，publish_to: none，仅作为仓库内部工作区（resolution: workspace）的一环，与 flutter_tools、dart_mcp 等一起解析依赖；
• SDK 约束 ^3.11.0-0，使用较新的 Dart；
• 运行依赖里 dart_mcp 提供 MCP 协议骨架（MCPServer、Tool、Schema、CallToolResult 等），process_runner 负责启动子进程并捕获输出，stream_channel 提供双向字节/字符串流抽象；
• 测试侧使用 process_fakes 提供的 FakeProcessManager/FakeProcess 来模拟子进程，保证单测无需真实构建。

三、三个内置工具：名称、入参与底层命令

README 只给出了两个查询示例，真正的"工具目录"藏在 lib/server.dart 的 initialize 中。从源码可确认服务器共注册三个工具（server.dart）：

工具名	描述	输入参数	实际调用的命令
engine_build_help	获取构建工具帮助与 config 列表	无	./bin/et build --help
engine_build	构建一个 engine 目标（可能耗时较长）	config（必填，字符串）、target（可选，字符串）	./bin/et build -c <config> [<target>]
engine_list_targets	列出指定 config 下的构建目标	config（必填，字符串）	./third_party/gn/gn ls ../out/<config>

三个工具均标记了 ToolAnnotations(readOnlyHint: true)，即对 Agent 声明"只读"意图。注意 engine_build 描述中提示 "This is potentially a long running process"，说明构建可能持续很长时间，属于 Agent 使用时应预留耐心等待的调用。

3.1 engine_build_help：先问清楚有哪些 config

实现位于 server.dart，直接执行 ./bin/et build --help 并把 stdout 原样返回给 Agent：

final arguments = <String>['./bin/et', 'build', '--help'];
final ProcessRunnerResult result = await _processRunner.runProcess(arguments);
return CallToolResult(content: [TextContent(text: output)]);

Agent 在不确定 config 取值前，应优先调用本工具查看 et build 的帮助输出，从而获知当前 checkout 支持的 config 集合。

3.2 engine_build：执行实际构建

对应实现为 server.dart。它把入参拼成一条命令：

final arguments = <String>['./bin/et', 'build', '-c', config!];
if (target != null) {
  arguments.add(target);
}

即：

• 只给 config：./bin/et build -c host_profile_arm64；
• 同时给 config 与 target：./bin/et build -c host_profile_arm64 //flutter/tools/licenses_cpp。

随后通过 _processRunner.processManager.start(arguments) 以异步方式启动进程，逐行消费 stdout（代码中预留了发送 MCP progress 进度通知的 TODO，见 server.dart，当前版本并不真正推送进度），最终按退出码返回非常精简的结论：Build succeeded. 或 Build failed.；命令抛出异常时则返回 isError: true 的结果。

3.3 engine_list_targets：查询某 config 的全部 GN 目标

实现见 server.dart。它调用 GN 自带的查询命令并返回目标清单文本：

final arguments = <String>['./third_party/gn/gn', 'ls', '../out/$config'];
final ProcessRunnerResult result = await _processRunner.runProcess(arguments);
return CallToolResult(content: [TextContent(text: output)]);

注意 ../out/$config 里的 ..：因为 ./third_party/gn/gn 是相对当前 CWD（即 engine/src/flutter）的路径，而 GN 输出目录约定在 engine 根的 out/，所以 ../out/<config> 实际解析到 engine/src/out/<config>。这正是前文强调"CWD 必须是 //engine/src/flutter"的原因——命令拼接大量依赖该固定工作目录。README 中的示例查询"what impellerc targets are there for host_debug_unopt_arm64?"，本质上就是问"在 host_debug_unopt_arm64 这个 config 的构建产物目录里存在哪些目标"，而该工具正是回答这类问题的入口。

四、与 MCP 客户端交互的完整流程

README 给出该服务器是 stdio 型、走 stdout 输出，但一次完整会话还需满足 MCP 协议握手。测试文件 server_test.dart 中的初始化消息展示了正确顺序：每个新会话必须先发送 initialize 请求（声明协议版本 2025-03-26、clientInfo 等），收到结果后再发送具体工具请求。

典型手工流程如下。

第 1 步：初始化（协议握手）

{ "jsonrpc": "2.0", "id": 1,"method": "initialize", "params": {"protocolVersion": "2025-03-26", "capabilities": { "roots": {"listChanged": true },"sampling": {} },"clientInfo": { "name": "ExampleClient", "version": "1.0.0"}}}

第 2 步：列出可用工具

{ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }

服务端会返回包含 engine_build_help、engine_build、engine_list_targets 及其 JSON Schema 的工具清单。

第 3 步：调用工具（沿用 README 原例）

{ "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "engine_build", "arguments": { "config": "host_profile_arm64", "target": "//flutter/tools/licenses_cpp"} } }

成功时返回 result.content[0].text == "Build succeeded."。

五、三种测试路径（README 原文继承 + 源码补充）

5.1 手工发送 JSON-RPC 请求

服务器程序本身以流（stream）形式读写，README 建议直接手工注入上面的 JSON 请求来观察响应。将 tools/list、tools/call 两条消息写入其标准输入，即可在 stdout 依次看到 tools/list 结果与构建执行结果。此方式适合快速冒烟验证。

5.2 通过 Gemini CLI 端到端测试

README 提供了最贴近真实用法的验证方式：在 //engine/src/flutter（即 engine/src/flutter）目录下启动 Gemini CLI，直接用自然语言提问：

cd //engine/src/flutter
gemini -p "what impellerc targets are there for host_debug_unopt_arm64?"

Gemini CLI 会依据发现到的该 MCP 服务器，自行编排 engine_list_targets 等工具调用并汇总答案。这也解释了为何服务器假定 CWD 为 engine 源码根：Gemini 在该目录被配置为自动连接此 MCP server，二者共用同一 CWD 才能让 ./bin/et、./third_party/gn/gn、../out/... 等相对路径全部生效。

5.3 仓库内 Dart 自动化测试

engine/src/flutter/tools/mcp/test/server_test.dart 用 dart_mcp + process_fakes 提供了三个单测，分别对应三个工具的调用链验证，是理解服务器行为的"可执行文档"：

• list tools：发送 initialize 与 tools/list，断言响应 jsonrpc == "2.0"、id 回显一致，且 result.tools 非空（server_test.dart）；
• build：注入 FakeProcessManager，当命令恰好是 ./bin/et build -c host_profile_arm64 //flutter/tools/licenses_cpp（长度 5 的 argv）时返回假进程 stdout Build succeeded，断言最终文本为 Build succeeded.；任何其它命令组合则模拟失败（server_test.dart）；
• list targets：当命令是 ./third_party/gn/gn ls ../out/foobar（长度 3）时返回 //foo\n//bar\n，断言结果原样透传（server_test.dart）。

这套测试正好印证了第 3 节整理的三条命令拼接规则，且说明 config/target 均来自 request.arguments，为字符串类型。

六、结合源码看实现边界与后续演进方向

从代码可以归纳出当前实现刻意简化、仍在演进之处：

• 结果信息极简：engine_build 只回传成功/失败两个词，不附带构建日志；engine_list_targets、engine_build_help 则直接把子进程 stdout 原样作为文本返回。若需更丰富的诊断信息，属于未来增强项。
• 进度通知未实现：server.dart 的 TODO 注释明确计划基于 MCP 规范（2025-03-26 版 basic/utilities/progress）向客户端推送构建进度，当前只是消费掉 stdout 行而不转发。
• 测试与 workspace 集成未完成：README 自述"Automated testing is a bit lacking until we can get it integrated with the dart workspace"，即上述单测已就绪，但仍期待并入 engine 侧 Dart 工作区（resolution: workspace，见 pubspec.yaml）以在 CI 中常态运行。
• 错误处理：三个工具的实现都把子进程启动/执行的异常捕获后转为 isError: true 的 CallToolResult，保证 MCP 协议层始终能返回结构化错误而非崩溃（例如 server.dart）。

如果你想基于此扩展更多工具（比如查询 impellerc 的 target、运行某个 engine 测试），可以参照 initialize() 中 registerTool(_xxx, _doXxx) 的注册模式：定义 Tool（含名称、描述、inputSchema）与对应处理函数，在 initialize 里 registerTool 即可。

七、总结

Engine MCP 是 Flutter 官方把"引擎开发能力"开放给 AI Agent 的标准桥梁：一条 stdio 上的 JSON-RPC 2.0 服务，三个封装了 ./bin/et build、./third_party/gn/gn ls 的命令工具，一套用 process_fakes 模拟子进程的可执行测试。结合 README.md、lib/server.dart 与 test/server_test.dart 三份文件对照阅读，既能看清每个工具背后的真实命令与参数语义，也能把握其"先帮助、再查询、后构建"的 Agent 使用节奏。对希望为大型 C++/GN 代码库搭建类似 AI 开发助手的团队而言，这是一个小而完整的范本。