feat(filesystem): implement MCP roots protocol for dynamic directory management

[nandsha]

Description

Implements the MCP roots protocol in the filesystem server to enable dynamic directory access management. This allows clients to update the list of accessible directories at runtime without restarting the server.

Server Details

• Server: filesystem
• Changes to: core directory access control, initialization flow, documentation

Motivation and Context

Fixes #401 - The filesystem server previously had a fixed set of allowed directories specified via command-line arguments. This implementation adds support for the MCP roots protocol, enabling flexible directory access configuration and runtime updates to accessible filesystem paths.

How Has This Been Tested?

• Tested with roots-capable client - MCP Inspector (successful dynamic directory updates)
• Tested for backwards compatibility with args
• Tested edge cases: empty roots, invalid directories, no initial directories
• All existing tests pass
• Added test coverage for roots processing utility

Breaking Changes

No breaking changes. The implementation maintains full backwards compatibility:

• Existing command-line configurations continue to work unchanged
• Clients without roots support see no change in behaviour
• Only change: roots-capable clients can now override server directories

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• 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

Implementation Details:

• Server checks client capabilities during initialization
• Roots completely replace command-line directories (not additive)
• Server fetches roots on two occasions:
  1. After initialization (via oninitialized callback)
  2. When client sends roots/list_changed notification
• Comprehensive error handling for missing directories scenario

Key Changes:

1. index.ts:

   • Added roots protocol support with oninitialized callback
   • Added notification handler for roots/list_changed
   • Enhanced error messages for better user guidance

2. README.md:

   • Added "Directory Access Control" section explaining both methods
   • Documented the interaction between command-line args and MCP roots

3. roots-utils.ts:

• Added roots processing logic as testable utility module

4. **tests/roots-utils.test.ts:

• Added test coverage for all URI formats (file://, plain paths)
• Tests for error scenarios (non-existent dirs, files vs directories)
• Edge case testing (empty arrays, invalid paths, complex path normalization)
• 100% statement and function coverage

[olaservo]

Hi @nandsha , thanks a lot for adding this! I finally merged in some changes today to support adding and running tests for the filesystem server: #1405

Could you get the latest from main and add some test coverage for these changes?

[nandsha]

Sure @olaservo, thanks for adding the tests and reaching out

[nandsha]

Hi @olaservo, refactored roots processing logic into roots-utils.ts to make it testable, added full test coverage, and it's ready for your review. Please take a look. Thanks!

[olaservo]

Left a few comments on docs and logging, otherwise I think this LGTM.

[nandsha]

Thanks again @olaservo! Applied the updates from your suggestions. Appreciate you taking the time!

[olaservo]

@nandsha Sorry one quick ask - can you pull in the latest from main? We merged in a couple updates to CI that I'd like to run on this PR. Thanks!

[nandsha]

All good @olaservo, rebased and ready!

[olaservo]

Thanks @nandsha , LGTM! Heads up I'm still checking in on another PR from the core team that might need to go ahead of this, but I'll plan to merge this one on Monday.

[nandsha]

Hi @olaservo, I have synced the latest changes and added symlink resolution and home directory expansion support for roots URI processing. Thanks!

[olaservo]

Hi @nandsha , I checked this out locally on my Windows machine since I realized that platform differences can have a big impact with this server. I ran into some issues running the race condition tests on Windows, that were due to the environment being less permissive with creating symlinks by default. There is also a Windows-specific issue with the way the path is being validated. However, there is also an incoming PR I'm helping prepare to add Windows fixes, so I am going to go ahead and merge this and then address those as a fast follow.

One other thing I'm thinking about is how to validate this more fully end-to-end with a client that is actually integrated with a model. I think that is outside of the scope of the groundwork you did here, since this change has been validated with Inspector. Basically this PR is still ahead of the curve on where most host apps are at wrt Roots (to the best of my knowledge). But I think it will actually be useful in helping us solve that chicken or egg problem.

If you have any interest in getting involved with a new Community Working Group around validation and reference implementations, please take a look at the CWG repo for more info on how to get involved there too: https://github.com/modelcontextprotocol-community/working-groups?tab=readme-ov-file#participation-and-contributions

[therealsickonechase-bit]

No directory root