JSONL工具MCP服务器

一个模型上下文协议（MCP）服务器，为处理JSON日志（JSONL文件）提供了强大的工具。非常适合解析、搜索、过滤和分析结构化日志文件，具有智能配置和模式检测功能。

特性

🔧 配置和设置工具

get_config -查看当前配置设置
set_config -更新配置（日志目录、模式映射、默认值）
检测模式 -从示例文件中自动检测日志架构
list_log_files -列出可用的日志文件并进行筛选

📊 岩心分析工具

parse_jsonl -使用智能格式化解析和读取JSONL文件
search_logs -使用语义字段名称搜索和相关性检测
过滤器日志 -按级别、事件、时间范围和自定义条件筛选
find_related_logs -使用配置的相关字段查找相关日志
分析logs模式 -具有错误检测功能的高级模式分析

🎯 主要特点

语义字段映射 -使用“级别”、“消息”、“事件”代替原始字段名
自动模式检测 -自动检测时间戳、相关性和API响应字段
智能关联 -在多个ID字段中查找相关日志
可配置显示器 -控制输出格式、截断和漂亮打印
误差分析 -专用错误模式检测和分析

安装

bun install
bun run build

配置

服务器使用配置文件(.jsonl-tools-config.json)要映射字段名称并设置默认值，请执行以下操作：

初始设置

// 1. Set your log directory
set_config({ 
  config: { 
    logDirectory: "/path/to/your/logs" 
  } 
})

// 2. Auto-detect schema from sample log
detect_schema({ 
  file_path: "sample.jsonl", 
  sample_size: 100 
})

// 3. Update config with detected schema
set_config({ 
  config: { 
    schema: { 
      timestampField: "timestamp",
      levelField: "level", 
      correlationFields: ["migrationId", "taskId", "listId"]
    }
  }
})

配置选项

interface LogConfig {
  logDirectory: string;           // Base directory for log files
  schema: {
    timestampField: string;       // Field containing timestamps  
    levelField: string;           // Field containing log levels
    messageField: string;         // Field containing messages
    eventField?: string;          // Field containing event types
    correlationFields: string[];  // Fields for finding related logs
    apiResponseFields: string[];  // Fields containing API JSON
    errorFields: string[];        // Fields containing error info
  };
  defaults: {
    searchLimit: number;          // Default search result limit
    contextWindow: number;        // Context lines around matches
    timeWindowMinutes: number;    // Time window for related logs
  };
  display: {
    prettyPrintApiResponses: boolean;  // Format API JSON
    showLineNumbers: boolean;          // Add line numbers to output
    maxFieldValueLength: number;       // Truncate long values
  };
}

用法

该服务器作为MCP服务器运行，可以与MCP兼容的客户端集成。

工具示例

设置和配置

// List available log files
list_log_files({ pattern: "*.jsonl" })

// Auto-detect schema from your logs
detect_schema({ 
  file_path: "clickup-migration.jsonl",
  sample_size: 100 
})

// Configure for ClickUp migration logs
set_config({
  config: {
    logDirectory: "./logs",
    schema: {
      timestampField: "timestamp",
      levelField: "level",
      messageField: "message", 
      eventField: "event",
      correlationFields: ["migrationId", "taskId", "listId", "spaceId"],
      apiResponseFields: ["response", "data"],
      errorFields: ["error", "errorMessage"]
    }
  }
})

增强日志分析

// Parse with automatic formatting (uses config defaults)
parse_jsonl({
  file_path: "migration.jsonl",  // Relative to configured log directory
  limit: 50
})

// Search using semantic field names
search_logs({
  file_path: "migration.jsonl",
  search_term: "migration-1750050885613",
  field: "message"  // Uses configured messageField
})

// Search and auto-detect correlation fields
search_logs({
  file_path: "migration.jsonl", 
  search_term: "901502943040"  // Will find in taskId, listId, etc.
})

// Filter using semantic fields
filter_logs({
  file_path: "migration.jsonl",
  level: "error",           // Uses configured levelField
  event: "api_response",    // Uses configured eventField
  time_from: "2025-06-16T05:00:00Z"
})

// Find related logs across all correlation fields
find_related_logs({
  file_path: "migration.jsonl",
  correlation_id: "migration-1750050885613"  // Searches all configured correlation fields
})

// Advanced pattern analysis with error detection
analyze_log_patterns({
  file_path: "migration.jsonl",
  group_by: "event",        // Uses semantic field name
  include_timeline: true,
  analyze_errors: true      // Analyzes configured error fields
})

使用ClickUp迁移日志

// Find all logs related to a specific migration
find_related_logs({
  file_path: "migration.jsonl",
  correlation_id: "migration-1750050885613",
  context_window: 3,
  time_window_minutes: 5
})

