io.github.SheldonZhuang/spacesentinel-mcp (MCP)

This MCP server provides conversational guidance for Windows disk cleanup using a whitelist-only approach, plus device cleanup guides available in seven languages. It exposes Windows tools for read-only scanning, controlled cleanup, and disk ownership analysis to help AI agents understand reclaimable space and sources of junk.

🛠️ Key Features

Windows-focused disk cleanup via whitelist-only junk categories
Tools include scan_junk, clean_junk, and analyze_disk
Multilingual device cleanup guides (7 languages)
Conversational operation intended for AI agents (e.g., Claude Desktop, Cursor)

🚀 Use Cases

Identify reclaimable junk space through a read-only scan
Perform explicit, user-approved cleanup of whitelisted junk
Attribute disk usage via per-directory ownership evidence (size, PATH references, running processes, installed-app registry, and related signals)

⚡ Developer Benefits

Read-only analysis support with scan_junk and analyze_disk
Safety gate for clean_junk requiring confirm=true after explicit user approval

⚠️ Limitations

Cleanup is restricted to 13 whitelisted junk categories
clean_junk requires explicit user confirmation (confirm=true)

Tools

Tool

Platform

Description

scan_junk

Windows

Read-only scan of 13 whitelisted junk categories, reports reclaimable size

clean_junk

Windows

Cleans the whitelist (requires confirm=true after explicit user approval)

analyze_disk

Windows

Read-only disk-ownership analysis: per-directory evidence (size, PATH refs, running processes, installed-app registry, known-software signatures) so the AI can reason about what's safe to delete — the user always decides

get_cleanup_guide

All

Step-by-step cleanup guide for windows/mac/ios/android in 7 languages

Safety: only whitelisted paths are ever touched (temp files, caches, Recycle Bin) — never Documents, Desktop, Downloads or Photos. The underlying PowerShell tool is open source with Pester test coverage, including deletion-escape defenses.

Setup (Claude Desktop)

Add to claude_desktop_config.json:

json

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

Or from a local clone:

json

{
  "mcpServers": {
    "spacesentinel": {
      "command": "node",
      "args": ["D:/path/to/SpaceSentinel/mcp/index.js"]
    }
  }
}

Then ask your agent: "扫描一下我电脑上的垃圾" / "How do I free up space on my iPhone?"

Development

bash

npm install
node test-mcp.mjs   # protocol-level smoke test (initialize → tools/list → calls)

guides.json and CleanMyPC.ps1 are copied from the repo root — regenerate with node ../tools/build-api.js && cp ../api/guides.json guides.json && cp ../tools/CleanMyPC.ps1 CleanMyPC.ps1 after upstream changes.

io.github.SheldonZhuang/spacesentinel-mcp