Seq MCP

🚀 SEQ MCP 服務器

SEQ MCP 服務器是一個遵循 MCP（模型上下文協議）的服務器，它能夠讓大語言模型（LLMs）從 SEQ 結構化日誌服務器中查詢和分析日誌。

🚀 快速開始

SEQ MCP 服務器可助力大語言模型與 SEQ 結構化日誌服務器交互，實現日誌的查詢與分析。以下是使用本服務器的快速指南。

✨ 主要特性

• 搜索事件：使用強大的 SEQ 過濾語法查詢日誌。
• 獲取事件詳情：檢索特定日誌事件的完整信息。
• 分析日誌：對特定時間段內的日誌模式進行統計分析。
• 列出信號：訪問 SEQ 中配置的已保存搜索/信號。
• 健康檢查：監控 SEQ 服務器狀態。

📦 安裝指南

選項 1：使用 Docker（推薦）

# 使用 GitHub 容器註冊表
docker pull ghcr.io/roeej/seq-mcp:latest

# 或者使用 Docker Hub
docker pull roeej/seq-mcp:latest

選項 2：從源代碼安裝

git clone https://github.com/RoeeJ/seq-mcp.git
cd seq-mcp
npm install
npm run build

📚 詳細文檔

配置

環境變量

注意：如果你的 SEQ 實例啟用了身份驗證，則需要提供 SEQ_API_KEY。

配置說明

1. 複製示例環境文件：

cp .env.example .env

2. 使用你的 SEQ 服務器詳細信息編輯 .env 文件：

SEQ_URL=http://your-seq-server:5341
SEQ_API_KEY=your-api-key-here

與 Claude Desktop 配合使用

macOS

1. 打開 Claude Desktop 設置。
2. 導航到“開發者” → “編輯配置”。
3. 添加 SEQ 服務器配置：

{
  "mcpServers": {
    "seq": {
      "command": "node",
      "args": ["/absolute/path/to/seq-mcp/dist/index.js"],
      "env": {
        "SEQ_URL": "http://localhost:5341",
        "SEQ_API_KEY": "your-api-key-here"
      }
    }
  }
}

Windows

1. 打開 Claude Desktop 設置。
2. 導航到“開發者” → “編輯配置”。
3. 添加 SEQ 服務器配置：

{
  "mcpServers": {
    "seq": {
      "command": "node.exe",
      "args": ["C:\\path\\to\\seq-mcp\\dist\\index.js"],
      "env": {
        "SEQ_URL": "http://localhost:5341",
        "SEQ_API_KEY": "your-api-key-here"
      }
    }
  }
}

與 Claude Code 配合使用

選項 1：使用 .env 文件

1. 在項目根目錄創建一個 .env 文件：

SEQ_URL=http://localhost:5341
SEQ_API_KEY=your-api-key-here

2. 將其添加到你的 Claude Code MCP 配置中：

{
  "seq": {
    "command": "node",
    "args": ["/path/to/seq-mcp/dist/index.js"]
  }
}

選項 2：直接使用環境變量

{
  "seq": {
    "command": "node",
    "args": ["/path/to/seq-mcp/dist/index.js"],
    "env": {
      "SEQ_URL": "http://localhost:5341",
      "SEQ_API_KEY": "your-api-key-here",
      "SEQ_DEFAULT_LIMIT": "200",
      "SEQ_TIMEOUT": "60000"
    }
  }
}

選項 3：使用系統環境變量

在你的 shell 中設置環境變量：

# macOS/Linux - 添加到 ~/.bashrc 或 ~/.zshrc
export SEQ_URL="http://localhost:5341"
export SEQ_API_KEY="your-api-key-here"

# Windows PowerShell
$env:SEQ_URL = "http://localhost:5341"
$env:SEQ_API_KEY = "your-api-key-here"

然後使用簡單的配置：

{
  "seq": {
    "command": "node",
    "args": ["/path/to/seq-mcp/dist/index.js"]
  }
}