// Analyze API response patterns
analyze_log_patterns({
  file_path: "migration.jsonl",
  group_by: "client",
  include_timeline: true
})

// Filter for ClickUp API errors
filter_logs({
  file_path: "migration.jsonl",
  level: "error",
  custom_filter: { client: "ClickUp" }
})

日志格式支持

适用于任何JSONL格式。识别的常见字段：

timestamp -用于基于时间的过滤和分析
level -用于日志级过滤（信息、错误、调试等）
event -用于事件类型筛选
message -用于邮件内容搜索
用于关联的任何自定义字段（migrationId、taskId等）

日志条目示例

{
  "event": "workspace_discovery_start",
  "level": "info",
  "message": "Starting workspace discovery phase",
  "migrationId": "migration-1750050885613",
  "timestamp": "2025-06-16T05:14:45.623Z"
}

发展

# Watch mode for development
bun run dev

# Build for production
bun run build

# Start the server
bun run start

# Run tests
bun run test

# Run tests with file watching
bun run test:watch

# Run tests with coverage report
bun run test:coverage

测试

该项目包括一个全面的测试套件 69测试 涵盖所有核心功能：

测试覆盖率

配置管理：模式验证、字段映射、默认值
JSONL处理：解析、搜索、过滤、相关性检测
模式检测：使用启发式方法自动识别字段类型
模式分析：日志分组、时间线生成、错误分析
文件操作：路径解析、嵌套字段访问、错误处理
集成测试：带有临时测试数据的真实文件I/O

测试结构

src/__tests__/config.test.ts -配置和模式验证（11个测试）
src/__tests__/index.test.ts -核心服务器实用程序和模拟（21项测试）
src/__tests__/server-unit.test.ts -业务逻辑单元测试（25次测试）
src/__tests__/server-integration.test.ts -文件I/O集成测试（12个测试）

运行测试

# Run all tests
bun run test

# Watch mode for development
bun run test:watch

# Generate coverage report
bun run test:coverage

所有测试都使用支持TypeScript和ES模块的Jest。该测试套件包括对文件系统操作的全面模拟，并侧重于业务逻辑验证。

使用示例

AI助手提示和用例

以下是如何通过Claude这样的人工智能助手与MCP服务器交互的实际示例：

初始设置和发现

提示: *“我有一些来自ClickUp迁移的JSONL日志文件。你能帮我设置日志分析工具并了解我的日志中有什么吗？”*

AI Response using MCP tools:
1. get_config() - Check current configuration
2. list_log_files() - See what log files are available
3. detect_schema({ file_path: "migration.jsonl", sample_size: 100 }) - Auto-detect the log structure
4. set_config() - Apply the detected schema for optimal analysis

调试失败的迁移

提示: *“迁移'Migration-1750050885613'失败。你能找到所有相关日志并告诉我出了什么问题吗？”*

AI Response:
1. find_related_logs({ correlation_id: "migration-1750050885613" }) - Find all related entries
2. filter_logs({ level: "error", custom_filter: { migrationId: "migration-1750050885613" } }) - Focus on errors
3. analyze_log_patterns({ group_by: "event" }) - See the sequence of events
4. Provide analysis of failure points and recommendations

性能研究

提示: *“我们的API调用今天似乎很慢。你能分析性能模式并找到瓶颈吗？”*

AI Response:
1. analyze_log_patterns({ group_by: "endpoint", include_timeline: true }) - See which endpoints are active
2. filter_logs({ time_from: "2025-06-16T05:00:00Z" }) - Focus on recent logs
3. search_logs({ search_term: "timeout" }) - Look for timeout errors
4. find_related_logs() - Correlate slow requests with system events
5. Present performance summary with specific recommendations

错误模式分析

提示: *“我们遇到了间歇性的429个速率限制错误。你能分析它们何时发生以及触发它们的原因吗？”*

AI Response:
1. search_logs({ search_term: "429", field: "message" }) - Find rate limit errors
2. analyze_log_patterns({ group_by: "response.status", include_timeline: true }) - Pattern analysis
3. find_related_logs() - See what requests preceded the rate limits
4. Generate timeline showing rate limit patterns and suggestions for rate limiting strategy

数据迁移审计

提示: *“我需要审核我们的数据迁移。显示哪些任务失败，哪些成功，以及任何数据不一致。”*

AI Response:
1. analyze_log_patterns({ group_by: "event" }) - Overview of migration events
2. filter_logs({ event: "task_migration_complete" }) - Find completed tasks
3. filter_logs({ level: "error", event: "task_migration_failed" }) - Find failed tasks
4. search_logs({ search_term: "data_inconsistency" }) - Look for data issues
5. Provide comprehensive migration report with success/failure statistics

