feat: add MCP server for semantic search of notification templates

Add a complete MCP (Model Context Protocol) server implementation that provides
semantic search capabilities over OpenShift service notification templates using
vector embeddings and ChromaDB.

Key features:
- FastMCP server with HTTP transport for AI agent integration
- Vector similarity search using sentence-transformers
- ChromaDB storage with metadata extraction
- Multi-stage container build with podman support
- Variable placeholder extraction for template interpolation
- Database statistics and search tools

Changes include:
- MCP server implementation (main.py) with search tools
- Embedding generation script for vector database creation
- Container build configuration with multi-stage optimization
- Python project setup with uv package manager
- Documentation and configuration files
- Makefile build-container target for podman integration
- .gitignore to exclude build artifacts
- README update referencing MCP server documentation

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

Author: geowa4

.gitignore

@@ -0,0 +1 @@
+mcp/managed-notifications/

Makefile

@@ -21,6 +21,7 @@ help:
 	@echo ''
 	@echo 'Targets:'
 	@echo ' validate - validates that managed-notification descriptions end with a period.'
+	@echo ' build-container - builds the MCP server container with podman.'
 
 .PHONY: checklinks
 checklinks:
@@ -29,3 +30,12 @@ checklinks:
 .PHONY: checkseverity
 checkseverity:
 	scripts/checkseverity.sh
+
+.PHONY: build-container
+build-container:
+	@echo "Setting up managed-notifications directory for container build..."
+	@rm -rf mcp/managed-notifications
+	@mkdir -p mcp/managed-notifications
+	@cp -r cluster hcp ocm osd rosa scripts mcp/managed-notifications/
+	@echo "Building container with podman..."
+	cd mcp && podman build --no-cache -t managed-notifications-search .

README.md

@@ -35,6 +35,10 @@ Some template files have a `_tag` field for easier searching.
 
 For example, in GitHub, searching `t_network` will show you all the network related template files.
 
+## MCP Search Server
+
+This repository includes an MCP (Model Context Protocol) server that provides semantic search capabilities over the notification templates. See [mcp/README.md](mcp/README.md) for setup and usage instructions.
+
 ## Validating Managed Notifications
 
 Run `make validate` to perform basic validations against the notifications configured in this repo.

mcp/CLAUDE.md

@@ -0,0 +1,73 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Essential Commands
+
+**Development:**
+```bash
+# Install dependencies
+uv sync
+
+# Build embeddings database (required before first run)
+uv run build-embeddings
+
+# Run MCP server locally
+uv run serve
+
+# Lint code
+uv run ruff check
+
+# Type check code
+uv run mypy .
+
+# Build container
+podman build -t managed-notifications-search .
+
+# Run container
+podman run -p 8000:8000 managed-notifications-search
+```
+
+## Architecture Overview
+
+This is an MCP (Model Context Protocol) server that provides semantic search over OpenShift service notification logs using vector embeddings. The system has two main phases:
+
+### Build Phase (Offline)
+- **Input**: JSON notification files from `managed-notifications/` directory
+- **Processing**: `scripts/build_embeddings.py` extracts searchable text, creates embeddings via sentence-transformers, stores in ChromaDB
+- **Output**: Persistent vector database in `chroma_db/` directory
+- **Key Feature**: Extracts variable placeholders (e.g., `${TIME}`, `${POD}`) from notification templates
+
+### Runtime Phase (Online) 
+- **Server**: `main.py` implements FastMCP server with HTTP transport
+- **Search**: Uses same embedding model to vectorize queries, performs similarity search in ChromaDB
+- **Tools**: Exposes `search_service_logs` and `get_database_stats` MCP tools
+
+### Data Flow
+1. Problem statement → Query embedding → Vector similarity search → Ranked results
+2. Results include notification JSON, metadata (folder, severity, variables), and similarity scores
+
+## Critical Implementation Details
+
+**Variable Handling**: Service notifications contain template variables like `${NAMESPACE}`, `${REASON}` that must be interpolated. The system:
+- Extracts variables using regex during embedding creation
+- Stores them as JSON strings in ChromaDB metadata (scalar value requirement)
+- Returns parsed variable lists to guide LLM interpolation workflow
+
+**Container Architecture**: Multi-stage build separates embedding creation (expensive, cached) from runtime (lightweight). Only rebuilds embeddings when notification files or embedding script change.
+
+**Project Scripts**: Uses uv project scripts defined in `pyproject.toml`:
+- `serve = "main:main"` 
+- `build-embeddings = "scripts.build_embeddings:main"`
+
+**MCP Configuration**: `mcp-config.json` provides ready-to-use HTTP transport config for MCP clients connecting to `localhost:8000/mcp`.
+
+## Environment Variables
+
+- `EMBEDDING_MODEL`: Override default sentence transformer model (default: "all-MiniLM-L6-v2")
+- `HOST`: Server bind address (default: "127.0.0.1", container uses "0.0.0.0")
+- `PORT`: Server port (default: "8000")
+
+## Database Dependencies
+
+The MCP server requires the ChromaDB database to exist before startup. Always run `uv run build-embeddings` before `uv run serve` in fresh environments. The embeddings script includes a test search for "missing or insufficient permissions" to validate the database.

