# MCP Keyword Search Server

An MCP (Model Context Protocol) server that searches for keywords in files and returns matching lines with line numbers and match counts.

## Features

- **search_keyword** tool that finds all occurrences of a keyword in a file
- Returns line numbers, full line content, and match counts
- Supports case-sensitive and case-insensitive search
- Counts multiple matches per line
- Clear error handling for missing files or invalid inputs

## Installation

```bash
npm install
npm run build
```

## Quick Start

### Option 1: Test with MCP Inspector (Recommended)

```bash
npx @modelcontextprotocol/inspector node /path/to/mcp-ressl/build/index.js
```

This opens a web UI at `http://localhost:6277` where you can test the tool interactively.

### Option 2: Use with Claude Desktop

Add to your Claude Desktop config file:

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

```json
{
  "mcpServers": {
    "keyword-search": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-ressl/build/index.js"]
    }
  }
}
```

Restart Claude Desktop and the tool will be available.

## Tool: search_keyword

**Parameters:**
- `filePath` (string, required): Absolute path to the file to search
- `keyword` (string, required): The keyword to search for
- `caseSensitive` (boolean, optional): Whether search is case-sensitive (default: false)

**Example Input:**
```json
{
  "filePath": "/absolute/path/to/mcp-ressl/test-file.txt",
  "keyword": "TODO",
  "caseSensitive": false
}
```

**Example Output:**
```
Search Results for "TODO" in /absolute/path/to/mcp-ressl/test-file.txt
Total matches: 3
Lines with matches: 3

Line 4 (1 match):
  TODO: Add more test cases

Line 5 (1 match):
  TODO: Implement additional features

Line 7 (1 match):
  But this line has TODO again!
```

## Testing

### Using MCP Inspector UI

1. Start the inspector: `npx @modelcontextprotocol/inspector node build/index.js`
2. Open `http://localhost:6277` in your browser
3. Navigate to the "Tools" tab
4. Select `search_keyword`
5. Fill in the parameters and click "Run Tool"

### Test Case Examples

#### Test 1: Basic Search (Case-Insensitive)

**Input:**
```json
{
  "filePath": "/absolute/path/to/test-file.txt",
  "keyword": "keyword",
  "caseSensitive": false
}
```

**Expected Output:**
```
Search Results for "keyword" in /absolute/path/to/test-file.txt
Total matches: 6
Lines with matches: 4

Line 1 (1 match):
  This is a test file for keyword search.

Line 2 (1 match):
  The keyword appears here multiple times.

Line 3 (2 matches):
  We can search for any keyword in this file.

Line 9 (3 matches):
  KEYWORD, keyword, KeYwOrD should all match.
```

#### Test 2: Case-Sensitive Search

**Input:**
```json
{
  "filePath": "/absolute/path/to/test-file.txt",
  "keyword": "KEYWORD",
  "caseSensitive": true
}
```

**Expected:** Only finds "KEYWORD" (not "keyword" or "KeYwOrD")

#### Test 3: No Matches

**Input:**
```json
{
  "filePath": "/absolute/path/to/test-file.txt",
  "keyword": "nonexistent",
  "caseSensitive": false
}
```

**Expected Output:**
```
Search Results for "nonexistent" in /absolute/path/to/test-file.txt
Total matches: 0
Lines with matches: 0

No matches found.
```

#### Test 4: Error Handling

**Input:**
```json
{
  "filePath": "/path/to/nonexistent/file.txt",
  "keyword": "test",
  "caseSensitive": false
}
```

**Expected Output:**
```
Error: Failed to search file: ENOENT: no such file or directory, open '/path/to/nonexistent/file.txt'
```

#### Test 5: Search in Code Files

**Input:**
```json
{
  "filePath": "/absolute/path/to/mcp-ressl/src/index.ts",
  "keyword": "const",
  "caseSensitive": true
}
```

**Expected:** Finds all `const` declarations in the TypeScript file

### Quick Command Line Test

```bash
# Test directly with grep to verify results
cat test-file.txt | grep -n "TODO"
```

## How It Works

1. **Input:** You provide a file path and keyword to search
2. **Processing:** The tool reads the file, splits it into lines, and searches each line
3. **Matching:** Counts how many times the keyword appears on each line
4. **Output:** Returns all matching lines with line numbers and counts

## Troubleshooting

### Inspector won't start

```bash
# Try installing globally first
npm install -g @modelcontextprotocol/inspector
mcp-inspector node /path/to/mcp-ressl/build/index.js
```

### Port already in use

The inspector uses port 6277 by default. If it's in use, close other apps or the inspector will use a different port automatically.

### File not found errors

Always use **absolute paths** for the `filePath` parameter. Relative paths may not work correctly.

### Changes not reflecting

After modifying the source code, rebuild:
```bash
npm run build
```

## Development

```bash
# Watch mode for development (auto-rebuild on changes)
npm run dev

# Build for production
npm run build

# Run the server directly
node build/index.js
```

## Project Structure

```
mcp-ressl/
├── src/
│   └── index.ts          # Main server implementation
├── build/                # Compiled JavaScript output
├── test-file.txt        # Sample file for testing
├── TEST-EXAMPLES.json   # Test case examples
├── package.json         # Dependencies and scripts
└── README.md           # This file
```

## License

MIT