README.md•3.4 kB
# MCP Keyword Search Server
A FastAPI-based MCP (Model Context Protocol) server that provides a keyword search tool for searching within files.
## Features
- **Keyword Search**: Search for keywords in text files with line numbers and occurrence counts
- **Case Sensitivity**: Toggle between case-sensitive and case-insensitive searches
- **RESTful API**: Simple HTTP endpoints for easy integration
- **Error Handling**: Handles missing files, non-text files, and invalid paths
- **Interactive Docs**: Built-in Swagger UI for testing
## Setup
```bash
# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
# Install dependencies
pip install -r requirements.txt
```
## Usage
Start the server:
```bash
python server.py
```
Server runs at `http://127.0.0.1:8000`
Test the server (in another terminal):
```bash
python test_client.py
```
## API Endpoints
### POST `/search`
Search for a keyword in a file and get all matching lines.
**Request Body:**
```json
{
"file_path": "example.txt",
"keyword": "python",
"case_sensitive": false
}
```
**Response:**
```json
{
"file_path": "example.txt",
"keyword": "python",
"total_matches": 5,
"matches": [
{
"line_number": 2,
"content": "Python is a popular programming language.",
"occurrences": 1
}
]
}
```
**Parameters:**
- `file_path` (string, required): Path to the file to search
- `keyword` (string, required): Keyword to search for
- `case_sensitive` (boolean, optional): Enable case-sensitive search (default: false)
**Response Fields:**
- `file_path`: The searched file path
- `keyword`: The keyword that was searched
- `total_matches`: Number of lines containing the keyword
- `matches`: Array of matching lines with line numbers, content, and occurrence count
### GET `/health`
Health check endpoint to verify server status.
**Response:**
```json
{
"status": "healthy"
}
```
### GET `/`
Root endpoint with server information.
## Examples
### Using curl:
```bash
curl -X POST http://127.0.0.1:8000/search \
-H "Content-Type: application/json" \
-d '{"file_path": "example.txt", "keyword": "python", "case_sensitive": false}'
```
### Using Python:
```python
import requests
response = requests.post(
"http://127.0.0.1:8000/search",
json={
"file_path": "example.txt",
"keyword": "python",
"case_sensitive": False
}
)
result = response.json()
print(f"Found {result['total_matches']} matches")
```
## Testing
The `test_client.py` script demonstrates various search scenarios:
- Case-insensitive searches
- Case-sensitive searches
- Different keywords
- Error handling for missing files
Run it while the server is running to see example outputs.
## Error Responses
- **404**: File not found at the specified path
- **400**: Invalid file path or file is not readable as text
- **500**: Internal server error while processing the file
## Documentation
Interactive API documentation is available at:
- Swagger UI: `http://127.0.0.1:8000/docs`
- ReDoc: `http://127.0.0.1:8000/redoc`
## Project Structure
```
mcp-keyword-search/
├── server.py # Main FastAPI server
├── test_client.py # Test script with examples
├── example.txt # Sample file for testing
├── requirements.txt # Python dependencies
└── README.md # This file
```