# file_reader_mcp

An MCP (Model Context Protocol) server for reading and discovering files from the local filesystem.

## Current capabilities

This project now provides three MCP tools:

- **`list_files`** — Lists files and folders in a given directory
  - Folders are shown with a trailing `/`
  - Results are sorted alphabetically
  - Access is restricted to paths under the allowed workspace

- **`read_file`** — Reads the contents of a text file
  - Returns the full file content as a string
  - Supports files inside the allowed workspace only

- **`search_files`** — Searches for files by keyword within a directory tree
  - Returns matching file paths
  - Helps quickly locate relevant files

### Implementation notes

- The file access layer has been updated to use `pathlib` instead of `os` for a more modern and readable path handling approach.
- Access is still restricted to a safe allowed root for security.

## Requirements

- Python 3.10+
- [uv](https://docs.astral.sh/uv/) (recommended) or pip

## Setup

```bash
uv sync
```

## Running the server

```bash
uv run python src/server.py
```

The server uses stdio transport and is meant to be configured as an MCP server in Cursor or another MCP-compatible client.

## Project structure

```
file_reader_mcp/
├── src/
│   ├── file_access.py  # Pathlib-based file access helpers
│   └── server.py       # MCP server exposing list_files, read_file, and search_files
├── test/
│   └── test_os.py      # Local tests for directory listing
└── pyproject.toml
```