Skip to content

feat(mcp): let an AI agent drive PwrDisk over MCP, with embedded skills (port of tobi/disktree#102) - #14

Merged
Harold Hunt (huntharo) merged 8 commits into
mainfrom
feat/mcp-server
Oct 30, 2026
Merged

Harold Hunt (huntharo) merged 8 commits into
mainfrom
feat/mcp-server

Conversation

@huntharo

Copy link
Copy Markdown

Ports the MCP server from huntharo#7 (upstream tobi#102) onto PwrDisk and makes it ready to ship: embedded skills with each platform's cautions and confirm-first rules, PwrDisk naming throughout, and guards for SSH windows and Windows.

The first five commits are the original ones, with authorship kept. Their conflicts with PwrDisk's main were resolved: custom window chrome, the Updates panel, and the FSEvents/Spotlight categories. The last two commits are new.

What users get

pwrdisk mcp is an MCP server over stdio, with no port, token or sign-in. An agent such as Claude Code or Codex scans, walks the tree largest first, finds caches and build output, and marks what can go. It cannot delete anything: pwrdisk_review opens the review screen, and the person presses Enter. When a PwrDisk window is open, the agent reads that window's tree, its marks show up live, and the header names the agent.

claude mcp add --scope user pwrdisk -- pwrdisk mcp

Embedded skills

Compiled in from skills/ and served three ways: as skill:// resources, through the io.modelcontextprotocol/skills extension (skills/list, skills/get, with sha256 digests, following PwrSuiteLab Control's contract), and as the prompts free-space and explain-usage, which add the reference for the system the server runs on.

skill what it says
pwrdisk-explain-usage read-only "where did my space go"; never marks; accounts for space files don't explain
pwrdisk-free-space agree the list with the user before marking unless a standing instruction covers it, and only within that instruction's scope; say before opening review; never delete with a shell command or run a tool's clean command unapproved; no sudo, no Full Disk Access, no system-setting changes; Trash frees nothing until emptied
references/macos.md APFS clones, container volumes, local snapshots, purgeable, privacy grants (the agent's host vs PwrDisk's), library packages, iCloud/File Provider, Xcode/simulators/Docker
references/linux.md hardlinks, btrfs/ZFS snapshots, deleted-but-open files, journal and swap, package-manager caches, containers, trash backends
references/windows.md no window link yet and how to hand over, OneDrive placeholders, shadow copies, page file and hibernation, WinSxS, WSL/Docker VHDX, Recycle Bin

pwrdisk_status names the system and the reference to read before marking. The server instructions carry the confirm-first rules too, for clients that never open a skill.

Fixes found while getting it ready

  • SSH windows. A window showing an SSH host would have read and marked the agent's local paths against the remote tree. Now the window answers only hello and state. The session works headless and says why.
  • Windows. show and review started a window that could never link, then started another on every retry. They now say how the user takes the list over.
  • Socket. The socket is now pwrdisk.sock (or PWRDISK_LINK), so PwrDisk's agent never drives an upstream disktree window on the same machine.
  • Removal mode. The review message names the trash in use. On a Linux machine with no trash backend, it says removal is permanent.
  • Agent name. The header showed "an agent" when a client called a tool before initialized arrived. The name is now recorded during initialize.
  • CI. skills/** now runs full CI, since the server compiles those files in.

Screenshots

pwrdisk on a contrived tree on a 600 MB disk image named Fixtures, macOS 27. For the after shots, a scripted MCP client named claude-code marked two directories. The binary ran from /tmp/PwrDisk.app so no real paths appear.

Before (main)

before

After: an agent connected, two marks

after

After: Help › Work with an AI Agent…

overlay

Verification

  • cargo xtask lint and cargo xtask test pass on macOS. New tests: the skills catalog (frontmatter, every skill:// link resolves, exact-match reads only, digests), the skills/list/skills/get/resources contract, refusing an SSH window on both the session and window sides, and the Windows show/review path.
  • node --test scripts/ci/classify-changes.test.cjs passes.
  • A smoke test over stdio against the real binary covered initialize (extension declared), tools/list, resources/list/read (traversal refused), skills/list/get, prompts/get and pwrdisk_status.
  • Not run on Linux or Windows hardware; CI covers both. The Windows window link (a named pipe) is still a follow-up.

`disktree mcp` serves the Model Context Protocol over stdio, so Claude
Code, Codex or any MCP client can scan, walk the tree and mark what can
go, and the person removes it on the review screen. One command connects
it and there is nothing to configure, sign in to or approve: the agent
runs disktree as the user, and can do no more than the user's shell can.

Eight tools: status, scan, ls, find, show, mark, unmark and review. Each
mark answers with the real removal plan, what the guards keep back and
why, what another mark covers, and the free space it gives back on the
volume, counted the way the meter counts it. There is no tool that
deletes.

A window follows along over a per-user socket (disktree-link): marks
land in the mosaic and the meter, `show` moves the view, `review` opens
the review screen, and the top bar names the agent and its last action
while it is connected. When no window is open the agent can start one.
Without a display it works headless. Windows is headless for now; the
link needs a named pipe there.

The free-space procedure ships as a prompt and a resource from
skills/disktree-free-space/SKILL.md.
When a disktree window is open it is now the agent's source of truth.
disktree_ls, disktree_find and disktree_scan are answered from the tree
on screen, a mark is measured from it, and a path outside its root is
an error that tells the agent to scan from higher up, which the window
follows. The server's own scans are read only while no window is open,
so an agent in a terminal still needs nothing else.

The listing and search logic moves into disktree-core (query) so both
sides answer alike; the link gains Scan, Ls and Find requests, a Marked
answer that says what the window refused, and a tree summary with the
panel's findings in every State. The window applies the agent's scan
options, and a scan it is asked for lands as any other.
The line under the disk meter is easy to miss; Help is where a person
looks for how to hook something up. One item, the same overlay.
…H and Windows guards

The server now carries its own skills, compiled in from skills/:
pwrdisk-explain-usage (read-only: never marks) and pwrdisk-free-space
(agree the list with the user before marking unless a standing
instruction covers it; never delete by other means), with macOS, Linux
and Windows references for what each system hides from a scan and what
never to propose. They are served as skill:// resources, through the
io.modelcontextprotocol/skills extension's skills/list and skills/get,
and as the prompts free-space and explain-usage, which add this
system's reference. pwrdisk_status names the system and its reference.

What a person or agent sees is PwrDisk: `pwrdisk mcp`, the pwrdisk_*
tools, the server name, and the link socket (pwrdisk.sock,
PWRDISK_LINK), so a PwrDisk agent never drives an upstream disktree
window on the same machine.

A window showing an SSH host answers only hello and state, and the
session works headless and says why: an agent's paths are this
computer's. On Windows, where there is no window link yet, show and
review no longer start a window that can never answer; they say how the
user takes the list over. The review message names the trash in use, or
says removal is permanent where there is none.

skills/ now runs full CI: the server compiles those files in.
A client may call a tool as soon as initialize is answered, before the
initialized notification arrives; the window then took its name from the
first hello as "an agent". Record the name while answering initialize.
…, versions

- An agent's scan, mark or show leaves a window still on the source
  chooser and scans the root it names; start_scan only reopened the
  chooser, so the agent waited on a scan that never started. A window
  with no root no longer counts as covering every path.
- A window that answers hello with an error (another link version) or
  refuses the marks made before it linked is not followed. One reason,
  `unlinked`, replaces the SSH-only field; the marks stay in the session
  and the agent is told why, instead of losing them silently.
- pwrdisk_ls keeps its listing when show: true cannot reach a window.
- pwrdisk_find with no path skips a scan nested inside another held scan
  instead of counting its entries twice.
- The window's suggested first prompt asks for a proposal, not a
  standing instruction to mark.
- skills/ is checked out with LF everywhere, so frontmatter and digests
  do not change under Git for Windows' autocrlf.
@huntharo
Harold Hunt (huntharo) merged commit 2ce2193 into main Oct 30, 2026
13 checks passed
@huntharo
Harold Hunt (huntharo) deleted the feat/mcp-server branch November 9, 2026 03:30
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant