MCP Search Server

A Model Context Protocol (MCP) server built with FastMCP that provides semantic search capabilities by integrating with an OpenSearch-based search service. This server uses Server-Sent Events (SSE) transport and includes comprehensive validation, error handling, and Docker support.

Features

• ✅ FastMCP Integration: Built on FastMCP framework with SSE transport

• ✅ Pydantic Validation: Comprehensive input/output validation

• ✅ Docker Support: Multi-stage Dockerfile and docker-compose configuration

• ✅ Retry Logic: Automatic retry with exponential backoff

• ✅ Structured Logging: JSON and console logging support

• ✅ Health Checks: Built-in health monitoring

• ✅ Type Safety: Full type hints throughout the codebase

• ✅ Security: Non-root user in Docker container

• ✅ Configurable: Environment-based configuration

Architecture

┌─────────────────┐          ┌──────────────────┐          ┌─────────────────┐
│   MCP Client    │   SSE    │  MCP Search      │   HTTP   │ Search Service  │
│  (Claude/App)   │ ────────►│     Server       │ ────────►│  (OpenSearch)   │
└─────────────────┘          └──────────────────┘          └─────────────────┘
                                      │
                                      │
                                      ▼
                              ┌──────────────┐
                              │  Docker      │
                              │  Network     │
                              │ test_network │
                              └──────────────┘

Prerequisites

• Python 3.11+

• Docker and Docker Compose (for containerized deployment)

• Search service running on search_service:8008 (or configured URL)

Quick Start

Local Development

1. Clone the repository

   cd d:\projects\DeepResearch\MCPSearch

2. Install dependencies

   pip install -r requirements.txt

3. Configure environment

   cp mcp/.env.example mcp/.env
   # Edit mcp/.env with your configuration

4. Run the server

   cd mcp
   python server.py

The server will start on http://0.0.0.0:8080

Docker Deployment

1. Build and run with Docker Compose

   docker-compose up -d --build

2. Check logs

   docker logs -f mcp_search_server

3. Check health

   curl http://localhost:8080/health

Configuration

All configuration is managed through environment variables. Edit mcp/.env or set environment variables directly.

Environment Variables

Example .env File

# Search Service Configuration
SEARCH_SERVICE_URL=http://search_service:8008
SEARCH_TIMEOUT=30

# MCP Server Configuration
MCP_SERVER_HOST=0.0.0.0
MCP_SERVER_PORT=8080

# Default Values
DEFAULT_USER_ID=system

# Logging Configuration
LOG_LEVEL=INFO
LOG_FORMAT=json

# Request Configuration
MAX_RETRIES=3
RETRY_DELAY=1.0

Usage

Available Tools

search_documents

Search for documents in OpenSearch indices using the integrated search service.

Parameters:

• query (string, required): Search query text (minimum 1 character)

• user_id (string, required): User identifier for tracking

• indices (array of strings, required): OpenSearch indices to search

• filters (object, optional): Search filters

  • categories (array of strings): Filter by categories

  • date_from (string): Start date (ISO format)

  • date_to (string): End date (ISO format)

  • tags (array of strings): Filter by tags

  • metadata (object): Additional metadata filters

Returns:

{
  "results": [
    {
      "id": "doc_123",
      "score": 0.95,
      "index": "documents",
      "source": {
        "title": "Document Title",
        "content": "Document content..."
      },
      "highlights": {
        "content": ["...highlighted <em>text</em>..."]
      }
    }
  ],
  "query_expanded": "query with synonyms",
  "processing_time_ms": 45.2,
  "request_id": "req_abc123"
}

Example Usage

Basic Search:

{
  "query": "machine learning",
  "user_id": "user123",
  "indices": ["documents"]
}

Advanced Search with Filters:

{
  "query": "deep learning",
  "user_id": "researcher_001",
  "indices": ["research_papers", "articles"],
  "filters": {
    "categories": ["AI", "Machine Learning"],
    "tags": ["neural-networks", "computer-vision"],
    "date_from": "2023-01-01",
    "date_to": "2024-12-31",
    "metadata": {
      "language": "en",
      "difficulty": "advanced"
    }
  }
}

API Documentation

Search Service Integration

The MCP server communicates with a search service at http://search_service:8008/search (configurable).

Expected Search Service API:

• Endpoint: POST /search

• Content-Type: application/json

Request Body:

{
  "query": "search text",
  "user_id": "user_identifier",
  "indices": ["index1", "index2"],
  "filters": {
    "categories": ["category1"],
    "date_from": "2023-01-01",
    "date_to": "2024-12-31",
    "tags": ["tag1", "tag2"],
    "metadata": {}
  }
}

Response Body:

{
  "results": [...],
  "query_expanded": "expanded query",
  "processing_time_ms": 45.2,
  "request_id": "unique_id"
}

Docker

Building the Image

docker build -t mcp-search-server .

Running the Container

docker run -d \
  --name mcp_search_server \
  --network test_network \
  -p 8080:8080 \
  -e SEARCH_SERVICE_URL=http://search_service:8008 \
  mcp-search-server

Docker Compose

The provided docker-compose.yml sets up:

• MCP Search Server on port 8080

• Connected to test_network

• Health checks enabled

• Automatic restart policy

• Logging configuration

Start services:

docker-compose up -d

Stop services:

docker-compose down

View logs:

docker-compose logs -f mcp_search_server

Development

Project Structure

MCPSearch/
├── mcp/
│   ├── __init__.py
│   ├── server.py           # Main MCP server implementation
│   ├── config.py           # Configuration management
│   ├── .env                # Environment variables
│   ├── prompts/
│   │   └── search_prompts.md  # Usage examples and documentation
│   └── tools/              # (Reserved for additional tools)
├── requirements.txt        # Python dependencies
├── Dockerfile             # Multi-stage Docker build
├── docker-compose.yml     # Docker orchestration
└── README.md             # This file

Running Tests

# Install dev dependencies
pip install pytest pytest-asyncio httpx

# Run tests (if implemented)
pytest tests/

Code Quality

The codebase follows:

• PEP 8 style guidelines

• Type hints throughout

• Docstrings for all public functions

• Pydantic for data validation

• Structured logging with context

Adding New Tools

To add new MCP tools:

1. Define the tool function in server.py or create a new module in mcp/tools/

2. Decorate with @mcp.tool()

3. Add proper type hints and docstrings

4. Update documentation in prompts/ directory

Example:

@mcp.tool()
async def new_tool(param: str) -> Dict[str, Any]:
    """Tool description.
    
    Args:
        param: Parameter description
        
    Returns:
        Result description
    """
    # Implementation
    return {"result": "data"}

Logging

The server uses structured logging with configurable output format.

JSON Format (default for production):

{
  "timestamp": "2024-01-15T10:30:45.123Z",
  "level": "info",
  "event": "search_request_successful",
  "request_id": "req_123",
  "results_count": 5,
  "processing_time_ms": 45.2
}

Console Format (for development):

2024-01-15 10:30:45 [info] search_request_successful request_id=req_123 results_count=5

Configure via LOG_FORMAT environment variable.

Error Handling

The server implements comprehensive error handling:

Validation Errors

{
  "error": "Validation failed: query must be at least 1 character"
}

HTTP Errors

{
  "error": "Search service returned error 500: Internal Server Error"
}

Connection Errors

{
  "error": "Failed to connect to search service: Connection refused"
}

Retry Logic

• Automatic retry for 5xx errors and connection failures

• Exponential backoff: 1s, 2s, 3s

• Maximum 3 retry attempts (configurable)

Troubleshooting

Server Won't Start

1. Check if port 8080 is available:

   netstat -ano | findstr :8080  # Windows
   lsof -i :8080                 # Linux/Mac

2. Verify Python version:

   python --version  # Should be 3.11+

3. Check configuration:

   cat mcp/.env

Can't Connect to Search Service

1. Verify search service is running:

   docker ps | grep search_service

2. Check network connectivity:

   docker network inspect test_network

3. Test search service directly:

   curl -X POST http://search_service:8008/search \
     -H "Content-Type: application/json" \
     -d '{"query":"test","user_id":"test","indices":["test"]}'

Container Issues

1. Check container logs:

   docker logs mcp_search_server

2. Inspect container:

   docker inspect mcp_search_server

3. Rebuild image:

   docker-compose down
   docker-compose build --no-cache
   docker-compose up -d

Performance

Optimization Tips

1. Connection Pooling: HTTP client uses connection pooling (max 20 connections)

2. Timeout Configuration: Adjust SEARCH_TIMEOUT based on search complexity

3. Retry Strategy: Configure MAX_RETRIES and RETRY_DELAY for your needs

4. Index Selection: Only search necessary indices to improve performance

5. Filter Usage: Use filters instead of including criteria in query text

Monitoring

Key metrics to monitor:

• processing_time_ms in search responses

• HTTP request/response times

• Error rates and retry attempts

• Container resource usage

Security

Best Practices Implemented

• ✅ Non-root user in Docker container (UID 1000)

• ✅ No sensitive data in logs

• ✅ Input validation with Pydantic

• ✅ Timeout protection against slow requests

• ✅ Health check endpoints

• ✅ Minimal container image (python:3.11-slim)

Recommendations

1. Use HTTPS in production

2. Implement authentication/authorization

3. Set up rate limiting

4. Use secrets management for sensitive config

5. Regular security updates for dependencies

Contributing

Contributions are welcome! Please follow these guidelines:

1. Fork the repository

2. Create a feature branch

3. Make your changes with tests

4. Update documentation

5. Submit a pull request

License

[Specify your license here]

Support

For issues and questions:

1. Check the Troubleshooting section

2. Review logs: docker logs mcp_search_server

3. Check search service logs

4. Open an issue on GitHub

Resources

• FastMCP Documentation

• Model Context Protocol

• Pydantic Documentation

• OpenSearch Documentation

• Docker Documentation

Changelog

Version 1.0.0 (2024-01-15)

• Initial release

• FastMCP integration with SSE transport

• Search documents tool

• Pydantic validation

• Docker support

• Comprehensive documentation

Built with ❤️ using FastMCP and Python