深色模式
MCP 工具参考
本页是 AgileMedic MCP sidecar(agilemedic-mcp.exe)全部工具的权威清单:名称、用途、参数、返回、是否需授权,均直接对应源码注册。
sidecar 当前共注册 21 个工具:13 个只读(直接可调) + 8 个写操作(执行前经本机 consent 授权,详见 概览)。
读 / 写标识
- 只读 —— AI 可直接调用,不改系统状态;即使 GUI 未运行也能用。
- 需授权(consent) —— 执行前 sidecar 会连 GUI 主程序弹窗,你亲手点"允许"才执行;GUI 未运行则失败不执行。
关于参数默认值
参数值均取自源码 schema。缺省行为(如 find_large_files 默认扫描用户 Home 目录、默认 ≥50MB)在各工具说明中标注。
只读工具
list_processes
列出系统当前所有进程 —— PID、名称、父进程、路径、内存占用、CPU%、签名缓存状态。用于排查异常进程 / 找占内存的进程。
- 参数:无
- 返回:
{ total, processes: [{ pid, parent_pid, name, exe_path, memory_bytes, memory_display, cpu_percent, cpu_display, signature }], signature_summary }cpu_percent = -1表示受保护进程无法读取;首次调用会自动双采样(约 +500ms)以拿到真实 CPU%。signature仅返回已缓存的签名状态,不主动触发验签(避免阻塞);要实际验签用verify_signatures。
get_process_tree
按父子关系构建嵌套进程树,排查"哪个进程拉起了哪些子进程"、可疑派生链。
- 参数:无
- 返回:
{ total, roots: [{ pid, name, children: [...] }] }(森林结构,含防环处理)
get_process_command_line
读取指定 PID 进程的完整命令行(读 PEB),区分同名进程实际跑的参数(哪个 svchost / python / node 是什么)。
- 参数:
| 名 | 类型 | 必填 | 说明 |
|---|---|---|---|
pid | integer | 是 | 目标进程 PID |
- 返回:
{ pid, command_line, note }。受保护 / 系统进程 / 已退出 / 跨位读取失败时command_line为空并在note说明。
list_startup_items
列出注册表 Run 项的开机启动项(HKLM + HKCU),排查启动慢 / 恶意自启。
- 参数:无
- 返回:
{ total, startup_items: [{ name, command, exe_path, source, source_label, source_path, enabled }] }source为hklm/hkcu(传给set_startup_item_enabled用);source_label为人类可读的"系统"/"用户";enabled是 StartupApproved 状态。
list_network_connections
列出当前所有 TCP/UDP、IPv4/IPv6 网络连接 —— 本地/远端地址、状态、PID、进程名。排查异常网络连接 / 找哪个进程在占端口。
- 参数:无
- 返回:
{ total, tcp_count, udp_count, ipv6_count, connections: [{ protocol, ip_version, local, remote, state, pid, process_name }] }
find_process_by_port
查指定端口被哪个进程占用(只读)。用于排查"端口被占,dev server 起不来"。要结束占用进程用 kill_by_port。
- 参数:
| 名 | 类型 | 必填 | 说明 |
|---|---|---|---|
port | integer | 是 | 要查询的本地端口号(1–65535) |
- 返回:
{ port, matches, connections: [{ protocol, ip_version, local, remote, state, pid, process_name }] }
list_services
列出系统全部 Windows 服务(SCM API)—— 名称、显示名、描述、状态、启动类型、PID、二进制路径。仅读取;启动/停止/改类型走独立授权工具。
- 参数:无
- 返回:
{ total, running, entries: [{ name, display_name, description, binary_path, state, start_type, pid }] }
list_uninstall_entries
列出已安装软件(从 Uninstall 注册表读)—— 名称、版本、发布者、安装位置、估算大小。盘点已装软件 / 找占空间的程序。
- 参数:无
- 返回:
{ total, entries: [{ display_name, display_version, publisher, install_location, uninstall_string, size_kb, size_display, source }] }
find_large_files
在指定目录递归找大文件,按大小降序返回 top N。找占空间的文件(老旧安装包/缓存/日志)。同步扫描可能耗时 5–30 秒。
- 参数:
| 名 | 类型 | 必填 | 说明 |
|---|---|---|---|
root_path | string | 否 | 扫描根目录(绝对路径)。默认为用户 Home 目录 |
min_size_bytes | integer | 否 | 最小文件大小(字节)。默认 52428800(50MB) |
max_results | integer | 否 | 返回的 top N 数量。默认 50 |
- 返回:
{ scanned_files, hit_count, root_path, min_size_bytes, files: [{ path, size_bytes, size_mb }] } - 进度:支持 SSE 中间进度(每扫约 500 个文件推一次)。
scan_junk
扫描可清理的磁盘垃圾(只读)—— 约 30 个分类,按 group 分三组:system(临时/日志/转储/缩略图/更新缓存)、browser(Chrome/Edge/Firefox 缓存)、devtools(npm/pip/gradle/cargo/uv/JetBrains/Maven 等开发缓存,开发机大头)。
- 参数:无
- 返回:
{ category_count, total_size_bytes, total_size_mb, total_file_count, categories: [{ category_id, category_name, group, description, safety, size_bytes, size_mb, file_count, sample_paths }], note }safety为safe(绝对安全删)或caution(有副作用:更新需重下 / 索引重建 / 依赖重下)。- 清理用
clean_junk传回这里拿到的category_id;browser 类清理前需关闭对应浏览器。
verify_signatures
对 exe 文件做 Windows Authenticode 数字签名验证(只读)。排查可疑进程(未签名 / 签名无效的 exe 风险高)。首次验签每文件约 50–300ms,缓存命中秒回(结果跨会话持久化,mtime 未变直接复用);验全部进程可能耗时数十秒。
- 参数:
| 名 | 类型 | 必填 | 说明 |
|---|---|---|---|
paths | string[] | 否 | 要验签的 exe 绝对路径数组。留空 = 验当前全部进程的 exe |
only_suspicious | boolean | 否 | 默认 false。true = results[] 仅返回非"已签名"条目(签名无效/未签名/未知),计数仍含全部,极大省 token |
include_signer | boolean | 否 | 默认 false。true = 对有签名条目额外返回 signer(签名者证书主体名,如 "Microsoft Corporation"),区分微软官方 vs 第三方 |
- 返回:
{ total, trusted, untrusted, unsigned, unknown, results: [{ path, signature, signer? }] } - 进度:支持 SSE(每验 20 个推一次)。
get_system_metrics
采集当前系统实时指标 —— CPU%、物理内存(占用%/已用/总量)、提交内存(commit charge 承诺值/上限/占比)、磁盘忙率与读写速率、网络收发速率。即时采样约 250ms。用于回答"电脑卡不卡 / 内存紧不紧"。
- 参数:无
- 返回:
{ cpu_percent, memory_percent, memory_used_bytes, memory_total_bytes, memory_display, commit_percent, commit_charge_bytes, commit_limit_bytes, commit_display, disk_percent, disk_read_kbs, disk_write_kbs, net_recv_kbs, net_send_kbs, commit_note }
关于"清理内存"的误区
返回里的 commit_note 提醒:提交内存(commit charge)是 OS 的承诺计数器,非物理占用,无法"清理";逼近上限(commit_percent > 90)才是真风险。物理内存占用高常是正常缓存,不应建议用户"清理内存"。
get_app_info
返回 AgileMedic 自身的元信息 —— 版本、平台、Qt 版本、数据目录、可执行路径。AI client 初次握手后建议先调一次了解上下文。
- 参数:无
- 返回:
{ name, version, organization, platform, kernel_version, qt_version, data_dir, executable, description }
写工具(需授权 consent)
以下工具都会改变系统状态
每个写工具执行前,sidecar 会通过命名管道 agilemedic-consent-v1 连 GUI 主程序弹窗,展示操作内容 + 影响范围 + AI 传入的 reason。你亲手点"允许"才执行;拒绝、120 秒无响应、或 GUI 未运行 → 操作不执行,返回错误(isError)。
所有写工具都接受一个可选的 reason 字符串参数 —— AI 执行操作的理由,会显示在授权弹窗里。
kill_process 🔒
强制结束指定 PID 的进程。建议先用 list_processes 确认目标。
- 参数:
| 名 | 类型 | 必填 | 说明 |
|---|---|---|---|
pid | integer | 是 | 要结束的进程 PID |
reason | string | 否 | 结束理由,展示在授权弹窗中 |
- 安全兜底:拒绝结束系统关键进程(System Idle Process / System,PID 0 / 4)和 AgileMedic 自身;PID 不存在时报错。
- 返回:
{ killed, pid, process_name, message }
kill_by_port 🔒
结束占用指定端口的所有进程。建议先用 find_process_by_port 确认目标。
- 参数:
| 名 | 类型 | 必填 | 说明 |
|---|---|---|---|
port | integer | 是 | 要释放的本地端口号(1–65535) |
reason | string | 否 | 理由,展示在授权弹窗中 |
- 安全兜底:跳过 System/Idle(PID 0/4)与 AgileMedic 自身;端口无可结束进程时报错。
- 返回:
{ port, killed_count, failed_count, killed: [...], failed: [...] }
unlock_file 🔒
解锁被占用的文件/文件夹 —— 关闭占用它的进程句柄(Restart Manager)。文件未被任何进程占用时直接返回成功(无需授权弹窗)。
- 参数:
| 名 | 类型 | 必填 | 说明 |
|---|---|---|---|
path | string | 是 | 要解锁的文件或文件夹绝对路径 |
reason | string | 否 | 理由,展示在授权弹窗中 |
- 返回:
{ unlocked, path, closed_processes: [{ pid, app_name, exe_path }], message }
clean_junk 🔒
清理指定分类的磁盘垃圾 —— 把内容移到回收站(可恢复)。先用 scan_junk 拿 category_id。
- 参数:
| 名 | 类型 | 必填 | 说明 |
|---|---|---|---|
category_ids | string[] | 是 | 要清理的分类 id 数组(来自 scan_junk),如 ["user_temp","crash_dumps"] |
reason | string | 否 | 理由,展示在授权弹窗中 |
- 安全兜底:清理前重新扫描拿最新路径;
browser类若对应浏览器进程正开着则跳过该分类并在skipped说明;safety=caution的分类建议 AI 先向用户说明副作用。文件走回收站可恢复。 - 返回:
{ cleaned, freed_bytes, freed_mb, file_count, categories: [...], skipped: [...], message }
set_startup_item_enabled 🔒
启用或禁用一个开机启动项(写 StartupApproved\Run 注册表,与任务管理器同款机制)。用 list_startup_items 拿 source/name 后再调。
- 参数:
| 名 | 类型 | 必填 | 说明 |
|---|---|---|---|
source | string | 是 | hklm(系统级)或 hkcu(用户级) |
name | string | 是 | 注册表 value 名(启动项名称,大小写敏感) |
enabled | boolean | 是 | true=启用,false=禁用 |
reason | string | 否 | 理由,展示在授权弹窗中 |
- 注意:HKLM 项需以管理员身份运行 AgileMedic 才能写入;若目标已是目标状态则直接返回
changed:false,不弹窗。 - 返回:
{ changed, source, name, enabled, message }
start_service 🔒
启动一个已停止的 Windows 服务(StartServiceW)。需管理员权限。已运行则直接返回。用 list_services 拿 name 后再调。
- 参数:
| 名 | 类型 | 必填 | 说明 |
|---|---|---|---|
name | string | 是 | 服务键名(非显示名),来自 list_services |
reason | string | 否 | 理由,展示在授权弹窗中 |
- 返回:
{ changed, name, message }
stop_service 🔒
停止一个运行中的 Windows 服务(ControlService)。需管理员权限。已停止则直接返回。注意:依赖此服务的功能可能失效。
- 参数:
| 名 | 类型 | 必填 | 说明 |
|---|---|---|---|
name | string | 是 | 服务键名,来自 list_services |
reason | string | 否 | 理由,展示在授权弹窗中 |
- 返回:
{ changed, name, message }
set_service_start_type 🔒
设置 Windows 服务启动类型(ChangeServiceConfigW)。需管理员。下次启动生效,不影响当前运行状态。引导/系统驱动不可改。
- 参数:
| 名 | 类型 | 必填 | 说明 |
|---|---|---|---|
name | string | 是 | 服务键名,来自 list_services |
start_type | string | 是 | auto(自动)/ auto_delayed(自动延迟)/ manual(手动)/ disabled(禁用) |
reason | string | 否 | 理由,展示在授权弹窗中 |
- 注意:若启动类型已是目标值则直接返回
changed:false,不弹窗。 - 返回:
{ changed, name, start_type, message }
MCP 协议方法
sidecar 实现了 MCP 最小方法集(供了解链路,非工具):
| 方法 | 作用 |
|---|---|
initialize | 协议握手,返回 capabilities / serverInfo |
notifications/initialized | client 通知 server(无响应) |
tools/list | 列出全部注册工具 |
tools/call | 调用一个工具,返回 content[] |
ping | 健康检查 |
协议版本对齐 MCP spec 2024-11-05,stdio 传输为 newline-delimited JSON(NDJSON)。
下一步
- 反向 MCP Server 概览 —— 工作原理与 consent 安全机制
- 接入 Claude Desktop
- 接入 Cursor 及其他编辑器