Disk Inventory MCP

Disk Inventory MCP

一款适用于 macOS 的本地只读磁盘分析工具，将 CLI 和 MCP 服务集成在一个原生可执行文件中。查找大型文件和文件夹，查看文件扩展名分布，并准确了解扫描未完成的部分。

v0.1.0 是只读预览版。 它不包含删除、移至废纸篓、执行清理或读取内容的工具。需要 macOS 13 或更高版本。除 macOS 框架外，没有运行时依赖项。

安装

推荐：从项目的 Homebrew tap 安装（从源代码构建；需要 Xcode Command Line Tools，且 Swift 版本为 5.9 或更高）：

brew install LemmaLemming/tap/disk-inventory-mcp
disk-inventory --version

GitHub Releases 还提供通用 Intel/Apple Silicon .tar.gz、MCP bundle（.mcpb）、对应的源代码和 SHA256SUMS。可下载的二进制文件采用临时签名，未经 Developer ID 签名，也未通过 Apple 公证。Homebrew 会从源代码构建。导入 MCP bundle 取决于客户端支持情况，且可能受到 macOS 安全检查限制。

CLI

disk-inventory scan ~/Downloads
disk-inventory scan ~/Downloads --json
disk-inventory scan ~/Downloads --json --limit 50 --max-entries 200000 --max-seconds 60

JSON 输出包含 summary、top_children 和 file_types。字节数使用十进制字符串，以保留 64 位精度。顶层子项是根目录的直接子项；目录总量包含其所有后代。CLI 退出代码：0 表示完成，2 表示调用无效，3 表示未完成（JSON 仍可使用）。

MCP 设置

配置任何能够启动本地 stdio 服务的 MCP 客户端。将示例路径替换为计算机上的绝对路径；使用 command -v disk-inventory 查找已安装的可执行文件。以下示例使用常见的 Apple Silicon Homebrew 路径：

{
  "mcpServers": {
    "disk-inventory": {
      "command": "/opt/homebrew/bin/disk-inventory",
      "args": ["mcp", "--root", "/Users/YOU/Downloads"]
    }
  }
}

添加更多 --root、PATH 对，以授予其他目录的访问权限。服务必须指定明确的根目录才能启动，并会拒绝根目录之外的扫描路径，包括通过符号链接逃逸的路径。兼容 MCPB 的客户端也可以导入发布 bundle，并提示用户选择一个允许访问的目录。

示例提示词：

• “显示我的 Downloads 目录中最大的文件夹，并告诉我扫描是否有遗漏。”
• “在该次扫描中，找出最大的 .zip 文件。”
• “按扩展名统计已观察到的文件，并说明逻辑字节数和已分配字节数之间的差异。”

工具	用途
list_roots	显示启动时授予访问权限的目录
scan_start	启动有界的后台元数据扫描；返回扫描 ID
scan_status	进度、最终总量、跳过的路径和统计注意事项
scan_cancel	协作式停止当前扫描
query_usage	排序/筛选结果、分页，或深入查看某个目录 ID
file_types	分页显示文件扩展名分组

该服务通过 stdio 实现以换行符分隔的 JSON-RPC、初始化、ping 和工具。它会协商协议版本 2025-11-25、2025-06-18 和 2025-03-26。工具结果同时包含结构化 JSON 和序列化文本。扫描任务使用应用级 ID；此版本不会声明可选的 MCP Tasks 功能。请以合理的间隔轮询状态（例如每秒一次）。

计量与限制

• 默认预算：100,000 个条目和 30 秒。每次扫描上限：500,000 个条目和 300 秒。目录遍历深度上限为 128。时间和取消检查在文件系统调用之间进行；如果操作系统调用因文件系统而阻塞，可能会延迟检查。
• 内存中保留一个进行中的扫描和最近完成的两个扫描。开始更多扫描会淘汰较早的已完成结果。进程重启后，所有扫描都会丢失。目前没有持久化数据库或扫描对比功能。
• 查询每页最多返回 200 个条目。根目录的 ID 为 0。ID 仅在其所属扫描中有效。parent_id 会返回直接子项；省略它时会考虑所有后代。避免将目录总量与其子项相加。
• 逻辑字节数会统计每个已观测到的普通文件或符号链接路径。已分配字节数使用 st_blocks * 512 计算，硬链接会按设备号和 inode 去重。共享的硬链接存储空间会归属于最先遇到的路径，因此各文件夹的归属量可能随枚举顺序而变化。
• 不计入目录元数据。APFS 克隆和快照保留的块不会去重；已分配字节数不等于可回收字节数。这里的任何信息都不能证明某个文件可以安全删除。
• 遍历后代符号链接时会统计链接本身，不会跟随链接。其他文件系统会被跳过并报告。启动时会规范化根路径；遍历时打开路径组件不会跟随符号链接。本实现未复制 Disk Inventory X 的特殊 firmlink 遍历行为。
• 权限错误、已消失的条目、达到限制、挂载边界和无效 UTF-8 名称都会使 complete=false。此时总量仅反映已观测到的数据。最多返回 100 条问题详情，并提供完整的问题计数。条目可能显示已观测字节数为 0 且 complete=false；这不表示该条目为空。
• 扫描是实时观测，并非原子文件系统快照。遍历期间，文件内容和目录可能发生变化。该工具不会请求提升权限，也不会绕过 macOS 隐私保护。
• 文件类型仅根据文件名扩展名推断，不参考文件内容或应用程序归属。扫描器不会读取文件内容；但浏览云服务提供商的目录仍可能触发提供商的元数据活动。

隐私

可执行文件不会发起网络请求，不包含遥测功能，也不会写入扫描缓存。它会将路径、大小和错误详情返回给调用它的 CLI 或 MCP 客户端。该客户端可能会根据自身设置，将工具结果发送给其模型提供商或保留日志。请将文件名视为不可信数据。仅将你打算分析的路径授予工具。

开发

swift build -c release
DISK_INVENTORY_BIN="$PWD/.build/release/disk-inventory" python3 tests/integration.py
bash scripts/package.sh

集成测试使用生成的临时测试夹具：普通文件、硬链接、稀疏文件、符号链接循环/逃逸、不可读目录、恶意文件名、分页、取消操作、CLI 退出码和 MCP 协议错误。测试不会扫描个人目录。可选的互操作性测试使用官方 Python MCP SDK；请参阅 tests/sdk_interop.py。

许可证与来源

GPL-3.0-or-later；请参阅 LICENSE。这是一个全新的 Swift 实现，其设计参考了对 Tjark Derlien 的 Disk Inventory X 和 TreeMapView 的评估。本项目未捆绑它们的 Objective-C 源代码、艺术素材、TreeMapView、Omni 框架或 CocoaTech 组件，也不是 Disk Inventory X 的官方发行版。GPL 许可证文本转载自公开的 Disk Inventory X 代码库。原上游项目的所有权和声明仍保留在各自的代码库中。

后续计划：持久化扫描对比、基于证据的清理预览，然后再单独审核清理执行功能。这些功能不属于 v0.1.0。