AI导哈

Elasticsearch异常分析服务器

一个支持多团队和多环境的Elasticsearch集成服务器，用于异常搜索、模式分析和日志查询。

  • by FynnianB
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 fynnianb/elasticsearch-mcp-server

使用说明

Elasticsearch MCP服务器

用于Elasticsearch集成的模型上下文协议（MCP）服务器，支持多团队和多环境。该服务器允许AI助手以安全和有组织的方式在不同的团队和环境中搜索异常、分析模式和查询日志。

特性

  • 多团队支持：使用自己的Elasticsearch集群配置多个团队
  • 多环境支持：为每个团队的开发、登台和生产环境提供支持
  • 例外搜索：具有过滤和频率排序功能的灵活异常搜索
  • 异常分析：对具体异常进行深入分析，并提出原因和解决方案建议
  • 趋势分析：分析异常模式、频率趋势和服务运行状况
  • 日志搜索：使用各种过滤器搜索应用程序日志
  • 连接测试：测试团队和环境的Elasticsearch连接
  • 灵活的身份验证：支持API密钥和用户名/密码身份验证
  • HTTP和STDIO传输：支持HTTP+SSE和STDIO传输协议

安装

npm install

配置

环境变量

  • LOG_LEVEL：日志记录级别（默认值： info)-由记录仪直接处理
  • HTTP_PATH_PREFIX：HTTP路径前缀（默认值： /)
  • TEAMS_CONFIG_PATH：团队配置文件的路径（可选）
  • PORT：HTTP服务器端口（默认值： 3000)

团队配置

创建一个 teams-config.json 文件基于 teams-config.example.json:

{
  "server": {
    "name": "elasticsearch-mcp",
    "version": "1.0.0"
  },
  "teams": {
    "team-alpha": {
      "teamId": "team-alpha",
      "teamName": "Team Alpha",
      "defaultEnvironment": "production",
      "environments": {
        "staging": {
          "node": "https://alpha-staging-es.company.com",
          "apiKey": "your-api-key"
        },
        "production": {
          "node": "https://alpha-prod-es.company.com",
          "apiKey": "your-api-key"
        }
      },
      "indexPatterns": {
        "exceptions": ["alpha-logs-*", "alpha-exceptions-*"],
        "applications": ["alpha-apm-*", "alpha-metrics-*"],
        "logs": ["alpha-app-logs-*"]
      },
      "maxSearchResults": 50,
      "allowedOperations": ["search_exceptions", "analyze_exception", "analyze_trends", "search_logs", "test_connection"]
    }
  }
}

配置选项

  • teamId：团队的唯一标识符
  • 团队名称：人类可读的团队名称
  • 默认环境：未指定时使用的默认环境
  • 环境：每个环境的Elasticsearch连接配置
    • 节点：Elasticsearch集群URL
    • apiKey：用于身份验证的API密钥（可选）
    • 用户名/密码：基本身份验证（可选）
    • maxRetries：最大重试次数（默认值：3）
    • requestTimeout：请求超时（毫秒）（默认值：30000）
  • 索引模式：不同数据类型的索引模式
    • 例外：异常/错误日志模式
    • 应用：应用程序度量/APM数据的模式
    • 日志：一般应用程序日志的模式
  • 最大搜索结果：要返回的最大结果数（默认值：50）
  • 允许的操作：此团队允许的操作列表（可选）

用法

STDIO模式（适用于MCP客户端）

npm run dev
# or
npm start

HTTP模式（用于web界面）

npm run start-http
# or
npm run dev -- --http

HTTP服务器将在以下位置可用：

  • SSE 端点 ： GET http://localhost:3000/sse
  • 消息端点： POST http://localhost:3000/messages
  • 健康检查： GET http://localhost:3000/health

可用工具

1. search_exceptions 🔍

灵活的异常搜索，具有高级过滤和排序功能。

参数：

  • environment （可选）：搜索环境
  • message （可选）：按异常消息内容筛选
  • query （可选）：异常消息或堆栈跟踪的搜索词
  • service （可选）：按服务名称筛选
  • severity （可选）：按日志严重性级别筛选
  • timeRange （可选）：自定义时间范围
    • start：ISO格式的开始时间
    • end：ISO格式的结束时间
  • timeframe （可选）：预定义的时间范围(1h, 6h, 12h, 24h, 7d)
  • limit （可选）：要返回的结果数（默认值：20，最大值：100）
  • sortByFrequency （可选）：按频率排序（最频繁的优先）

使用案例：

  • “哪些例外适用于此提交/拉请求？”
  • “显示过去 6 小时的所有数据库异常”
  • 查找用户服务中最常见的例外

