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

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

python server.py

Server runs at http://127.0.0.1:8000

Test the server (in another terminal):

python test_client.py

API Endpoints

POST /search

Search for a keyword in a file and get all matching lines.

Request Body:

{
  "file_path": "example.txt",
  "keyword": "python",
  "case_sensitive": false
}

Response:

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

{
  "status": "healthy"
}

GET /

Root endpoint with server information.

Examples

Using curl:

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:

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