On macOS, /tmp is a symlink to /private/tmp. When users specify /tmp
as an allowed directory, the server was resolving it to /private/tmp
during startup but then rejecting paths like /tmp/file.txt because
they dont start with /private/tmp.
This fix stores BOTH the original normalized path AND the resolved
path in allowedDirectories, so users can access files through either
form. For example, with /tmp as allowed directory, both /tmp/file.txt
and /private/tmp/file.txt will now be accepted.
Fixes#3253
Previously, the server would crash if any configured directory was
unavailable (e.g., unmounted external drive). Now it:
- Filters out inaccessible directories with a warning
- Continues operating with remaining accessible directories
- Only fails if NO directories are accessible
Fixes#2815
**Files touched**
- [src/filesystem/index.ts](../blob/HEAD/src/filesystem/index.ts) — add `annotations` metadata to each tool definition
- [src/filesystem/README.md](../blob/HEAD/src/filesystem/README.md) — document ToolAnnotations mapping for all filesystem tools
## Description
This change adds MCP `ToolAnnotations` (`readOnlyHint`, `idempotentHint`, `destructiveHint`) to all filesystem tools and documents the mapping in the filesystem README. MCP clients can now accurately distinguish read‑only vs. write tools, understand which operations are safe to retry, and highlight potentially destructive actions.
## Server Details
- **Server**: filesystem
- **Area**: tools (metadata returned via `listTools` / `ListToolsRequest`) and server docs
## Motivation and Context
Previously, the filesystem server did not expose ToolAnnotations, so many clients (e.g. ChatGPT Apps) conservatively treated filesystem tools as generic write operations. This led to:
- READ operations being surfaced with WRITE badges and confirmation prompts.
- No way for clients to know which write tools are idempotent or potentially destructive.
This PR aligns the implementation with `servers#2988` and updates the README to clearly document the semantics of each tool. Read‑only operations no longer need to be treated as writes, and destructive/idempotent behavior is explicit for UI and retry logic.
## How Has This Been Tested?
- `npm run build --workspace @modelcontextprotocol/server-filesystem`
- `npm test --workspaces --if-present`
## Breaking Changes
None.
## Types of changes
- [ ] Bug fix (non-breaking change which fixes an issue)
- [x] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to change)
- [x] Documentation update
## Checklist
- [x] I have read the [MCP Protocol Documentation](https://modelcontextprotocol.io)
- [x] My changes follows MCP security best practices
- [x] I have updated the server's README accordingly
- [x] I have tested this with an LLM client
- [x] My code follows the repository's style guidelines
- [x] New and existing tests pass locally
- [x] I have added appropriate error handling
- [ ] I have documented all environment variables and configuration options
## Additional context
None.
Co-authored-by: Valeriy_Pavlovich <vp@strato.space>
For text-only tool responses, simplify outputSchemas from complex nested
arrays to simple { content: z.string() } format. All tool responses now
include structuredContent matching their outputSchema, fixing MCP protocol
violations when tools had output schemas but no structured content.
This applies to both filesystem and everything servers.
Address two items from Camila's review:
1. Use blob type for non-image/non-audio media files, restoring the
original behavior. This matches the previous implementation which
used blob as the fallback for unknown binary types. Use type
assertion to satisfy the SDK's type constraints.
2. Reuse ReadTextFileArgsSchema.shape in the deprecated read_file tool
instead of redefining the schema inline.
* fix(filesystem): convert to modern TypeScript SDK APIs
Convert the filesystem server to use the modern McpServer API instead
of the low-level Server API.
Key changes:
- Replace Server with McpServer from @modelcontextprotocol/sdk/server/mcp.js
- Convert all 13 tools to use registerTool() instead of manual request handlers
- Use Zod schemas directly in inputSchema/outputSchema
- Add structuredContent to all tool responses
- Fix type literals to use 'as const' assertions
- Update roots protocol handling to use server.server.* pattern
- Fix tsconfig to exclude vitest.config.ts
Tools converted:
- read_file (deprecated)
- read_text_file
- read_media_file
- read_multiple_files
- write_file
- edit_file
- create_directory
- list_directory
- list_directory_with_sizes
- directory_tree
- move_file
- search_files
- get_file_info
- list_allowed_directories
The modern API provides:
- Less boilerplate code
- Better type safety with Zod
- More declarative tool registration
- Cleaner, more maintainable code
* fix: use default import for minimatch
minimatch v10+ uses default export instead of named export
* fix(filesystem): use named import for minimatch
The minimatch module doesn't have a default export, so we need to use
the named import syntax instead.
Fixes TypeScript compilation error:
error TS2613: Module has no default export. Did you mean to use
'import { minimatch } from "minimatch"' instead?
- Update documentation with directory_tree declaration
- Add excludePatterns parameter to DirectoryTreeArgsSchema
- Implement pattern exclusion in buildTree function using minimatch
- Pass excludePatterns through recursive calls
- Support both simple and glob patterns for exclusion
- Maintain consistent behavior with search_files implementation
* Add tests and fix implementation
---------
Co-authored-by: Ola Hungerford <olahungerford@gmail.com>
Co-authored-by: Adam Jones <adamj+git@anthropic.com>
Co-authored-by: Adam Jones <adamj@anthropic.com>
* fix: comprehensive Windows path handling improvements
- Add path-utils module for consistent path handling
- Handle Windows paths with spaces via proper quoting
- Support Unix-style Windows paths (/c/path)
- Support WSL paths (/mnt/c/path)
- Add comprehensive test coverage
- Fix path normalization for all path formats
Closes#447
* tested locally and working now
* Add filesystem path utils and tests
* Ensure Windows drive letters are capitalized in normalizePath
* adding test for gh pr comment
* pushing jest and windows testing config
* last commit? fixing comments on PR
* Fix bin and bump sdk
* Remove redundant commonjs version of path-utils and import from ts version
* Remove copying cjs file
* Remove copying run-server
* Remove complex args parsing and do other cleanup
* Add missing tools details to Readme
* Move utility functions from index to lib
* Add more tests and handle very small and very large files edge cases
* Finish refactoring and include original security fix comments
* On Windows, also check for drive root
* Check symlink support on restricted Windows environments
* Fix tests
* Bump SDK and package version
* Clean up
---------
Co-authored-by: olaservo <olahungerford@gmail.com>
Co-authored-by: adam jones <adamj+git@anthropic.com>
The tool description was ambiguous about subdirectory access within allowed directories.
Updated the description to explicitly state that subdirectories are also accessible.
Co-authored-by: claude[bot] <209825114+claude[bot]@users.noreply.github.com>
Co-authored-by: Ola Hungerford <olaservo@users.noreply.github.com>
- Add symlink resolution using fs.realpath() for security consistency
- Support home directory expansion (~/) in root URI specifications
- Improve error handling with null checks, detailed error messages, and informative logging
- Change allowedDirectories from constant to variable to support roots protocol directory management
- Extract roots processing logic from index.ts into testable roots-utils.ts module and add Test suite
- Update README to recommend MCP roots protocol for dynamic directory management
- Add support for dynamic directory updates via MCP roots protocol
- Allow clients to override command-line directories at runtime
- Maintain backwards compatibility with existing command-line args
- Add comprehensive error handling for edge cases
- Update documentation to explain both configuration methods
Fixes#401
- Add head/tail functionality for memory-efficient file reading
- Implement new list_directory_with_sizes command with file size info
- Add formatSize utility for human-readable file sizes
following config throws error
```
"filesystem": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-filesystem",
"~"
]
},
```
```
Error accessing directory ~: Error: ENOENT: no such file or directory, stat '~'
at async Object.stat (node:internal/fs/promises:1032:18)
at async file:///Users/USER_NAME/.npm/_npx/a3241bba59c344f5/node_modules/@modelcontextprotocol/server-filesystem/dist/index.js:33:23━━━━━━━━━━━━━━━━━
at async Promise.all (index 0)
at async file:///Users/USER_NAME/.npm/_npx/a3241bba59c344f5/node_modules/@modelcontextprotocol/server-filesystem/dist/index.js:31:1 {
errno: -2,
code: 'ENOENT',
syscall: 'stat',
path: '~'
}
```
this commit fixes error and allows to set ~ as allowed directory
- Add excludePatterns property to SearchFilesArgsSchema
- Modify searchFiles function to handle path exclusions
- Add minimatch import for glob pattern matching
This change allows excluding specific directories (like node_modules)
from file searches to prevent context window overflow.
Issue: modelcontextprotocol/servers#251
