# spacesentinel-mcp

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/SheldonZhuang/SpaceSentinel  
**npm Downloads (last month):** 811  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/spacesentinel-mcp

## Description
Conversational Windows disk cleanup (whitelist-only) + device cleanup guides in 7 languages.

## Claude Desktop Quick Installation
Heuristic fallback — verify the package name and runner against the repository README before running it. Uses `npx` (confidence: low):

```json
"mcpServers": {
  "spacesentinel-mcp": {
    "command": "npx",
    "args": ["-y","spacesentinel-mcp"]
  }
}
```

## Documentation & README

# 🛡️ SpaceSentinel

**智能释放空间，守护每一寸磁盘 | Smart disk cleanup for every device**

🌐 **在线体验 / Live Demo**: [https://spacesentinel.vercel.app](https://spacesentinel.vercel.app)

[中文](#中文) | [English](#english)

---

## 中文

### 🚀 30 秒上手（Windows 清理）

1. **下载** [CleanMyPC.zip](https://spacesentinel.vercel.app/downloads/CleanMyPC.zip) 并解压
2. **双击 `run.bat`** —— 自动扫描并清理 13 类系统垃圾（右键"以管理员身份运行"解锁全部项）
3. 查看"本次共释放"报告，按回车退出。完成！

> 只想看看能清多少？命令行运行 `run.bat -ScanOnly`，只统计不删除。

SpaceSentinel 包含两个互补的交付物：

1. **多语言清理向导网站**（纯静态，零后端）—— 引导 Windows / Mac / iOS / Android 用户安全释放磁盘空间，并提供浏览器本地图片压缩。
2. **CleanMyPC 一键清理工具**（Windows）—— 双击即自动扫描并清理白名单垃圾，真正释放磁盘空间。

### ✨ 网站功能

- 🌍 **7 语种自由切换**：中文 / English / Français / Deutsch / Español / 日本語 / 한국어（自动检测浏览器语言，localStorage 记忆选择）
- 📱 **全设备适配**：桌面 / 手机 / 平板响应式布局
- 🧭 **分设备清理指引**：Windows、Mac、iOS、Android 各 4 步安全清理步骤
- 🖼️ **图片在线瘦身**：Canvas 本地压缩，质量可调，**文件不离开设备、不上传任何服务器**
- ⬇️ **Windows 一键工具下载**：选择 Windows 后可直接下载 CleanMyPC
- 💎 玻璃拟态 UI + 雷达扫描动效

> **诚实原则**：扫描动画明确标注为引导演示——网页无法访问访问者的文件，真实清理由本地开源工具或用户按指引亲手完成。绝不显示虚构的"已释放 XX GB"。

### 🧹 CleanMyPC 一键清理工具

**使用**：下载 [CleanMyPC.zip](https://spacesentinel.vercel.app/downloads/CleanMyPC.zip)（或直接用仓库 `tools/` 目录），解压后双击 `run.bat` 即自动完成扫描 → 清理 → 释放量报告。右键"以管理员身份运行"可解锁全部 13 项。

```
run.bat            # 双击：自动全量清理
run.bat -ScanOnly  # 只扫描统计，不删除任何文件
run.bat -Deep      # 清理后额外运行 DISM 压缩 WinSxS 组件存储（需管理员，约 10-20 分钟）
```

**安全白名单（仅清理以下 13 类，绝不触碰文档/桌面/下载/相册）：**

| # | 清理目标 | 需要管理员 |
|---|---------|:---:|
| 1 | 用户临时文件 (%TEMP%) | |
| 2 | 系统临时文件 (Windows\Temp) | ✔ |
| 3 | 回收站（所有盘） | |
| 4 | Windows 更新缓存 | ✔ |
| 5 | 缩略图缓存 | |
| 6 | Chrome 缓存 | |
| 7 | Edge 缓存 | |
| 8 | npm 缓存 | |
| 9 | pip 缓存 | |
| 10 | npm 缓存（Roaming 旧位置） | |
| 11 | 安装器缓存 (SquirrelTemp) | |
| 12 | 程序崩溃转储 (CrashDumps) | |
| 13 | 系统崩溃转储 (Minidump) | ✔ |

**安全设计**：
- 仅操作白名单路径（TEMP / Windows / LocalAppData 根之下），路径合法性双重防御（拒绝空路径与盘根相对路径）
- junction / 符号链接只删链接本身，绝不递归进目标目录
- 被占用文件自动跳过，不报错不中断
- Pester 单元测试覆盖（含白名单安全测试、删除逃逸防御测试）

### 🤖 AI 集成（面向 Agent 与开发者）

- **内容 API**：[`/api/guides.json`](https://spacesentinel.vercel.app/api/guides.json) —— 7 语种 × 4 设备的清理步骤，机器可读，AI Agent 可直接引用（由 `tools/build-api.js` 从语言包生成）
- **llms.txt**：[`/llms.txt`](https://spacesentinel.vercel.app/llms.txt) —— 面向 AI 爬虫与助手的站点导引和事实清单
- **MCP Server**：[`spacesentinel-mcp`](https://www.npmjs.com/package/spacesentinel-mcp)（npm v0.1.4，**已收录 [MCP 官方注册表](https://registry.modelcontextprotocol.io)**：`io.github.SheldonZhuang/spacesentinel-mcp`）—— 让 Claude Desktop 等 Agent 对话式扫描/清理本机，新增 `analyze_disk` 磁盘归属分析（只读证据采集，AI 推理，用户决策）。配置：`"command": "npx", "args": ["-y", "spacesentinel-mcp"]`，详见 [mcp/README.md](mcp/README.md)
- **Claude Skill**：[`skills/disk-cleanup`](skills/disk-cleanup/SKILL.md) —— 拷贝到 `~/.claude/skills/` 即可让 Claude Code 掌握清理决策流
- **GPTs Action**：[`api/openapi.json`](https://spacesentinel.vercel.app/api/openapi.json) + [配置指南](docs/gpts-action.md) —— 5 分钟接入 ChatGPT
- **SEO 指引页**：[`/guides`](https://spacesentinel.vercel.app/guides) —— 4 设备 × 7 语种共 28 个静态页（hreflang + HowTo 结构化数据）
- **长尾问答页**：[`/qa`](https://spacesentinel.vercel.app/qa) —— 6 个高频磁盘问题 × 中英双语共 12 页（FAQ 结构化数据，内容源 `tools/qa-content.js`，全部来自真实案例、零恐吓话术）
- **路线图**：Claude Skill、SEO 内容页等，详见 [`docs/ai-roadmap.md`](docs/ai-roadmap.md)

### ❤️ 支持项目 / Support

如果这个项目帮你释放了磁盘空间，欢迎请作者喝杯咖啡：[GitHub Sponsors](https://github.com/sponsors/SheldonZhuang) · [Buy Me a Coffee](https://www.buymeacoffee.com/sheldonzhuang)。开源免费，永不捆绑。

If SpaceSentinel freed up your disk, consider buying the author a coffee — free & open source forever, no bundleware.

### ⚙️ 自动部署

push 到 `main` 分支即自动生产部署（Vercel Git 集成，仓库单分支工作流）。

### 🗂️ 项目结构

```
├── index.html          # 单页四区块：Hero → 设备选择 → 扫描动效 → 指引+压缩
├── css/                # tailwind.css（构建期静态生成）+ style.css（玻璃拟态/雷达动效）
├── js/
│   ├── i18n.js         # i18n 引擎（自动检测 / localStorage 记忆 / 失败兜底）
│   ├── app.js          # 区块状态机 / 扫描动效 / 指引渲染
│   └── compressor.js   # Canvas 本地图片压缩
├── locales/*.json      # 7 语种语言包（43 keys 逐一对齐）
├── api/guides.json     # 机器可读清理指引 API（AI Agent 友好）
├── qa/                 # 长尾问答页（6 题 × 中英，FAQ JSON-LD）
├── llms.txt            # AI 爬虫/助手导引（GEO）
├── downloads/          # CleanMyPC.zip（含使用说明.txt）
├── tools/
│   ├── CleanMyPC.ps1   # 清理脚本（PowerShell 5.1，函数化 + dot-source 守卫）
│   ├── AnalyzeDisk.ps1 # 磁盘归属分析（只读证据采集，MCP analyze_disk 后端）
│   ├── run.bat         # 双击入口（绕过执行策略，透传参数）
│   ├── pack.ps1        # 打包脚本：重新生成 downloads/CleanMyPC.zip
│   ├── build-api.js    # 从语言包生成 api/guides.json
│   ├── build-guides-pages.js # 生成 guides/qa 静态页 + sitemap
│   ├── qa-content.js   # 问答页内容源（中英双语）
│   └── gen-og.ps1      # 生成 og.png / apple-touch-icon.png
├── docs/ai-roadmap.md  # AI 时代战略规划与路线图
├── .github/workflows/  # push main 自动部署 Vercel
└── tests/              # Pester 单元测试
```

### 🛠️ 开发

```bash
# 本地预览（语言包 fetch 需要 HTTP 服务，file:// 不可用）
npx -y serve -l 3999

# 运行测试（Windows 自带 Pester）
powershell -NoProfile -ExecutionPolicy Bypass -Command "Invoke-Pester -Path tests/CleanMyPC.Tests.ps1"

# 修改 CleanMyPC.ps1 后：重新打包下载分发的 zip
powershell -NoProfile -ExecutionPolicy Bypass -File tools/pack.ps1

# 部署（Vercel）
vercel deploy --prod
```

---

## English

### 🚀 30-Second Quick Start (Windows)

1. **Download** [CleanMyPC.zip](https://spacesentinel.vercel.app/downloads/CleanMyPC.zip) and unzip
2. **Double-click `run.bat`** — automatic scan & cleanup of 13 whitelisted junk categories (right-click "Run as administrator" to unlock all)
3. Check the freed-space report, press Enter. Done!

> Scan without deleting: `run.bat -ScanOnly`

**For AI agents & developers**: machine-readable cleanup guides at [`/api/guides.json`](https://spacesentinel.vercel.app/api/guides.json), site guide for AI assistants at [`/llms.txt`](https://spacesentinel.vercel.app/llms.txt). MCP server & Claude Skill on the roadmap — see [`docs/ai-roadmap.md`](docs/ai-roadmap.md).

SpaceSentinel ships two complementary deliverables:

1. **A multilingual cleanup guide website** (pure static, zero backend) — walks Windows / Mac / iOS / Android users through safely freeing up disk space, plus an in-browser image compressor.
2. **CleanMyPC one-click cleanup tool** (Windows) — double-click to automatically scan and clean whitelisted junk, actually reclaiming disk space.

### ✨ Website Features

- 🌍 **7 languages**: 中文 / English / Français / Deutsch / Español / 日本語 / 한국어 (auto-detected, remembered via localStorage)
- 📱 **Responsive** across desktop / phone / tablet
- 🧭 **Per-device cleanup guides**: 4 safe steps each for Windows, Mac, iOS, Android
- 🖼️ **Image slimming**: Canvas-based local compression with adjustable quality — **files never leave your device**
- ⬇️ **One-click tool download** for Windows users
- 💎 Glassmorphism UI + radar scan animation

> **Honesty principle**: the scan animation is clearly labeled as a guided demo — web pages cannot access visitors' files. Real cleanup is done by the local open-source tool or by the user following the guide. No fake "XX GB freed" numbers, ever.

### 🧹 CleanMyPC

**Usage**: download [CleanMyPC.zip](https://spacesentinel.vercel.app/downloads/CleanMyPC.zip) (or use `tools/` in this repo), unzip, double-click `run.bat` — it scans, cleans, and reports freed space automatically. Run as Administrator to unlock all 13 targets.

```
run.bat            # double-click: automatic full cleanup
run.bat -ScanOnly  # scan & report only, deletes nothing
run.bat -Deep      # additionally compress the WinSxS component store via DISM (admin, ~10-20 min)
```

**Safety whitelist** — only these 13 categories are ever touched (never Documents / Desktop / Downloads / Photos): user temp, system temp (admin), Recycle Bin (all drives), Windows Update cache (admin), thumbnail cache, Chrome / Edge caches, npm / pip caches, legacy Roaming npm cache, installer cache (SquirrelTemp), app crash dumps, system crash dumps (admin).

**Safety design**: whitelist-rooted paths with input hardening (rejects empty and drive-root-relative paths), reparse points (junctions/symlinks) deleted link-only without recursing into targets, in-use files skipped silently, covered by Pester unit tests including deletion-escape defenses.

### 🛠️ Development

```bash
npx -y serve -l 3999          # local preview (locales fetch requires HTTP)
powershell -NoProfile -ExecutionPolicy Bypass -Command "Invoke-Pester -Path tests/CleanMyPC.Tests.ps1"
powershell -NoProfile -ExecutionPolicy Bypass -File tools/pack.ps1   # repack zip after editing CleanMyPC.ps1
vercel deploy --prod          # deploy
```

---

**Tech Stack**: HTML5 · Tailwind CSS (CDN) · Vanilla JS (ES6+) · PowerShell 5.1 · Pester · Vercel