# MCP File Manager — File System Operations for AI Agents

> An MCP server that gives AI agents file system access: read, write, search, hash, directory trees — 12 tools, zero dependencies, pure Python stdlib.

## Features

- **12 MCP Tools**: `read_file`, `read_file_lines`, `write_file`, `append_file`, `delete_file`, `copy_file`, `move_file`, `list_directory`, `search_files`, `file_info`, `file_hash`, `directory_tree`
- **Zero dependencies** — pure Python stdlib (os, shutil, hashlib, fnmatch, pathlib)
- **Content search** — grep-like search inside files (20+ file extensions)
- **File hashing** — MD5, SHA-1, SHA-256, SHA-512
- **Directory trees** — recursive tree generation with depth control
- **STDIO JSON-RPC mode** — drop-in for Claude Desktop, Hermes, or any MCP client

## Quick Start

```bash
python -m src.server --stdio    # STDIO mode
python -m src.server --manifest # Print manifest
```

### Use as a library

```python
from src.server import MCPFileManagerServer
import json

server = MCPFileManagerServer()

# Write a file
server.handle_tool_call("write_file", {"path": "/tmp/test.txt", "content": "Hello!"})

# Read it back
result = json.loads(server.handle_tool_call("read_file", {"path": "/tmp/test.txt"}))
print(result["content"])  # "Hello!"

# Search for files
result = server.handle_tool_call("search_files", {"path": ".", "pattern": "*.py", "target": "files"})

# Search inside files (grep)
result = server.handle_tool_call("search_files", {"path": ".", "pattern": "TODO", "target": "content"})

# Get file hash
result = server.handle_tool_call("file_hash", {"path": "/tmp/test.txt", "algorithm": "sha256"})

# Directory tree
result = server.handle_tool_call("directory_tree", {"path": ".", "max_depth": 3})
```

## MCP Tool Reference

| Tool | Description | Required Params |
|------|-------------|-----------------|
| `read_file` | Read file content | `path` |
| `read_file_lines` | Read specific lines | `path` |
| `write_file` | Write file (creates dirs) | `path`, `content` |
| `append_file` | Append to file | `path`, `content` |
| `delete_file` | Delete file or dir | `path` |
| `copy_file` | Copy file or dir | `src`, `dst` |
| `move_file` | Move/rename | `src`, `dst` |
| `list_directory` | List dir contents | — |
| `search_files` | Find by name or grep | `pattern` |
| `file_info` | File metadata | `path` |
| `file_hash` | File hash (md5/sha256) | `path` |
| `directory_tree` | Directory tree | — |

## Tests

```bash
python -m pytest tests/ -v  # 36 tests, all passing
```

## License

MIT

## Author

aaameobius-crypto — [github.com/aaameobius-crypto](https://github.com/aaameobius-crypto)

Freelance portfolio: [https://ameobius-space.github.io/kwork-portfolio/](https://ameobius-space.github.io/kwork-portfolio/)