README.md•4.33 kB
# 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:
```bash
# Using uv (recommended)
uv sync
# Using poetry
poetry install
# Using pip
pip install -e .
```
2. Run the development server with interactive playground:
```bash
# Using uv
uv run playground
# Using poetry
poetry run playground
```
3. Or run the server without playground:
```bash
# 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](https://smithery.ai))
### Steps
1. **Initialize Git repository** (if not already done):
```bash
cd fileops-server
git init
git add .
git commit -m "Initial commit: File operations MCP server"
```
2. **Create GitHub repository**:
- Go to [github.com](https://github.com) and create a new repository
- Follow GitHub's instructions to push your local repository:
```bash
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](https://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
```python
# Tool: read_file
# Parameters: file_path="example.txt"
# Returns: Contents of example.txt
```
### List Directory
```python
# Tool: list_directory
# Parameters: directory_path=".", pattern="*.py"
# Returns: List of all Python files in the directory
```
### Search in Files
```python
# Tool: search_in_files
# Parameters: search_term="TODO", directory_path=".", file_pattern="*.py"
# Returns: All lines containing "TODO" in Python files
```
### Get File Info
```python
# Tool: get_file_info
# Parameters: file_path="example.txt"
# Returns: Detailed file information (size, type, permissions, etc.)
```
### Count Lines
```python
# 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.