Managed Notifications Search MCP Server

托管通知搜索MCP服务器

MCP（模型上下文协议）服务器，使AI代理能够搜索 OpenShift服务通知日志使用ChromaDB和 句子转换。

概述

此服务器通过OpenShift服务提供语义搜索功能 通知JSON文件，允许AI代理基于 关于问题描述。该系统使用向量嵌入来实现语义 匹配，而不仅仅是关键字搜索。

特性

• 语义搜索：使用以下命令根据问题描述查找通知

向量相似性

• 元数据丰富结果包括文件夹类别（hcp、osd、rosa、，

等）、严重性级别和完整通知数据

• 高效的容器部署：多阶段Docker构建，优化

分层包埋再生

• 数据库统计：深入了解可用的通知和类别

安装

先决条件

• Python 3.13+
• uv（Python包管理器）
• Git及其子模块
• Podman或Docker（用于容器化部署）

地方发展

1. 克隆并设置存储库：

   git clone 
   cd managed-notifications-mcp
   git submodule update --init --recursive

1. 安装依赖项：

   uv sync

1. 构建嵌入数据库：

   uv run build-embeddings

1. 运行MCP服务器：

   uv run serve

容器部署

1. 构建容器：

   podman build -t managed-notifications-search .

1. 运行容器：

   podman run -p 8000:8000 managed-notifications-search

MCP客户端配置

要从MCP客户端连接到服务器，请使用提供的配置文件：

文件： mcp-config.json

{
  "mcpServers": {
    "service-logs": {
      "type": "http",
      "url": "http://localhost:8000/mcp",
      "auth": {}
    }
  }
}

此配置使MCP客户端（如Claude Desktop）能够连接到 在localhost端口8000上运行服务器。

用法

服务器提供两个主要的MCP工具：

search_service_logs

搜索与问题陈述匹配的通知。

参数：

• problem_statement （必填）：要搜索的问题的描述
• max_results （可选，默认值：5）：返回的最大结果数

例子：

# Search for pod scheduling issues
results = search_service_logs(
    problem_statement="pods stuck in pending state unable to schedule",
    max_results=3
)

关于变量插值的重要说明： 许多服务通知包含可变占位符，如 ${TIME}, ${REASON}, ${POD}, ${NAMESPACE} 需要用实际值替换。 使用此工具时：

1. 检查 variables 领域 在每个结果中查看哪些变量需要插值
2. 向用户询问具体值 在呈现通知时为每个变量
3. 帮助插值变量 在发送给客户之前，将通知文本

常见变量包括：

• ${TIME}：问题发生的时间戳
• ${REASON}：失败的具体原因
• ${POD}：受影响吊舱的名称
• ${NAMESPACE}：Kubernetes命名空间
• ${CLUSTER_ID}：群集标识符
• ${NUM_OF_WORKERS}：工作节点数

get_database_stats

获取通知数据库的统计信息。

退货：

• 通知总数
• 可用文件夹类别
• 严重程度
• 服务名称
• 数据库路径

建筑

组件

1. 嵌入脚本 (scripts/build_embeddings.py):

- 处理托管通知子模块中的所有JSON文件 - 从通知字段中提取可搜索文本 - 使用句子变换器创建向量嵌入 - 将嵌入内容与元数据一起存储在ChromaDB中

1. MCP服务器 (main.py):

- 基于FastMCP的服务器，配备搜索工具 - 启动时加载预构建的ChromaDB数据库 - 提供语义搜索和数据库统计信息

1. 容器配置:

- 将嵌入创建与运行时分离的多阶段构建 - 优化分层以最大限度地减少重建 - 非root用户安全

数据流

1. 构建阶段：JSON文件� 文本提取� 矢量嵌入�

ChromaDB

1. 运行时阶段：问题陈述� 查询嵌入� 相似性搜索

� 格式化结果

通知类别

系统按文件夹结构组织通知：

• hcp：托管控制平面通知
• 屏幕显示：OpenShift专用通知
• 罗莎：AWS通知上的Red Hat OpenShift服务
• 簇：常规集群通知
• ocm：OpenShift群集管理器通知

发展

项目结构

├── main.py                    # MCP server implementation
├── scripts/
│   └── build_embeddings.py   # Embedding creation script
├── managed-notifications/     # Git submodule with notification JSONs
├── Containerfile             # Multi-stage container build
├── .containerignore          # Container build exclusions
└── pyproject.toml            # Python dependencies

嵌入模型

该系统使用 all-MiniLM-L6-v2 默认情况下为句子转换器模型。 您可以通过设置 EMBEDDING_MODEL 环境变量 嵌入脚本。

数据库结构

每个通知都存储在以下位置：

• 文件：连接的可搜索文本（摘要、描述、标签等）
• 元数据：文件路径、文件夹类别、严重性、服务名称、变量

列表，完整JSON

• 嵌入：384维向量（用于默认模型）
• 变量：提取变量占位符（例如。，

["TIME", "REASON", "POD"])用于插值

贡献

1. 确保管理通知子模块是最新的
2. 在通知更改后运行嵌入脚本
3. 测试本地和容器化部署
4. 验证搜索结果的准确性和相关性