Json Logs MCP Server

🚀 JSON日誌MCP服務器

JSON日誌MCP服務器是一個基於模型上下文協議（MCP）的服務器，它能讓Claude Desktop（或任何MCP客戶端）讀取和分析JSON格式的日誌文件。該服務器提供了用於搜索、過濾、聚合和分析結構化日誌數據的工具。

🚀 快速開始

JSON日誌MCP服務器允許Claude Desktop（或任何MCP客戶端）讀取和分析JSON格式的日誌文件。以下是使用該服務器的基本步驟：

1. 確保你已經安裝了Python 3.11或更高版本，並且擁有Claude Desktop（或其他MCP客戶端）。
2. 按照安裝指南進行安裝和配置。
3. 配置日誌目錄和Claude Desktop。
4. 按照日誌格式要求生成或準備日誌文件。
5. 通過Claude Desktop使用可用的工具與日誌進行交互。

✨ 主要特性

• 📁 瀏覽日誌文件 - 列出並讀取JSON格式的日誌文件。
• 🔍 搜索和過濾 - 按級別、模塊、函數、消息內容和時間範圍查詢日誌。
• 📊 聚合數據 - 按各種標準對日誌進行分組和分析。
• 📈 統計信息 - 獲取關於日誌數據的全面統計信息。
• 🚀 快速高效 - 針對處理大型日誌文件進行了優化。

📦 安裝指南

克隆倉庫

git clone https://github.com/mfreeman451/json-logs-mcp-server.git
cd json-logs-mcp-server

創建虛擬環境

python3 -m venv .venv
source .venv/bin/activate  # 在Windows上: .venv\Scripts\activate

安裝包

pip install -e .

創建包裝腳本

cat > run-json-logs-server.sh << 'EOF'
#!/bin/bash
cd "$(dirname "$0")"
source .venv/bin/activate
exec python json_logs_mcp_server.py
EOF
chmod +x run-json-logs-server.sh

📚 詳細文檔

配置日誌目錄

默認情況下，服務器會在運行目錄的./logs目錄中查找日誌。你可以通過設置環境變量或編輯代碼來更改此目錄： 選項1：使用環境變量

export MCP_JSON_LOGS_DIR="/path/to/your/logs"

配置Claude Desktop

將服務器添加到Claude Desktop配置文件中：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "json-logs": {
      "command": "/absolute/path/to/run-json-logs-server.sh",
      "args": [],
      "env": {
        "MCP_JSON_LOGS_DIR": "/path/to/your/logs"
      }
    }
  }
}

重要提示：請使用包裝腳本的絕對路徑。

日誌格式

服務器期望JSON日誌文件每行包含一個JSON對象。每個日誌條目應包含以下字段：

{
  "timestamp": "2024-01-15T10:30:45.123456",
  "level": "INFO",
  "message": "User authentication successful",
  "module": "auth.handler",
  "function": "authenticate_user",
  "line": 42
}

必需字段

• timestamp - ISO格式的時間戳
• level - 日誌級別（DEBUG、INFO、WARNING、ERROR、CRITICAL）
• message - 日誌消息
• module - 模塊名稱
• function - 函數名稱
• line - 行號

示例日誌文件

創建一個名為example.log的文件，內容如下，以測試服務器：

{"timestamp": "2024-01-15T10:30:45.123456", "level": "INFO", "message": "Application started successfully", "module": "main", "function": "startup", "line": 15}
{"timestamp": "2024-01-15T10:30:46.234567", "level": "DEBUG", "message": "Loading configuration from config.json", "module": "config.loader", "function": "load_config", "line": 42}
{"timestamp": "2024-01-15T10:30:47.345678", "level": "INFO", "message": "Database connection established", "module": "db.connection", "function": "connect", "line": 78}
{"timestamp": "2024-01-15T10:31:02.456789", "level": "WARNING", "message": "Rate limit approaching: 85% of quota used", "module": "api.ratelimit", "function": "check_limits", "line": 156}
{"timestamp": "2024-01-15T10:32:15.567890", "level": "ERROR", "message": "Failed to authenticate user: Invalid credentials", "module": "auth.handler", "function": "authenticate_user", "line": 203}
{"timestamp": "2024-01-15T10:32:16.678901", "level": "INFO", "message": "Retry attempt 1/3 for user authentication", "module": "auth.handler", "function": "retry_auth", "line": 215}
{"timestamp": "2024-01-15T10:33:45.789012", "level": "CRITICAL", "message": "Database connection lost: Connection timeout", "module": "db.connection", "function": "health_check", "line": 92}
{"timestamp": "2024-01-15T10:33:46.890123", "level": "INFO", "message": "Attempting database reconnection", "module": "db.connection", "function": "reconnect", "line": 105}
{"timestamp": "2024-01-15T10:33:48.901234", "level": "INFO", "message": "Database connection restored", "module": "db.connection", "function": "reconnect", "line": 112}
{"timestamp": "2024-01-15T10:35:22.012345", "level": "DEBUG", "message": "Cache hit for key: user_session_abc123", "module": "cache.manager", "function": "get", "line": 67}

Python日誌記錄器配置示例

