# disk-space-mcp

A small [Model Context Protocol](https://modelcontextprotocol.io) server that
reports and validates free disk space. It exposes a single read-only tool,
`check_disk_space`, backed by Node's `fs.statfs` — no shell-outs to `df`, no
runtime dependencies beyond the MCP SDK and Zod.

## Tool: `check_disk_space`

Reports total / used / available space for the filesystem that contains a path,
and validates it against optional free-space thresholds.

| Argument         | Type   | Default        | Description                                                                 |
| ---------------- | ------ | -------------- | --------------------------------------------------------------------------- |
| `path`           | string | home directory | Any path; stats apply to the filesystem containing it.                      |
| `minFreeGb`      | number | —              | If available space is below this many GiB, `status` becomes `"warning"`.    |
| `minFreePercent` | number | `10`           | If available space is below this percentage, `status` becomes `"warning"`.  |

It returns both a human-readable text block and `structuredContent`:

```json
{
  "path": "/Users/you",
  "totalBytes": 494384795648,
  "usedBytes": 312000000000,
  "freeBytes": 182000000000,
  "availableBytes": 175000000000,
  "usedPercent": 63.11,
  "availablePercent": 35.4,
  "status": "ok",
  "message": "OK: 163 GiB available of 460 GiB (35.4% free, 63.11% used) on /Users/you."
}
```

`availableBytes` (POSIX `bavail`) is the space actually usable by your user and
is the value the thresholds check; `freeBytes` (`bfree`) additionally counts
space reserved for root.

## Develop

```bash
npm install
npm run build      # tsc -> dist/
npm test           # vitest: pure-logic unit tests + in-memory protocol tests
npm run typecheck  # tsc --noEmit
npm run smoke      # build first, then spawn the server and call the tool over stdio
```

## Register with Claude Code

```bash
npm run build
claude mcp add disk-space --scope user -- node /ABSOLUTE/PATH/TO/disk-space-mcp/dist/index.js
```

Or add it manually to an MCP client config:

```json
{
  "mcpServers": {
    "disk-space": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/disk-space-mcp/dist/index.js"]
    }
  }
}
```

## Design notes

- **Layered for testability.** `diskSpace.ts` is a pure module (byte math,
  thresholds, formatting) with no I/O, unit-tested in isolation. `getDiskStats.ts`
  is the thin `fs.statfs` adapter, injected into `createServer()` so the protocol
  wiring can be tested end-to-end against an in-memory transport with fabricated
  stats.
- **stdio-safe.** All diagnostics go to stderr; stdout carries only JSON-RPC.
- **Read-only and shell-free.** The tool only reads filesystem capacity via
  `statfs`; it never reads file contents and never invokes a shell, so there is
  no command-injection surface. Paths are resolved to absolute and failures
  (missing path, permission denied) return a clean `isError` result.
- **Unit semantics.** Byte counts use `frsize` when available (Node ≥ 24.16),
  falling back to `bsize` on older runtimes. Sizes are formatted with binary
  (IEC) units — KiB / MiB / GiB.

## Security

- **Read-only, shell-free.** The only side effect is `fs.statfs`. There is no
  `child_process`/`exec`/`spawn` anywhere, so there is no command-injection
  surface, and `statfs` exposes filesystem capacity only — never file contents.
- **Input is validated at the boundary.** The `path` argument is length-capped
  and rejected if it contains control characters (NUL, ESC, CR, …), which both
  neutralizes `statfs`'s silent null-byte truncation and prevents control/ANSI
  sequences from being reflected into tool output that a terminal or agent later
  renders. `minFreeGb` / `minFreePercent` are bounded and must be finite.
- **No information leak on error.** Failures return a clean `isError` result
  with an errno code (e.g. `ENOENT`) rather than raw runtime internals; full
  error detail is logged to stderr only.
- **stdio-only.** Only `StdioServerTransport` is instantiated. The MCP SDK
  transitively pulls in an HTTP/auth stack that this server never uses; since
  consumers only run the stdio binary, those code paths are never reached. For a
  hardened install, `npm ci --ignore-scripts` is safe (no runtime dependency
  needs an install script). CI gates production dependencies with
  `npm audit --omit=dev --audit-level=high`.

## License

MIT — see [LICENSE](LICENSE).