File Operations MCP Server

A Model Context Protocol (MCP) server that provides tools for common file processing operations. Built with FastMCP and ready for deployment on Smithery.

Features

This server provides the following file operation tools:

• read_file: Read and return the contents of text files
• list_directory: List files and directories with optional glob pattern filtering
• search_in_files: Search for text across multiple files with pattern matching
• get_file_info: Get detailed information about files (size, type, permissions, etc.)
• count_lines: Count the number of lines in text files

Configuration

The server supports session-specific configuration:

• base_path: Base directory for file operations (default: current directory)
• max_file_size: Maximum file size in bytes to process (default: 1MB)

Security Features

• Path traversal protection (prevents accessing files outside base_path)
• File size limits to prevent memory issues
• Binary file detection and handling
• Error handling for permissions and encoding issues

Local Development

Prerequisites

• Python 3.12 or higher
• uv (recommended), poetry, or pip package manager

Setup

1. Install dependencies:

   # Using uv (recommended)
   uv sync
   
   # Using poetry
   poetry install
   
   # Using pip
   pip install -e .
   

2. Run the development server with interactive playground:

   # Using uv
   uv run playground
   
   # Using poetry
   poetry run playground
   

3. Or run the server without playground:

   # Using uv
   uv run dev
   
   # Using poetry
   poetry run dev
   

The playground provides an interactive interface to test all server tools in real-time.

Deployment to Smithery

Prerequisites

• GitHub account
• Smithery account (connect at smithery.ai)

Steps

1. Initialize Git repository (if not already done):

   cd fileops-server
   git init
   git add .
   git commit -m "Initial commit: File operations MCP server"
   

2. Create GitHub repository:

   • Go to github.com and create a new repository
   • Follow GitHub's instructions to push your local repository:

   git remote add origin https://github.com/YOUR_USERNAME/fileops-server.git
   git branch -M main
   git push -u origin main
   

3. Connect to Smithery:

   • Visit smithery.ai
   • Connect your GitHub account
   • Find your fileops-server repository

4. Deploy:

   • Navigate to the Deployments tab on your server page
   • Click "Deploy" to build and host your server
   • Smithery will automatically containerize and deploy your server

Post-Deployment

Once deployed, you can:

• Share your server with others
• Configure per-user settings (base_path, max_file_size)
• Monitor usage and logs through the Smithery dashboard
• Update the server by pushing changes to GitHub

Project Structure

fileops-server/
├── smithery.yaml              # Smithery runtime configuration
├── pyproject.toml            # Python project configuration
├── README.md                 # This file
└── src/
    └── fileops_server/
        ├── __init__.py       # Package initialization
        └── server.py         # MCP server implementation

Usage Examples

Read a File

# Tool: read_file
# Parameters: file_path="example.txt"
# Returns: Contents of example.txt

List Directory

# Tool: list_directory
# Parameters: directory_path=".", pattern="*.py"
# Returns: List of all Python files in the directory

Search in Files

# Tool: search_in_files
# Parameters: search_term="TODO", directory_path=".", file_pattern="*.py"
# Returns: All lines containing "TODO" in Python files

Get File Info

# Tool: get_file_info
# Parameters: file_path="example.txt"
# Returns: Detailed file information (size, type, permissions, etc.)

Count Lines

# Tool: count_lines
# Parameters: file_path="example.txt"
# Returns: Number of lines in the file

License

MIT License - feel free to use and modify as needed.

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.