MCP Search Server MCP Server

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"],