MCP Log Search

日志搜索MCP服务器

一个模型上下文协议（MCP）服务器，用于使用自然语言查询搜索和分析微服务日志。使用NestJS构建，旨在与Claude Code和其他MCP客户端配合使用。

特性

• 自然语言搜索：使用简明英语查询日志
• 多服务支持：跨多个微服务搜索
• 请求行程跟踪：使用请求ID跨所有服务跟踪请求
• 每小时统计：性能分析和峰值时间识别
• 状态聚合：按状态统计和分析日志条目
• 流处理：高效处理大型gzip压缩日志文件
• 缓存：5分钟TTL缓存以提高性能

系统架构

该服务器专为微服务架构而设计。默认服务包括：

1. api网关：所有API请求的入口点
2. 身份验证服务：身份验证和授权
3. 用户服务：用户管理和配置文件
4. 通知服务：电子邮件、短信和推送通知

您可以通过以下方式自定义服务列表 SERVICES 环境变量。

先决条件

• Node.js>=18.x
• npm或纱线
• gzip压缩的JSON格式的日志文件（NDJSON）

安装

# Clone the repository
git clone 
cd log-search-mcp-server

# Install dependencies
npm install

# Configure environment
cp .env.example .env
# Edit .env and set LOG_DIRECTORY to your logs location

# Build the project
npm run build

配置

环境变量

创建 .env 文件：

LOG_DIRECTORY=/path/to/your/logs
SERVICES=api-gateway,auth-service,user-service,notification-service
CACHE_TTL=300
DEFAULT_SEARCH_LIMIT=100

日志文件结构

日志应按以下方式组织：

{LOG_DIRECTORY}/
  ├── api-gateway/
  │   └── 2025-10-30.gz
  ├── auth-service/
  │   └── 2025-10-30.gz
  ├── user-service/
  │   └── 2025-10-30.gz
  └── notification-service/
      └── 2025-10-30.gz

每个日志文件应包含换行符分隔的JSON（NDJSON）：

{"level":"INFO","message":"Request processed","timestamp":"2025-10-30T10:30:00Z","requestId":"req-123","service":"api-gateway"}

使用Claude Code CLI

全球安装

# Add MCP server globally
claude mcp add --scope user --transport stdio log-search \
  --env LOG_DIRECTORY=/path/to/logs \
  -- node /path/to/dist/src/main.js

# Verify installation
claude mcp list

查询示例

✅ "show errors in api-gateway on 2025-10-30"
✅ "find logs with user-12345"
✅ "how many requests failed today"
✅ "track request req-abc-123"
✅ "authentication errors in auth-service"
✅ "hourly stats for api-gateway"

MCP工具

服务器公开了4个MCP工具：

1.搜索日志

使用自然语言查询搜索日志。

参数：

• query （必填）：自然语言搜索查询
• startDate （可选）：开始日期（YYYY-MM-DD）
• endDate （可选）：结束日期（YYYY-MM-DD）
• service （可选）：服务名称
• identifier （可选）：按标识符（用户ID、交易ID等）过滤
• logLevel （可选）：信息、错误、警告、调试
• source （可选）：源系统名称
• limit （可选）：最大结果（默认值：10，最大值：100）

2.get_log_summary

获取日志的统计摘要。

参数：

• startDate （必填）：开始日期
• endDate （必填）：结束日期
• service （必填）：服务名称

3.track_request_journey

跨所有服务跟踪请求。

参数：

• requestId （必填）：请求跟踪ID
• startDate （可选）：开始日期

4.获取小时数

获取日志统计的每小时细分。

参数：

• date （必填）：日期（YYYY-MM-DD）
• service （必填）：服务名称

发展

# Run tests
npm test

# Run tests with coverage
npm test -- --coverage

# Run tests in watch mode
npm test -- --watch

# Build with watch mode
npm run build -- --watch

测试

生成测试日志

./scripts/setup-test-logs.sh

这创建了一个 test-logs/ 目录中包含用于测试的示例gzip压缩JSON日志。

定制

添加自定义服务

1. 设置 SERVICES 环境变量：

   SERVICES=order-service,payment-service,inventory-service

1. 在LOG_DIRECTORY中创建相应的目录

1. 服务器将自动检测并搜索这些服务

日志格式要求

• 必填字段: level, message
• 可选但推荐: timestamp （或 @timestamp), requestId, service
• 格式：换行分隔的JSON（NDJSON），gzip压缩

演出

• 流媒体：逐行处理（不加载完整文件）
• 缓存：搜索结果上的5分钟TTL
• 提前终止：达到限制时停止
• 默认限制：最多500k条线路，以防止超时

故障排除

“未配置MCP服务器”

从项目目录中运行或使用添加 --scope user 旗帜。

“未找到LOG_DIRECTORY”

确保路径 .env 是绝对的和可读的。

“服务类型是必需的”

在查询中指定服务或使用“gateway”、“auth”等关键字。

贡献

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 运行测试： npm test
5. 提交拉取请求

许可证

国际学生委员会

作者

鲁特维克·劳特