安全调查

提示: *“我怀疑我们的日志中可能存在一些可疑活动。您能查找身份验证失败、异常访问模式或潜在的安全问题吗？”*

AI Response:
1. search_logs({ search_term: "authentication failed" }) - Find auth failures
2. search_logs({ search_term: "unauthorized" }) - Look for access denials
3. filter_logs({ level: "error", time_from: "2025-06-16T00:00:00Z" }) - Recent errors
4. analyze_log_patterns({ group_by: "userId", include_timeline: true }) - User activity patterns
5. Present security summary with suspicious patterns and recommendations

系统健康监测

提示: *“给我检查一下我们的系统。错误率是多少，最常见的问题是什么，我应该担心哪些趋势？”*

AI Response:
1. analyze_log_patterns({ group_by: "level", include_timeline: true }) - Error rate overview
2. analyze_log_patterns({ group_by: "event" }) - Most common events
3. filter_logs({ level: "error", time_from: "last 24 hours" }) - Recent errors
4. search_logs({ search_term: "exception" }) - Find exceptions
5. Generate system health dashboard with trends and alerts

用户体验分析

提示: *“我们的用户抱怨响应缓慢。你能分析用户会话并找出瓶颈所在吗？”*

AI Response:
1. search_logs({ search_term: "slow" }) - Find slow response mentions
2. filter_logs({ custom_filter: { "response.duration": ">5000" } }) - Find slow requests
3. find_related_logs({ correlation_id: "session-id" }) - Trace user sessions
4. analyze_log_patterns({ group_by: "endpoint" }) - See which endpoints are slow
5. Provide UX analysis with specific performance recommendations

API集成调试

提示: *“我们与ClickUp API的集成间歇性失败。你能帮我了解发生了什么以及什么时候失败吗？”*

AI Response:
1. filter_logs({ custom_filter: { client: "ClickUp" } }) - Focus on ClickUp API calls
2. search_logs({ search_term: "ClickUp", field: "message" }) - Find ClickUp-related logs
3. analyze_log_patterns({ group_by: "response.status" }) - See response patterns
4. find_related_logs({ time_window_minutes: 5 }) - Find correlating events
5. Present API integration analysis with failure patterns and retry recommendations

数据质量验证

提示: *“我需要验证迁移数据的质量。您能检查是否存在字段缺失、格式无效或数据损坏问题吗？”*

AI Response:
1. search_logs({ search_term: "validation_error" }) - Find validation issues
2. search_logs({ search_term: "missing_field" }) - Look for missing data
3. filter_logs({ event: "data_validation" }) - Focus on validation events
4. analyze_log_patterns({ group_by: "validation_status" }) - See validation results
5. Generate data quality report with specific issues and fix recommendations

定制业务逻辑调查

提示: *“我们有用于任务分配的自定义业务规则。您能分析这些规则的触发频率以及它们是否正常工作吗？”*

AI Response:
1. search_logs({ search_term: "business_rule", field: "event" }) - Find rule executions
2. filter_logs({ event: "task_assignment" }) - Focus on assignments
3. analyze_log_patterns({ group_by: "rule_type" }) - See which rules fire most
4. find_related_logs({ correlation_id: "task-id" }) - Trace rule execution chains
5. Present business rule analysis with effectiveness metrics

快速启动提示

对于新用户，以下是开始使用的简单提示：

“为我的项目设置日志分析” → 指导配置设置 “我的日志文件中有什么？” → 发现并分析日志结构 “查找今天的所有错误” → 快速错误分析 “显示最常见的事件” → 图案概述 “查找与\[特定ID\]相关的日志” → 相关分析 “下午2点到3点之间发生了什么？” → 基于时间的调查 “检查系统运行状况” → 整体健康仪表板 “查找慢速请求” → 性能分析 “显示失败的迁移” → 故障调查

基本设置和配置

// 1. Start with configuration
get_config()
// Returns current configuration settings

// 2. Set your log directory
set_config({
  config: {
    logDirectory: "/path/to/your/logs"
  }
})

// 3. Auto-detect schema from your logs
detect_schema({
  file_path: "migration.jsonl",
  sample_size: 100
})
// Analyzes 100 log entries and suggests field mappings

// 4. Apply detected schema
set_config({
  config: {
    schema: {
      timestampField: "timestamp",
      levelField: "level", 
      messageField: "message",
      correlationFields: ["migrationId", "taskId", "listId"],
      apiResponseFields: ["response", "data"],
      errorFields: ["error", "errorMessage"]
    }
  }
})

使用日志文件

// List available log files
list_log_files({ pattern: "*.jsonl" })
// Returns: ["migration.jsonl", "api-calls.jsonl", "errors.jsonl"]