mcp/Containerfile

@@ -0,0 +1,64 @@
+# Multi-stage build for Managed Notifications Search MCP Server
+# Stage 1: Build embeddings (only rebuilds when notifications or script changes)
+FROM python:3.13-slim as embeddings-builder
+
+# Install uv
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /usr/local/bin/
+
+# Set working directory
+WORKDIR /app
+
+# Copy all source files
+COPY pyproject.toml ./
+COPY uv.lock ./
+
+# Install dependencies and project
+RUN uv sync --frozen --no-dev
+
+# Pre-download the sentence transformer model
+RUN uv run python -c "from sentence_transformers import SentenceTransformer; SentenceTransformer('all-MiniLM-L6-v2')"
+
+# Build embeddings database
+COPY scripts/ ./scripts/
+COPY managed-notifications/ ./managed-notifications/
+RUN uv run scripts/build_embeddings.py
+
+# Stage 2: Runtime image with MCP server
+FROM python:3.13-slim as runtime
+
+# Install uv
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /usr/local/bin/
+
+# Set working directory
+WORKDIR /app
+
+# Copy all source files
+COPY pyproject.toml ./
+COPY uv.lock ./
+
+# Install dependencies and project
+RUN uv sync --frozen --no-dev
+
+# Pre-download the sentence transformer model
+RUN uv run python -c "from sentence_transformers import SentenceTransformer; SentenceTransformer('all-MiniLM-L6-v2')"
+
+# Copy pre-built embeddings database from builder stage
+COPY --from=embeddings-builder /app/chroma_db/ ./chroma_db/
+
+# Set environment variables for MCP server
+ENV HOST=0.0.0.0
+ENV PORT=8000
+
+# Copy mcp server code
+COPY main.py ./
+
+# Create non-root user for security
+RUN useradd --create-home --shell /bin/bash mcp
+RUN chown -R mcp:mcp /app
+USER mcp
+
+# Expose port for MCP server
+EXPOSE 8000
+
+# Default command
+CMD ["uv", "run", "main.py"]

mcp/README.md

