Pc Reviewer

PC审阅器LLM（自定义GPT+MCP连接器）

一个谨慎的只读PC审阅器，允许chatgpt.com上的自定义GPT检查您的机器（磁盘使用情况、大文件、缓存、Docker使用情况、顶级进程），并提出优先清理计划。您可以完全控制：破坏性行为是按命令选择和门控的。

协议

• 协议： 通过WebSocket的模型上下文协议（MCP）（远程MCP）
• 服务器： Python+FastAPI+websockets；跨平台（macOS/Linux；计划使用Windows）
• 连接器： ChatGPT自定义GPT→ 此服务器的MCP连接器
• 安全模型： 默认情况下为只读；可选的 exec.run 在明确的用户批准和分配列表背后

为什么存在

本地磁盘充满了构建工件、缓存、模拟器数据、容器和日志。“更干净”的应用程序不透明且有风险。此项目将LLM保留在您的计算机之外，并仅公开生成可验证和批准的计划的狭窄、可审计的工具。

特性

只读工具

• fs.du(path, depth) --目录大小
• fs.bigfiles(path, min_size, limit) --最大的文件
• pkg.caches() --Homebrew/npm/pip缓存大小
• docker.df() --Docker大小信息
• proc.top(limit) --顶级内存/CPU进程

清理计划（LLM输出）按GB进行YAML排名，并释放基本原理、风险级别、模拟运行命令、验证和回滚。

护栏

• 拒绝删除 ~/Documents, ~/Pictures, ~/Desktop 默认情况下
• 试运行/报告第一个命令
• 可选的 exec.run 默认情况下，该工具处于关闭状态
• 可审计性：每个工具调用和批准的命令都是可记录的

建筑

flowchart TD
    subgraph Remote
        A["ChatGPT Custom GPT
('PC Reviewer')
- uses MCP tools"]
        A --> C["YAML Cleanup Plan
(sorted by GB freed)"]
    end
    subgraph Local["Your Computer"]
        B["MCP Server
(runs locally)
- /mcp websocket
- read-only tools"]
        D["Your Machine
(read-only first)"]
    end
    A  |wss| B
    B --> |"OS utilities: du, find, ps, docker"| D

回购布局

pc-reviewer-mcp/
├─ README.md
├─ src/
│  ├─ mcp_server.py          # WebSocket MCP endpoint + tool registry
│  ├─ tools/
│  │  ├─ fs_tools.py         # du, bigfiles
│  │  ├─ pkg_tools.py        # brew/npm/pip caches
│  │  ├─ docker_tools.py     # docker df
│  │  ├─ proc_tools.py       # top processes (psutil)
│  │  └─ exec_tool.py        # optional, disabled by default
│  └─ logging_middleware.py  # request/response logging, redaction
├─ requirements.txt
├─ .env.example              # PORT, ALLOWLIST paths, etc.
├─ Makefile                  # dev targets (run, lint, test)
├─ scripts/
│  └─ dev-tunnel.sh          # ngrok/cloudflared quick-start
├─ tests/
│  ├─ test_fs_tools.py
│  ├─ test_pkg_tools.py
│  └─ test_protocol.py
├─ .github/
│  ├─ ISSUE_TEMPLATE.md
│  └─ workflows/ci.yml
└─ LICENSE

快速启动

1.先决条件

• Python 3.10+
• macOS或Linux（Windows支持在问题中跟踪）
• 可选：Docker桌面（如果你愿意 docker.df)
• 如果您在本地运行，则使用隧道工具（ngrok或cloudflared）

2.安装并运行

git clone https://github.com/your-org/pc-reviewer-mcp.git
cd pc-reviewer-mcp
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

# Start server (defaults: 0.0.0.0:8765, ws route /mcp)
uvicorn src.mcp_server:app --host 0.0.0.0 --port 8765

可选：安全暴露

# Example: cloudflared (no account needed for quick tunnel)
cloudflared tunnel --url http://localhost:8765
# Note WSS URL (e.g., wss://random.trycloudflare.com/mcp if you map /mcp path)

3.在ChatGPT中创建MCP连接器（团队/企业/Edu）

1. 在ChatGPT中： 设置→ 连接器→ 添加自定义连接器
2. 类型： 远程MCP（WebSocket）
3. 网址： wss:///mcp
4. 姓名： PC审阅者
5. 保存。

4.创建自定义GPT

1. ChatGPT 探索→ 创建GPT→ 配置
2. 连接器：启用 PC审阅者.
3. 说明（粘贴）：

You are a cautious PC Reviewer. Use the MCP tools:
- fs.du(path, depth)
- fs.bigfiles(path, min_size, limit)
- pkg.caches()
- docker.df()
- proc.top(limit)

Workflow:
1) Gather facts using tools.
2) Output a YAML CLEANUP PLAN sorted by estimated GB freed (descending). Each action includes:
   - title, rationale, est_space_gb, risk (Low/Medium/High)
   - commands.macos / linux / windows (prefer dry-run/report-first)
   - verification steps and rollback notes
3) Never propose deleting Documents/Pictures/Desktop unless user explicitly asks.
4) If an execution tool exists, require user to type APPROVE "" before any destructive action.

