README.md•5.34 kB
# 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