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 searchkeyword(string, required): The keyword to search forcaseSensitive(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:6277in 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