AI导哈

通知日志语义搜索服务

一个基于MCP协议的服务器，提供对OpenShift服务通知日志的语义搜索功能，利用ChromaDB和句子转换器实现。

  • by geowa4
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 geowa4/managed-notifications-mcp

使用说明

托管通知搜索MCP服务器

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

概述

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

特性

  • 语义搜索：使用以下命令根据问题描述查找通知 向量相似性
  • 元数据丰富结果包括文件夹类别（hcp、osd、rosa、， 等）、严重性级别和完整通知数据
  • 高效的容器部署：多阶段Docker构建，优化 分层包埋再生
  • 数据库统计：深入了解可用的通知和类别

安装

先决条件

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

地方发展

  1. 克隆并设置存储库：

    git clone <repository-url>
cd managed-notifications-mcp
git submodule update --init --recursive

  2. 安装依赖项：

    uv sync

  3. 构建嵌入数据库：

    uv run build-embeddings

  4. 运行MCP服务器：

    uv run serve

容器部署

  1. 构建容器：

    podman build -t managed-notifications-search .

  2. 运行容器：

    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中

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

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

  3. 容器配置:

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

数据流

  1. 构建阶段：JSON文件� 文本提取� 矢量嵌入� ChromaDB
  2. 运行时阶段：问题陈述� 查询嵌入� 相似性搜索 � 格式化结果

通知类别

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

  • 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. 验证搜索结果的准确性和相关性

相关 MCP