# MCP Local File Reader

A Model Context Protocol (MCP) server that provides comprehensive file system operations with support for multiple document formats. Works with Claude Desktop and other MCP-compatible AI tools.

## Features

- 📁 **File System Operations**: List directories, read files, get file metadata
- 🔍 **Search Capabilities**: Grep-like content search and file name pattern matching
- 📄 **Multi-Format Support**:
  - PDF text extraction
  - Excel (.xlsx, .xls) with sheet listing and per-sheet reading
  - Word documents (.docx)
  - PowerPoint presentations (.pptx)
  - CSV files
  - Text files with automatic encoding detection (Shift-JIS/UTF-8)
- 🌐 **Character Encoding**: Automatic detection and conversion of Shift-JIS and UTF-8
- 🔒 **Security**: Path validation to prevent access outside designated root directory

## Installation

### Using npx (Recommended)

No installation needed! Just configure Claude Desktop to use npx:

```json
{
  "mcpServers": {
    "localfile-reader": {
      "command": "npx",
      "args": [
        "-y",
        "github:yryuu/mcp-localfile-all-read"
      ],
      "env": {
        "MCP_ROOT_PATH": "/path/to/your/directory"
      }
    }
  }
}
```

### Local Installation

```bash
npx github:yryuu/mcp-localfile-all-read
```

## Configuration

### Claude Desktop

Edit your Claude Desktop configuration file:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`

**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

Add the server configuration:

```json
{
  "mcpServers": {
    "localfile-reader": {
      "command": "npx",
      "args": ["-y", "github:yryuu/mcp-localfile-all-read"],
      "env": {
        "MCP_ROOT_PATH": "/Users/yourname/Documents"
      }
    }
  }
}
```

Or if installed globally:

```json
{
  "mcpServers": {
    "localfile-reader": {
      "command": "mcp-localfile-reader",
      "env": {
        "MCP_ROOT_PATH": "/Users/yourname/Documents"
      }
    }
  }
}
```

### Environment Variables

- `MCP_ROOT_PATH`: Root directory for file access (defaults to current working directory)

**Windows Example:**
```json
{
  "env": {
    "MCP_ROOT_PATH": "C:\\Users\\YourName\\Documents"
  }
}
```

**macOS/Linux Example:**
```json
{
  "env": {
    "MCP_ROOT_PATH": "/Users/yourname/Documents"
  }
}
```

> **Note**: On Windows, use double backslashes (`\\`) or forward slashes (`/`) in paths. See [WINDOWS.md](WINDOWS.md) for detailed Windows compatibility information.

## Available Tools

### `list_directory`

List contents of a directory.

**Parameters:**
- `path` (string): Relative path from root directory. Use "." for root.

**Example:**
```
List the contents of the current directory
```

### `read_file`

Read file content with automatic format detection.

**Parameters:**
- `path` (string): Relative path to the file.

**Supported formats:**
- Text files (.txt, .md, .json, .xml, etc.)
- PDF (.pdf)
- Excel (.xlsx, .xls)
- Word (.docx)
- PowerPoint (.pptx)
- CSV (.csv)

**Example:**
```
Read the contents of report.pdf
```

### `get_file_info`

Get metadata about a file or directory.

**Parameters:**
- `path` (string): Relative path to the file or directory.

**Example:**
```
Get information about data.xlsx
```

### `search_content`

Search for text patterns in files. Returns a list of file paths that contain the pattern.

**Parameters:**
- `path` (string): Relative path to search in.
- `pattern` (string): Text pattern or regex to search for.
- `max_results` (number): Optional. Maximum number of files to return (default: 1000).
- `file_pattern` (string, optional): Filter files by name pattern.
- `case_sensitive` (boolean, optional): Case sensitive search. Default: false.

**Example:**
```
Search for "TODO" in all JavaScript files
```

### `find_files`

Find files by name pattern.

**Parameters:**
- `path` (string): Relative path to search in.
- `name_pattern` (string): File name pattern or regex.
- `case_sensitive` (boolean, optional): Case sensitive search. Default: false.

**Example:**
```
Find all PDF files in the current directory
```

### `list_excel_sheets`

List all sheet names in an Excel file.

**Parameters:**
- `path` (string): Relative path to the Excel file.

**Example:**
```
List all sheets in budget.xlsx
```

### `read_excel_sheet`

Read a specific sheet from an Excel file.

**Parameters:**
- `path` (string): Relative path to the Excel file.
- `sheet_name` (string): Name of the sheet to read.

**Example:**
```
Read the "Sales" sheet from budget.xlsx
```

## Development

### Setup

```bash
git clone https://github.com/yryuu/mcp-localfile-all-read.git
cd mcp-localfile-all-read
npm install
```

### Build

```bash
npm run build
```

### Testing Locally

Use the MCP Inspector to test the server:

```bash
npx @modelcontextprotocol/inspector node dist/index.js
```

Or set the root path:

```bash
MCP_ROOT_PATH=/path/to/test/directory npx @modelcontextprotocol/inspector node dist/index.js
```

## Usage Examples

### With Claude Desktop

After configuration, you can ask Claude:

- "List all files in the current directory"
- "Read the contents of report.pdf"
- "Search for 'error' in all log files"
- "Find all Excel files"
- "List the sheets in budget.xlsx and read the Sales sheet"
- "Read the Word document proposal.docx"

### Programmatic Usage

```typescript
import { Server } from '@modelcontextprotocol/sdk/server/index.js';

// The server runs on stdio transport
// See src/index.ts for implementation details
```

## File Format Support Details

### PDF
- Extracts all text content from PDF files
- Handles multi-page documents
- Uses `pdf-parse` library

### Excel
- Supports .xlsx and .xls formats
- List all sheet names
- Read specific sheets or all sheets
- Returns data as JSON arrays

### Word
- Supports .docx format
- Extracts plain text content
- Uses `mammoth` library

### PowerPoint
- Supports .pptx format
- Extracts text from all slides
- Returns slide-by-slide content

### CSV
- Automatic delimiter detection
- Character encoding detection (Shift-JIS/UTF-8)
- Returns structured JSON data

### Text Files
- Automatic character encoding detection
- Supports Shift-JIS and UTF-8
- Handles various text-based formats

## Security

- Path validation prevents access outside the configured root directory
- All paths are resolved and validated before file operations
- Error handling for permission issues and invalid paths

## License

MIT

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## Author

yryuu

## Repository

https://github.com/yryuu/mcp-localfile-all-read