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

npm install
npm run build

Quick Start

Option 1: Test with MCP Inspector (Recommended)

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

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

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

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

Test Case Examples

Test 1: Basic Search (Case-Insensitive)

Input:

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

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

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

Test 3: No Matches

Input:

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

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

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

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

How It Works

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

Troubleshooting

Inspector won't start

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

npm run build

Development

# 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

MCP Keyword Search Server