cd files-mcp
bun install

# Directories the agent can access (comma-separated)
FS_ROOTS=/path/to/vault,/path/to/docs

# Or for a single directory:
# FS_ROOT=/path/to/vault

# Optional
LOG_LEVEL=info
MAX_FILE_SIZE=1048576

# Force-include ignored folders (comma-separated relative paths)
# These folders will be visible even if matched by .gitignore
# FS_INCLUDE=data,build/output

bun dev

{
  "mcpServers": {
    "filesystem": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/files-mcp/src/index.ts"],
      "env": {
        "FS_ROOTS": "/Users/you/vault,/Users/you/docs"
      }
    }
  }
}

{
  "manifest_version": "0.2",
  "name": "files-mcp",
  "version": "1.0.0",
  "server": {
    "type": "node",
    "entry_point": "dist/index.js",
    "mcp_config": {
      "command": "node",
      "args": ["${__dirname}/dist/index.js"],
      "env": {
        "FS_ROOT": "${user_config.FS_ROOT}"
      }
    }
  },
  "user_config": {
    "FS_ROOT": {
      "type": "directory",
      "title": "Root Directory",
      "description": "The directory the agent will have access to.",
      "required": true
    }
  }
}

🔒 SANDBOXED FILESYSTEM — This tool can ONLY access specific mounted directories.
   You CANNOT access arbitrary system paths like /Users or C:\.
   Always start with fs_read(".") to see available mounts.

⚠️ ALWAYS read a file BEFORE answering questions about its content.
⚠️ ALWAYS read a file BEFORE modifying it (you need the checksum).

MANDATORY WORKFLOW:
1. fs_read(".") → see available mounts
2. fs_search(...) → locate files or content
3. fs_read("path/file.md") → get content + checksum
4. fs_write with dryRun=true → preview diff
5. fs_write with dryRun=false + checksum → apply change
6. fs_manage for structural changes (delete/rename/move/copy/mkdir)

{
  path: string;                    // "." for root, "docs/", "notes/todo.md"
  
  // Options
  depth?: number;                  // Directory traversal depth (default 1)
  details?: boolean;               // Include size/modified (default false)
  lines?: string;                  // "10-50" for partial read
  types?: string[];                // Filter directory listing by type
  glob?: string;                   // Glob filter for listing
  exclude?: string[];              // Exclude patterns
  respectIgnore?: boolean;         // Honor .gitignore (default true)
}

{
  success: boolean;
  path: string;
  type: "directory" | "file";
  
  // For directories
  entries?: Array<{ path, kind, children?, size?, modified? }>;
  summary?: string;
  
  // For files
  content?: {
    text: string;        // With line numbers
    checksum: string;    // Pass to fs_write
    totalLines: number;
    range?: { start: number; end: number };
    truncated: boolean;
  };
  
  hint: string;          // Next action suggestion
}

{
  path: string;                   // "." for all mounts
  query: string;                  // Search term
  target?: "all" | "filename" | "content";
  patternMode?: "literal" | "regex" | "fuzzy";
  caseInsensitive?: boolean;
  wholeWord?: boolean;
  multiline?: boolean;
  types?: string[];
  glob?: string;
  exclude?: string[];
  depth?: number;                 // Default 5
  maxResults?: number;            // Default 100, max 1000
  respectIgnore?: boolean;
}

{
  success: boolean;
  query: string;
  files: Array<{ name: string; path: string }>;        // Filename matches
  content?: Array<{ path: string; line: number; text: string }>;  // Content matches
  totalCount: number;
  truncated: boolean;          // True if maxResults cap was hit
  error?: { code: string; message: string };
  hint: string;                // Actionable guidance
}

{
  path: string;
  operation: "create" | "update";
  
  // For create
  content?: string;
  
  // For update — target by lines
  lines?: string;                  // "10-15" — PREFERRED
  
  // For update — action
  action?: "replace" | "insert_before" | "insert_after" | "delete_lines";
  content?: string;                // New content
  
  // Safety
  checksum?: string;               // From fs_read — RECOMMENDED
  dryRun?: boolean;                // Preview only (default false)
  createDirs?: boolean;            // Auto-create parent dirs (default true)
}

{
  status: "applied" | "preview" | "error";
  path: string;
  operation: "create" | "update";
  
  result?: {
    action: string;              // "created", "would_create", "replaced", etc.
    targetRange?: { start: number; end: number };  // For updates
    newChecksum?: string;        // After apply
    diff?: string;               // Unified diff
  };
  
  error?: {
    code: string;
    message: string;
    recoveryHint: string;        // Always present on errors
  };
  
  hint: string;                  // Actionable guidance
}

