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:

git clone <your-repo-url>
cd ressl-mcp-server

2. Install dependencies:

npm install

3. Build the project:

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

{
  "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:

{
  "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:

{
  "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:

{
  "filePath": "./src/index.ts"
}

Usage Examples

Example 1: Search within a single file

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

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

Example 2: Search across project files

Find all TypeScript files containing "async":

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

Example 3: Get file statistics

Retrieve information about a specific file:

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

Development

# 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:

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