j0hanz/fs-context-mcp-server

FS Context MCP Server

A read-only MCP server that provides AI assistants with secure filesystem access for exploring, searching, and reading files within approved directories.

One-Click Install

Overview

This server enables AI assistants to navigate your filesystem through a set of read-only tools:

• Explore directory structures with ls and tree
• Find files using glob patterns with find
• Search file contents with grep
• Read files with options for previews, line ranges, and batch operations
• Access file metadata through stat and stat_many

All operations are restricted to explicitly approved directories, with no write or modification capabilities.

Features

Directory Operations

• List directory contents with ls
• Render directory trees with configurable depth using tree
• Find files by glob patterns with find

File Operations

• Read single files with optional line ranges or head preview
• Batch read up to 100 files in a single operation
• Get file metadata (size, timestamps, permissions) with stat and stat_many

Search

• Content search across files using grep
• Respects .gitignore patterns and common ignore directories
• Configurable search timeout and worker threads

Security

• Read-only operations only
• Access restricted to explicitly approved directories
• Path traversal protection (blocks .. and symlink escapes)
• RE2-based regex engine prevents ReDoS attacks

When to Use

Quick Start

NPX (Recommended)

For current directory:

npx -y @j0hanz/fs-context-mcp@latest --allow-cwd

For specific projects:

npx -y @j0hanz/fs-context-mcp@latest /path/to/project /path/to/docs

Note: If your MCP client supports the Roots protocol, you can omit directory arguments—the client will provide them automatically.

VS Code

Add to .vscode/mcp.json:

{
  "servers": {
    "fs-context": {
      "command": "npx",
      "args": ["-y", "@j0hanz/fs-context-mcp@latest", "${workspaceFolder}"]
    }
  }
}

Installation

NPX

Run without installation:

npx -y @j0hanz/fs-context-mcp@latest /path/to/dir1 /path/to/dir2

Global Installation

For permanent setup across all projects:

npm install -g @j0hanz/fs-context-mcp
fs-context-mcp /path/to/your/project

From Source

For contributors or custom builds:

git clone https://github.com/j0hanz/fs-context-mcp-server.git
cd fs-context-mcp-server
npm install
npm run build
node dist/index.js /path/to/your/project

Directory Access and Resolution

Access is always restricted to explicitly allowed directories.

1. CLI directories are validated and added first (if provided).
2. --allow-cwd optionally adds the current working directory.
3. MCP Roots from the client are used next:
   • If CLI and/or --allow-cwd are provided, only roots inside those baseline directories are accepted.
   • If no baseline is provided, roots become the allowed directories.
4. If nothing is configured and the client provides no roots, the server starts with no accessible directories and logs a warning until roots are provided.

Notes:

• Windows drive-relative paths like C:path are rejected. Use C:\path or C:/path.
• Reserved Windows device names (e.g., CON, NUL) are blocked.

Configuration

All configuration is optional. Sizes in bytes, timeouts in milliseconds.

Environment Variables

See for examples and CLI usage.

Resources

This server exposes standard MCP resources to provide static documentation and handle large content efficiently.

Note on Large Outputs: Tools like read, read_many, and grep automatically cache content exceeding value limits (default 20k chars). In these cases, the tool returns a preview and a resource_link (URI) that can be read by the client to retrieve the full content.

Tools

All tools return both human-readable text and structured JSON. Structured responses include ok, optional error (with code, message, path, suggestion), plus the tool-specific fields documented below.

roots

List all directories that this server can access.

Returns: Allowed directory paths. Structured output includes ok and directories.

ls

List the immediate contents of a directory (non-recursive). Omit path to use the first allowed root.

Returns: Entries with name, relativePath, type, size, and modified time. Structured output includes ok, path, entries, and totalEntries.

find

Search for files using glob patterns. Omit path to search from the first allowed root. By default, find excludes common dependency/build directories (node_modules, dist, .git, etc.); set includeIgnored: true to include ignored directories and disable built-in excludes.

Notes:

• When includeIgnored=false, results also respect a root .gitignore file (if present under the base path).

Returns: Matching paths (relative) with size and modified date. Structured output includes ok, results, totalMatches, and truncated.

tree

Render a directory tree (bounded recursion). Omit path to use the first allowed root.

• path (string, optional; default: first root): Base directory to render
• maxDepth (number, optional; default: 5): Maximum recursion depth (0 = just the root)
• maxEntries (number, optional; default: 1000): Maximum number of entries before truncating
• includeHidden (boolean, optional; default: false): Include hidden files/directories
• includeIgnored (boolean, optional; default: false): Include ignored dirs and disable built-in + .gitignore filtering

Notes:

