bounded-filesystem-mcp 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 Anthropic, PBC
+Copyright (c) 2026 Shivam Singh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,281 @@
-# Temporary Holding Version
+# bounded-filesystem-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A fork of the [Filesystem MCP server](https://github.com/modelcontextprotocol/servers/tree/2026.1.14/src/filesystem) where every tool result has a size limit. Large files are read in windows instead of being returned in one piece.
+
+## Provenance
+
+Vendored from [modelcontextprotocol/servers](https://github.com/modelcontextprotocol/servers), tag [`2026.1.14`](https://github.com/modelcontextprotocol/servers/tree/2026.1.14/src/filesystem) (commit `3e805376da81c063c2798410906b5fd134334a43`), directory `src/filesystem`. This repository's history starts from that snapshot. Upstream is MIT licensed, copyright Anthropic, PBC; see [LICENSE](LICENSE).
+
+`lib.ts`, `path-validation.ts`, `path-utils.ts`, `roots-utils.ts` and their tests are unchanged from upstream (only `__tests__/structured-content.test.ts` is adapted, see below), so they can be synced by copying the files. The changes live in `index.ts` (tool registration) and the new `bounded.ts`.
+
+## Differences from upstream
+
+- **Result cap.** A text result longer than the cap (default 50,000 characters) keeps its first 50,000 characters, never splitting a surrogate pair. A notice is added on its own line:
+  ```
+  [Result truncated: showing characters 1-50,000 of 1,234,567. Call again with offset=50000 to continue.]
+  ```
+  Tools that cannot page say how to narrow the request instead, for example:
+  ```
+  [Result truncated: showing characters 1-50,000 of 812,345. To see the rest, narrow the request: pass a deeper path, or add excludePatterns.]
+  ```
+- **Paged reads.** `read_text_file` and `read_file` take `offset` and `limit`, both counted in characters. Follow the `offset` in each notice to walk the whole file; the last window has no notice. The file is streamed and only the window is kept in memory. `head` and `tail` work as before, but cannot be combined with `offset` or `limit`.
+- **Capped listings.** `read_multiple_files`, `directory_tree`, `search_files`, `list_directory`, `list_directory_with_sizes` and `edit_file`'s diff all use the cap. `read_multiple_files` caps the combined text, and its notice says how many of the requested files were included in full. It reads the files one after another rather than in parallel.
+- **Media size limit.** `read_media_file` refuses files over 5 MB (5,242,880 bytes) with an error naming the file size and the limit. It checks the size before reading any bytes.
+- **Plain text results.** Tools have no `outputSchema` and return no `structuredContent`, only content blocks. Hosts that prefer `structuredContent` would otherwise see the text JSON-escaped and the payload doubled, so a capped result would not be the size the cap promises.
+- The server reports itself as `bounded-filesystem` in `initialize`. Tool names and existing parameters are unchanged.
+
+"Characters" here means UTF-16 code units, the same as a JavaScript string's `length`.
+
+## Options
+
+| Flag | Environment variable | Default | Meaning |
+| --- | --- | --- | --- |
+| `--max-result-chars <n>` | `BOUNDED_FS_MAX_RESULT_CHARS` | `50000` | Largest text result, in characters, before the truncation notice |
+| `--max-media-bytes <n>` | `BOUNDED_FS_MAX_MEDIA_BYTES` | `5242880` | Largest file `read_media_file` will return |
+
+A flag wins over its environment variable. Both flags also accept the `--flag=<n>` form. Everything else on the command line is an allowed directory:
+
+```bash
+bunx bounded-filesystem-mcp@0.1.0 --max-result-chars 40000 /path/to/dir1 /path/to/dir2
+```
+
+## Features
+
+- Read/write files
+- Create/list/delete directories
+- Move files/directories
+- Search files
+- Get file metadata
+- Dynamic directory access control via [Roots](https://modelcontextprotocol.io/docs/learn/client-concepts#roots)
+
+## Directory Access Control
+
+The server uses a flexible directory access control system. Directories can be specified via command-line arguments or dynamically via [Roots](https://modelcontextprotocol.io/docs/learn/client-concepts#roots).
+
+### Method 1: Command-line Arguments
+Specify Allowed directories when starting the server:
+```bash
+bounded-filesystem-mcp /path/to/dir1 /path/to/dir2
+```
+
+### Method 2: MCP Roots (Recommended)
+MCP clients that support [Roots](https://modelcontextprotocol.io/docs/learn/client-concepts#roots) can dynamically update the Allowed directories. 
+
+Roots notified by Client to Server, completely replace any server-side Allowed directories when provided.
+
+**Important**: If server starts without command-line arguments AND client doesn't support roots protocol (or provides empty roots), the server will throw an error during initialization.
+
+This is the recommended method, as this enables runtime directory updates via `roots/list_changed` notifications without server restart, providing a more flexible and modern integration experience.
+
+### How It Works
+
+The server's directory access control follows this flow:
+
+1. **Server Startup**
+   - Server starts with directories from command-line arguments (if provided)
+   - If no arguments provided, server starts with empty allowed directories
+
+2. **Client Connection & Initialization**
+   - Client connects and sends `initialize` request with capabilities
+   - Server checks if client supports roots protocol (`capabilities.roots`)
+   
+3. **Roots Protocol Handling** (if client supports roots)
+   - **On initialization**: Server requests roots from client via `roots/list`
+   - Client responds with its configured roots
+   - Server replaces ALL allowed directories with client's roots
+   - **On runtime updates**: Client can send `notifications/roots/list_changed`
+   - Server requests updated roots and replaces allowed directories again
+
+4. **Fallback Behavior** (if client doesn't support roots)
+   - Server continues using command-line directories only
+   - No dynamic updates possible
+
+5. **Access Control**
+   - All filesystem operations are restricted to allowed directories
+   - Use `list_allowed_directories` tool to see current directories
+   - Server requires at least ONE allowed directory to operate
+
+**Note**: The server will only allow operations within directories specified either via `args` or via Roots.
+
+
+
+## API
+
+### Tools
+
+- **read_text_file**
+  - Read complete contents of a file as text, or a window of it
+  - Inputs:
+    - `path` (string)
+    - `head` (number, optional): First N lines
+    - `tail` (number, optional): Last N lines
+    - `offset` (integer, optional): Character position to start from (default 0)
+    - `limit` (integer, optional): Number of characters to return, clamped to the result cap
+  - Always treats the file as UTF-8 text regardless of extension
+  - Cannot specify both `head` and `tail` simultaneously, or combine either with `offset`/`limit`
+  - Results over the cap end with a notice giving the `offset` to continue from
+  - `read_file` is the deprecated alias and behaves the same
+
+- **read_media_file**
+  - Read an image or audio file
+  - Inputs:
+    - `path` (string)
+  - Streams the file and returns base64 data with the corresponding MIME type
+  - Files over `--max-media-bytes` (default 5 MB) return an error without being read
+
+- **read_multiple_files**
+  - Read multiple files simultaneously
+  - Input: `paths` (string[])
+  - Failed reads won't stop the entire operation
+  - The combined text is capped; the notice says how many files were included in full
+
+- **write_file**
+  - Create new file or overwrite existing (exercise caution with this)
+  - Inputs:
+    - `path` (string): File location
+    - `content` (string): File content
+
+- **edit_file**
+  - Make selective edits using advanced pattern matching and formatting
+  - Features:
+    - Line-based and multi-line content matching
+    - Whitespace normalization with indentation preservation
+    - Multiple simultaneous edits with correct positioning
+    - Indentation style detection and preservation
+    - Git-style diff output with context
+    - Preview changes with dry run mode
+  - Inputs:
+    - `path` (string): File to edit
+    - `edits` (array): List of edit operations
+      - `oldText` (string): Text to search for (can be substring)
+      - `newText` (string): Text to replace with
+    - `dryRun` (boolean): Preview changes without applying (default: false)
+  - Returns detailed diff and match information for dry runs, otherwise applies changes
+  - Best Practice: Always use dryRun first to preview changes before applying them
+
+- **create_directory**
+  - Create new directory or ensure it exists
+  - Input: `path` (string)
+  - Creates parent directories if needed
+  - Succeeds silently if directory exists
+
+- **list_directory**
+  - List directory contents with [FILE] or [DIR] prefixes
+  - Input: `path` (string)
+
+- **list_directory_with_sizes**
+  - List directory contents with [FILE] or [DIR] prefixes, including file sizes
+  - Inputs:
+    - `path` (string): Directory path to list
+    - `sortBy` (string, optional): Sort entries by "name" or "size" (default: "name")
+  - Returns detailed listing with file sizes and summary statistics
+  - Shows total files, directories, and combined size
+
+- **move_file**
+  - Move or rename files and directories
+  - Inputs:
+    - `source` (string)
+    - `destination` (string)
+  - Fails if destination exists
+
+- **search_files**
+  - Recursively search for files/directories that match or do not match patterns
+  - Inputs:
+    - `path` (string): Starting directory
+    - `pattern` (string): Search pattern
+    - `excludePatterns` (string[]): Exclude any patterns.
+  - Glob-style pattern matching
+  - Returns full paths to matches
+
+- **directory_tree**
+  - Get recursive JSON tree structure of directory contents
+  - Inputs:
+    - `path` (string): Starting directory
+    - `excludePatterns` (string[]): Exclude any patterns. Glob formats are supported.
+  - Returns:
+    - JSON array where each entry contains:
+      - `name` (string): File/directory name
+      - `type` ('file'|'directory'): Entry type
+      - `children` (array): Present only for directories
+        - Empty array for empty directories
+        - Omitted for files
+  - Output is formatted with 2-space indentation for readability
+    
+- **get_file_info**
+  - Get detailed file/directory metadata
+  - Input: `path` (string)
+  - Returns:
+    - Size
+    - Creation time
+    - Modified time
+    - Access time
+    - Type (file/directory)
+    - Permissions
+
+- **list_allowed_directories**
+  - List all directories the server is allowed to access
+  - No input required
+  - Returns:
+    - Directories that this server can read/write from
+
+### Tool annotations (MCP hints)
+
+This server sets [MCP ToolAnnotations](https://modelcontextprotocol.io/specification/2025-03-26/server/tools#toolannotations)
+on each tool so clients can:
+
+- Distinguish **read‑only** tools from write‑capable tools.
+- Understand which write operations are **idempotent** (safe to retry with the same arguments).
+- Highlight operations that may be **destructive** (overwriting or heavily mutating data).
+
+The mapping for filesystem tools is:
+
+| Tool                        | readOnlyHint | idempotentHint | destructiveHint | Notes                                            |
+|-----------------------------|--------------|----------------|-----------------|--------------------------------------------------|
+| `read_text_file`            | `true`       | –              | –               | Pure read                                       |
+| `read_media_file`           | `true`       | –              | –               | Pure read                                       |
+| `read_multiple_files`       | `true`       | –              | –               | Pure read                                       |
+| `list_directory`            | `true`       | –              | –               | Pure read                                       |
+| `list_directory_with_sizes` | `true`       | –              | –               | Pure read                                       |
+| `directory_tree`            | `true`       | –              | –               | Pure read                                       |
+| `search_files`              | `true`       | –              | –               | Pure read                                       |
+| `get_file_info`             | `true`       | –              | –               | Pure read                                       |
+| `list_allowed_directories`  | `true`       | –              | –               | Pure read                                       |
+| `create_directory`          | `false`      | `true`         | `false`         | Re‑creating the same dir is a no‑op             |
+| `write_file`                | `false`      | `true`         | `true`          | Overwrites existing files                       |
+| `edit_file`                 | `false`      | `false`        | `true`          | Re‑applying edits can fail or double‑apply      |
+| `move_file`                 | `false`      | `false`        | `false`         | Move/rename only; repeat usually errors         |
+
+> Note: `idempotentHint` and `destructiveHint` are meaningful only when `readOnlyHint` is `false`, as defined by the MCP spec.
+
+## Usage
+
+MCP clients start the server over stdio:
+
+```json
+{
+  "mcpServers": {
+    "filesystem": {
+      "command": "bunx",
+      "args": [
+        "bounded-filesystem-mcp@0.1.0",
+        "/Users/username/Desktop",
+        "/path/to/other/allowed/dir"
+      ]
+    }
+  }
+}
+```
+
+`npx -y bounded-filesystem-mcp@0.1.0 <dirs...>` works the same way.
+
+## Build
+
+```bash
+npm install
+npm run build
+npm test
+```
+
+## License
+
+MIT. The upstream code is copyright Anthropic, PBC; the changes in this fork are copyright Shivam Singh. See [LICENSE](LICENSE).

package/dist/bounded.js

@@ -0,0 +1,184 @@
+import { createReadStream } from "fs";
+import { StringDecoder } from "string_decoder";
+import { validatePath } from "./lib.js";
+// "Characters" throughout are UTF-16 code units, i.e. JavaScript string length.
+export const DEFAULT_MAX_RESULT_CHARS = 50_000;
+export const DEFAULT_MAX_MEDIA_BYTES = 5 * 1024 * 1024;
+const LIMIT_OPTIONS = {
+    "--max-result-chars": { key: "maxResultChars", env: "BOUNDED_FS_MAX_RESULT_CHARS" },
+    "--max-media-bytes": { key: "maxMediaBytes", env: "BOUNDED_FS_MAX_MEDIA_BYTES" },
+};
+function parsePositiveInteger(raw, source) {
+    if (!/^\d+$/.test(raw.trim()) || Number(raw) < 1 || !Number.isSafeInteger(Number(raw))) {
+        throw new Error(`${source} must be a positive integer, got "${raw}"`);
+    }
+    return Number(raw);
+}
+// Flags win over environment variables, which win over the defaults.
+export function parseServerArgs(argv, env = process.env) {
+    const limits = {
+        maxResultChars: DEFAULT_MAX_RESULT_CHARS,
+        maxMediaBytes: DEFAULT_MAX_MEDIA_BYTES,
+    };
+    for (const { key, env: envName } of Object.values(LIMIT_OPTIONS)) {
+        const value = env[envName];
+        if (value !== undefined && value !== "") {
+            limits[key] = parsePositiveInteger(value, envName);
+        }
+    }
+    const directories = [];
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        const [name, inlineValue] = arg.split(/=(.*)/s, 2);
+        if (Object.hasOwn(LIMIT_OPTIONS, name)) {
+            const value = inlineValue ?? argv[++i];
+            if (value === undefined) {
+                throw new Error(`${name} needs a value`);
+            }
+            limits[LIMIT_OPTIONS[name].key] = parsePositiveInteger(value, name);
+        }
+        else {
+            directories.push(arg);
+        }
+    }
+    return { directories, limits };
+}
+const formatCount = (n) => n.toLocaleString("en-US");
+function isHighSurrogate(code) {
+    return code >= 0xd800 && code <= 0xdbff;
+}
+function isLowSurrogate(code) {
+    return code >= 0xdc00 && code <= 0xdfff;
+}
+function splitsSurrogatePair(text, index) {
+    return index > 0 && index < text.length &&
+        isHighSurrogate(text.charCodeAt(index - 1)) && isLowSurrogate(text.charCodeAt(index));
+}
+export function pagingNotice(start, end, total) {
+    return `[Result truncated: showing characters ${formatCount(start + 1)}-${formatCount(end)} of ${formatCount(total)}. ` +
+        `Call again with offset=${end} to continue.]`;
+}
+export function narrowingNotice(end, total, hint, detail = "") {
+    return `[Result truncated: showing characters 1-${formatCount(end)} of ${formatCount(total)}. ` +
+        `${detail}To see the rest, narrow the request: ${hint}.]`;
+}
+// Where to cut `text` so that at most `maxChars` characters stay and no surrogate pair is split.
+export function cutIndex(text, maxChars) {
+    if (text.length <= maxChars) {
+        return text.length;
+    }
+    if (!splitsSurrogatePair(text, maxChars)) {
+        return maxChars;
+    }
+    return maxChars > 1 ? maxChars - 1 : maxChars + 1;
+}
+// Caps a result from a tool that cannot page. `hint` names the parameters that narrow the request.
+export function capText(text, maxChars, hint, detail = "") {
+    const end = cutIndex(text, maxChars);
+    if (end === text.length) {
+        return text;
+    }
+    return `${text.slice(0, end)}\n${narrowingNotice(end, text.length, hint, detail)}`;
+}
+// Streams the file once, keeping only the requested window in memory, and counts its total length.
+// A window edge that would split a surrogate pair moves so the pair stays whole: the start moves
+// back to include it, the end moves back to leave it for the next window (or forward when the
+// window would otherwise be empty, so paging always advances).
+export async function readTextWindow(filePath, offset, limit) {
+    const keepFrom = Math.max(0, offset - 1);
+    const keepTo = offset + limit + 1;
+    const decoder = new StringDecoder("utf8");
+    const kept = [];
+    let position = 0;
+    const keep = (chunk) => {
+        const from = Math.max(keepFrom, position);
+        const to = Math.min(keepTo, position + chunk.length);
+        if (from < to) {
+            kept.push(chunk.slice(from - position, to - position));
+        }
+        position += chunk.length;
+    };
+    for await (const chunk of createReadStream(filePath, { highWaterMark: 64 * 1024 })) {
+        keep(decoder.write(chunk));
+    }
+    keep(decoder.end());
+    const total = position;
+    if (offset > total) {
+        throw new Error(`offset ${offset} is past the end of the file, which has ${formatCount(total)} characters`);
+    }
+    const region = kept.join("");
+    let start = offset;
+    if (splitsSurrogatePair(region, start - keepFrom)) {
+        start -= 1;
+    }
+    let end = Math.min(start + limit, total);
+    if (splitsSurrogatePair(region, end - keepFrom)) {
+        end = end - 1 > start ? end - 1 : end + 1;
+    }
+    return { text: region.slice(start - keepFrom, end - keepFrom), start, end, total };
+}
+export function windowResult(window) {
+    if (window.end >= window.total) {
+        return window.text;
+    }
+    return `${window.text}\n${pagingNotice(window.start, window.end, window.total)}`;
+}
+const ENTRY_SEPARATOR = "\n---\n";
+function entryText(entry) {
+    if ("error" in entry) {
+        const text = `${entry.path}: Error - ${entry.error}`;
+        return { shown: text, fullLength: text.length };
+    }
+    const header = `${entry.path}:\n`;
+    const complete = entry.window.end >= entry.window.total;
+    return {
+        shown: header + entry.window.text + (complete ? "\n" : ""),
+        fullLength: header.length + entry.window.total + 1,
+    };
+}
+// Joins entries the way upstream's read_multiple_files does, capped as a whole. Entries may hold
+// only the start of a file's text, as long as each one holds at least as much as can still fit.
+export function joinMultipleFiles(entries, maxChars) {
+    const parts = entries.map(entryText);
+    const joined = parts.map((p) => p.shown).join(ENTRY_SEPARATOR);
+    const total = parts.reduce((sum, p) => sum + p.fullLength, 0) + ENTRY_SEPARATOR.length * Math.max(0, parts.length - 1);
+    if (total <= maxChars) {
+        return joined;
+    }
+    const end = cutIndex(joined, maxChars);
+    let entryEnd = 0;
+    let complete = 0;
+    for (const [i, part] of parts.entries()) {
+        entryEnd += (i > 0 ? ENTRY_SEPARATOR.length : 0) + part.fullLength;
+        if (entryEnd > end)
+            break;
+        complete++;
+    }
+    const detail = `${complete} of ${entries.length} requested files were included in full. `;
+    const hint = "pass fewer paths, or read the remaining files one at a time with read_text_file using offset";
+    return `${joined.slice(0, end)}\n${narrowingNotice(end, total, hint, detail)}`;
+}
+// Reads the files in order, each only as far as the cap can still show, then joins them.
+export async function readMultipleFiles(paths, maxChars) {
+    const entries = [];
+    let used = 0;
+    for (const filePath of paths) {
+        if (entries.length > 0) {
+            used += ENTRY_SEPARATOR.length;
+        }
+        try {
+            const validPath = await validatePath(filePath);
+            const header = `${filePath}:\n`;
+            const room = Math.max(0, maxChars - used - header.length);
+            const window = await readTextWindow(validPath, 0, room + 1);
+            entries.push({ path: filePath, window });
+            used += header.length + window.total + 1;
+        }
+        catch (error) {
+            const entry = { path: filePath, error: error instanceof Error ? error.message : String(error) };
+            entries.push(entry);
+            used += entryText(entry).fullLength;
+        }
+    }
+    return joinMultipleFiles(entries, maxChars);
+}