2. analyze_exception 🔬

对特定异常进行深入分析，并给出原因和解决方案建议。

参数：

  • environment （可选）：要分析的环境
  • exceptionMessage （必填）：要分析的特定异常消息
  • timeframe （可选）：分析的时间范围（默认值： 24h)

使用案例：

  • “分析此异常：‘UserService 中的 NullPointerException’”
  • “连接超时”错误的原因是什么？

3. analyze_trends 📈

分析异常模式、频率趋势和服务健康状况随时间的变化。

参数：

  • environment （可选）：要分析的环境
  • timeRange （可选）：自定义分析时间范围
  • timeframe （可选）：预定义的时间范围（默认值： 24h)
  • analysisType （可选）：分析类型(exceptions, services, both)
  • services （可选）：要分析的具体服务列表

使用案例：

  • “过去24小时发生的例外情况是什么？”
  • “哪些服务最近引起了更多的例外？”
  • “告诉我支付系统的例外趋势”

4. search_logs 📋

使用过滤功能搜索一般应用程序日志。

参数：

  • environment （可选）：搜索环境
  • message （可选）：按日志消息内容筛选
  • service （可选）：按服务名称筛选
  • timeRange （可选）：搜索的时间范围（默认为最后1小时）

使用案例：

  • “显示上一小时用户服务的所有日志”
  • 查找“payment failed”的日志

5. test_connection 🔌

测试团队和环境的Elasticsearch连接。

参数：

  • environment （可选）：测试环境

使用案例：

  • “测试与生产的连接”
  • “Elasticsearch是否可用？”

🚀 常见提示和用例

异常调查

"Welche Exceptions sind in den letzten 24h häufiger aufgetreten?"
→ Uses: analyze_trends with analysisType="exceptions"

"Mir ist diese Exception 'OutOfMemoryError' aufgefallen, finde mehr über sie heraus"
→ Uses: analyze_exception with exceptionMessage="OutOfMemoryError"

"Welche Exceptions passen zu diesem API-Endpoint /users/profile?"
→ Uses: search_exceptions with query="/users/profile"

服务健康监测

"Welche Services werfen in letzter Zeit mehr Exceptions?"
→ Uses: analyze_trends with analysisType="services"

"Zeige mir alle Exceptions vom Payment-Service der letzten 6 Stunden"
→ Uses: search_exceptions with service="payment-service" and timeframe="6h"

调试与故障排除

"Suche nach Database-Connection-Errors der letzten 24h"
→ Uses: search_exceptions with query="database connection" and timeframe="24h"

"Analysiere die häufigsten Exceptions im User-Service"
→ Uses: search_exceptions with service="user-service" and sortByFrequency=true

🛠️ 发展

代码质量

该项目保持高代码质量标准：

# Run all quality checks
npm run check

# Individual checks
npm run typecheck    # TypeScript type checking
npm run lint         # ESLint code analysis
npm run format:check # Prettier formatting check

# Auto-fix issues
npm run lint:fix     # Fix ESLint issues
npm run format       # Format code with Prettier

建筑

# Build the project
npm run build

# Clean build artifacts
npm run clean

脚本概述

  • npm run dev -使用热重新加载启动开发服务器
  • npm run build -为生产而建
  • npm run start -构建并启动生产服务器
  • npm run cli -运行CLI工具
  • npm run check -执行所有质量检查

建筑

服务器采用模块化架构构建：

  • 配置管理器：处理团队配置加载和验证
  • Elasticsearch服务：管理Elasticsearch连接和查询
  • MCP工具：用于不同操作的单个工具（5个优化工具）
  • HTTP服务器：为web界面提供HTTP+SSE传输
  • STDIO传输：为MCP客户端提供STDIO传输

工具设计哲学

这些工具的设计遵循以下原则：

  • 简短而难忘的名字 （11-17个字符）
  • 明确区分关注点 （搜索vs.分析vs.趋势）
  • 灵活的参数 支持各种用例
  • 无功能重复 工具之间

安全考虑

  • 安全地存储敏感凭据（API密钥、密码）
  • 使用环境变量进行敏感配置
  • 考虑Elasticsearch连接的网络安全
  • 为每个团队实施适当的访问控制
  • 使用 allowedOperations 配置以限制团队能力

错误处理

服务器包括全面的错误处理：

  • 启动时的配置验证
  • 重试连接错误处理
  • 对不可用服务的优雅降级
  • 用于故障排除的详细日志记录

许可证

麻省理工学院

贡献

  1. 分叉存储库
  2. 创建要素分支
  3. 进行更改
  4. 如果适用，添加测试
  5. 运行linting和格式化
  6. 提交拉取请求

相关 MCP