Filesystem MCP Server

A Model Context Protocol (MCP) server implementation providing file system operations, analysis, and manipulation capabilities through a standardized tool interface.

Architecture

The server is built on the MCP SDK and organized into distinct layers:

graph TD
    A[MCP Server Layer] --> B[Tool Registry]
    B --> C[Operations Layer]
    C --> D[File System Operations]
    C --> E[Analysis Operations]
    C --> F[Stream Operations]

Components

• Server Layer: Handles MCP protocol communication and tool dispatch
• Tool Registry: Manages tool registration and execution
• Operations Layer: Implements core functionality
• File System Interface: Provides safe file system access

Installation

1. Clone the repository:

git clone 
cd filesystem-server

2. Install dependencies:

npm install

3. Build the server:

npm run build

4. Configure MCP settings (cline_mcp_settings.json):

{
  "mcpServers": {
    "filesystem": {
      "command": "node",
      "args": ["path/to/filesystem-server/build/index.js"]
    }
  }
}

Tool Reference

Directory Operations

list_directory

Lists directory contents with metadata.

interface ListDirectoryParams {
    path: string;       // Directory path
    recursive?: boolean; // List recursively (default: false)
}

interface ListDirectoryResult {
    entries: {
        name: string;
        path: string;
        isDirectory: boolean;
        size: number;
        created: string;
        modified: string;
        accessed: string;
        mode: string;
    }[];
}

create_directory

Creates a new directory.

interface CreateDirectoryParams {
    path: string;       // Directory path
    recursive?: boolean; // Create parent directories (default: true)
}

File Operations

read_file

Reads file content with encoding support.

interface ReadFileParams {
    path: string;     // File path
    encoding?: string; // File encoding (default: 'utf8')
}

write_file

Writes content to a file.

interface WriteFileParams {
    path: string;     // File path
    content: string;  // Content to write
    encoding?: string; // File encoding (default: 'utf8')
}

append_file

Appends content to a file.

interface AppendFileParams {
    path: string;     // File path
    content: string;  // Content to append
    encoding?: string; // File encoding (default: 'utf8')
}

Analysis Operations

analyze_text

Analyzes text file properties.

interface AnalyzeTextParams {
    path: string; // File path
}

interface AnalyzeTextResult {
    lineCount: number;
    wordCount: number;
    charCount: number;
    encoding: string;
    mimeType: string;
}

calculate_hash

Calculates file hash using specified algorithm.

interface CalculateHashParams {