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）
- 在ChatGPT中： 设置→ 连接器→ 添加自定义连接器
- 类型： 远程MCP（WebSocket）
- 网址：
wss:///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 "" 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 # pytestEnv变量（.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反向代理代码段。
贡献
- 首先打开一个问题以进行重大更改。
- 为新工具或策略更改编写测试。
- 保持默认行为只读和安全。
许可证
麻省理工学院（或您的偏好）。如果您捆绑了第三方示例，请添加通知。