managed-notifications-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Essential Commands

Development:

# 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/ git submodule
• 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