• When includeIgnored=false, the tree respects both built-in ignore rules (e.g., node_modules, dist, .git) and a root .gitignore file (if present).

Returns: ASCII tree output plus a structured JSON tree (ok, root, tree, ascii, truncated, totalEntries).

read

Read the contents of a text file.

Notes:

• Reads are UTF-8 text only; binary files are rejected.
• Full reads are capped by MAX_FILE_SIZE (default 10MB). When head is set, output stops at the line limit or size budget, whichever comes first.
• head cannot be combined with startLine/endLine.
• If the content exceeds a size limit (default 20k chars), the tool returns a resource_link instead of inline content.

Returns: File content plus structured metadata (ok, path, content, truncated, totalLines, and range metadata when applicable).

read_many

Read multiple files in parallel.

Notes:

• Reads files as UTF-8 text; binary files are not filtered. Max size per file is capped by MAX_FILE_SIZE (default 10MB).
• Total read budget across all files is capped by MAX_READ_MANY_TOTAL_SIZE.
• No binary detection is performed; use read for single-file safety checks.
• head cannot be combined with startLine/endLine.
• If any file content exceeds the inline limit, it is returned as a resource_link.

Returns: Per-file content or error, plus structured summary (total, succeeded, failed).

stat

Get detailed metadata about a file or directory.

Returns: name, path, type, size, timestamps (created/modified/accessed), permissions, hidden status, MIME type (for files), and symlink target (if applicable). Structured results may include tokenEstimate (rule of thumb: ceil(size/4)).

stat_many

Get metadata for multiple files/directories in parallel.

Returns: Array of file info with individual success/error status, plus summary (total, succeeded, failed).

grep

Search for text content within files.

• Omit path to search from the first allowed root.
• Pass a file path in path to search only that file.

pattern is treated as a literal string and matched case-insensitively.

Example (search a single file):

{ "path": "src/transform.ts", "pattern": "TODO" }

Returns: Matching lines with file path, line number, content, and optional context.

Notes:

• grep skips binary files by default.
• Very large files are skipped based on MAX_SEARCH_SIZE (default 1MB). “No matches” is not proof the text is absent from skipped files.

Note: the grep tool currently exposes only path, pattern, and includeHidden. Context fields are omitted unless enabled internally.

Structured output includes ok, matches, totalMatches, and truncated. Matched line content is trimmed to 200 characters.

Built-in exclude list: grep skips common dependency/build/output directories and files: node_modules, dist, build, coverage, .git, .vscode, .idea, .DS_Store, .next, .nuxt, .output, .svelte-kit, .cache, .yarn, jspm_packages, bower_components, out, tmp, .temp, npm-debug.log, yarn-debug.log, yarn-error.log, Thumbs.db.

Error Codes

Client Configuration

{
  "servers": {
    "fs-context": {
      "command": "npx",
      "args": ["-y", "@j0hanz/fs-context-mcp@latest", "${workspaceFolder}"]
    }
  }
}

{
  "mcpServers": {
    "fs-context": {
      "command": "npx",
      "args": ["-y", "@j0hanz/fs-context-mcp@latest", "C:\\path\\to\\project"]
    }
  }
}

{
  "mcpServers": {
    "fs-context": {
      "command": "npx",
      "args": ["-y", "@j0hanz/fs-context-mcp@latest", "${workspaceFolder}"]
    }
  }
}

[mcp_servers.fs-context]
command = "npx"
args = ["-y", "@j0hanz/fs-context-mcp@latest", "/path/to/your/project"]

{
  "mcpServers": {
    "fs-context": {
      "command": "npx",
      "args": ["-y", "@j0hanz/fs-context-mcp@latest", "${workspaceFolder}"]
    }
  }
}

Security Details

This server implements multiple layers of security:

Development

Prerequisites

• Node.js >= 20.0.0
• npm

Scripts

Project Structure

src/
  index.ts                 # CLI entry point
  server.ts                # MCP server wiring and roots handling
  tools.ts                 # MCP tool registration + response helpers
  schemas.ts               # Zod input/output schemas
  config.ts                # Shared types and formatting helpers
  instructions.md          # Tool usage instructions (bundled in dist)
  lib/                     # Core logic and filesystem operations
  __tests__/               # node:test + tsx tests
node-tests/                # Additional Node.js checks
docs/                      # Static docs assets
dist/                      # Build output (generated)

Troubleshooting

Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Run format, lint, type-check, build, and tests (npm run format && npm run lint && npm run type-check && npm run build && npm run test)
4. Commit your changes (git commit -m 'Add amazing feature')
5. Push to the branch (git push origin feature/amazing-feature)
6. Open a Pull Request

Code Style

• Use TypeScript with strict mode
• Follow ESLint configuration
• Use Prettier for formatting
• Write tests for new features