mcp

# @shieldfive/mcp

A [Model Context Protocol](https://modelcontextprotocol.io) server that lets
Claude, ChatGPT, Cursor or a local model tidy two things:

- **your ShieldFive vault**: find duplicates, see what takes the space, rename,
  move, and move to the Bin. It works on the folders you grant, decrypts on your
  machine, and every change can be undone;
- **folders on your own disk**: the same jobs, with no network access at all.

ShieldFive's servers never see a file name or a byte of content in the clear,
and that holds with this server running too. Decryption happens inside this
process, on your computer. What the assistant then does with what it reads is a
separate question, answered under [Security model](#security-model).

<!-- DEMO: a 40-second screen recording of a duplicate-cleanup session in Claude
Desktop: "find duplicates in my Photos" → groups with sizes → "trash the copies"
→ preview → confirm → the items appear in ShieldFive's Bin → one is undone from
Settings → AI assistants. Record against a demo vault, never a real one. -->

## Connect your vault in 60 seconds

Requires Node 20 or newer.

1. Add the server to your assistant. For Claude Desktop, add this to
   `claude_desktop_config.json` (Cursor uses the same block in `~/.cursor/mcp.json`):

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

   For Claude Code: `claude mcp add shieldfive -- npx -y @shieldfive/mcp`

2. Restart the assistant and ask it to *tidy up my ShieldFive vault*. It calls
   `vault_connect`, which opens ShieldFive in your browser.
3. In that tab, choose the folders, *Read only* or *Read and organize*, and an
   expiry (1 hour to 90 days), then click **Authorize**.

That is the whole setup: the connection is delivered straight to the server
running on your computer — over `127.0.0.1`, never through ShieldFive — and
stored in your system keychain. Nothing is copied by hand.

To connect before you start a conversation, run `npx -y @shieldfive/mcp login`:
same browser page, same result. `login --paste` takes a connection string you
copied from Settings → AI assistants instead, for a machine with no browser.

`npx @shieldfive/mcp status` shows which connection is configured and whether
ShieldFive still accepts it. `npx @shieldfive/mcp logout` removes it from the
keychain. Revoking it in ShieldFive is what cuts off access everywhere.

For CI or a machine without a keychain, set `SHIELDFIVE_GRANT` to the connection
string instead. Anything that can read the server's environment can then read
the connection, so prefer the keychain wherever there is one. Setting
`SHIELDFIVE_GRANT=none` keeps one client local-only on a machine whose keychain
holds a connection for another.

### How the browser hand-off is kept honest

- The page never accepts a callback URL, only a port number, and builds
  `http://127.0.0.1:<port>/callback` itself. A crafted link cannot send your
  connection anywhere but your own machine.
- The listener accepts exactly one delivery: a POST to `/callback`, `Host`
  exactly the loopback address (so a rebound DNS name is refused), no `Origin`
  but ShieldFive's, and a 256-bit state compared in constant time. Then it
  closes.
- The connection string travels in a form body, never in a URL, so it does not
  land in browser history.
- The listener exists only while a connection is being authorized, and for at
  most 10 minutes.

## Security model

In plain terms:

- **The connection string holds two things.** A *token* the server checks on
  every request, and a *secret* that never leaves your machine. ShieldFive stores
  only a hash of the token and has never seen the secret.
- **The secret opens only the folders you chose.** When you create a connection,
  your browser wraps those folders' keys under a key derived from the secret. It
  wraps nothing else: not your vault root key, not your password, not your
  post-quantum secret key. Subfolders open through the vault's normal folder-key
  chain. A folder you did not choose cannot be opened with anything this server
  holds.
- **ShieldFive enforces scope, expiry and revocation on every request.** The
  checks in this process only produce clearer errors; the server is the
  boundary. Revoking a connection makes its next request fail. Nothing is
  cached that would outlive a revocation.
- **Decryption happens here, in memory.** No plaintext, key or ciphertext is
  written to disk. The vault modules do not import the filesystem, and a test
  asserts that.
- **Nothing is deleted.** `vault_trash` moves items into a folder in your Bin
  that belongs to the connection. There is no permanent-delete tool, and the
  API a connection can reach has no delete route. Every rename, move and trash
  appears in *Settings → AI assistants → Activity* with an Undo button.
- **Every change is previewed first.** Mutating tools report a plan, and the
  confirmed call must carry that plan's token and is refused if the items
  changed in between.

What this does not protect:

- **Your AI provider sees what the assistant reads.** File names, and the
  contents of files the assistant opens, go to the assistant, and for a cloud
  assistant that means to its provider, like the rest of your conversation. The
  only way to avoid that is a local model.
- **Revoking cannot un-read.** Anything the assistant has already read stays
  read. Nothing else survives it: file contents are streamed through
  ShieldFive on each request, so there is no download link to outlive a
  revocation.
- **A connection is built from what the server shows your browser when you
  create it.** Every later extension is checked against your own keys, so a
  compromised server cannot widen a connection afterwards. At the moment of
  creation, though, a compromised server could mislabel which folder you
  picked.
- **A copied connection string is a live key** to the folders it covers until
  it expires or you revoke it. Keep it in the keychain.
- **Files can contain instructions aimed at the assistant.** This server marks
  every name and file content as data, fences file contents in a block the file
  cannot close, caps `vault_trash` at 50 items per call, requires a preview for
  every change, and keeps every change undoable. A model can still be talked
  into a reversible mistake inside the folders you granted.

The full design, including the threat model and the reasoning behind each
decision, is in
[`docs/mcp-grants-design.md`](https://github.com/shieldfive/web/blob/main/docs/mcp-grants-design.md).

## Vault tools

`vault_connect` is always available. The rest are registered once a connection
exists — connecting mid-conversation announces them with
`notifications/tools/list_changed`. Everything below names things by id; paths
are for people.

| Tool | Needs | What it does |
|---|---|---|
| `vault_connect` | — | opens ShieldFive in the browser to authorize a connection, and stores it in the keychain |
| `vault_list_files` | read | files and folders in scope, with decrypted names, paths, sizes, dates |
| `vault_search_files` | read | by name, path, extension, size or date, run locally over decrypted names |
| `vault_storage_stats` | read | totals, the biggest folders and files, a breakdown by type |
| `vault_find_duplicates` | read | same-size files decrypted in memory and compared by SHA-256; budgeted, and says when a result is a lower bound |
| `vault_read_file` | read | text files as fenced, untrusted content (up to 1 M characters); other types return details only |
| `vault_rename` | organize | rename a file or folder |
| `vault_move` | organize | move into another folder in scope |
| `vault_create_folder` | organize | create a folder in scope |
| `vault_trash` | organize | up to 50 items into the connection's folder in the Bin |

Limits a user may meet:

- **Post-quantum files uploaded from a phone or the CLI** show as
  `readable: false` until you next open ShieldFive on the web, which adds the key
  the connection needs. Files uploaded in the web app are ready straight away.
- **The first listing of a large vault takes a while.** Each name costs about
  70 ms of Argon2id, spread over your CPU cores (about 20 seconds for 2,000
  names on 8 cores). Names are cached in memory for the rest of the session.
- **Items at the very top of a whole-vault connection** can be read and moved
  into a folder, but not renamed in place, and nothing can be moved to the top.
  Their names are sealed under your vault root key, which a connection never
  holds.
- **Uploads are not available yet.** The design allows them, but they ship
  after the read and organize tools have been in use for a while.

## Local files

Every path after the package name is a **root**. The local tools can read and
write inside those directories and nowhere else, and make no network request.

```sh
npx @shieldfive/mcp ~/Documents ~/Downloads
```

In `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "shieldfive": {
      "command": "npx",
      "args": ["-y", "@shieldfive/mcp", "/Users/you/Documents", "/Volumes/Archive"]
    }
  }
}
```

With a connection configured and no roots, only the vault tools are registered.
With roots and no connection, only the local tools are, and the server behaves
exactly as 0.2.0 did. With both, you get both.

`SHIELDFIVE_MCP_ROOTS` adds roots as well — the two are combined, not
alternatives — as a list separated by your platform's path separator (`:` on
macOS and Linux, `;` on Windows):

```sh
SHIELDFIVE_MCP_ROOTS="/Users/you/Documents:/Volumes/Archive" npx @shieldfive/mcp
```

Whitespace around a root is ignored. In a path given to a tool it is not: there,
every character is part of the path.

### See it work first

```bash
npm run demo
```

`demo/run-demo.mjs` builds five files in a temporary directory — two with
identical contents under different names, a same-size decoy, a 12 MB archive and
a two-year-old PDF — runs the read tools