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.example.json 创建 teams-config.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：团队的唯一标识符
• teamName：便于阅读的团队名称
• defaultEnvironment：未指定环境时使用的默认环境
• environments：各环境的 Elasticsearch 连接配置
  • node：Elasticsearch 集群 URL
  • apiKey：用于身份验证的 API 密钥（可选）
  • username/password：基本身份验证（可选）
  • maxRetries：最大重试次数（默认值：3）
  • requestTimeout：请求超时时间，单位为毫秒（默认值：30000）
• indexPatterns：不同数据类型的索引模式
  • exceptions：异常/错误日志的模式
  • applications：应用指标/APM 数据的模式
  • logs：常规应用日志的模式
• maxSearchResults：返回结果的最大数量（默认值：50）
• allowedOperations：此团队允许执行的操作列表（可选）

使用方法

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 小时内的所有数据库异常”
• “找出 User 服务中最常见的异常”

2. analyze_exception 🔬

深入分析特定异常及其原因，并提供解决方案建议。

参数：

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

使用场景：

• “分析此异常：'UserService 中的 NullPointerException'”
• “'Connection timeout' 错误的原因是什么？”

3. analyze_trends 📈

分析异常模式、频率趋势以及服务随时间变化的运行状况。

参数：

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

使用场景：

• “最近 24h 内哪些异常出现得更频繁？”
• “最近哪些服务抛出的异常更多？”
• “显示 Payment 系统的异常趋势”

4. search_logs 📋

搜索常规应用日志，并支持筛选。

参数：

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

使用场景：

• “显示 User-Service 过去一小时的所有日志”
• “搜索包含 'payment failed' 的日志”

5. test_connection 🔌

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

参数：

• environment（可选）：要测试的环境

使用场景：

• “测试与 Production 的连接”
• “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 - 运行所有质量检查

架构

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

• ConfigManager：处理团队配置的加载和验证
• ElasticsearchService：管理 Elasticsearch 连接和查询
• MCP Tools：用于不同操作的独立工具（5 个经过优化的工具）
• HTTP Server：为 Web 界面提供 HTTP+SSE 传输
• STDIO Transport：为 MCP 客户端提供 STDIO 传输

工具设计理念

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

• 名称简短易记（11-17 个字符）
• 职责划分清晰（搜索、分析和趋势）
• 参数灵活，支持多种使用场景
• 工具之间不重复实现功能

安全注意事项

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

错误处理

该服务包含全面的错误处理机制：

• 启动时验证配置
• 通过重试处理连接错误
• 服务不可用时优雅降级
• 提供详细日志以便故障排除

许可证

MIT

贡献

1. Fork 此代码库
2. 创建功能分支
3. 进行更改
4. 视情况添加测试
5. 运行 lint 和格式检查
6. 提交拉取请求