| layout | default |
|---|---|
| title | Chapter 2: Filesystem Server |
| nav_order | 2 |
| parent | MCP Servers Tutorial |
Welcome to Chapter 2: Filesystem Server. In this part of MCP Servers Tutorial: Reference Implementations and Patterns, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.
The filesystem server is the canonical example of capability scoping and safe tool design.
The official filesystem server exposes tools for:
- reading text and media files
- writing/editing/moving files
- listing/searching directories
- querying file metadata
- enumerating currently allowed directories
The key design is allowlisted directory boundaries.
Two configuration methods are supported:
- command-line allowed roots
- dynamic roots from clients that support the MCP roots protocol
When roots are provided by the client, they replace static startup roots.
Dynamic roots allow clients to adjust accessible scope at runtime without restarting the server. This is convenient, but it increases the need for:
- explicit trust boundaries
- event logging for root changes
- policy checks before privileged operations
The server marks tools with hints (read-only, idempotent, destructive). These hints are valuable for client UX and safety policies.
Example policy usage:
- auto-run read-only tools
- require confirmation for destructive tools
- require stronger policy checks on non-idempotent mutations
Use dry-run where available before mutating files.
1) run edit in preview mode
2) inspect diff
3) apply if expected
This mirrors modern CI-safe change workflows and reduces accidental corruption.
- path traversal and symlink edge cases
- unexpected binary payload handling
- overly broad root configuration
- insufficient audit metadata for writes
You now understand the filesystem server's core safety model and how to adapt it responsibly.
Next: Chapter 3: Git Server
Most teams struggle here because the hard part is not writing more code, but deciding clear boundaries for edit, preview, mode so behavior stays predictable as complexity grows.
In practical terms, this chapter helps you avoid three common failures:
- coupling core logic too tightly to one implementation path
- missing the handoff boundaries between setup, execution, and validation
- shipping changes without clear rollback or observability strategy
After working through this chapter, you should be able to reason about Chapter 2: Filesystem Server as an operating subsystem inside MCP Servers Tutorial: Reference Implementations and Patterns, with explicit contracts for inputs, state transitions, and outputs.
Use the implementation notes around inspect, diff, apply as your checklist when adapting these patterns to your own repository.
Under the hood, Chapter 2: Filesystem Server usually follows a repeatable control path:
- Context bootstrap: initialize runtime config and prerequisites for
edit. - Input normalization: shape incoming data so
previewreceives stable contracts. - Core execution: run the main logic branch and propagate intermediate state through
mode. - Policy and safety checks: enforce limits, auth scopes, and failure boundaries.
- Output composition: return canonical result payloads for downstream consumers.
- Operational telemetry: emit logs/metrics needed for debugging and performance tuning.
When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.
Use the following upstream sources to verify implementation details while reading this chapter:
- MCP servers repository
Why it matters: authoritative reference on
MCP servers repository(github.com).
Suggested trace strategy:
- search upstream code for
editandpreviewto map concrete implementation paths - compare docs claims against actual runtime/config code before reusing patterns in production
- Tutorial Index
- Previous Chapter: Chapter 1: Getting Started
- Next Chapter: Chapter 3: Git Server
- Main Catalog
- A-Z Tutorial Directory
The find_changed_packages function in scripts/release.py handles a key part of this chapter's functionality:
def find_changed_packages(directory: Path, git_hash: GitHash) -> Iterator[Package]:
for path in directory.glob("*/package.json"):
if has_changes(path.parent, git_hash):
yield NpmPackage(path.parent)
for path in directory.glob("*/pyproject.toml"):
if has_changes(path.parent, git_hash):
yield PyPiPackage(path.parent)
@click.group()
def cli():
pass
@cli.command("update-packages")
@click.option(
"--directory", type=click.Path(exists=True, path_type=Path), default=Path.cwd()
)
@click.argument("git_hash", type=GIT_HASH)
def update_packages(directory: Path, git_hash: GitHash) -> int:
# Detect package type
path = directory.resolve(strict=True)
version = gen_version()
for package in find_changed_packages(path, git_hash):
name = package.package_name()
package.update_version(version)
click.echo(f"{name}@{version}")This function is important because it defines how MCP Servers Tutorial: Reference Implementations and Patterns implements the patterns covered in this chapter.
The cli function in scripts/release.py handles a key part of this chapter's functionality:
# requires-python = ">=3.12"
# dependencies = [
# "click>=8.1.8",
# "tomlkit>=0.13.2"
# ]
# ///
import sys
import re
import click
from pathlib import Path
import json
import tomlkit
import datetime
import subprocess
from dataclasses import dataclass
from typing import Any, Iterator, NewType, Protocol
Version = NewType("Version", str)
GitHash = NewType("GitHash", str)
class GitHashParamType(click.ParamType):
name = "git_hash"
def convert(
self, value: Any, param: click.Parameter | None, ctx: click.Context | None
) -> GitHash | None:
if value is None:
return None
if not (8 <= len(value) <= 40):This function is important because it defines how MCP Servers Tutorial: Reference Implementations and Patterns implements the patterns covered in this chapter.
The update_packages function in scripts/release.py handles a key part of this chapter's functionality:
)
@click.argument("git_hash", type=GIT_HASH)
def update_packages(directory: Path, git_hash: GitHash) -> int:
# Detect package type
path = directory.resolve(strict=True)
version = gen_version()
for package in find_changed_packages(path, git_hash):
name = package.package_name()
package.update_version(version)
click.echo(f"{name}@{version}")
return 0
@cli.command("generate-notes")
@click.option(
"--directory", type=click.Path(exists=True, path_type=Path), default=Path.cwd()
)
@click.argument("git_hash", type=GIT_HASH)
def generate_notes(directory: Path, git_hash: GitHash) -> int:
# Detect package type
path = directory.resolve(strict=True)
version = gen_version()
click.echo(f"# Release : v{version}")
click.echo("")
click.echo("## Updated packages")
for package in find_changed_packages(path, git_hash):
name = package.package_name()
click.echo(f"- {name}@{version}")This function is important because it defines how MCP Servers Tutorial: Reference Implementations and Patterns implements the patterns covered in this chapter.
The generate_notes function in scripts/release.py handles a key part of this chapter's functionality:
)
@click.argument("git_hash", type=GIT_HASH)
def generate_notes(directory: Path, git_hash: GitHash) -> int:
# Detect package type
path = directory.resolve(strict=True)
version = gen_version()
click.echo(f"# Release : v{version}")
click.echo("")
click.echo("## Updated packages")
for package in find_changed_packages(path, git_hash):
name = package.package_name()
click.echo(f"- {name}@{version}")
return 0
@cli.command("generate-version")
def generate_version() -> int:
# Detect package type
click.echo(gen_version())
return 0
@cli.command("generate-matrix")
@click.option(
"--directory", type=click.Path(exists=True, path_type=Path), default=Path.cwd()
)
@click.option("--npm", is_flag=True, default=False)
@click.option("--pypi", is_flag=True, default=False)
@click.argument("git_hash", type=GIT_HASH)
def generate_matrix(directory: Path, git_hash: GitHash, pypi: bool, npm: bool) -> int:This function is important because it defines how MCP Servers Tutorial: Reference Implementations and Patterns implements the patterns covered in this chapter.
flowchart TD
A[find_changed_packages]
B[cli]
C[update_packages]
D[generate_notes]
E[generate_version]
A --> B
B --> C
C --> D
D --> E