Clyan
Enables AI agents to clean disk space by scanning and removing temporary files, caches, and duplicates through natural language commands via MCP protocol.
README
Clyan — 给 AI Agent 用的磁盘清理工具
一个由 AI agent 驱动的命令行磁盘清理工具。你可以通过 CLI 或 MCP 协议与它交互，说一句话就能完成全盘扫描、垃圾识别、空间释放。
功能
- 26+ 缓存检测器：npm / pip / cargo / Go / Docker / IDE 缓存 / 浏览器缓存 / Windows 系统缓存 / 开发垃圾
- 重复文件检测：三步检测（按大小分组 → BLAKE2b 部分哈希 → 全量哈希）
- Windows 深度清理：WinSxS 组件存储、Windows.old 旧系统、DriverStore 驱动备份、Delivery Optimization 缓存、DISM 清理
- 三级安全体系：Safe（安全可删）/ Caution（谨慎，可能需重建）/ Unsafe（不可删，含配置/凭据），配合保护路径系统和豁免规则
- 回收站 + 历史回溯：默认走回收站，SQLite 记录每次操作，支持按 ID 撤销
- MCP 服务器：AI agent 可通过 Model Context Protocol 直接调用所有工具（无需 CLI subprocess）
- 并行高速模式：ThreadPoolExecutor 并发删除 + ProcessPoolExecutor 并发扫描
- 安全边界：
%APPDATA%\npm等全局包管理器目录受保护，不被误清理
快速开始
pip install -e .
# 全盘快速体检
clyan scan quick C:\
# 只看大件开发垃圾
clyan scan dev-garbage C:\ --min-size-mb 100
# 预览清理结果
clyan clean --items items.json --dry-run
# 执行清理（大文件直接删，不走回收站）
clyan clean --items items.json --fast
命令
| 命令 | 说明 |
|---|---|
scan space <path> |
目录空间分析 |
scan dev-garbage <path> |
开发者缓存/垃圾 |
scan browsers |
浏览器缓存 |
scan system |
Windows 临时文件 + 回收站 |
scan duplicates <path> |
重复文件检测 |
scan quick <path> |
一键全量扫描 |
clean --items <file> |
预览或执行清理 |
history |
查看清理历史 |
undo <id> |
撤销某次清理 |
mcp |
启动 MCP 服务器 |
MCP 服务器
启动 MCP 服务器后，AI agent 可以通过 stdio 传输协议直接调用所有功能：
clyan mcp
暴露的 MCP 工具：
scan_quick/scan_dev_garbage/scan_browsers/scan_system/scan_duplicatesclean_preview/clean_executehistory
安全体系
采用 三层危险等级 + 保护路径 + 豁免规则 的组合策略：
| 等级 | 含义 | 示例 |
|---|---|---|
| 🟢 safe | 可安全删除，自动重建 | node_modules/, .cache/, Temp/, NGEN 镜像 |
| 🟡 caution | 注意 — 可能需重装或重建 | .venv/, VS Code 扩展, .dart_tool |
| 🔴 unsafe | 不可删 — 含配置/凭据/数据 | .ssh/, .git/, Desktop/, 全局 npm |
保护路径（31条）：C:\Windows、C:\Program Files、%APPDATA%\npm、Desktop、Documents、.ssh、.git……
豁免规则（34条）：node_modules/（排除全局 npm）、Temp/、.cache/、assembly/、dist/（排除 npm 内）……
参考项目
Clyan 的设计和实现参考了以下开源项目：
| 项目 | 参考内容 |
|---|---|
| TurboClean | 多进程磁盘扫描框架 |
| Czkawka | 重复文件检测策略、临时文件扫描 |
| ddh | 轻量重复文件查找 + JSON 输出格式 |
| bleachbit | 安全边界模型、保护路径 XML、系统清理 |
| cache-commander | Provider 模块化架构、MCP 集成、SafetyLevel 设计 |
| null-e | 50+ 缓存类型覆盖、Windows 支持 |
| dev-cleaner | Windows 全栈开发者缓存路径 |
| dustoff | JS/TS 构建产物清理 |
| modclean | node_modules 深度瘦身 |
| space | Rust 磁盘分析器 TUI/CLI 设计 |
| cull | 交互式 TUI 磁盘分析 |
Recommended Servers
playwright-mcp
A Model Context Protocol server that enables LLMs to interact with web pages through structured accessibility snapshots without requiring vision models or screenshots.
Magic Component Platform (MCP)
An AI-powered tool that generates modern UI components from natural language descriptions, integrating with popular IDEs to streamline UI development workflow.
Audiense Insights MCP Server
Enables interaction with Audiense Insights accounts via the Model Context Protocol, facilitating the extraction and analysis of marketing insights and audience data including demographics, behavior, and influencer engagement.
VeyraX MCP
Single MCP tool to connect all your favorite tools: Gmail, Calendar and 40 more.
graphlit-mcp-server
The Model Context Protocol (MCP) Server enables integration between MCP clients and the Graphlit service. Ingest anything from Slack to Gmail to podcast feeds, in addition to web crawling, into a Graphlit project - and then retrieve relevant contents from the MCP client.
Kagi MCP Server
An MCP server that integrates Kagi search capabilities with Claude AI, enabling Claude to perform real-time web searches when answering questions that require up-to-date information.
E2B
Using MCP to run code via e2b.
Neon Database
MCP server for interacting with Neon Management API and databases
Exa Search
A Model Context Protocol (MCP) server lets AI assistants like Claude use the Exa AI Search API for web searches. This setup allows AI models to get real-time web information in a safe and controlled way.
Qdrant Server
This repository is an example of how to create a MCP server for Qdrant, a vector search engine.