# Ressl MCP Server - Advanced File Search

A sophisticated Model Context Protocol (MCP) server providing powerful file search capabilities for Claude Desktop and other MCP-compatible clients.

## Features

- **Single File Search**: Search for keywords within a single file with line numbers
- **Directory Search**: Recursively search across entire directories with extension filtering
- **File Information**: Get detailed metadata about files (size, line count, modification date)
- **Advanced Options**: Case-sensitive search, custom result limits, configurable formatting
- **Error Handling**: Comprehensive error handling with clear messages
- **Performance**: Efficient regex-based search with result limiting

## Installation

1. Clone this repository:
```bash
git clone <your-repo-url>
cd ressl-mcp-server
```

2. Install dependencies:
```bash
npm install
```

3. Build the project:
```bash
npm run build
```

## Configuration for Claude Desktop

Add the following to your Claude Desktop configuration file:

**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "fileSearch": {
      "command": "node",
      "args": [
        "C:\\path\\to\\ressl-mcp-server\\dist\\index.js"
      ]
    }
  }
}
```

Make sure to replace the path with your actual project path.

## Available Tools

### 1. search_in_file

Search for a keyword within a single file.

**Parameters:**
- `filePath` (required): Path to the file to search
- `keyword` (required): The keyword or pattern to search for
- `caseSensitive` (optional): Case-sensitive search (default: false)
- `includeLineNumbers` (optional): Include line numbers (default: true)
- `maxResults` (optional): Maximum results to return (default: 100)

**Example:**
```json
{
  "filePath": "./src/index.ts",
  "keyword": "function",
  "caseSensitive": false,
  "maxResults": 50
}
```

### 2. search_in_directory

Search for a keyword across all files in a directory recursively.

**Parameters:**
- `directoryPath` (required): Path to the directory
- `keyword` (required): The keyword or pattern to search for
- `fileExtensions` (optional): Array of extensions to filter by, e.g., ["ts", "js"]
- `caseSensitive` (optional): Case-sensitive search (default: false)
- `includeLineNumbers` (optional): Include line numbers (default: true)
- `maxResults` (optional): Maximum results to return (default: 500)

**Example:**
```json
{
  "directoryPath": "./src",
  "keyword": "class",
  "fileExtensions": ["ts", "js"],
  "maxResults": 100
}
```

### 3. get_file_info

Get detailed information about a file.

**Parameters:**
- `filePath` (required): Path to the file

**Example:**
```json
{
  "filePath": "./src/index.ts"
}
```

## Usage Examples

### Example 1: Search within a single file

Search for all occurrences of "search" in the main server file:

```json
{
  "filePath": "./src/index.ts",
  "keyword": "search",
  "includeLineNumbers": true
}
```

### Example 2: Search across project files

Find all TypeScript files containing "async":

```json
{
  "directoryPath": "./src",
  "keyword": "async",
  "fileExtensions": ["ts"],
  "maxResults": 200
}
```

### Example 3: Get file statistics

Retrieve information about a specific file:

```json
{
  "filePath": "./README.md"
}
```

## Development

```bash
# Development mode with watch
npm run dev

# Build for production
npm run build

# Start the server
npm start
```

## Testing with MCP Inspector

You can test the server using the MCP Inspector:

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

## Project Structure

```
ressl-mcp-server/
├── src/
│   └── index.ts          # Main server implementation
├── dist/                 # Compiled JavaScript (generated)
├── examples/             # Example files for testing
├── package.json
├── tsconfig.json
└── README.md
```

## Technical Details

- **Language**: TypeScript
- **Runtime**: Node.js 18+
- **Framework**: MCP SDK v0.5.0
- **Pattern Matching**: Regex-based with special character escaping
- **File Handling**: UTF-8 encoding with error recovery
- **Performance**: Efficient streaming for large files

## Error Handling

The server provides clear error messages for:
- File not found
- Invalid paths
- Permission issues
- Exceeded result limits

## License

MIT

## Author

Shweta Patel