1. 保存。

使用它

询问您的GPT：

• “扫描我的主文件夹至深度2，显示最重的25个目录。”
• “在~/Downloads中列出超过500MB的文件（限制150个）。”
• “估计缓存清理（brew/npm/pip）和Docker节省。”
• “起草一份只包含模拟运行命令的清理计划。”

你会得到一个排名的YAML计划。将您同意的命令复制/粘贴到终端中，或启用可选 exec.run 稍后工具。

可选：选择加入执行工具

默认情况下禁用。当你准备好了：

• 添加/启用 exec.run 在……里面 src/tools/exec_tool.py 与：

- 明确的用户批准要求， - 路径分配表（例如Xcode DerivedData、模拟器设备）， - 服务器端日志记录， - 在可能的情况下悬挂干跑旗。

政策示例（概念性）：

SAFE_PREFIXES = [
  os.path.expanduser("~/Library/Developer/Xcode/DerivedData"),
  os.path.expanduser("~/Library/Caches"),
]

# Only allow rm within SAFE_PREFIXES, and require params.approved == True

安全态势

• 默认只读。未明确选择加入，不得删除。
• Denylist和allowlist。默认情况下拒绝核心系统路径和用户内容；只允许已知的缓存/工件目录。
• 先进行试运行。更喜欢 brew cleanup -n -s, docker system df, du -sh 比较。
• 审核日志。使用时间戳和参数记录工具调用和批准的命令（如果需要，请编辑路径）。

跨平台笔记

• macOS和Linux： du, find, ps, docker 应该开箱即用。
• Windows（在“问题”中跟踪）：替换为PowerShell等效项(Get-ChildItem, Measure-Object, Get-Process)WSL检测和Docker Desktop数据路径。

发展

make run          # uvicorn dev server
make lint         # ruff/flake8 (configure as you like)
make test         # pytest

Env变量（.Env.示例）

PORT=8765
LOG_LEVEL=info
ALLOWLIST=/Users/you/Library/Developer/Xcode/DerivedData:/Users/you/Library/Caches
DENYLIST=/Users/you/Documents:/Users/you/Desktop:/Users/you/Pictures

示例工具语义（基于WS的JSON-RPC）

# Request: list tools
{"id":"1","method":"tools.list","params":{}}

# Response
{"id":"1","result":{"tools":["fs.du","fs.bigfiles","pkg.caches","docker.df","proc.top"]}}

# Call a tool
{"id":"2","method":"tools.call","params":{"name":"fs.du","arguments":{"path":"~","depth":2}}}

# Result
{"id":"2","result":{"name":"fs.du","data":[{"path":"/Users/you","kb":1234567}, ...]}}

GPT提示示例

• 在~和pkg.cacheds上使用fs.du（深度2），然后仅使用dry-run命令返回一个YAML清理计划
• 查找重复项超出了范围；相反，使用fs.bigfiles报告前50个大于500MB的文件
• “不建议删除任何用户文档/照片；只保留在缓存/工件中。”

路线图（第一天开放的问题）

• Windows支持：PowerShell工具(Get-ChildItem, Measure-Object, Get-Process)WSL路径映射。
• 执行工具（选择加入）：

- 批准握手(APPROVE "") - 路径分配策略 - 测井+模拟运行支持

• Docker指标：解析 docker system df -v 按图像/体积进行结构化总计。
• 浏览器缓存（选择加入）：配置文件目录检测和报告（默认情况下不删除）。
• 可配置策略：用于定义允许/拒绝和风险级别的YAML策略文件。
• 遥测切换：仅本地JSON日志；默认情况下没有网络出口。
• 测试：夹具 du/find 产出；WS协议的契约测试。
• CI：皮棉/类型检查/PR测试；预提交挂钩。
• 文档：“在自定义GPT中启用连接器”截图；故障排除指南。
• 发布：用于自托管的Dockerfile和Compose；带有WSS的Caddy/Nginx反向代理代码段。

贡献

• 首先打开一个问题以进行重大更改。
• 为新工具或策略更改编写测试。
• 保持默认行为只读和安全。

许可证

麻省理工学院（或您的偏好）。如果您捆绑了第三方示例，请添加通知。