内容
# AI 进程管理器 — MCP 服务器
**用于 AI 代理的结构化 Windows 状态 — 无截图。**
本 MCP 服务器将 [AI 进程管理器](https://github.com/agorapassadoagora-debug/AIPM) 的本地 HTTP API 公开为 Claude Desktop、Cursor 和任何 MCP 客户端的工具。代理读取 **JSON 和文本**（每个查询约 15-150 个令牌）来自进程、窗口、控制台和 UI 自动化树，而不是捕获像素（每张 1080p 截图约 2765 个令牌）。
> **需要：** 在 Windows 上运行的 AIProcessManager.exe（系统托盘）。Node.js ≥ 14。零 npm 依赖。
<!-- mcp-name: io.github.agorapassadoagora-debug/AIPM -->
## 为什么存在
计算机使用代理通常通过截图“查看”桌面。这很慢（3-5 秒），令牌消耗高，并且通过模型发送像素数据。AIPM 在环回上回答结构化问题：
| 问题 | 截图 | AIPM 工具 |
| --- | --- | --- |
| 渲染是否仍在运行？ | ~2765 个令牌 | `check_process` → ~15 个令牌 |
| 控制台输出是什么？ | 截图 + OCR | `read_window` → ~30 个令牌 |
| 导出是否完成？ | 轮询 + 截图 | `wait_for(file_stable=...)` → 一次调用 |
在真实机器上测量：**每个操作减少约 94-98% 的感知令牌**，与截图相比。
## 快速开始
### 1. 启动后端
确保 `AIProcessManager.exe` 在系统托盘中运行。
### 2. 配置您的 MCP 客户端
**Claude Desktop** — `claude_desktop_config.json`:
```json
{
"mcpServers": {
"ai-process-manager": {
"command": "node",
"args": ["C:\\path\\to\\ai-process-manager\\mcp\\server.js"]
}
}
}
```
Cursor 和其他 stdio MCP 客户端使用相同的 `command` / `args` 对。 可选环境变量 `AIPM_API` 覆盖 API 基本 URL（默认：从 `%LOCALAPPDATA%\AIProcessManager\endpoint.txt` 读取，否则为 `http://127.0.0.1:9147`）。
### 3. 重启 MCP 客户端
工具显示为 `ai-process-manager`。首先调用 `health_check`。
## 工具（20）
读取工具被注释为 `readOnlyHint: true` — 客户端可能会自动批准它们。操作工具为 `readOnlyHint: false`，除非用户选择加入（参见 [隐私](#隐私)），否则拒绝运行。
| 工具 | 标题 | 端点 |
| --- | --- | --- |
| `health_check` | 检查 AI 进程管理器状态 | `GET /` |
| `check_process` | 检查进程是否正在运行 | `GET /processes` |
| `list_processes` | 列出正在运行的进程 | `GET /processes` |
| `list_windows` | 列出打开的窗口 | `GET /windows` |
| `get_system_status` | 获取系统状态（CPU、RAM、GPU、磁盘） | `GET /system` |
| `get_taskbar` | 显示任务栏应用 | `GET /taskbar` |
| `read_window` | 从窗口读取文本 | `GET /window/text` |
| `get_ui_tree` | 获取窗口的 UI 元素树 | `GET /ui/tree` |
| `ui_find` | 查找交互式 UI 元素 | `GET /ui/find` |
| `wait_for` | 等待满足条件 | `GET /wait` |
| `get_recent_events` | 列出最近的 PC 事件 | `GET /events/history` |
| `check_file` | 检查文件或文件夹 | `GET /filesystem/watch` |
| `get_app_knowledge` | 获取应用的学习配方 | `GET /knowledge/app` |
| `get_economy_stats` | 获取代币经济统计 | `GET /analytics/summary` |
| `get_audit_log` | 查看 API 审计日志 | `GET /audit` |
**操作层级 — 需要选择加入，默认关闭：**
| 工具 | 标题 | 端点 |
| --- | --- | --- |
| `ui_invoke` | 点击 UI 元素 | `POST /ui/invoke` |
| `ui_set_value` | 设置 UI 字段的值 | `POST /ui/set_value` |
| `focus_window` | 将窗口带到前台 | `POST /ui/focus` |
**本地遥测（仅写入本地存储，元数据）：**
| 工具 | 标题 | 端点 |
| --- | --- | --- |
| `report_task_outcome` | 报告任务结果（遥测） | `POST /telemetry/task` |
| `report_action_outcome` | 报告 UI 操作结果（遥测） | `POST /telemetry/action` |
### 读取深 UI 树（Chromium/Electron）
`get_ui_tree` 默认 `depth=4`，对于原生 Win32 应用足够。Chromium/Electron 应用（VS Code、Slack、Discord、Claude Desktop、Teams）在 ~10 级 `Pane`/`Group` 包装器下隐藏内容 — 在低深度下，响应只有空面板。请求 `depth=15-20`（最大 30）并使用 `max_nodes`（默认 200，最大 1000）限制成本： **`max_nodes` 是成本刹车，不是 `depth`。** 当响应为 `truncated: true` 时，树被剪切 — 在得出窗口的任何结论之前，请使用更高的 `depth`/`max_nodes` 重复。
## 隐私
**没有任何数据离开机器。没有远程遥测，没有云服务，也没有账户。**
### 网络
- 后端仅监听 **环回接口** (`127.0.0.1:9147`) — 而不是 `0.0.0.0`，因此 LAN 上没有任何东西可以访问它。
- 每个请求都必须带有 `Host` 头部，值为 `localhost` 或 `127.0.0.1`；否则会被 `403 forbidden_host` 拒绝（反 DNS 绑定，因此您访问的网页无法驱动 API）。
- 此 MCP 服务器仅进行一种类型的 outbound 调用：到本地地址的 HTTP 调用。它发送一个 `User-Agent`，值为 `mcp:<您的 MCP 客户端名称>`，因此本地审计日志显示哪个代理提出了请求。
### 默认只读
- 20 个工具中有 15 个是纯 `GET` 读取，注释为 `readOnlyHint: true`。
- 3 个操作工具 (`ui_invoke`、`ui_set_value`、`focus_window`) 在用户执行 **两步操作** 之前返回 `403 action_denied`：在托盘菜单中启用 *代理操作*，并将目标进程添加到每个应用的允许列表中。两者默认均关闭，设置按应用进行 — 允许记事本不允许浏览器。
### 遥测存储的内容 — 仅元数据
记录：应用/进程名称、元素角色 (`Button`、`Edit`…)、代理请求的 **元素名称**、操作 (`invoke`/`set_value`/`focus`)、成功或失败、持续时间（毫秒）和失败原因。两个机械不变性使“仅元数据”可验证，而不是承诺：
1. **操作记录存储代理请求的内容，而不是应用显示的内容。** 角色和名称来自代理自己的 `role=`/`name_contains=` 参数。屏幕上实际解析的元素名称永远不会被写入，因此工具 *看到* 的内容永远不会成为遥测数据。
2. **失败原因是封闭词汇表** (`elemento_nao_encontrado`、`ui_timeout`、`erro_uia`、`outro`，…) 。任何其他字符串存储为 `outro`。异常消息 — 可能携带文件路径或屏幕文本 — 因此无法到达磁盘。
**永远不会存储：** 屏幕内容、`read_window` 读取的窗口文本、`ui_set_value` 输入的文本 (`value=`)、文件内容、按键、截图。被动学习 UI 形状 (`ui_shape`) 仅包含计数、UIA 角色名称、深度和布尔值：`exposes_text` 表示 *是否存在* 文本，`named_controls` 表示 *有多少* 元素具有名称 — 永远不会是文本本身。
**掩码：** 在记录任何请求之前，`value=` 和 `api_key=` 被替换为 `***`，因此 `get_audit_log` 或磁盘查询日志都无法透露输入的文本或机密。
**一个诚实的细微差别：** 审计/查询日志存储请求行，因此 *其他* 查询参数保持可读 — 例如 `check_file(path=D:/videos/out.mp4)` 记录为该路径，`check_process(title_contains=...)` 保留该片段。这是代理请求的本地日志。只有 `value=` 和 `api_key=` 被掩码。
### 数据存储位置以及如何删除
所有内容都位于 `%LOCALAPPDATA%\AIProcessManager\` 下：
| 路径 | 内容 |
| --- | --- |
| `db\*.jsonl`、`db\rollup.json` | 遥测：任务、操作、查询、UI 形状、计数器 |
| `ledger.jsonl` | 已报告/执行的操作的防篡改哈希链日志（仅元数据） |
| `actions.cfg` | 操作层是否开启 + 每个应用的允许列表 |
| `log.txt`、`endpoint.txt` | 应用日志和当前使用的 API 地址 |
要擦除：从托盘退出应用，然后删除文件夹（或仅删除 `db\` 以重置学习和经济计数器；删除 `actions.cfg` 会将操作层关闭）。没有任何数据写入其他地方， `/audit` 环形缓冲区仅存在于内存中 — 当应用关闭时，它就会消失。您可以使用 `get_audit_log`、`get_economy_stats` 和 `GET /analytics/actions` 检查存储的内容。
## 故障排除
| 症状 | 含义 | 修复 |
| --- | --- | --- |
| `connection_refused` | AIProcessManager.exe 未运行 | 从“开始”菜单启动它（绿色托盘图标） |
| `action_denied` | 操作层关闭，或应用不在允许列表中 | 托盘菜单 → *代理操作*，然后允许该应用 |
| `api_paused` | 用户从托盘暂停了 API | 托盘菜单 → *恢复 API* |
| 空 `Pane` 树 | `depth` 对于 Chromium/Electron 应用太低 | 重试 `get_ui_tree`，使用 `depth=17` |
每个错误载荷都带有 `next_action` 字段，提供相同的指导。
## 覆盖范围（有测量，诚实）
| 堆栈 | 读取状态 | 语义操作 |
| --- | --- | --- |
| Win32 / WinForms / WPF / UWP | ✅ 完整 | ✅ |
| **Delphi VCL**（旧商业应用） | ✅ 完整 | ✅ |
| 控制台（cmd、PowerShell、Windows Terminal） | ✅ 文本 | — |
| **Chromium / Electron**（Chrome、Cursor、Claude Desktop） | ✅ 唤醒后 | ✅ |
| Electron 在旧的 MSAA 桥上（例如 Discord） | ⚠️ 唤醒，但 ~120 ms/节点 — 目前太慢 | ⚠️ |
| Java Swing | ⚠️ 需要 Java 访问桥 | 路线图 |
我们故意发布尚不可用的内容 — 在依赖它之前，您应该了解边缘情况。
> **行为注意：** Chromium/Electron 窗口的首次读取会要求它激活其可访问性树 — 与屏幕阅读器相同的标准请求。然后，该应用保持计算可访问性数据（该应用的 CPU 成本），并且不会自行恢复休眠。原生 Win32 应用不受影响。
## 免费 vs 付费
- **免费 & 开源（MIT）：** 此 MCP 服务器。
- **免费（封闭源代码）：** `AIProcessManager.exe` 后端 — 传感器。您免费使用。
- **付费：** **AIPM Pilot**，使用 AIPM 的结构化感知驱动应用端到端。参见 [promoflix.site](https://promoflix.site)。
## 支持项目
如果 AIPM 为您节省了令牌，请考虑 [赞助](https://github.com/sponsors/agorapassadoagora-debug)。
## 许可证
MCP 服务器使用 [MIT](LICENSE) 许可证。后端和 AIPM Pilot 是单独的产品。
