# 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**
   ```bash
   cd d:\projects\DeepResearch\MCPSearch
   ```

2. **Install dependencies**
   ```bash
   pip install -r requirements.txt
   ```

3. **Configure environment**
   ```bash
   cp mcp/.env.example mcp/.env
   # Edit mcp/.env with your configuration
   ```

4. **Run the server**
   ```bash
   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**
   ```bash
   docker-compose up -d --build
   ```

2. **Check logs**
   ```bash
   docker logs -f mcp_search_server
   ```

3. **Check health**
   ```bash
   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

```env
# 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:**

```json
{
  "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:**

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

**Advanced Search with Filters:**

```python
{
  "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:**

```json
{
  "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:**

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

## Docker

### Building the Image

```bash
docker build -t mcp-search-server .
```

### Running the Container

```bash
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:**

```bash
docker-compose up -d
```

**Stop services:**

```bash
docker-compose down
```

**View logs:**

```bash
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

```bash
# 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:

```python
@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):

```json
{
  "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

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

### HTTP Errors

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

### Connection Errors

```json
{
  "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:
   ```bash
   netstat -ano | findstr :8080  # Windows
   lsof -i :8080                 # Linux/Mac
   ```

2. Verify Python version:
   ```bash
   python --version  # Should be 3.11+
   ```

3. Check configuration:
   ```bash
   cat mcp/.env
   ```

### Can't Connect to Search Service

1. Verify search service is running:
   ```bash
   docker ps | grep search_service
   ```

2. Check network connectivity:
   ```bash
   docker network inspect test_network
   ```

3. Test search service directly:
   ```bash
   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:
   ```bash
   docker logs mcp_search_server
   ```

2. Inspect container:
   ```bash
   docker inspect mcp_search_server
   ```

3. Rebuild image:
   ```bash
   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](#troubleshooting) section
2. Review logs: `docker logs mcp_search_server`
3. Check search service logs
4. Open an issue on GitHub

## Resources

- [FastMCP Documentation](https://github.com/jlowin/fastmcp)
- [Model Context Protocol](https://modelcontextprotocol.io)
- [Pydantic Documentation](https://docs.pydantic.dev/)
- [OpenSearch Documentation](https://opensearch.org/docs/)
- [Docker Documentation](https://docs.docker.com/)

## 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**