@@ -0,0 +1,221 @@
+# Managed Notifications Search MCP Server
+
+An MCP (Model Context Protocol) server that enables AI agents to search through
+OpenShift service notification logs using semantic search powered by ChromaDB and
+sentence transformers.
+
+## Overview
+
+This server provides semantic search capabilities over OpenShift service
+notification JSON files, allowing AI agents to find relevant notifications based
+on problem descriptions. The system uses vector embeddings to enable semantic
+matching rather than just keyword search.
+
+## Features
+
+- **Semantic Search**: Find notifications based on problem descriptions using
+  vector similarity
+- **Metadata Enrichment**: Results include folder categories (hcp, osd, rosa,
+  etc.), severity levels, and full notification data
+- **Efficient Container Deployment**: Multi-stage Docker build with optimized
+  layering for embedding regeneration
+- **Database Statistics**: Get insights into available notifications and categories
+
+## Installation
+
+### Prerequisites
+
+- Python 3.13+
+- uv (Python package manager)
+- Git
+- Podman or Docker (for containerized deployment)
+
+### Local Development
+
+1. **Clone and setup the repository:**
+
+   ```bash
+   git clone <repository-url>
+   cd managed-notifications
+   ```
+
+2. **Install dependencies:**
+
+   ```bash
+   uv sync
+   ```
+
+3. **Build the embeddings database:**
+
+   ```bash
+   uv run build-embeddings
+   ```
+
+4. **Run the MCP server:**
+
+   ```bash
+   uv run serve
+   ```
+
+### Container Deployment
+
+1. **Build the container:**
+
+   ```bash
+   podman build -t managed-notifications-search .
+   ```
+
+2. **Run the container:**
+
+   ```bash
+   podman run -p 8000:8000 managed-notifications-search
+   ```
+
+### MCP Client Configuration
+
+To connect to the server from an MCP client, use the provided configuration file:
+
+**File: `mcp-config.json`**
+
+```json
+{
+  "mcpServers": {
+    "service-logs": {
+      "type": "http",
+      "url": "http://localhost:8000/mcp",
+      "auth": {}
+    }
+  }
+}
+```
+
+This configuration enables MCP clients (like Claude Desktop) to connect to the
+running server on localhost port 8000.
+
+## Usage
+
+The server provides two main MCP tools:
+
+### `search_service_logs`
+
+Search for notifications matching a problem statement.
+
+**Parameters:**
+
+- `problem_statement` (required): Description of the issue to search for
+- `max_results` (optional, default: 5): Maximum number of results to return
+
+**Example:**
+
+```python
+# Search for pod scheduling issues
+results = search_service_logs(
+    problem_statement="pods stuck in pending state unable to schedule",
+    max_results=3
+)
+```
+
+**Important Note on Variable Interpolation:**
+Many service notifications contain variable placeholders like `${TIME}`,
+`${REASON}`, `${POD}`, `${NAMESPACE}` that need to be replaced with actual values.
+When using this tool:
+
+1. **Check the `variables` field** in each result to see what variables need interpolation
+2. **Ask users for specific values** for each variable when presenting a notification
+3. **Help interpolate variables** into the notification text before sending to customers
+
+Common variables include:
+
+- `${TIME}`: Timestamp when the issue occurred
+- `${REASON}`: Specific reason for the failure  
+- `${POD}`: Name of the affected pod
+- `${NAMESPACE}`: Kubernetes namespace
+- `${CLUSTER_ID}`: Cluster identifier
+- `${NUM_OF_WORKERS}`: Number of worker nodes
+
+### `get_database_stats`
+
+Get statistics about the notification database.
+
+**Returns:**
+
+- Total number of notifications
+- Available folder categories
+- Severity levels
+- Service names
+- Database path
+
+## Architecture
+
+### Components
+
+1. **Embedding Script** (`scripts/build_embeddings.py`):
+   - Processes all JSON files in the managed-notifications directory
+   - Extracts searchable text from notification fields
+   - Creates vector embeddings using sentence-transformers
+   - Stores embeddings in ChromaDB with metadata
+
+2. **MCP Server** (`main.py`):
+   - FastMCP-based server with search tools
+   - Loads pre-built ChromaDB database on startup
+   - Provides semantic search and database statistics
+
+3. **Container Configuration**:
+   - Multi-stage build separating embedding creation from runtime
+   - Optimized layering to minimize rebuilds
+   - Non-root user for security
+
+### Data Flow
+
+1. **Build Phase**: JSON files � Text extraction � Vector embeddings �
+   ChromaDB
+2. **Runtime Phase**: Problem statement � Query embedding � Similarity search
+   � Formatted results
+
+## Notification Categories
+
+The system organizes notifications by folder structure:
+
+- **hcp**: Hosted Control Plane notifications
+- **osd**: OpenShift Dedicated notifications  
+- **rosa**: Red Hat OpenShift Service on AWS notifications
+- **cluster**: General cluster notifications
+- **ocm**: OpenShift Cluster Manager notifications
+
+## Development
+
+### Project Structure
+
+```text
+├── main.py                    # MCP server implementation
+├── scripts/
+│   └── build_embeddings.py   # Embedding creation script
+├── managed-notifications/     # Directory with notification JSONs
+├── Containerfile             # Multi-stage container build
+├── .containerignore          # Container build exclusions
+└── pyproject.toml            # Python dependencies
+```
+
+### Embedding Model
+
+The system uses the `all-MiniLM-L6-v2` sentence transformer model by default.
+You can override this by setting the `EMBEDDING_MODEL` environment variable in
+the embedding script.
+
+### Database Structure
+
+Each notification is stored with:
+
+- **Document**: Concatenated searchable text (summary, description, tags, etc.)
+- **Metadata**: File path, folder category, severity, service name, variables
+  list, full JSON
+- **Embedding**: 384-dimensional vector (for default model)
+- **Variables**: Extracted variable placeholders (e.g.,
+  `["TIME", "REASON", "POD"]`) for interpolation
+
+## Contributing
+
+1. Ensure the managed-notifications directory is up to date
+2. Run the embedding script after notification changes
+3. Test both local and containerized deployments
+4. Validate search results for accuracy and relevance