AlilogMCP

阿里云日志服务（SLS）的 MCP（Model Context Protocol）服务器，支持通过 MCP 协议查询阿里云日志，特别适用于根据关键词查询 traceId，然后根据 traceId 查询详细日志的场景。

功能特性

• ✅ 支持多 AK 组配置
• ✅ 支持多 Logstore 查询
• ✅ 根据关键词查询 traceId 列表
• ✅ 根据 traceId 查询详细日志
• ✅ 支持自定义时间范围
• ✅ 使用阿里云官方 SDK @alicloud/log

安装

这是一个 CLI 工具，推荐使用 npx 直接运行，无需安装：

npx alilogmcp

或者全局安装：

npm install -g alilogmcp
alilogmcp

配置

配置文件位置：~/.alilogmcp/config.json

配置文件格式

{
  "accounts": [
    {
      "name": "prod",
      "accessKeyId": "LTAI5txxxxxxxxxxxxx",
      "accessKeySecret": "your-access-key-secret",
      "region": "cn-hangzhou",
      "endpoint": "cn-hangzhou.log.aliyuncs.com",
      "project": "my-project",
      "logstores": ["app-logs", "error-logs", "access-logs"]
    }
  ],
  "defaultTraceIdField": "traceId"
}

配置说明

• accounts: 账户配置数组，每个账户代表一个 AK 组
  • name: 账户名称（用于在 MCP 工具中指定）
  • accessKeyId: 阿里云 AccessKey ID
  • accessKeySecret: 阿里云 AccessKey Secret
  • region: 区域名称（如：cn-hangzhou）
  • endpoint: 日志服务端点（格式：{region}.log.aliyuncs.com）
  • project: 项目名称
  • logstores: Logstore 名称数组，或配置对象数组（支持为每个 logstore 单独配置返回字段）
  • 字符串格式：["logstore1", "logstore2"]
  • 对象格式：[{"name": "logstore1", "returnFields": ["field1", "field2"]}]
• returnFields: 返回字段白名单（可选）
  • 全局配置：应用到所有账户和 logstore
  • 账户配置：应用到该账户的所有 logstore
  • Logstore 配置：仅应用到该 logstore
  • 优先级：Logstore 配置 > 账户配置 > 全局配置
  • 支持通配符：如 __tag__:* 匹配所有以 __tag__ 开头的字段
• defaultTraceIdField: traceId 字段名，默认为 "traceId"

MCP 工具

1. list_accounts

列出所有配置的账户。

参数: 无

返回示例:

{
  "accounts": [
    {
      "name": "prod",
      "region": "cn-hangzhou",
      "project": "my-project",
      "logstoreCount": 3
    }
  ]
}

2. list_logstores

列出指定账户的所有 Logstore。

参数:

• accountName (string, required): 账户名称

返回示例:

{
  "logstores": ["app-logs", "error-logs", "access-logs"]
}

3. query_trace_ids

根据关键词查询 traceId 列表。

参数:

• accountName (string, required): 账户名称
• logstore (string, required): Logstore 名称
• keyword (string, required): 搜索关键词
• timeRange (object, required): 时间范围（必需）
  • from (string, required): 开始时间，必须使用格式 "YYYY-MM-DD HH:mm:ss" (例如 "2025-11-01 12:00:00")
  • to (string, required): 结束时间，必须使用格式 "YYYY-MM-DD HH:mm:ss" (例如 "2025-11-01 13:00:00")
  • 时间范围不能超过 7 天
• limit (number, optional): 返回结果数量限制，默认 100

返回示例:

{
  "traceIds": ["trace-123", "trace-456"],
  "totalCount": 50
}

4. query_by_trace_id

根据 traceId 查询详细日志。

参数:

• accountName (string, required): 账户名称
• logstore (string, required): Logstore 名称
• traceId (string, required): TraceId
• timeRange (object, required): 时间范围（必需）
  • from (string, required): 开始时间，必须使用格式 "YYYY-MM-DD HH:mm:ss" (例如 "2025-11-01 12:00:00")
  • to (string, required): 结束时间，必须使用格式 "YYYY-MM-DD HH:mm:ss" (例如 "2025-11-01 13:00:00")
  • 时间范围不能超过 7 天
• limit (number, optional): 返回结果数量限制，默认 1000

返回示例:

{
  "logs": [
    {
      "traceId": "trace-123",
      "level": "ERROR",
      "message": "Something went wrong",
      "__time__": 1234567890
    }
  ],
  "totalCount": 10
}

使用示例

在 MCP 客户端中使用

1. 配置 MCP 客户端（如 Cursor、Claude Desktop）连接到该服务
2. 使用 MCP 工具查询日志

典型工作流程

1. 查询 traceId:

   使用 query_trace_ids 工具，传入关键词

2. 查询详细日志:

   使用 query_by_trace_id 工具，传入上一步获取的 traceId

查询语法

支持阿里云 SLS 的完整查询语法：

关键词查询 (query_trace_ids)

