Coralogix MCP Server

这是一个连接到Coralogix日志的MCP（模型上下文协议）服务器，提供工具供AI助手（如Cursor或Claude Desktop）查询和分析日志数据。该服务器通过简单的界面提供了强大的日志分析、可视化和故障排除功能。

功能

日志查询与分析

• 使用Lucene语法查询日志 (query_logs)
• 搜索特定错误消息 (search_logs_by_error)
• 查找与特定函数相关的日志 (find_logs_by_function)
• 通过应用程序名称和子系统进行高级过滤
• 自定义查询的时间范围
• 分页和结果限制

可视化

• 从日志流生成序列图 (generate_sequence_diagram)
• 支持Mermaid图表语法
• 自定义图表标题和时间戳
• 基于线程的分组选项
• 系统交互的可视化表示

用户分析

• 从日志中提取用户列表 (extract_users_list)
• 配置用户标识字段
• 聚合用户活动
• 用户行为模式识别

数据验证和类型安全

• 使用Zod模式进行运行时验证
• 强大的TypeScript类型检查
• 全面的错误处理
• 输入清理和验证

集成功能

• 与Coralogix集成的RESTful API
• 基于环境的配置
• 灵活的身份验证处理
• 请求速率限制和优化

安装

1. 克隆仓库（如果尚未完成）。

2. 安装依赖项：

   npm install
   

3. 设置环境变量： 在项目根目录创建一个.env文件（复制自.env.template），并填写您的Coralogix详细信息：

   # Coralogix API端点（根据您的区域查看文档）
   CORALOGIX_API_URL=https://api.coralogix.com/api/v2/dataprime/query
   # 您的Coralogix API密钥（日志查询密钥）
   CORALOGIX_API_KEY=your_api_key_here
   # 可选：用于筛选日志的默认应用程序名称
   CORALOGIX_APP_NAME=
   # 可选：用于筛选日志的默认子系统名称
   CORALOGIX_SUBSYSTEM_NAME=
   

4. 构建TypeScript代码：

   npm run build
   

可用工具

1. 查询日志

使用Lucene语法查询Coralogix日志：

{
  query: string;        // Lucene查询字符串
  timeframe: string;    // 例如："last 24h"，"last 7d"
  applicationName?: string;
  subsystemName?: string;
  limit?: number;
  offset?: number;      // 用于分页
  sortBy?: string;      // 排序字段
  sortOrder?: 'asc' | 'desc';
}

2. 根据错误搜索日志

搜索具有上下文的特定错误消息：

{
  errorMessage: string; // 要搜索的错误消息
  timeframe: string;    // 例如："last 24h"，"last  7d"
  includeStackTrace?: boolean;
  contextLines?: number; // 错误前后行数
  severity?: string;    // 错误严重级别
}

3. 根据函数查找日志

查找与特定函数相关的日志，并进行高级过滤：

{
  functionName: string; // 要搜索的函数名
  filePath?: string;   // 可选文件路径
  timeframe?: string;  // 例如："last 24h"，"last 7d"
  includeParams?: boolean; // 包含函数参数
  includeReturns?: boolean; // 包含返回值
  stackDepth?: number; // 堆栈跟踪深度
}

4. 生成序列图

从日志流生成Mermaid序列图：

{
  query: string;       // 用于过滤日志的Lucene查询
  timeframe: string;   // 例如："last 24h"，"last 7d"
  title?: string;      // 图表标题
  showTimestamps?: boolean;
  groupByThread?: boolean;
  excludePatterns?: string[]; // 要排除的模式
  includePatterns?: string[]; // 要包含的模式
  style?: {
    theme?: string;    // 图表主题
    wrap?: boolean;    // 文本换行
    boxed?: boolean;   // 参与者周围的框
  }
}

5. 提取用户列表

从日志中提取并分析用户信息：

{
  timeframe: string;   // 例如："last 24h"，"last 7d"
  query: string;       // 用于过滤日志的Lucene查询
  userIdentifierField?: string; // 包含用户ID的字段
  aggregations?: {     // 可选聚合
    byAction?: boolean;
    byTimestamp?: boolean;
    byStatus?: boolean;
  };
  includeMetadata?: boolean; // 包含用户元数据
}

开发

在开发模式下运行

npm run dev

测试

# 运行单元测试
npm test

# 运行带有覆盖率的测试
npm run test:coverage

# 运行集成测试
npm run test:integration

调试

服务器支持多种调试模式：

# 启用调试日志
DEBUG=coralogix-mcp:* npm run dev

# 调试特定组件
DEBUG=coralogix-mcp:api npm run dev
DEBUG=coralogix-mcp:diagram npm run dev

项目结构

src/
├── index.ts              # 主服务器入口点
├── coralogix-client.ts   # Coralogix API客户端
├── sequence-diagram.ts   # 序列图生成
├── types.ts             # TypeScript接口和Zod模式
├── utils/
│   ├── validation.ts    # 输入验证实用程序
│   ├── formatting.ts    # 输出格式化实用程序
│   └── errors.ts       # 错误处理实用程序
└── services/
    ├── log-service.ts   # 日志查询服务
    ├── diagram-service.ts # 图表生成服务
    └── user-service.ts  # 用户分析服务

错误处理

服务器实现了全面的错误处理：

• 输入验证错误
• API连接错误
• 速率限制错误
• 认证错误
• 处理错误

每个错误都会返回一个结构化的响应，包括：

• 错误码
• 易读的消息
• 建议的解决方案
• 请求上下文（适用时）

性能考虑

• 实现请求缓存
• 优化大型结果集
• 支持大型响应的流式传输
• 实现连接池
• 平稳处理速率限制

许可证

MIT