Which integrations are available for this server?

Enables semantic search capabilities by integrating with OpenSearch-based search services, allowing for document retrieval across multiple indices with support for advanced filtering by categories, dates, tags, and metadata.

How do I use MCP Search Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@MCP Search Server search for 'machine learning' in the research_papers index" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

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

Clone the repository
cd d:\projects\DeepResearch\MCPSearch
Install dependencies
pip install -r requirements.txt
Configure environment
cp mcp/.env.example mcp/.env # Edit mcp/.env with your configuration
Run the server
cd mcp python server.py

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

Docker Deployment

Build and run with Docker Compose
docker-compose up -d --build
Check logs
docker logs -f mcp_search_server
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:

Define the tool function in server.py or create a new module in mcp/tools/
Decorate with @mcp.tool()
Add proper type hints and docstrings
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

Check if port 8080 is available:
netstat -ano | findstr :8080 # Windows lsof -i :8080 # Linux/Mac
Verify Python version:
python --version # Should be 3.11+
Check configuration:
cat mcp/.env

Can't Connect to Search Service

Verify search service is running:
docker ps | grep search_service
Check network connectivity:
docker network inspect test_network
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

Check container logs:
docker logs mcp_search_server
Inspect container:
docker inspect mcp_search_server
Rebuild image:
docker-compose down docker-compose build --no-cache docker-compose up -d

Performance

Optimization Tips

Connection Pooling: HTTP client uses connection pooling (max 20 connections)
Timeout Configuration: Adjust SEARCH_TIMEOUT based on search complexity
Retry Strategy: Configure MAX_RETRIES and RETRY_DELAY for your needs
Index Selection: Only search necessary indices to improve performance
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

Use HTTPS in production
Implement authentication/authorization
Set up rate limiting
Use secrets management for sensitive config
Regular security updates for dependencies

Contributing

Contributions are welcome! Please follow these guidelines:

Fork the repository
Create a feature branch
Make your changes with tests
Update documentation
Submit a pull request

License

[Specify your license here]

Support

For issues and questions:

Check the Troubleshooting section
Review logs: docker logs mcp_search_server
Check search service logs
Open an issue on GitHub

Resources

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

MCP Search Server

Features

Architecture

Prerequisites

Quick Start

Local Development

Docker Deployment

Configuration

Environment Variables

Example .env File

Usage

Available Tools

search_documents

Example Usage

API Documentation

Search Service Integration

Docker

Building the Image

Running the Container

Docker Compose

Development

Project Structure

Running Tests

Code Quality

Adding New Tools

Logging

Error Handling

Validation Errors

HTTP Errors

Connection Errors

Retry Logic

Troubleshooting

Server Won't Start

Can't Connect to Search Service

Container Issues

Performance

Optimization Tips

Monitoring

Security

Best Practices Implemented

Recommendations

Contributing

License

Support

Resources

Changelog

Version 1.0.0 (2024-01-15)

Resources

New MCP Servers

Latest Blog Posts

MCP directory API

`search_documents`