以下是如何配置Python日誌記錄器以輸出所需格式的示例：

import logging
import json
from datetime import datetime

class JSONFormatter(logging.Formatter):
    def format(self, record):
        log_obj = {
            "timestamp": datetime.fromtimestamp(record.created).isoformat(),
            "level": record.levelname,
            "message": record.getMessage(),
            "module": record.module,
            "function": record.funcName,
            "line": record.lineno
        }
        return json.dumps(log_obj)

# 配置日誌記錄器
logger = logging.getLogger()
handler = logging.FileHandler('app.log')
handler.setFormatter(JSONFormatter())
logger.addHandler(handler)
logger.setLevel(logging.INFO)

# 示例用法
logger.info("Application started")
logger.error("Something went wrong")

可用工具

1. list_log_files

列出所有可用的日誌文件及其元數據。

在Claude中的示例用法：

• "列出所有日誌文件"
• "顯示可用的日誌"

2. query_logs

搜索和過濾日誌條目。

參數：

• files - 要搜索的文件列表（可選，默認為所有文件）
• level - 按日誌級別過濾
• module - 按模塊名稱過濾
• function - 按函數名稱過濾
• message_contains - 在消息內容中搜索
• start_time - 開始時間過濾（ISO格式）
• end_time - 結束時間過濾（ISO格式）
• limit - 最大結果數（默認：100）

在Claude中的示例用法：

• "顯示今天所有的ERROR日誌"
• "查找包含'數據庫連接'的日誌"
• "顯示過去一小時內auth模塊的錯誤"
• "搜索認證失敗的日誌"

3. aggregate_logs

按指定標準聚合日誌數據。

參數：

• files - 要分析的文件（可選）
• group_by - 分組標準："level"、"module"、"function" 或 "hour"

在Claude中的示例用法：

• "按級別分組日誌"
• "顯示哪個模塊生成的日誌最多"
• "按小時分析日誌分佈"
• "日誌級別的分佈情況如何？"

4. get_log_stats

獲取關於日誌文件的全面統計信息。

在Claude中的示例用法：

• "顯示日誌統計信息"
• "我的日誌的總體摘要是什麼？"
• "我總共有多少個錯誤？"

💻 使用示例

示例1：查找錯誤

你: "顯示過去一小時內所有的ERROR和CRITICAL日誌"
Claude: 我將搜索過去一小時內的ERROR和CRITICAL級別日誌...
[使用query_logs工具進行級別和時間過濾]

示例2：分析模式

你: "哪個模塊生成的警告最多？"
Claude: 讓我按模塊分析WARNING日誌的分佈...
[使用帶有級別過濾的query_logs，然後按模塊分組使用aggregate_logs]

示例3：調試問題

你: "查找所有數據庫連接錯誤，並顯示錯誤發生前的情況"
Claude: 我將搜索數據庫連接錯誤及其上下文...
[使用query_logs查找特定錯誤和周圍的日誌條目]

獨立運行

你也可以獨立運行服務器進行測試（MCP Inspector或其他MCP客戶端）：

# 使用標準輸入輸出傳輸（默認）
python json_logs_mcp_server.py

🔧 技術細節

性能考慮

• 服務器按需加載日誌文件，而不是一次性加載所有文件。
• 大型日誌文件（>100MB）可能需要一些時間來處理。
• 在查詢中使用limit參數來控制結果大小。
• 考慮輪轉日誌文件以保持性能。

故障排除

服務器無法啟動

• 檢查是否安裝了Python 3.8+：python3 --version
• 確保所有依賴項都已安裝：pip install -e .
• 驗證日誌目錄是否存在幷包含.log文件。

"spawn python ENOENT"錯誤

• 在配置中使用python3而不是python。
• 使用包裝腳本的完整絕對路徑。
• 檢查包裝腳本是否可執行：chmod +x run-json-logs-server.sh。

"Module not found"錯誤

• 確保你使用的是激活虛擬環境的包裝腳本。
• 檢查依賴項是否安裝在虛擬環境中：source .venv/bin/activate && pip list。
• 重新安裝依賴項：pip install -e .。

未找到日誌

• 驗證日誌文件是否存在於配置的目錄中。
• 檢查日誌文件是否具有.log擴展名（匹配*.log*的文件將被找到）。
• 確保日誌文件格式正確（每行一個有效的JSON對象）。
• 嘗試使用上面提供的示例日誌文件。

工具未在Claude中顯示

• 配置更改後重啟Claude Desktop。
• 檢查Claude Desktop中的“連接應用”部分。
• 在Claude的開發者控制檯中查找錯誤消息。
• 確保服務器在Claude的UI中顯示為“已連接”。

調試提示

• 手動運行服務器以查看任何錯誤消息：./run-json-logs-server.sh。
• 檢查服務器輸出：通過標準輸入輸出運行時，診斷消息將顯示在標準錯誤輸出中。
• 首先使用上面的示例數據測試一個簡單的日誌文件。
• 驗證JSON格式：每行必須是包含所有必需字段的有效JSON。

📄 許可證

本項目採用MIT許可證，詳情請參閱LICENSE文件。