FS Context MCP Server

A secure, read-only MCP server for filesystem scanning, searching, and analysis with comprehensive security validation.

One-Click Install

Features

• Directory listing (immediate contents)
• Path search with glob patterns (files and directories)
• Content search with regex and context lines
• File reading with head previews (first N lines)
• Batch reads and metadata lookups in parallel
• Security: path validation, symlink escape protection, read-only operations

When to Use

Quick Start

NPX (recommended)

Allow the current working directory explicitly:

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

Or pass explicit directories:

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

If your MCP client supports the Roots protocol, you can omit directory arguments and let the client provide allowed directories. Otherwise, pass explicit directories or use --allow-cwd (if neither is provided, the server defaults to the current working directory).

VS Code (workspace folder)

Add to .vscode/mcp.json:

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

Installation

NPX (no install)

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

Global installation

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

From source

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 defaults to the current working directory and logs a warning.

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 CONFIGURATION.md for examples and CLI usage.

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. Automatically excludes common dependency/build directories (node_modules, dist, .git, etc.). Omit path to search from the first allowed root.

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

read

Read the contents of a text file.

Notes:

• Reads are UTF-8 text only; binary files are rejected.
• Max file size is capped by MAX_FILE_SIZE (default 10MB).

Returns: File content plus structured metadata (ok, path, content, truncated, totalLines).

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 at 100MB.
• No binary detection is performed; use read for single-file safety checks.

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).

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 using regular expressions. Omit path to search from the first allowed root.

Returns: Matching lines with file path, line number, content, and optional context. Structured output includes ok, matches, totalMatches, and truncated. Matched line content is trimmed to 200 characters.

Built-in exclude list includes 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. Pass excludePatterns: [] or includeIgnored: true to disable it.

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

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
  instructions.md          # Tool usage instructions (bundled in dist)
  config/                  # Shared types and formatting helpers
  lib/                     # Core logic and filesystem operations
  schemas/                 # Zod input/output schemas
  tools/                   # MCP tool registration
  __tests__/               # node:test + tsx tests
node-tests/                # Isolated Node.js checks

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 tests and linting (npm run lint && 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