modelcontextprotocol / modelcontextprotocol/servers

Return distinct filesystem error codes for missing roots and out-of-scope paths

Open
#3,606 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
TypeScript
Stars
90.5k
Forks
11.7k
Avg merge
2d 2h
Merged PRs (30d)
5

Description

Problem
Filesystem startup and path-validation failures currently surface as free-form text, which makes it hard for clients to distinguish startup misconfiguration from a request that is outside allowed roots.

Why now
The filesystem server is a reference safety boundary for MCP clients. Explicit error taxonomy matters here because clients use it to validate fail-closed behavior.

Evidence packet

  • Commit under test: c4b38bc6382c247a307ace49ede95f9c3e134592
  • Runtime: macOS 15.3 / Darwin 25.3.0 arm64, Node v22.19.0
  • Relevant codepaths:
    • src/filesystem/index.ts
    • src/filesystem/lib.ts
    • src/filesystem/path-validation.ts
  • Minimal repro:
    1. Start the server with no accessible root directories.
    2. Start it with valid roots, then request a path outside those roots.
    3. Compare the resulting startup/tool failure surfaces.
  • Expected: distinct machine-readable classifications for missing roots, invalid path, and out-of-scope path denial.
  • Actual: startup uses plain stderr strings such as Error: None of the specified directories are accessible, while path denial throws generic Access denied ... messages from validatePath.

Scope
This is a platform contract issue in the filesystem reference server.

Validation target
Startup and path-validation tests should assert stable error codes or other machine-readable classifiers for each failure class.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Trace startup handling in src/filesystem/index.ts and path checks in src/filesystem/lib.ts and src/filesystem/path-validation.ts, then reproduce both failure cases described in the issue. Review the existing startup and path-validation tests; done means they assert stable machine-readable classifications distinguishing missing roots, invalid paths, and out-of-scope denials.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
backend, security
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
55/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.