從 SEQ 獲取 API 密鑰

1. 在 Web 瀏覽器中打開你的 SEQ 實例。
2. 導航到“設置” → “API 密鑰”。
3. 點擊“添加 API 密鑰”。
4. 提供一個標題（例如，“MCP 服務器”）。
5. 設置適當的權限（通常“讀取”權限就足夠了）。
6. 複製生成的 API 密鑰。

在 Claude 中使用示例

配置完成後，你可以自然地查詢日誌：

"顯示過去一小時內的所有錯誤日誌"
"查找包含 'timeout' 錯誤的日誌"
"分析我的 API 服務的日誌模式"
"過去 24 小時內最常見的錯誤是什麼？"
"獲取事件 ID 為 abc123 的詳細信息"

可用工具

search_events

使用過濾器搜索事件：

- query: SEQ 過濾語法（例如，"Level = 'Error'" 或 "@Message like '%failed%'"）
- count: 結果數量（1 - 1000）
- fromDate/toDate: ISO 日期字符串
- level: 按日誌級別過濾

get_event

按 ID 獲取特定事件的詳細信息。

analyze_logs

分析日誌模式：

- query: 可選的 SEQ 過濾器
- timeRange: 1h、6h、24h、7d 或 30d
- groupBy: 用於分組結果的屬性名稱

list_signals

列出 SEQ 中所有配置的信號（已保存的搜索）。

check_health

檢查 SEQ 服務器的健康狀態。

故障排除

連接問題

1. 驗證 SEQ 是否正在運行：

curl http://localhost:5341/api/health

2. 檢查 API 密鑰權限：確保你的 API 密鑰具有“讀取”權限。
3. 網絡/防火牆：確保 MCP 服務器可以訪問你的 SEQ 實例。
4. 超時錯誤：對於大型查詢，增加 SEQ_TIMEOUT。

常見錯誤

• “Unauthorized”：檢查你的 API 密鑰是否正確。
• “Connection refused”：驗證 SEQ_URL 並確保 SEQ 正在運行。
• “Timeout”：查詢可能過於複雜，嘗試添加更具體的過濾器。

開發

# 在開發模式下運行
npm run dev

# 運行測試
npm test

# 代碼檢查
npm run lint

# 類型檢查
npm run typecheck

SEQ 查詢示例

• Level = 'Error' - 所有錯誤日誌。
• @Message like '%timeout%' - 包含“timeout”的消息。
• Application = 'MyApp' and Level in ['Warning', 'Error'] - MyApp 的警告和錯誤日誌。
• @Timestamp > Now() - 1h - 過去一小時內的事件。
• StatusCode >= 400 - HTTP 錯誤。
• Environment = 'Production' and ResponseTime > 1000 - 生產環境中的慢請求。
• UserId = '12345' - 特定用戶的所有日誌。
• @Exception is not null - 所有包含異常的日誌。

高級配置

使用 Docker

如果 SEQ 在 Docker 中運行：

{
  "seq": {
    "command": "node",
    "args": ["/path/to/seq-mcp/dist/index.js"],
    "env": {
      "SEQ_URL": "http://host.docker.internal:5341",
      "SEQ_API_KEY": "your-api-key"
    }
  }
}

使用遠程 SEQ

對於雲託管的 SEQ 實例：

{
  "seq": {
    "command": "node",
    "args": ["/path/to/seq-mcp/dist/index.js"],
    "env": {
      "SEQ_URL": "https://seq.yourcompany.com",
      "SEQ_API_KEY": "your-api-key",
      "SEQ_TIMEOUT": "60000"
    }
  }
}

Docker 使用說明

運行容器

# 基本用法
docker run --rm \
  -e SEQ_URL=http://host.docker.internal:5341 \
  -e SEQ_API_KEY=your-api-key \
  ghcr.io/roeej/seq-mcp:latest

