modelcontextprotocol / modelcontextprotocol/servers
Add machine-readable startup errors for filesystem directory validation
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 90.5k
- Forks
- 11.7k
- Avg merge
- 2d 2h
- Merged PRs (30d)
- 5
Description
Filesystem startup failures are currently human-readable only, which makes client-side classification and automated troubleshooting brittle.
Current behavior is insufficient because invalid or inaccessible allowed directories only emit ad hoc stderr strings such as warnings and a final fatal message, but no stable error code or structured payload that a caller can classify.
Why now: the filesystem server is a reference implementation for fail-closed directory access, so startup validation should be as machine-readable as the runtime protocol surface it protects.
Claim-to-codepath map:
- Startup directory validation in
src/filesystem/index.ts - Roots path validation in
src/filesystem/roots-utils.ts - Startup integration tests in
src/filesystem/__tests__/startup-validation.test.ts
Requested behavior:
- Fatal startup validation failures should emit one stable machine-readable error shape.
- The error should identify the failure class (for example
no_accessible_directories) and include the rejected inputs when safe. - Existing fail-closed behavior should remain unchanged.
Evidence Packet
- Commit under test:
a97aba19eb21 - Runtime environment:
- OS: Darwin 25.3.0 arm64
- Node: v22.19.0
- pnpm: 10.23.0
- Minimal repro:
- Start
mcp-server-filesystemwith only inaccessible or invalid directory arguments. - Observe stderr output and process exit.
- Attempt to classify the failure programmatically.
- Start
- Expected behavior: one stable error code/payload for startup validation failures.
- Actual behavior: startup failure details are only available as free-form stderr text.
Acceptance Criteria
- Add a machine-readable startup error format for fatal filesystem directory-validation failures.
- Keep the server fail-closed when no accessible directories are available.
- Add focused startup validation tests that assert the structured error output.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with startup directory validation in src/filesystem/index.ts and roots path validation in src/filesystem/roots-utils.ts, then run src/filesystem/tests/startup-validation.test.ts. Define one stable machine-readable error shape for fatal validation failures, including the failure class and safe rejected inputs. Done means focused tests assert the structured output while no accessible directories still cause fail-closed startup.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- backend
- Issue type
- Feature
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 72/100