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

Variable	Default	Description
SEARCH_SERVICE_URL	http://search_service:8008	Base URL of the search service
SEARCH_TIMEOUT	30	HTTP request timeout in seconds
MCP_SERVER_HOST	0.0.0.0	Server bind address
MCP_SERVER_PORT	8080	Server port
DEFAULT_USER_ID	system	Default user ID for requests
LOG_LEVEL	INFO	Logging level (DEBUG, INFO, WARNING, ERROR)
LOG_FORMAT	json	Log format (json or console)
MAX_RETRIES	3	Maximum retry attempts for failed requests
RETRY_DELAY	1.0	Base delay between retries in seconds

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