Files and paths can be disallowed inside of directories

[cantino]

This code was entirely written by Claude, with incremental testing by the human.

Description

Added the ability to exclude specific paths from filesystem access using patterns in the arguments list.

Server Details

• Server: filesystem
• Changes to: Command-line arguments processing, path validation, exclusion logic

Motivation and Context

Users needed more control over which files and directories could be accessed within an allowed directory. This change allows specifying excluded paths (e.g., .env files, build directories, .git directories) that should never be accessible, even if they exist within an allowed directory.

The feature provides enhanced security by allowing fine-grained access control. For instance, a user can allow access to a project directory while preventing access to sensitive files or directories within it.

How Has This Been Tested?

• Tested with Docker configuration to verify exclusion patterns work correctly
• Verified that negation patterns (e.g., !.git) can re-enable access to otherwise excluded paths
• Confirmed case-insensitive matching works (e.g., TSCONFIG.json excludes both uppercase and lowercase variants)
• Validated subdirectory exclusions (e.g., test/foo excludes that specific subdirectory)
• Tested all filesystem operations (read, write, list, etc.) to ensure excluded paths are consistently blocked

Breaking Changes

Existing configurations without exclusion patterns will continue to work as before, except that now .git and node_modules are excluded by default.

Types of changes

• New feature (non-breaking change which adds functionality)
• Bug fix (non-breaking change which fixes an issue)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update

Checklist

• I have read the MCP Protocol Documentation
• My changes follows MCP security best practices
• I have updated the server's README accordingly
• I have tested this with an LLM client
• My code follows the repository's style guidelines
• New and existing tests pass locally
• I have added appropriate error handling
• I have documented all environment variables and configuration options

Additional context

The implementation supports the following features:

1. Default Exclusions: .git and node_modules are excluded by default for security reasons.

2. Custom Exclusions: Add exclusions with the syntax /path/to/dir!file1,dir2,path/to/file3.

3. Negation Patterns: Override default or higher-level exclusions by prefixing with !, e.g., !.git to allow access to the .git directory even though it's excluded by default.

4. Case-Insensitive Matching: All exclusion patterns are case-insensitive for security on all operating systems.

5. Path-Based Exclusions: Support for excluding specific paths like test/foo to block access to subdirectories.

Example usage:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/path/to/allowed/dir!.env,dist,secrets"
      ]
    }
  }
}

[olaservo]

Thanks for the PR! Had some minor comments. Also I was trying to compare this to this other PR: #623 to see if this approach would be consistent with that older one which I'm in the process of looking at, too.

[olaservo]

Suggested change

	const DEFAULT_EXCLUSIONS = ['.git', 'node_modules'];
	const DEFAULT_EXCLUSIONS = [
	'.git',
	'node_modules',
	'.env*',
	'id_rsa',
	'id_dsa',
	'*.pem'
	];

(So this could also exclude common secrets/key files by default)

[olaservo]

I think we should make it clearer to the LLM that its not accessible on purpose, something like: Access denied - path matches exclusion pattern

[olaservo]

Same here and with other new errors being added.

[olaservo]

I think as long as the tool descriptions have good descriptions for the LLM then you don't need to add this logging.