{
  operation: "delete" | "rename" | "move" | "copy" | "mkdir" | "stat";
  path: string;
  target?: string;                 // rename/move/copy
  recursive?: boolean;             // mkdir/copy/move only (default false)
  force?: boolean;                 // overwrite (default false)
}

**Output:**
```ts
{
  success: boolean;
  operation: string;
  path: string;
  target?: string;
  stat?: { size, modified, created, isDirectory };
  hint: string;
}

{ "path": "." }

18 items (15 files, 3 directories)

- Core/
- Projects/
- Books/
- map.md
- inbox.md
...

hint: "Showing contents of 'vault'. Use fs_read on any path to explore deeper."

{ "path": ".", "query": "todo", "target": "filename" }

Found 3 filename match(es)

- Core/Todo.md
- Projects/Todo.md
- inbox.md
...

hint: "Found 3 filename match(es)."

{ "path": "Core/Values.md" }

File read complete. Checksum: a1b2c3d4e5f6.

   1| # Values
   2|
   3| ## Integrity
   4| Be honest, even when it's hard.
   5|
   6| ## Growth
   7| Learn something new every day.
...

hint: "To edit this file, use fs_write with checksum a1b2c3d4e5f6."

{ "path": ".", "query": "- \\[ \\] ", "patternMode": "regex", "target": "content" }

Found 7 content match(es) in 4 file(s).

- Projects/Alice.md:12 — "- [ ] Implement search"
- Projects/Alice.md:15 — "- [ ] Add tests"
- inbox.md:3 — "- [ ] Review PR"
...

{
  "path": "Core/Values.md",
  "operation": "update",
  "action": "replace",
  "lines": "3",
  "content": "Act with integrity",
  "checksum": "a1b2c3d4e5f6",
  "dryRun": true
}

DRY RUN — no changes applied.

--- a/Core/Values.md
+++ b/Core/Values.md
@@ -3,1 +3,1 @@
-Be honest, even when it's hard.
+Act with integrity, even when it's hard.

hint: "Review the diff above. Run with dryRun=false to apply."

{
  "operation": "move",
  "path": "Projects/Alice.md",
  "target": "Archive/Alice.md",
  "force": true
}

Move completed successfully.

{
  "path": "inbox.md",
  "operation": "update",
  "action": "replace",
  "lines": "3",
  "content": "- [x] Review PR",
  "checksum": "xyz789"
}

replaced 1 line(s). New checksum: abc123.

hint: "The diff above shows what changed."

FS_INCLUDE=docs,workspaces,data/embeddings

FS_ROOTS=/Users/me/vault,/Users/me/projects,/Users/me/notes

{
  "mcpServers": {
    "filesystem": {
      "command": "bun",
      "args": ["run", "/path/to/files-mcp/src/index.ts"],
      "env": {
        "FS_ROOTS": "/Users/me/vault"
      }
    }
  }
}

{
  "filesystem": {
    "command": "bun",
    "args": ["run", "/path/to/files-mcp/src/index.ts"],
    "env": {
      "FS_ROOTS": "/Users/me/vault"
    }
  }
}

bun dev           # Start with hot reload
bun test          # Run tests
bun run typecheck # TypeScript check
bun run lint      # Lint code
bun run build     # Production build
bun run inspector # Test with MCP Inspector

src/
├── index.ts              # Entry point: stdio transport
├── config/
│   ├── env.ts            # Environment config & mount parsing
│   └── metadata.ts       # Tool descriptions
├── core/
│   ├── capabilities.ts   # Server capabilities
│   └── mcp.ts            # McpServer builder
├── tools/
│   ├── index.ts          # Tool registration
│   ├── fs-read.tool.ts   # Read and explore
│   ├── fs-search.tool.ts # Filename + content search
│   ├── fs-write.tool.ts  # Create and update
│   └── fs-manage.tool.ts # Structural operations
├── lib/
│   ├── checksum.ts       # SHA256 checksums
│   ├── diff.ts           # Unified diff generation
│   ├── filetypes.ts      # Text/binary detection
│   ├── ignore.ts         # .gitignore support
│   ├── lines.ts          # Line manipulation
│   ├── paths.ts          # Multi-mount path resolution
│   └── patterns.ts       # Pattern matching utilities
└── utils/
    ├── errors.ts         # Error utilities
    └── logger.ts         # Logging