• 简单关键词: error
• 多关键词AND: error 787128 (相当于 error AND 787128)
• 逻辑运算: error OR 787128, error AND 787128, NOT error
• 精确短语: "exact phrase"
• 字段查询: level:error, message:"user login"

关键词将直接透传给 SLS，不做任何处理，用户可以完全控制查询语法。

TraceId 查询 (query_by_trace_id)

• 自动构建字段查询：traceId:xxx
• 如果 traceId 包含特殊字符，会使用引号包围

字段过滤配置

为了减少返回数据量，支持两种字段过滤模式：

1. 白名单模式（returnFields）

只返回指定的字段。

2. 黑名单模式（excludeFields）

排除指定的字段，返回其他所有字段。

配置优先级

支持三级配置，优先级从高到低：

1. Logstore 级别（最高优先级）
2. 账户级别
3. 全局级别（最低优先级）

配置示例

示例 1：只排除系统字段（推荐）

{
  "accounts": [
    {
      "name": "prod",
      "logstores": ["pd-suishiwen"],
      "excludeFields": ["__tag__:*"]
    }
  ]
}

效果：返回除 __tag__ 开头的所有字段。

示例 2：只返回关键字段

{
  "accounts": [
    {
      "name": "prod",
      "returnFields": ["level", "message", "trace_id", "__time__"]
    }
  ]
}

效果：只返回这 4 个字段。

示例 3：组合使用（先白名单后黑名单）

{
  "accounts": [
    {
      "name": "prod",
      "returnFields": ["*"],
      "excludeFields": ["__tag__:*", "__source__"]
    }
  ]
}

效果：返回所有字段，但排除 __tag__ 开头的字段和 __source__ 字段。

示例 4：多级配置

{
  "excludeFields": ["__tag__:*"],
  "accounts": [
    {
      "name": "prod",
      "excludeFields": ["__tag__:*", "__source__"],
      "logstores": [
        "app-logs",
        {
          "name": "error-logs",
          "excludeFields": ["__tag__:*", "__source__", "__topic__"]
        }
      ]
    }
  ]
}

通配符支持

支持使用通配符匹配字段名：

• __tag__:* - 匹配所有以 __tag__ 开头的字段
• __* - 匹配所有以 __ 开头的系统字段
• *__tag__* - 匹配包含 __tag__ 的字段

过滤规则

1. 如果只配置了 returnFields：只返回白名单字段
2. 如果只配置了 excludeFields：返回除黑名单外的所有字段
3. 如果两者都配置：先应用白名单，再从结果中排除黑名单
4. 如果都未配置：返回所有字段

注意事项

• 如果配置的字段在日志中不存在，该字段不会被返回（白名单）或不会被排除（黑名单）
• 字段过滤在应用层进行，不影响阿里云日志服务的查询性能
• 阿里云日志服务本身不支持字段过滤，需要在应用层处理

注意事项

1. 确保配置文件中的 AccessKey 具有足够的权限访问日志服务
2. traceId 字段需要在日志服务中配置字段索引
3. 时间范围是必需参数，必须提供 timeRange.from 和 timeRange.to
4. 时间范围不能超过 7 天
5. 配置文件路径：~/.alilogmcp/config.json
6. 字段过滤可以减少返回数据量，提升处理效率

时间格式说明

时间范围是必需参数，且必须严格遵守 YYYY-MM-DD HH:mm:ss 格式。

正确示例

• "2025-11-01 12:00:00"
• Unix 时间戳（秒/毫秒）：1704067200

错误示例（不再支持）

• 1h ago
• now
• 2025/11/01
• 2025-11-01T12:00:00

配置示例：

{
  "timeRange": {
    "from": "2025-11-01 10:00:00",
    "to": "2025-11-01 11:00:00"
  }
}

开发

# 安装依赖
npm install

# 开发模式运行
npm run dev

# 构建
npm run build

调试

方法 1: 直接测试工具函数（推荐）

不通过 MCP 协议，直接调用工具函数进行测试，适合快速调试：

# 列出所有账户
npm run test:debug list-accounts

# 列出指定账户的 Logstore
npm run test:debug list-logstores prod

# 根据关键词查询 traceId
npm run test:debug query-trace-ids prod app-logs error

# 根据 traceId 查询日志
npm run test:debug query-by-trace-id prod app-logs trace-123

# 指定时间范围查询
npm run test:debug query-trace-ids prod app-logs error 1704067200 1704070800

# 启用详细调试日志
DEBUG=true npm run test:debug query-trace-ids prod app-logs error

# 查看帮助
npm run test:debug help

方法 2: 测试 MCP 协议通信

模拟 MCP 客户端与服务器通信，测试 MCP 协议是否正常：

npm run test:mcp

方法 3: 启用调试模式运行 MCP 服务

在运行 MCP 服务时启用调试日志：

DEBUG=true npm run dev
# 或
DEBUG=true npx alilogmcp

调试日志会输出到 stderr，不会影响 MCP 协议的通信（MCP 协议使用 stdout）。

License

MIT