日志搜索MCP服务器
一个模型上下文协议（MCP）服务器，用于使用自然语言查询搜索和分析微服务日志。使用NestJS构建，旨在与Claude Code和其他MCP客户端配合使用。
特性
- 自然语言搜索：使用简明英语查询日志
- 多服务支持：跨多个微服务搜索
- 请求行程跟踪：使用请求ID跨所有服务跟踪请求
- 每小时统计：性能分析和峰值时间识别
- 状态聚合：按状态统计和分析日志条目
- 流处理：高效处理大型gzip压缩日志文件
- 缓存：5分钟TTL缓存以提高性能
系统架构
该服务器专为微服务架构而设计。默认服务包括：
- api网关：所有API请求的入口点
- 身份验证服务：身份验证和授权
- 用户服务：用户管理和配置文件
- 通知服务：电子邮件、短信和推送通知
您可以通过以下方式自定义服务列表 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（必填）：请求跟踪IDstartDate（可选）：开始日期
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日志。
定制
添加自定义服务
- 设置
SERVICES环境变量：
SERVICES=order-service,payment-service,inventory-service- 在LOG_DIRECTORY中创建相应的目录
- 服务器将自动检测并搜索这些服务
日志格式要求
- 必填字段:
level,message - 可选但推荐:
timestamp（或@timestamp),requestId,service - 格式：换行分隔的JSON（NDJSON），gzip压缩
演出
- 流媒体：逐行处理（不加载完整文件）
- 缓存：搜索结果上的5分钟TTL
- 提前终止：达到限制时停止
- 默认限制：最多500k条线路，以防止超时
故障排除
“未配置MCP服务器”
从项目目录中运行或使用添加 --scope user 旗帜。
“未找到LOG_DIRECTORY”
确保路径 .env 是绝对的和可读的。
“服务类型是必需的”
在查询中指定服务或使用“gateway”、“auth”等关键字。
贡献
- 分叉存储库
- 创建要素分支
- 进行更改
- 运行测试：
npm test - 提交拉取请求
许可证
国际学生委员会
作者
鲁特维克·劳特