@shieldfive/mcp 0.2.0

package/src/scan.mjs

@@ -0,0 +1,269 @@
+// Directory walking and content hashing.
+//
+// Symlinks are never followed. Every entry is inspected with lstat, and a link
+// is counted and skipped rather than traversed. That is a containment decision
+// before it is a loop-avoidance one: following a link is exactly how a walk
+// leaves the configured root, and roots.mjs cannot re-check a path the walk
+// never surfaced.
+//
+// Nothing here is silently truncated. When a cap is hit the result says so and
+// names the number, because a listing that quietly stops is read as a complete
+// listing and the conclusions drawn from it are wrong in a way nobody notices.
+
+import { createHash } from 'node:crypto'
+import { createReadStream } from 'node:fs'
+import { opendir, lstat } from 'node:fs/promises'
+import { extname, join, relative } from 'node:path'
+
+/** Where trash_local moves things. Never walked; see DEFAULT_SKIP_DIRS. */
+export const TRASH_DIR_NAME = '.shieldfive-mcp-trash'
+
+/** Entries whose names are noise in every report. */
+const ALWAYS_SKIP = new Set(['.DS_Store', 'Thumbs.db', 'desktop.ini'])
+
+/**
+ * Directories excluded from every walk: build output, package caches and VCS
+ * metadata.
+ *
+ * `build`, `dist` and `target` are ordinary folder names outside a code tree,
+ * so this list can hide real user data. Every exclusion is counted and reported
+ * in the scan warnings, and there is no way to override the list yet.
+ */
+const DEFAULT_SKIP_DIRS = new Set([
+  'node_modules',
+  '.git',
+  '.svn',
+  '.hg',
+  '.cache',
+  '.venv',
+  'venv',
+  '__pycache__',
+  '.next',
+  '.turbo',
+  'dist',
+  'build',
+  'target',
+  'Pods',
+  '.gradle',
+  '.tox',
+  '.mypy_cache',
+  '.pytest_cache',
+  // This server's own trash. Walking it would offer already-trashed files back
+  // as fresh candidates on the next scan.
+  TRASH_DIR_NAME,
+])
+
+/**
+ * Walk one directory tree, breadth-first.
+ *
+ * `maxDepth` counts levels BELOW the start: the start directory is depth 0, so
+ * the default of 64 walks the start and 64 levels of subdirectories beneath it.
+ *
+ * Every field of `stats` is read by name elsewhere: scanWarnings() in format.mjs
+ * turns the counters into the sentences a user sees, and read.mjs copies a few
+ * into its payloads. Adding a field is safe; renaming one silently drops a
+ * warning.
+ *
+ * @returns {Promise<{
+ *   files: Array<{path, relativePath, size, mtimeMs, extension, hardlinked, dev, ino, nlink}>,
+ *   stats: {
+ *     directories: number, symlinksSkipped: number, hiddenSkipped: number,
+ *     skippedDirectories: string[], hardlinked: string[],
+ *     unreadable: Array<{path, code}>, depthLimited: string[],
+ *     truncated: boolean, maxFiles: number,
+ *   },
+ * }>}
+ */
+export async function walk(
+  startRealPath,
+  {
+    maxFiles = 200_000,
+    maxDepth = 64,
+    includeHidden = false,
+    skipDirs = DEFAULT_SKIP_DIRS,
+    signal,
+  } = {},
+) {
+  const files = []
+  const stats = {
+    directories: 0,
+    symlinksSkipped: 0,
+    hiddenSkipped: 0,
+    skippedDirectories: [],
+    hardlinked: [],
+    unreadable: [],
+    depthLimited: [],
+    truncated: false,
+    maxFiles,
+  }
+
+  const queue = [{ dir: startRealPath, depth: 0 }]
+
+  while (queue.length) {
+    signal?.throwIfAborted()
+    const { dir, depth } = queue.shift()
+
+    if (depth > maxDepth) {
+      stats.depthLimited.push(dir)
+      continue
+    }
+
+    let handle
+    try {
+      handle = await opendir(dir)
+    } catch (err) {
+      stats.unreadable.push({ path: dir, code: err.code })
+      continue
+    }
+    stats.directories++
+
+    try {
+      for await (const entry of handle) {
+        if (files.length >= maxFiles) {
+          stats.truncated = true
+          break
+        }
+        if (ALWAYS_SKIP.has(entry.name)) continue
+
+        const full = join(dir, entry.name)
+
+        // lstat before any name-based branch. The hidden check used to
+        // run on the dirent, so a dot-named symlink was consumed as "hidden"
+        // and never reached the symlink branch -- two links on disk, one
+        // reported. Trust lstat, not the dirent flags: a dirent can report
+        // DT_UNKNOWN on some filesystems, and isSymbolicLink() has to be
+        // authoritative here.
+        let st
+        try {
+          st = await lstat(full)
+        } catch (err) {
+          stats.unreadable.push({ path: full, code: err.code })
+          continue
+        }
+
+        if (st.isSymbolicLink()) {
+          stats.symlinksSkipped++
+          continue
+        }
+
+        const hidden = entry.name.startsWith('.')
+
+        if (st.isDirectory()) {
+          if (skipDirs.has(entry.name)) {
+            stats.skippedDirectories.push(full)
+            continue
+          }
+          if (!includeHidden && hidden) {
+            stats.hiddenSkipped++
+            continue
+          }
+          queue.push({ dir: full, depth: depth + 1 })
+          continue
+        }
+
+        if (!includeHidden && hidden) {
+          stats.hiddenSkipped++
+          continue
+        }
+
+        if (!st.isFile()) continue
+
+        // nlink > 1 means this inode is reachable by another name, possibly
+        // one outside every root. realpath resolves symlinks but not hardlinks,
+        // so containment cannot see that second name. Counting them is the
+        // honest response: it is reported, not silently trusted.
+        if (st.nlink > 1) stats.hardlinked.push(full)
+
+        files.push({
+          path: full,
+          relativePath: relative(startRealPath, full),
+          size: st.size,
+          mtimeMs: st.mtimeMs,
+          extension: extname(entry.name).toLowerCase(),
+          hardlinked: st.nlink > 1,
+          // Recorded so find_duplicates can tell two names of one file from two
+          // copies. Without them a hardlinked pair was reported as a duplicate
+          // whose removal would free space, and it frees none.
+          dev: st.dev,
+          ino: st.ino,
+          nlink: st.nlink,
+        })
+      }
+    } finally {
+      // `for await` closes the handle on normal completion; an early `break`
+      // leaves it open, and an unclosed dir handle is a real leak on a long-
+      // lived stdio server.
+      await handle.close().catch(() => {})
+    }
+
+    if (stats.truncated) break
+  }
+
+  return { files, stats }
+}
+
+/**
+ * Walk every root, tagging each file with the root it came from.
+ *
+ * `notScanned` lists the roots that were never walked because the file budget
+ * ran out first. They used to be walked with a cap of zero and then dropped
+ * from the per-root results, while every tool still listed them as scanned.
+ */
+export async function walkRoots(rootSet, options = {}) {
+  const files = []
+  const perRoot = []
+  const notScanned = []
+  const budget = options.maxFiles ?? 200_000
+
+  for (const root of rootSet) {
+    // A shared budget, decremented per root. Passing the same maxFiles to each
+    // walk made the documented cap a PER-ROOT cap, so N roots returned up to N
+    // times the number the caller asked for.
+    const remaining = budget - files.length
+    if (remaining <= 0 || perRoot.some((r) => r.truncated)) {
+      notScanned.push(root.realPath)
+      continue
+    }
+
+    const result = await walk(root.realPath, { ...options, maxFiles: remaining })
+
+    for (const f of result.files) {
+      f.root = root.realPath
+      // NOT files.push(...result.files): spreading an array as call arguments
+      // exceeds V8's argument limit at roughly 125,000 elements and throws
+      // RangeError, which made every scanning tool crash on a large root well
+      // below the 200,000-file cap the schema advertises.
+      files.push(f)
+    }
+
+    perRoot.push({
+      root: root.realPath,
+      ...result.stats,
+      maxFiles: budget,
+      files: result.files.length,
+    })
+  }
+
+  return { files, perRoot, notScanned }
+}
+
+/**
+ * SHA-256 of a file's bytes, optionally only the first `limit` bytes.
+ *
+ * Content identity is established by hashing content. Nothing in this server
+ * treats matching name and size as evidence that two files are the same — that
+ * inference is wrong often enough to delete the wrong copy, which is the one
+ * mistake this tool must never make.
+ */
+export function hashFile(path, { limit = Infinity, signal } = {}) {
+  return new Promise((resolvePromise, reject) => {
+    const hash = createHash('sha256')
+    const stream = createReadStream(path, {
+      end: Number.isFinite(limit) ? limit - 1 : undefined,
+      signal,
+    })
+    stream.on('error', reject)
+    stream.on('data', (chunk) => hash.update(chunk))
+    stream.on('end', () => resolvePromise(hash.digest('hex')))
+  })
+}

