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)
• File search with glob patterns
• 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. If pattern is provided, listing is recursive up to maxDepth.

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. find does not apply a built-in exclude list; scope your pattern to avoid dependency/build directories (e.g., src/**/*.ts).

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

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 (used by grep when excludePatterns is not provided and includeIgnored is false) 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
  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