npm package: @iflow-mcp/sylphx-filesystem-mcp
Description: An MCP server providing filesystem tools relative to a project root.
Author: Sylphx
Latest version: 0.6.0

<div align="center">

# Filesystem MCP 📁

**Secure filesystem operations for AI agents - Token-optimized with batch processing**

[![npm version](https://img.shields.io/npm/v/@sylphlab/filesystem-mcp?style=flat-square)](https://www.npmjs.com/package/@sylphlab/filesystem-mcp)
[![Docker Pulls](https://img.shields.io/docker/pulls/sylphlab/filesystem-mcp?style=flat-square)](https://hub.docker.com/r/sylphlab/filesystem-mcp)
[![License](https://img.shields.io/badge/License-MIT-blue?style=flat-square)](https://github.com/SylphxAI/filesystem-mcp/blob/main/LICENSE)

**Batch operations** • **Project root safety** • **Token optimized** • **Zod validation**

[Quick Start](#-quick-start) • [Installation](#-installation) • [Tools](#-features)

<a href="https://glama.ai/mcp/servers/@sylphlab/filesystem-mcp">
  <img width="380" height="200" src="https://glama.ai/mcp/servers/@sylphlab/filesystem-mcp/badge" alt="Filesystem MCP Server" />
</a>

</div>

---

## 🚀 Overview

Empower your AI agents (like Claude/Cline) with secure, efficient, and token-saving access to your project files. This Node.js server implements the [Model Context Protocol (MCP)](https://docs.modelcontextprotocol.com/) to provide a robust set of filesystem tools.

**The Problem:**
```
Traditional AI filesystem access:
- Shell commands for each operation ❌
- No batch processing (high token cost) ❌
- Unsafe (no project root boundaries) ❌
- High latency (shell spawn overhead) ❌
```

**The Solution:**
```
Filesystem MCP Server:
- Batch operations (10+ files at once) ✅
- Token optimized (reduce round trips) ✅
- Secure (confined to project root) ✅
- Direct API (no shell overhead) ✅
```

**Result: Safe, fast, and token-efficient filesystem operations for AI agents.**

---

## ⚡ Performance Advantages

### Token & Latency Optimization

| Metric | Individual Shell Commands | Filesystem MCP | Improvement |
|--------|---------------------------|----------------|-------------|
| **Operations/Request** | 1 file | 10+ files | **10x reduction** |
| **Round Trips** | N operations | 1 request | **N× fewer** |
| **Latency** | Shell spawn per op | Direct API | **5-10× faster** |
| **Token Usage** | High overhead | Batched context | **50-70% less** |
| **Error Reporting** | stderr parsing | Per-item status | Detailed |

### Real-World Benefits

- **Batch file reads** - Read 10 files in one request vs 10 requests
- **Multi-file edits** - Edit multiple files with single tool call
- **Recursive operations** - List entire directory trees efficiently
- **Detailed status** - Per-item success/failure reporting

---

## 🎯 Why Choose This Server?

### Security & Safety

- **🛡️ Project Root Confinement** - All operations restricted to `cwd` at launch
- **🔒 Permission Control** - Built-in chmod/chown tools
- **✅ Validation** - Zod schemas validate all arguments
- **🚫 Path Traversal Prevention** - Cannot escape project directory

### Efficiency & Performance

- **⚡ Batch Processing** - Process multiple files/directories per request
- **🎯 Token Optimized** - Reduce AI-server communication overhead
- **🚀 Direct API** - No shell process spawning
- **📊 Detailed Results** - Per-item status for batch operations

### Developer Experience

- **🔧 Easy Setup** - `npx`/`bunx` for instant use
- **🐳 Docker Ready** - Official Docker image available
- **📦 Comprehensive Tools** - 11+ filesystem operations
- **🔄 MCP Standard** - Full protocol compliance

---

## 📦 Installation

### Method 1: npx/bunx (Recommended)

The simplest way - always uses latest version from npm.

**Using npx:**
```json
{
  "mcpServers": {
    "filesystem-mcp": {
      "command": "npx",
      "args": ["@sylphlab/filesystem-mcp"],
      "name": "Filesystem (npx)"
    }
  }
}
```

**Using bunx:**
```json
{
  "mcpServers": {
    "filesystem-mcp": {
      "command": "bunx",
      "args": ["@sylphlab/filesystem-mcp"],
      "name": "Filesystem (bunx)"
    }
  }
}
```

**Important:** The server uses its own Current Working Directory (`cwd`) as the project root. Ensure your MCP host (e.g., Cline/VSCode) launches the command with `cwd` set to your project's root directory.

### Method 2: Docker

Use the official Docker image for containerized environments.

```json
{
  "mcpServers": {
    "filesystem-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "/path/to/your/project:/app",
        "sylphlab/filesystem-mcp:latest"
      ],
      "name": "Filesystem (Docker)"
    }
  }
}
```

**Remember to replace `/path/to/your/project` with your actual project path.**

### Method 3: Local Build (Development)

```bash
# Clone repository
git clone https://github.com/SylphxAI/filesystem-mcp.git
cd filesystem-mcp

# Install dependencies
pnpm install

# Build
pnpm run build

# Watch mode (auto-rebuild)
pnpm run dev
```

**MCP Host Configuration:**
```json
{
  "mcpServers": {
    "filesystem-mcp": {
      "command": "node",
      "args": ["/path/to/filesystem-mcp/dist/index.js"],
      "name": "Filesystem (Local Build)"
    }
  }
}
```

---

## 🚀 Quick Start

Once configured in your MCP host (see Installation), your AI agent can immediately use the filesystem tools.

### Example Agent Interaction

```xml
<use_mcp_tool>
  <server_name>filesystem-mcp</server_name>
  <tool_name>read_content</tool_name>
  <arguments>{"paths": ["src/index.ts", "package.json"]}</arguments>
</use_mcp_tool>
```

**Server Response:**
```json
{
  "results": [
    {
      "path": "src/index.ts",
      "content": "...",
      "success": true
    },
    {
      "path": "package.json",
      "content": "...",
      "success": true
    }
  ]
}
```

---

## 📋 Features

### File Operations

| Tool | Description | Batch Support |
|------|-------------|---------------|
| **read_content** | Read file contents | ✅ Multiple files |
| **write_content** | Write/append to files | ✅ Multiple files |
| **edit_file** | Surgical edits with diff output | ✅ Multiple files |
| **search_files** | Regex search with context | ✅ Multiple files |
| **replace_content** | Multi-file search & replace | ✅ Multiple files |

### Directory Operations

| Tool | Description | Batch Support |
|------|-------------|---------------|
| **list_files** | List files/directories recursively | Single path |
| **stat_items** | Get detailed file/directory status | ✅ Multiple items |
| **create_directories** | Create directories with parents | ✅ Multiple paths |

### Management Operations

| Tool | Description | Batch Support |
|------|-------------|---------------|
| **delete_items** | Remove files/directories | ✅ Multiple items |
| **move_items** | Move/rename files/directories | ✅ Multiple items |
| **copy_items** | Copy files/directories | ✅ Multiple items |

### Permission Operations

| Tool | Description | Batch Support |
|------|-------------|---------------|
| **chmod_items** | Change POSIX permissions | ✅ Multiple items |
| **chown_items** | Change ownership | ✅ Multiple items |

**Key Benefit:** Tools supporting batch operations process each item individually and return detailed per-item status reports.

---

## 💡 Design Philosophy

### Core Principles

1. **Security First**
   - All operations confined to project root
   - Path traversal prevention
   - Permission controls built-in

2. **Efficiency Focused**
   - Batch processing reduces token usage
   - Direct API calls (no shell overhead)
   - Minimal communication round trips

3. **Robustness**
   - Per-item success/failure reporting
   - Detailed error messages
   - Zod schema validation

4. **Simplicity**
   - Clear, consistent API
   - MCP standard compliance
   - Easy integration

---

## 📊 Comparison with Alternatives

| Feature | Filesystem MCP | Shell Commands | Other Scripts |
|---------|----------------|----------------|---------------|
| **Security** | ✅ Root confined | ❌ Full shell access | ⚠️ Variable |
| **Token Efficiency** | ✅ Batching | ❌ One op/command | ⚠️ Variable |
| **Latency** | ✅ Direct API | ❌ Shell spawn | ⚠️ Variable |
| **Batch Operations** | ✅ Most tools | ❌ No | ⚠️ Maybe |
| **Error Reporting** | ✅ Per-item detail | ❌ stderr parsing | ⚠️ Variable |
| **Setup** | ✅ Easy (npx/Docker) | ⚠️ Secure shell setup | ⚠️ Custom |
| **MCP Standard** | ✅ Full compliance | ❌ No | ⚠️ Variable |

---

## 🛠️ Tech Stack

| Component | Technology |
|-----------|------------|
| **Language** | TypeScript (strict mode) |
| **Runtime** | Node.js / Bun |
| **Protocol** | Model Context Protocol (MCP) |
| **Validation** | Zod schemas |
| **Package Manager** | pnpm |
| **Distribution** | npm + Docker Hub |

---

## 🎯 Use Cases

### AI Agent Development
Enable AI agents to:
- **Read project files** - Access code, configs, docs
- **Edit multiple files** - Refactor across codebase
- **Search codebases** - Find patterns and definitions
- **Manage project structure** - Create, move, organize files

### Code Assistants
Build powerful coding tools:
- **Cline/Claude integration** - Direct filesystem access
- **Batch refactoring** - Edit multiple files at once
- **Safe operations** - Confined to project directory
- **Efficient operations** - Reduce token costs

### Automation & Scripting
Automate development tasks:
- **File generation** - Create boilerplate files
- **Project setup** - Initialize directory structures
- **Batch processing** - Handle multiple files efficiently
- **Content transformation** - Search and replace across files

---

## 🗺️ Roadmap

**✅ Completed**
- [x] Core filesystem operations (read, write, edit, etc.)
- [x] Batch processing for most tools
- [x] Project root security
- [x] Docker image
- [x] npm package
- [x] Zod validation

**🚀 Planned**
- [ ] File watching capabilities
- [ ] Streaming support for large files
- [ ] Advanced filtering for `list_files`
- [ ] Performance benchmarks
- [ ] Compression/decompression tools
- [ ] Symlink management

---

## 🤝 Contributing

Contributions are welcome! Please follow these guidelines:

1. **Fork the repository**
2. **Create a feature branch** - `git checkout -b feature/my-feature`
3. **Write tests** - Ensure good coverage
4. **Follow TypeScript strict mode** - Type safety first
5. **Add documentation** - Update README if needed
6. **Submit a pull request**

### Development Setup

```bash
# Clone and install
git clone https://github.com/SylphxAI/filesystem-mcp.git
cd filesystem-mcp
pnpm install

# Build
pnpm run build

# Watch mode (auto-rebuild)
pnpm run dev
```

---

## 🤝 Support

[![npm](https://img.shields.io/npm/v/@sylphlab/filesystem-mcp?style=flat-square)](https://www.npmjs.com/package/@sylphlab/filesystem-mcp)
[![GitHub Issues](https://img.shields.io/github/issues/SylphxAI/filesystem-mcp?style=flat-square)](https://github.com/SylphxAI/filesystem-mcp/issues)

- 🐛 [Bug Reports](https://github.com/SylphxAI/filesystem-mcp/issues)
- 💬 [Discussions](https://github.com/SylphxAI/filesystem-mcp/discussions)
- 📧 [Email](mailto:hi@sylphx.com)

**Show Your Support:**
⭐ Star • 👀 Watch • 🐛 Report bugs • 💡 Suggest features • 🔀 Contribute

---

## 📄 License

MIT © [Sylphx](https://sylphx.com)

---

## 🙏 Credits

Built with:
- [Model Context Protocol](https://docs.modelcontextprotocol.com/) - MCP standard
- [Zod](https://zod.dev) - Schema validation
- [TypeScript](https://typescriptlang.org) - Type safety
- [pnpm](https://pnpm.io) - Package manager

Special thanks to the MCP community ❤️

---

## 📚 Publishing

This repository uses GitHub Actions to automatically publish to:
- **npm**: [@sylphlab/filesystem-mcp](https://www.npmjs.com/package/@sylphlab/filesystem-mcp)
- **Docker Hub**: [sylphlab/filesystem-mcp](https://hub.docker.com/r/sylphlab/filesystem-mcp)

Triggered on version tags (`v*.*.*`) pushed to `main` branch.

**Required secrets**: `NPM_TOKEN`, `DOCKERHUB_USERNAME`, `DOCKERHUB_TOKEN`

---

<p align="center">
  <strong>Secure. Efficient. Token-optimized.</strong>
  <br>
  <sub>The filesystem MCP server that saves tokens and keeps your projects safe</sub>
  <br><br>
  <a href="https://sylphx.com">sylphx.com</a> •
  <a href="https://x.com/SylphxAI">@SylphxAI</a> •
  <a href="mailto:hi@sylphx.com">hi@sylphx.com</a>
</p>