// Parse and read logs with formatting
parse_jsonl({
  file_path: "migration.jsonl",
  limit: 50,
  offset: 0
})
// Returns structured logs with line numbers and formatting

搜索和筛选

// Search for specific terms
search_logs({
  file_path: "migration.jsonl",
  search_term: "migration-1750050885613",
  field: "message",
  case_sensitive: false,
  limit: 20
})

// Search across all fields for correlation IDs
search_logs({
  file_path: "migration.jsonl", 
  search_term: "901502943040"  // Will find in taskId, listId, etc.
})

// Filter by log level
filter_logs({
  file_path: "migration.jsonl",
  level: "error",
  limit: 100
})

// Filter by time range
filter_logs({
  file_path: "migration.jsonl",
  time_from: "2025-06-16T05:00:00Z",
  time_to: "2025-06-16T06:00:00Z",
  event: "api_response"
})

// Custom filtering
filter_logs({
  file_path: "migration.jsonl",
  custom_filter: { 
    client: "ClickUp",
    status: "success" 
  }
})

查找相关日志

// Find all logs related to a migration
find_related_logs({
  file_path: "migration.jsonl",
  correlation_id: "migration-1750050885613",
  context_window: 5,      // Include 5 logs before/after each match
  time_window_minutes: 10 // Include logs within 10 minutes
})

// Find logs related to a specific task
find_related_logs({
  file_path: "migration.jsonl",
  correlation_id: "task-456789",
  context_window: 3
})

模式分析

// Analyze patterns by event type
analyze_log_patterns({
  file_path: "migration.jsonl",
  group_by: "event",
  include_timeline: true
})
// Returns: { "api_request": 150, "api_response": 148, "error": 12 }

// Analyze by log level with timeline
analyze_log_patterns({
  file_path: "migration.jsonl", 
  group_by: "level",
  include_timeline: true,
  analyze_errors: true
})

// Analyze API client patterns
analyze_log_patterns({
  file_path: "api-calls.jsonl",
  group_by: "client",
  include_timeline: false
})

真实世界ClickUp迁移示例

// 1. Setup for ClickUp migration logs
set_config({
  config: {
    logDirectory: "./clickup-migration-logs",
    schema: {
      timestampField: "timestamp",
      levelField: "level",
      messageField: "message",
      eventField: "event", 
      correlationFields: [
        "migrationId", "taskId", "listId", "spaceId", 
        "folderId", "userId", "workspaceId"
      ],
      apiResponseFields: ["response", "data", "result"],
      errorFields: ["error", "errorMessage", "stackTrace"]
    },
    display: {
      prettyPrintApiResponses: true,
      showLineNumbers: true,
      maxFieldValueLength: 500
    }
  }
})

// 2. Find all logs for a failed migration
find_related_logs({
  file_path: "migration-errors.jsonl",
  correlation_id: "migration-1750050885613"
})

// 3. Analyze what went wrong
filter_logs({
  file_path: "migration-errors.jsonl",
  level: "error",
  custom_filter: { migrationId: "migration-1750050885613" }
})

// 4. Check API response patterns for rate limiting
analyze_log_patterns({
  file_path: "api-responses.jsonl",
  group_by: "response.status",
  analyze_errors: true
})

// 5. Find timeline of events for a specific task
search_logs({
  file_path: "task-processing.jsonl",
  search_term: "task-901502943040"
})

调试工作流示例

// 1. Start with high-level analysis
analyze_log_patterns({
  file_path: "application.jsonl",
  group_by: "level",
  include_timeline: true
})

// 2. Focus on errors
filter_logs({
  file_path: "application.jsonl", 
  level: "error",
  time_from: "2025-06-16T05:00:00Z"
})

// 3. Find related logs for specific error
find_related_logs({
  file_path: "application.jsonl",
  correlation_id: "session-abc123",
  context_window: 10
})

// 4. Search for similar error patterns
search_logs({
  file_path: "application.jsonl",
  search_term: "database connection failed",
  field: "message"
})

性能分析示例

// 1. Analyze API response times by endpoint
analyze_log_patterns({
  file_path: "api-performance.jsonl",
  group_by: "endpoint",
  include_timeline: true
})

// 2. Find slow requests
filter_logs({
  file_path: "api-performance.jsonl",
  custom_filter: { 
    "response.duration": { "$gt": 5000 }  // >5 seconds
  }
})

// 3. Correlate slow requests with system events
find_related_logs({
  file_path: "system-events.jsonl", 
  correlation_id: "request-xyz789",
  time_window_minutes: 5
})

许可证

麻省理工学院

Jsonl Tools MCP

快速接入

详细介绍