反向 MCP Server 概览

MCP (Model Context Protocol) 是 Anthropic 在 2024 年推出的开放协议,让 AI 客户端(Claude Desktop / Cursor / Cline 等)可以调用外部工具,就像浏览器装插件一样扩展能力。

大多数应用接入 MCP 是为了"让 AI 帮自己干活"。AgileMedic 走的是反向的路子:

什么是"反向 MCP"

AgileMedic 自己是一个 MCP Server,把你这台电脑的系统状态做成一组工具,暴露给外部 AI 客户端。接入之后,Claude / Cursor 里的 AI 可以直接读你的电脑 —— 进程、资源占用、网络连接、启动项、已装软件、磁盘垃圾 —— 然后自己给出诊断结论。

方向不是"AI 让 AgileMedic 干活",而是**"让 AI 读你的系统"。这是与 AgileShot 类似的 MCP 独占能力,但 AgileShot 暴露的是屏幕截图,AgileMedic 暴露的是系统洞察**。

一句话对比:

• 打开 AgileMedic GUI → 你自己看进程、清垃圾、管服务。
• 接入 AgileMedic MCP → AI 替你读这些数据,自己诊断"电脑为什么卡",必要时(经你点头)动手清理。

为什么是独立 sidecar

AgileMedic 的 MCP 能力不是主程序加一个 --mcp 参数,而是一个独立的小二进制 agilemedic-mcp.exe,随安装包一起附带,和主程序 agile-medic.exe 放在同一目录。

外部 AI 客户端 spawn(拉起)的就是这个 agilemedic-mcp.exe,而不是 GUI 主程序。

为什么要独立进程

1. 进程身份清晰 —— 任务管理器里 agilemedic-mcp 与 GUI 的 agile-medic 一眼区分,不会出现"一堆 agile-medic.exe"让你误以为 GUI 多开了。
2. 物理上不可能弹窗 —— sidecar 不链接任何窗口/托盘代码,它根本没有 GUI,只在 stdio 上跑 JSON-RPC。
3. 读操作自包含 —— 列进程、扫垃圾等只读工具直接读操作系统,即使 GUI 没开也能用。

这是对齐 AgileShot 的 agileshot-mcp 独立进程模式的设计。区别是:AgileShot 的 sidecar 是纯转发器(工具依赖 GUI 运行态,所有调用转发给 GUI 执行);AgileMedic 的 sidecar 是自包含的 —— 只读工具自己直接读系统,只有写操作才需要联系 GUI 授权。

工作原理

传输层是 line-delimited JSON-RPC 2.0 over stdio(每行一条 JSON,无 Content-Length 头,即 NDJSON)。协议版本对齐 MCP spec 2024-11-05。

┌────────────────────┐   stdio JSON-RPC   ┌────────────────────────┐
│  Claude Desktop /   │ ◄────────────────► │  agilemedic-mcp.exe    │
│  Cursor / Cline …   │   (NDJSON 2.0)     │  (独立 MCP sidecar)     │
└────────────────────┘                    └───────────┬────────────┘
        │                                              │
        │ "我电脑有点卡, 帮我看看"                        │  ┌─── 只读工具 ───┐
        │ ────────────────────────────────────────────►│  │ 直接读 OS:      │
        │                                              │──┤ 进程/网络/服务/  │
        │                                              │  │ 垃圾/大文件/指标 │
        │                        ◄─────────────────────│  └───────────────┘
        │  收到系统快照 → AI 分析 → 给你诊断结论           │
        │                                              │  ┌─── 写工具 ─────┐
        │ "那把这个占资源的进程结束掉"                    │  │ 走 consent:     │
        │ ────────────────────────────────────────────►│──┤ named pipe 连   │
        │                                              │  │ GUI 弹窗授权     │
        │              ┌──────────────────────┐        │  └───────┬───────┘
        │              │  agile-medic.exe(GUI) │◄───────┼─────────┘
        │              │  ConsentService 弹窗   │        │  命名管道:
        │              │  用户点"允许/拒绝"      │────────►│  agilemedic-consent-v1
        │              └──────────────────────┘        │
        ▼                                              ▼

只读过程完全无感:AI 自己拿数据、自己分析、自己回答,你什么都不用点。 写操作必须经过下方的 consent 授权,AI 不能背着你动手。

真实工具一览

sidecar 当前注册了 21 个工具:13 个只读、8 个需授权。工具名和参数以本表 + 工具参考为权威来源。

只读工具(直接可调,无需授权)

工具名	用途
list_processes	列出全部进程:PID / 父进程 / 路径 / 内存 / CPU% / 签名缓存
get_process_tree	按父子关系构建嵌套进程树,排查可疑派生链
get_process_command_line	读指定 PID 的完整命令行(区分同名 svchost/python/node)
list_startup_items	列出注册表 Run 开机启动项(HKLM + HKCU)
list_network_connections	列出全部 TCP/UDP、IPv4/IPv6 连接及占用进程
find_process_by_port	查某端口被哪个进程占用("dev server 起不来")
list_services	列出全部 Windows 服务(状态 / 启动类型 / PID)
list_uninstall_entries	列出已安装软件(名称 / 版本 / 发布者 / 大小)
find_large_files	在指定目录递归找大文件,按大小降序 top N
scan_junk	扫描可清理磁盘垃圾(system / browser / devtools 三组)
verify_signatures	对 exe 做 Authenticode 数字签名验证(排查可疑进程)
get_system_metrics	采集实时指标:CPU / 内存 / 提交内存 / 磁盘 / 网络速率
get_app_info	返回 AgileMedic 自身版本 / 平台 / Qt 版本 / 数据目录