package/src/server.mjs

@@ -0,0 +1,363 @@
+#!/usr/bin/env node
+// @shieldfive/mcp — a Model Context Protocol server for local file management.
+//
+// WHAT THIS SERVER DOES NOT DO, AND WHY THAT IS THE DESIGN
+//
+// It holds no ShieldFive credential, makes no network request, and does not
+// import @shieldfive/crypto. That is not a gap to be filled later; it is the
+// security boundary, expressed as an absence.
+//
+// The alternative was to authenticate with a full ShieldFive account JWT. That
+// token also opens /api/vault-key — the wrapped root key and an ML-KEM public
+// key — and every content-download route, and none of it can be scoped away,
+// because no scoped vault credential exists. A server holding that token would
+// be DECLINING to read your files rather than being UNABLE to, with the
+// difference resting on a client-side denylist and on the token file not being
+// read by anything else on the machine. A server holding no token cannot read
+// them at all. See docs/mcp-v1-step0-discovery.md in shieldfive/web for the
+// full argument, and README.md § "What this cannot do" for the consequences.
+//
+// The cost: v1 cannot tell you whether a local file is already backed up. It
+// will not guess either, because matching a filename and a size against a vault
+// listing is how a tool deletes the only copy of something.
+
+import { readFileSync, realpathSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import { z } from 'zod'
+
+import { toolFailure } from './format.mjs'
+import { LIMITS } from './limits.mjs'
+import { createPlanStore } from './plans.mjs'
+import { NO_ROOTS_MESSAGE, resolveRoots, rootCandidatesFrom, ToolError } from './roots.mjs'
+import {
+  findDuplicates,
+  findLargeFiles,
+  findOldFiles,
+  listLocal,
+  storageSummary,
+} from './tools/read.mjs'
+import { createLocalFolder, moveLocal, renameLocal, trashLocal } from './tools/mutate.mjs'
+
+// Read from package.json rather than repeated here. A second copy had no test,
+// and the first release that forgot to bump it would have reported the old one.
+export const VERSION = JSON.parse(
+  readFileSync(new URL('../package.json', import.meta.url), 'utf8'),
+).version
+
+/** stdout is the protocol channel. Everything human goes to stderr. */
+const log = (...parts) => process.stderr.write(`[shieldfive-mcp] ${parts.join(' ')}\n`)
+
+// Every cap here is also applied by the handler; see limits.mjs. The path cap
+// is not about the filesystem: without it a 5 MB path argument was reflected
+// verbatim into the error message and landed 1:1 in the model's context.
+const pathArg = z
+  .string()
+  .max(LIMITS.pathChars, 'path is longer than any filesystem accepts')
+  .describe('Absolute path. Must resolve inside a configured root; relative paths are refused.')
+
+// A confirmed call carries the token its own preview returned; see plans.mjs.
+const planTokenArg = z
+  .string()
+  .optional()
+  .describe(
+    'The plan_token this tool returned when called without confirm. Required with ' +
+      'confirm: true, single use, and only valid while the plan still matches the tree.',
+  )
+
+const scanArgs = {
+  path: pathArg.optional().describe('Directory to scan. Omit to scan every configured root.'),
+  include_hidden: z.boolean().optional().describe('Include dotfiles and dot-directories.'),
+  max_files: z
+    .number()
+    .int()
+    .positive()
+    .max(LIMITS.maxFiles)
+    .optional()
+    .describe('Stop after this many files, at most 1,000,000. The result says so when the cap is hit.'),
+  limit: z
+    .number()
+    .int()
+    .positive()
+    .max(LIMITS.limit)
+    .optional()
+    .describe('Maximum rows to return, at most 10,000.'),
+}
+
+const TOOLS = [
+  {
+    name: 'list_local',
+    title: 'List local files',
+    description:
+      'List files in an allowed local directory, with sizes and modification dates. ' +
+      'Never follows symlinks and never leaves the configured roots.',
+    inputSchema: { ...scanArgs, sort_by: z.enum(['path', 'size', 'modified']).optional() },
+    annotations: { readOnlyHint: true, openWorldHint: false },
+    handler: listLocal,
+  },
+  {
+    name: 'find_duplicates',
+    title: 'Find duplicate files',
+    description:
+      'Find files with byte-identical contents. Identity is decided by a full SHA-256 ' +
+      'of each file, never by matching names or sizes. Reports how much space keeping ' +
+      'one copy of each would reclaim.',
+    inputSchema: {
+      ...scanArgs,
+      min_bytes: z
+        .number()
+        .int()
+        .nonnegative()
+        .optional()
+        .describe('Ignore files smaller than this. Default 1.'),
+      max_files_hashed: z
+        .number()
+        .int()
+        .positive()
+        .max(LIMITS.maxFilesHashed)
+        .optional()
+        .describe('Hashing budget in reads, at most 1,000,000. When reached, the result says it is a lower bound.'),
+    },
+    annotations: { readOnlyHint: true, openWorldHint: false },
+    handler: findDuplicates,
+  },
+  {
+    name: 'find_large_files',
+    title: 'Find large files',
+    description: 'List files at or above a size threshold, largest first.',
+    inputSchema: {
+      ...scanArgs,
+      min_bytes: z.number().int().positive().optional().describe('Default 100 MB.'),
+    },
+    annotations: { readOnlyHint: true, openWorldHint: false },
+    handler: findLargeFiles,
+  },
+  {
+    name: 'find_old_files',
+    title: 'Find stale files',
+    description:
+      'List files not modified for a given number of days. Modification time is a weak ' +
+      'signal and the result says so; treat the output as a shortlist to review.',
+    inputSchema: {
+      ...scanArgs,
+      older_than_days: z.number().int().positive().optional().describe('Default 365.'),
+    },
+    annotations: { readOnlyHint: true, openWorldHint: false },
+    handler: findOldFiles,
+  },
+  {
+    name: 'storage_summary',
+    title: 'Summarise local storage',
+    description:
+      'Total file count and bytes for the allowed roots, broken down by file extension ' +
+      'and by directory. Reports file-content sizes, which will not match a disk ' +
+      'utility exactly.',
+    inputSchema: scanArgs,
+    annotations: { readOnlyHint: true, openWorldHint: false },
+    handler: storageSummary,
+  },
+  {
+    name: 'move_local',
+    title: 'Move a file or folder',
+    description:
+      'Move a file, directory or symlink to another location inside the allowed roots. ' +
+      'A symlink is moved itself, never what it points to. Without confirm: true this ' +
+      'only reports what it would do. Refuses to overwrite unless overwrite: true is also ' +
+      'passed, and then moves what was there to the trash. Between volumes the move is a ' +
+      'copy, verified before the source is removed.',
+    inputSchema: {
+      source: pathArg,
+      destination: pathArg.describe(
+        'Absolute destination. If it is an existing directory, the source is moved into it.',
+      ),
+      overwrite: z.boolean().optional().describe('Replace the destination if it exists.'),
+      confirm: z.boolean().optional().describe('Required to actually move anything.'),
+      plan_token: planTokenArg
+    },
+    annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: false },
+    handler: moveLocal,
+  },
+  {
+    name: 'rename_local',
+    title: 'Rename a file or folder',
+    description:
+      'Rename an item in place; a symlink is renamed itself. new_name must be a bare ' +
+      'filename, not a path, and is used exactly as given. Never replaces an existing ' +
+      'file. Without confirm: true this only reports the plan.',
+    inputSchema: {
+      path: pathArg,
+      new_name: z
+        .string()
+        .max(LIMITS.nameBytes)
+        .describe('The new filename, used exactly as given: no directory separators, at most 255 bytes.'),
+      confirm: z.boolean().optional().describe('Required to actually rename.'),
+      plan_token: planTokenArg
+    },
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: false,
+      openWorldHint: false,
+    },
+    handler: renameLocal,
+  },
+  {
+    name: 'create_local_folder',
+    title: 'Create a folder',
+    description:
+      'Create a directory (and any missing parents) inside the allowed roots. ' +
+      'Without confirm: true this only reports the plan.',
+    inputSchema: {
+      path: pathArg,
+      confirm: z.boolean().optional().describe('Required to actually create it.'),
+      plan_token: planTokenArg
+    },
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false,
+    },
+    handler: createLocalFolder,
+  },
+  {
+    name: 'trash_local',
+    title: 'Move files to this server’s trash',
+    description:
+      'Move files or folders into a .shieldfive-mcp-trash directory inside their own ' +
+      'root and on their own volume, with a manifest recording where each came from. A ' +
+      'symlink is trashed itself, never what it points to. NOTHING IS DELETED and no ' +
+      'disk space is freed — the bytes stay on the same volume until you empty that ' +
+      'directory yourself. Without confirm: true this only reports the plan.',
+    inputSchema: {
+      paths: z
+        .array(pathArg)
+        .min(1)
+        .max(LIMITS.paths)
+        .describe('Absolute paths to move into the trash, at most 1,000.'),
+      confirm: z.boolean().optional().describe('Required to actually move anything.'),
+      plan_token: planTokenArg
+    },
+    annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: false },
+    handler: trashLocal,
+  },
+]
+
+/**
+ * Run one tool call and render its result or its refusal.
+ *
+ * extra.signal is aborted when the client cancels the request, and the SDK then
+ * sends no response at all. For a tool that changes files the outcome is
+ * therefore written to the log, the only record left of what a cancelled call
+ * did. Every error raised after a cancellation used to be replaced with
+ * "Cancelled.", including a partial trash carrying its account of what had
+ * already moved; a mutation's own error now passes through intact, detail
+ * included, and only a read-only tool's abort becomes a plain cancellation.
+ */
+export async function runTool(tool, ctx, args, extra, write = log) {
+  const signal = extra?.signal
+  const mutates = tool.annotations?.readOnlyHint === false
+  try {
+    const result = await tool.handler({ ...ctx, signal }, args ?? {})
+    if (mutates && signal?.aborted) {
+      write(
+        `${tool.name}: the request was cancelled after the change had started, and it ` +
+          `completed: ${result?.content?.[0]?.text ?? ''}`,
+      )
+    }
+    return result
+  } catch (err) {
+    if (!mutates && (err?.name === 'AbortError' || signal?.aborted)) {
+      return toolFailure(new ToolError('cancelled', 'Cancelled.'))
+    }
+    if (err?.name !== 'ToolError') {
+      write(`${tool.name} failed:`, err?.stack ?? String(err))
+    }
+    if (mutates && signal?.aborted) {
+      write(
+        `${tool.name}: the request was cancelled; outcome: [${err?.code ?? 'error'}] ` +
+          `${err?.message ?? String(err)}`,
+      )
+    }
+    return toolFailure(err)
+  }
+}
+
+export function createServer(ctx) {
+  const server = new McpServer(
+    { name: 'shieldfive-mcp', version: VERSION },
+    {
+      instructions:
+        'Local file management for the directories the user allowed at startup. ' +
+        'This server has no ShieldFive credential and makes no network calls, so it ' +
+        'cannot see, list or verify anything in a ShieldFive vault. Do not tell the ' +
+        'user a local file is backed up: this server cannot know that, and guessing ' +
+        'from a filename and size is how the only copy of something gets deleted. ' +
+        'Mutating tools do nothing until called with confirm: true — show the user ' +
+        'the plan first, then pass back the plan_token that preview returned. A ' +
+        'confirmed call without it, or after the files have changed, is refused.',
+    },
+  )
+
+  for (const tool of TOOLS) {
+    server.registerTool(
+      tool.name,
+      {
+        title: tool.title,
+        description: tool.description,
+        inputSchema: tool.inputSchema,
+        annotations: tool.annotations,
+      },
+      (args, extra) => runTool(tool, ctx, args, extra),
+    )
+  }
+
+  return server
+}
+
+export async function main(argv = process.argv.slice(2), env = process.env) {
+  const { roots, rejected } = await resolveRoots(rootCandidatesFrom(argv, env))
+
+  for (const r of rejected) log(`ignoring root ${r.path}: ${r.reason}`)
+  if (roots.length) {
+    log(`serving ${roots.length} root(s):`, roots.map((r) => r.realPath).join(', '))
+  } else {
+    log('NO ROOTS CONFIGURED — every tool will refuse.')
+    log(NO_ROOTS_MESSAGE)
+  }
+
+  const now = () => Date.now()
+  const ctx = { roots, noRootsMessage: NO_ROOTS_MESSAGE, now, plans: createPlanStore({ now }) }
+  const server = createServer(ctx)
+  await server.connect(new StdioServerTransport())
+  log('ready on stdio.')
+  return server
+}
+
+/**
+ * Is this module the program, rather than something someone imported?
+ *
+ * Both sides must be realpath'd. npm installs the `bin` as a SYMLINK — argv[1]
+ * is `node_modules/.bin/shieldfive-mcp` while `import.meta.url` is the resolved
+ * `node_modules/@shieldfive/mcp/src/server.mjs`. Comparing them unresolved is
+ * false for every installed copy, so the server exits silently the moment it is
+ * run the way an actual user runs it. `import.meta.main` would avoid this but
+ * is Node 24+, and this package supports 20.
+ */
+function isMain() {
+  if (!process.argv[1]) return false
+  try {
+    return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))
+  } catch {
+    return false
+  }
+}
+
+if (isMain()) {
+  main().catch((err) => {
+    log('fatal:', err?.stack ?? String(err))
+    process.exit(1)
+  })
+}