# 使用所有環境變量
docker run --rm \
  -e SEQ_URL=http://your-seq-server:5341 \
  -e SEQ_API_KEY=your-api-key \
  -e SEQ_DEFAULT_LIMIT=200 \
  -e SEQ_TIMEOUT=60000 \
  ghcr.io/roeej/seq-mcp:latest

與 Claude Desktop 配合使用（Docker）

添加到你的 Claude Desktop 配置中：

{
  "mcpServers": {
    "seq": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "SEQ_URL=http://host.docker.internal:5341",
        "-e", "SEQ_API_KEY=your-api-key",
        "ghcr.io/roeej/seq-mcp:latest"
      ]
    }
  }
}

與 Claude Code 配合使用（Docker）

{
  "seq": {
    "command": "docker",
    "args": [
      "run",
      "--rm",
      "-i",
      "-e", "SEQ_URL=http://your-seq-server:5341",
      "-e", "SEQ_API_KEY=your-api-key",
      "ghcr.io/roeej/seq-mcp:latest"
    ]
  }
}

Docker Compose 示例

創建一個 docker-compose.yml 文件：

version: '3.8'

services:
  seq-mcp:
    image: ghcr.io/roeej/seq-mcp:latest
    environment:
      - SEQ_URL=http://seq:5341
      - SEQ_API_KEY=${SEQ_API_KEY}
    networks:
      - seq-network

  seq:
    image: datalust/seq:latest
    ports:
      - "5341:5341"
    environment:
      - ACCEPT_EULA=Y
    networks:
      - seq-network

networks:
  seq-network:
    driver: bridge

架構

• MCP 服務器：處理工具定義和請求路由。
• SEQ 客戶端：管理與 SEQ 的 API 通信。
• 類型安全：使用 TypeScript 和 Zod 進行驗證。
• 錯誤處理：優雅降級並提供有意義的錯誤消息。

安全

• API 密鑰不會被記錄或暴露。
• 所有請求在執行前都會進行驗證。
• 對長時間運行的查詢提供超時保護。
• 僅支持只讀操作（不修改日誌）。
• 支持 HTTP 和 HTTPS 連接。

CI/CD 管道

本項目使用 GitHub Actions 進行持續集成和部署：

• CI：每次推送和拉取請求時運行，以確保代碼質量。

  • 使用 ESLint 進行代碼檢查。
  • 使用 TypeScript 進行類型檢查。
  • 使用 Vitest 進行單元測試。
  • 多版本 Node.js 測試（18.x、20.x）。

• Docker 發佈：

  • 在主分支上自動構建併發布到 GitHub 容器註冊表。
  • 在版本標籤上發佈到 Docker Hub。
  • 多平臺構建（linux/amd64、linux/arm64）。
  • 語義化版本標籤。

創建發佈版本

1. 為你的發佈版本打標籤：

git tag v1.0.0
git push origin v1.0.0

2. GitHub Action 將自動執行以下操作：

• 構建多平臺 Docker 鏡像。
• 推送到 ghcr.io/roeej/seq-mcp:1.0.0。
• 推送到 dockerhub/roeej/seq-mcp:1.0.0（需要設置密鑰）。

所需的 GitHub 密鑰

對於 Docker Hub 發佈（可選）：

• DOCKERHUB_USERNAME：你的 Docker Hub 用戶名。
• DOCKERHUB_TOKEN：Docker Hub 訪問令牌。

注意：GitHub 容器註冊表（ghcr.io）發佈使用倉庫的 GITHUB_TOKEN 自動工作，無需額外設置。

貢獻

1. 分叉倉庫。
2. 創建你的功能分支 (git checkout -b feature/amazing-feature)。
3. 提交你的更改 (git commit -m 'Add some amazing feature')。
4. 推送到該分支 (git push origin feature/amazing-feature)。
5. 打開一個拉取請求。

📄 許可證

本項目採用 MIT 許可證。