写工具(执行前必须经用户授权)

工具名	用途	安全兜底
kill_process	强制结束指定 PID 的进程	拒绝结束系统关键进程与自身
kill_by_port	结束占用指定端口的全部进程	跳过 System/Idle 与自身
unlock_file	关闭占用某文件的进程句柄(Restart Manager)	未被占用直接返回
clean_junk	把指定垃圾分类移到回收站(可恢复)	浏览器进程开着时跳过
set_startup_item_enabled	启用/禁用一个开机启动项	HKLM 项需管理员
start_service	启动一个已停止的 Windows 服务	需管理员
stop_service	停止一个运行中的 Windows 服务	需管理员
set_service_start_type	修改服务启动类型(自动/手动/禁用)	需管理员,下次启动生效

每个工具的完整参数、返回字段、是否需 consent,见 工具参考。

典型用例

用例 1:AI 帮你诊断"电脑为什么卡"

你: 我电脑最近特别卡,帮我看看怎么回事。

AI:(调用 get_system_metrics 看 CPU/内存/提交内存 → list_processes 找占资源的进程 → 必要时 get_process_command_line 看它到底跑的什么)→ "有个 node.exe(PID 12480)吃了 4.2 GB 内存,命令行显示是某个卡住的构建进程,建议结束它。"

用例 2:AI 帮你查"端口被谁占了"

你: 我的 dev server 起不来,说 3000 端口被占用了。

AI:(调用 find_process_by_port(port=3000))→ "3000 端口被 python.exe(PID 8820)占用。要我帮你结束它吗?" →(你同意后调 kill_by_port,GUI 弹窗你再点一次"允许")

用例 3:AI 帮你排查可疑进程

你: 我怀疑电脑中招了,有没有可疑程序在跑?

AI:(调用 verify_signatures(only_suspicious=true) 只看未签名/签名无效的 exe → 对可疑项 get_process_command_line 看行为)→ 列出没有有效数字签名的进程供你判断。

用例 4:AI 帮你清理磁盘垃圾

你: C 盘满了,帮我清一下没用的缓存。

AI:(调用 scan_junk 看各分类可释放空间 → 向你说明 safety=caution 的分类有什么副作用)→ "可以安全释放约 8.6 GB,其中 npm/pip 开发缓存 5.1 GB。要清理吗?" →(你同意后调 clean_junk,GUI 弹窗再确认一次,文件移到回收站可恢复)

consent 安全机制

写操作不能被 AI 背着你执行

所有会改变系统状态的工具(结束进程、清理文件、改服务/启动项)在真正执行前,都会经过本机 consent(授权) 流程:

1. sidecar 通过固定名命名管道 agilemedic-consent-v1 连接 GUI 主程序 agile-medic.exe。
2. GUI 弹出授权对话框,展示操作内容 + 影响范围 + AI 给出的理由。
3. 你必须亲手点"允许",操作才会执行;点"拒绝"或 120 秒无人响应则自动拒绝。
4. GUI 未运行时授权失败,动作不执行(fail-safe)—— AI 拿不到"绕过授权"的路径。

也就是说:只读随便看,动手必问你。

consent 弹窗对每个写操作都会显示:

• 具体做什么(如"强制结束进程「node.exe」(PID 12480)")
• 影响细节(可执行路径、内存占用、注册表位置等)
• AI 传入的 reason 字段(AI 为什么要做这件事)

兼容客户端

一键接入(见 mcpserverpanel)数据驱动地支持以下 7 类客户端:

客户端	兼容状态	配置格式	备注
Claude Desktop	完全兼容	mcpServers JSON	官方 MCP 客户端
Claude Code (CLI)	完全兼容	mcpServers JSON	支持多实例(全局 + 各实例)
Cursor	完全兼容	mcpServers JSON	内置 MCP 支持
Cline (VS Code)	完全兼容	mcpServers JSON	结构同 Cursor
Codex (OpenAI CLI)	完全兼容	[mcp_servers.*] TOML	支持多实例
Zed	完全兼容	context_servers JSON	command 为嵌套对象
OpenCode	完全兼容	mcp JSON(数组式)	type: "local"
自研 Agent	兼容	标准 JSON-RPC 2.0	任何能起子进程通信的 Agent

一键接入会自动把 entry 写进对应 client 配置(写前 .bak 备份、保留你其他内容),并做三态检测(未接入 / 已接入 / 路径失效需重装)。

安全说明

接入前请了解

• 只读工具能读到你系统的全貌 —— 进程、网络连接、已装软件、文件路径等。接入前请确认你信任该 AI 客户端。
• 写操作永远需要你亲手授权 —— 但请认真看 consent 弹窗内容,不要无脑点"允许"。
• sidecar 不联网、不上传 —— 它只在本机 stdio 上响应 AI 客户端,系统数据是否离开本机取决于你用的 AI 客户端本身。
• 不想用时可随时取消接入 —— 在 MCP 面板点"取消接入",或在 client 配置里删掉 entry。

关于隐私边界的更多说明见 隐私设置。

下一步

• 接入 Claude Desktop —— 一键接入或手动配置
• 接入 Cursor —— Cursor / Cline 等编辑器
• 工具参考 —— 每个工具的完整参数与返回
• 想在 AgileMedic 里面用 AI 诊断(而非反向暴露给外部 AI),见 AI 诊断 与 AI 配置