使用说明

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<br/>('PC Reviewer')<br/>- uses MCP tools"]
        A --> C["YAML Cleanup Plan<br/>(sorted by GB freed)"]
    end
    subgraph Local["Your Computer"]
        B["MCP Server<br/>(runs locally)<br/>- /mcp websocket<br/>- read-only tools"]
        D["Your Machine<br/>(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）

在ChatGPT中： 设置→ 连接器→ 添加自定义连接器
类型： 远程MCP（WebSocket）
网址： wss://<your-tunnel-host>/mcp
姓名： PC审阅者
保存。

4.创建自定义GPT

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

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 "<command>" before any destructive action.

保存。

使用它

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

贡献

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

许可证

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