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

Usage

Start the server:

Server runs at http://127.0.0.1:8000

Test the server (in another terminal):

API Endpoints

POST /search

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

Request Body:

Response:

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:

GET /

Root endpoint with server information.

Examples

Using curl:

Using Python:

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