
GUI 自动化MCP 服务AI 应用【免费下载链接】PeekabooPeekaboo is a macOS CLI optional MCP server that enables AI agents to capture screenshots of applications, or the entire system, with optional visual question answering through local or remote AI models.项目地址https://gitcode.com/gh_mirrors/peekaboo6/Peekaboo点击查看免费下载本文基于 Peekaboo 开源仓库中的归档重构笔记 docs/archive/refactor/mcp-command-split.md 编写以当前仓库实际代码为准梳理MCPCommand从 1.2K 行单体文件拆分为子命令化架构的完整过程、遗留问题与后续演进建议并结合源码印证当前实现状态。背景为什么要拆 MCPCommand在 Peekaboo 的 CLI 演进过程中mcp命令最初被集中放在单个MCPCommand.swift文件中体量达到约1200 行。随着 MCPModel Context Protocol子命令与工具语法的增加这种单体文件带来了三方面问题职责混杂参数解析、默认值、调用负载构造、输出格式化、客户端管理与错误处理全部堆叠在一个文件里新增子命令时很难定位改哪里。重复代码多个子命令共享的 key/value 解析、JSON 解析逻辑在文件内重复出现改动一处容易漏改另一处。测试困难单体实现难以注入 mock参数解析、序列化、格式化等纯逻辑无法独立验证。归档笔记 docs/archive/refactor/mcp-command-split.md 记录的核心动作是将MCPCommand.swift按子命令拆成独立文件并抽出若干小助手类型来收敛职责、削减重复。拆分目标结构笔记计划的目标结构包含每个子命令对应独立文件抽出小助手类型MCPDefaults默认值、MCPCallTypes调用负载类型、MCPCallFormatter调用格式化、MCPArgumentParsing参数解析、MCPClientManaging客户端管理行为保持不变仅做结构重组。对照当前仓库 Apps/CLI/Sources/PeekabooCLI/Commands/MCP/ 目录可以看到拆分后的实际形态命名有后续演进Commands/MCP/ ├── MCPCommand.swift # 命令入口mcp 命令元数据与子命令注册 ├── MCPCommandCommanderMetadata.swift # Commander 签名transport/port/browser-handoff/allow-* 等 ├── MCPCommandServe.swift # mcp serve 子命令实现 ├── MCPArgumentParsing.swift # 参数解析助手 ├── MCPToolCommandOutput.swift # 工具调用输出格式化助手 ├── BrowserCommand.swift # browser 子命令 └── BrowserHandoffReceiptStore.swift # browser 交接凭证存储入口与子命令注册MCPCommand.swift现在是一个极薄的入口结构它只声明commandName: mcp、abstract、讨论文案和subcommands: [Serve.self]并把defaultSubcommand设为Serve同时showHelpOnEmptyInvocation: false。也就是说peekaboo mcp不带子命令时默认进入serve子命令集合本身也是mcp serve这一条后续新增子命令只需在数组中追加入口文件不再膨胀。对应源码Apps/CLI/Sources/PeekabooCLI/Commands/MCP/MCPCommand.swift。参数元数据与 Command 声明的分离拆分的另一个收益是把命令的 Commander 元数据签名、帮助文本、长短选项与命令执行逻辑分离。MCPCommandCommanderMetadata.swift通过CommanderSignatureProviding提供mcp serve的全部选项选项类型说明--transportoption传输类型当前仅stdio可用HTTP/SSE 预留但未实现--portoption预留端口默认8080供未来 HTTP/SSE 使用--browser-handoffoption消费一份已签名的浏览器交接凭证到本服务的 scoped 子进程--allow-foregroundflag授权本 MCP 服务进程使用前台/全局 UI 与浏览器用户激活--allow-temporary-clipboardflag允许对精确快照做受限的临时剪贴板粘贴UI 仍保持后台-onlyserve 子命令拆分后唯一的核心执行单元MCPCommandServe.swift承载了拆分后全部的执行逻辑其运行流程可以梳理为清晰的五段传输校验通过transportType(named:)把字符串映射为PeekabooCore.TransportType非法值输出Error: Invalid transport ...JSON 模式对应INVALID_ARGUMENThttp/sse明确报not implementedVALIDATION_ERROR后以ExitCode.failure退出。守护进程决策若运行时服务是RemotePeekabooServices即显式--bridge-socket走远程 Bridge 宿主跳过本地 daemon 启动否则启动PeekabooDaemon(configuration: .embeddedMCP())。工具上下文组装makeToolContext依据allowForeground/allowTemporaryClipboard构造MCPToolExecutionAuthority并接入 snapshot mutation coordinator 与 capture preflight refusal形成MCPToolContext。浏览器交接如果命令绑定了browserHandoffReceiptBundleData会先构造BrowserMCPHandoffGrant——注释明确Server initialization opens the authenticated remote scope before tools are registered or served即服务初始化发生在工具注册之前。服务启动实例化PeekabooMCPServer并serve(transport:port:)退出时统一stopLocalDaemon。Serve还通过PreRuntimeValidatingCommand在运行时创建前校验 browser handoff 的前置条件必须已加载凭证、必须preferRemote、不能请求远程隔离、必须提供--bridge-socket否则抛出BrowserHandoffCLIInputError.localExecutionRefused。对应源码Apps/CLI/Sources/PeekabooCLI/Commands/MCP/MCPCommandServe.swift。参数解析助手MCPArgumentParsing笔记中规划的MCPArgumentParsing在仓库中落地为 Apps/CLI/Sources/PeekabooCLI/Commands/MCP/MCPArgumentParsing.swift提供两个被多处复用的纯函数parseJSONObject(_:)把字符串解析为[String: Any]。空串或null返回空字典非对象 JSON如数组抛出MCPCommandError.invalidArguments。parseKeyValueList(_:label:)把[A1, Btwo]解析为字典键为空或缺均抛错。配套的单元测试 Apps/CLI/Tests/CoreCLITests/MCPArgumentParsingTests.swift 覆盖了四个关键分支JSON 对象解析、null返回空、非对象类型抛错、key/value 列表解析与非法输入拒绝。这正是笔记中Testing gaps: add unit tests for argument parsing的落地成果之一。在调用侧BrowserCommand.arguments()在--mcp-args-json上先调用parseJSONObject做前置校验失败报--mcp-args-json must be a JSON object再原样透传字符串见 BrowserCommand.swift 第 326-333 行。输出格式化MCPToolCommandOutput 与 ResultEnvelope笔记规划了MCPCallFormatter并明确指出下一阶段的目标是把 List/Info 的 JSON 与文本格式化收拢到 formatter 中统一字段命名与顺序。当前仓库中这一职责由MCPToolCommandOutput承担它把每个 MCP 工具调用的ToolResponse统一映射为 CLI 可输出的ResultEnvelope文本模式把MCP.Tool.Content的 text 内容拼接输出图片/音频/资源内容转为占位摘要如[Image: image/png, base64 bytes: N]JSON 模式构造MCPToolCommandPayloadtool、isError、content、text、meta再从响应 meta 中解码DesktopActionOutcome.Projection、target_identity、target_receipt与error_code组装成带success/effect/outcome/target_identity/target_receipt/debug_logs/error的标准信封错误码归一错误时error_code优先级高于推断值无 canonical 元数据时按是否有 outcome 回退为INTERACTION_FAILED或VALIDATION_ERROR退出码策略工具报错默认抛ExitCode(1)也允许显式覆盖。对应源码Apps/CLI/Sources/PeekabooCLI/Commands/MCP/MCPToolCommandOutput.swift以及ResultEnvelope的 JSON 编码入口 Apps/CLI/Sources/PeekabooCLI/CLI/Output/JSONOutput.swift。测试 Apps/CLI/Tests/CoreCLITests/MCPToolCommandOutputTests.swift 验证了三条关键行为默认与显式退出码、成功不抛错、以及browser场景下错误信封如何保留INTERACTION_FAILED/AGENT_EXECUTION_POLICY_REFUSAL/VALIDATION_ERROR等 canonical 错误码与精确目标元数据。遗留问题与后续演进方向归档笔记明确列出了三块待办其中行为保持不变这一点已经达成其余作为后续演进建议保留1. 引入 MCPClientService 门面笔记提出下一步应引入MCPClientService门面包装TachikomaMCPClientManager并共享MCPContext以消除各子命令中残留的RuntimeStorage样板代码、让 mock 注入变得直接。从当前仓库看客户端管理相关的实际实现位于 Core 层Core/PeekabooCore/Sources/PeekabooAgentRuntime/Browser/BrowserMCPService.swift与BrowserMCPSessionManager.swift。CLI 层通过MCPToolContext包含 services、snapshotMutationCoordinator、snapshotExecutionGate、executionAuthority、capturePreflightRefusal来传递依赖RuntimeStorage var runtime: CommandRuntime?仍出现在BrowserCommand中说明消除 RuntimeStorage 样板的目标在 CLI 侧尚未完全收尾。2. 输出渲染收敛笔记建议把 List/Info 的 JSON 文本格式化统一搬进 formatter保证字段命名与顺序一致同时决定 stderr 与 os_log 抑制逻辑是保留还是收进单一 helper。当前MCPToolCommandOutput已承担大部分格式化工作但决定抑制逻辑去留仍是开放决策。3. 错误处理归一笔记指出今天只有 Call 使用CallError建议让所有子命令共享一个映射到ErrorCode的错误类型并复用 key/value 与 JSON 解析 helper。当前实现中MCPCommandError.invalidArguments是参数解析统一错误BrowserCommandInputError实现了ResultEnvelopeError并将envelopeCode归一到VALIDATION_ERROR——归一化方向已经确立但全子命令统一错误类型的收尾仍需继续。4. 测试补齐笔记规划了四类单测参数解析、call 负载序列化、list/info 格式化配合 mock client service外加swift build与 CLI smoke tests。当前仓库已落地参数解析单测MCPArgumentParsingTests与输出信封单测MCPToolCommandOutputTestscall 负载序列化与基于 mock client service 的 list/info 格式化仍属待补项。如何验证当前重构成果对mcp命令本身可用 docs/commands/mcp.md 中的方式快速验证拆分后的行为一致性# 默认进入 servestdio peekaboo mcp # 显式选择传输 peekaboo mcp serve --transport stdio # 前台授权 peekaboo mcp serve --allow-foreground # 受限临时剪贴板 peekaboo mcp serve --allow-temporary-clipboard # 走已有 Bridge 宿主 peekaboo mcp serve --bridge-socket $HOME/Library/Application Support/Peekaboo/bridge.sock需要构建验证时在仓库根目录执行swift buildCLI 目标由 Apps/CLI/Package.swift 声明参数解析与输出格式化的行为回归由上文两个测试文件覆盖。故障排查时可用--json或--verbose展开错误细节并用peekaboo permissions status确认 Screen Recording 与辅助功能权限。小结mcp-command-split.md记录的这次重构是一次典型的行为不变、结构先行的渐进式拆分入口薄化、子命令独立、解析与格式化助手化同时把后续的门面封装、错误归一、测试补齐明确写为下一步计划。对照当前仓库可以看到参数解析与输出格式化两条线已经落地并有单测守护MCPClientService门面与全子命令错误归一仍留作演进空间。对希望参与 Peekaboo CLI 维护的开发者这份笔记连同 docs/archive/refactor/README.md 下的其他重构日志agent-command-split、config-command-split、menu-service-refactor等构成了完整的命令拆分方法论参考。赞分享GUI 自动化MCP 服务AI 应用【免费下载链接】PeekabooPeekaboo is a macOS CLI optional MCP server that enables AI agents to capture screenshots of applications, or the entire system, with optional visual question answering through local or remote AI models.项目地址https://gitcode.com/gh_mirrors/peekaboo6/Peekaboo点击查看免费下载相关推荐Scalene 重构实录从 1885 行巨型 Profiler 到职责清晰的多模块架构Scalene 重构实录从 1885 行巨型 Profiler 到职责清晰的多模块架构 本文以仓库内 refactoring_todo.md https://开发工具性能测试AI 应用PicoClaw Pipeline 重构实践将 1400 行单体 runTurn 拆分为职责清晰的多文件管线PicoClaw Pipeline 重构实践将 1400 行单体 runTurn 拆分为职责清晰的多文件管线 导读 本文基于 PicoClaw 开源仓库中的《人工智能AI 应用AI Agent交互助手工具调用MCP ClientsAgent 记忆picoclaw Agent 流水线重构解析将 1400 行 pipeline.go 拆分为职责清晰的五文件结构picoclaw Agent 流水线重构解析将 1400 行 pipeline.go 拆分为职责清晰的五文件结构 导读 本文基于仓库内 docs/archit人工智能AI 应用AI Agent交互助手工具调用MCP ClientsAgent 记忆上一篇3分钟上手Metabase全格式导出从CSV到PDF的零代码方案下一篇Freqtrade WebUI使用指南可视化交易管理与监控创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考