@seaxlab/aliyun-mcp

阿里云可观测 MCP Server（Node.js，Streamable HTTP），提供 SLS 日志查询与 ARMS 调用链分析两大模块。

工具列表

SLS 模块（@alicloud/sls20201230）

| 工具 | 说明 | | --- | --- | | sls_query_logs | 查询应用日志。支持 TID/traceId 链路日志、服务名（serviceId）、关键字、接口路径、日志级别、时间范围、分页（nextPage） | | sls_get_context_logs | 查询某条日志前后的上下文；先用 sls_query_logs 的 includeContextMeta=true 获取 packId 和 packMeta，默认前后各 50 条 | | sls_execute_sql | 执行 SLS 查询分析语句（<检索> \| SELECT ...），用于统计聚合、慢请求分析、错误分布等，返回结构化行列（默认最多返回 100 行，超出截断） | | sls_list_services | 聚合日志中出现过的服务（serviceId），支持关键字过滤；本地列表只增不减，本地未命中时自动查询 SLS 并回填，空结果不缓存 | | sls_get_histograms | 查询日志随时间的数量分布，判断报错突增和故障起点 |

查询条件由服务端拼接：tid → TID: "..."，serviceIds → (serviceId: "a" or serviceId: "b")，keywords/path → message: "..."，条件之间 and 连接。字段名可通过 [sls.fields] 适配不同索引结构。

ARMS 模块（@alicloud/arms20190808）

| 工具 | 说明 | | --- | --- | | arms_trace_analysis | 按 TID/traceId 查询调用链并做耗时路径分析：span 树、服务耗时占比（serviceCosts）、关键耗时路径（criticalPath）、自身耗时 Top 榜（slowestSpans）、疑似错误 span | | arms_search_traces | 按服务名、接口名、最小耗时（慢调用）、是否错误搜索调用链，返回 traceID 列表 | | arms_list_trace_apps | 查询接入 ARMS 的应用列表（appName/pid） |

耗时热点看 selfDurationMs（去掉子调用后的自身耗时）。GetTrace 返回的平铺 span 会按 parentSpanId 组装成树；ARMS 的 resultCode: "-1" 表示无状态码，不判为错误。

SLS 的 TID 与 ARMS 的 traceId 是同一体系（已实测确认），两个模块用同一个 tid 双向关联：

• 慢调用排查：arms_search_traces 找慢调用拿到 traceID → arms_trace_analysis 定位耗时热点 → sls_query_logs 按同一 tid 查日志明细
• 日志排查：sls_query_logs 从报错日志拿到 TID → arms_trace_analysis 分析该请求的完整调用链和耗时路径

查询示例

13 个工具调用示例（TID 链路、上下文日志、慢调用、SQL 统计等）和组合排查套路见 查询示例。

快速开始

npm install
cp config.example.toml config.toml   # 填入 AK 和环境映射
chmod 600 config.toml                # 文件含明文 AccessKey Secret
npm run build && node dist/index.js serve --config config.toml

• MCP endpoint：http://127.0.0.1:9020/mcp（Streamable HTTP，无状态）
• 健康检查：GET /health

服务端不维护会话：响应不下发 Mcp-Session-Id，每个 POST /mcp 独立处理，请求间无共享状态，多副本部署不需要会话粘连。除 POST 外的方法统一返回 405，其中包括用于通知流的 GET 和用于终止会话的 DELETE（本服务只提供请求-响应型工具，无服务端主动推送）；携带跨站 Origin 的请求由 DNS 重绑定防护返回 403。

基于 MCP TypeScript SDK v2（@modelcontextprotocol/server），同一端点同时服务两个协议版本：2026-07-28（协议本身按请求无会话）与 2025 系列客户端（走 SDK 默认的 legacy: "stateless" 兼容路径）。客户端无需为此调整配置。

随 v2 一并升级到 zod 4 后，工具的 inputSchema 不再输出 additionalProperties: false。服务端行为不变，未声明的入参仍会被剥离；仅 JSON Schema 层面少了这条约束提示。

MCP 客户端配置示例：

{
  "mcpServers": {
    "aliyun-mcp": {
      "type": "streamable-http",
      "url": "http://127.0.0.1:9020/mcp"
    }
  }
}

配置

全部配置来自一个 TOML 文件，完整样例见 config.example.toml。路径通过 --config 或 ALIYUN_MCP_CONFIG 指定，两者都未提供时拒绝启动：

aliyun-mcp serve --config ~/.config/aliyun-mcp/config.toml
# 或
ALIYUN_MCP_CONFIG=~/.config/aliyun-mcp/config.toml aliyun-mcp serve

要点：

• [aliyun]：access_key_id / access_key_secret / region 为 SLS 和 ARMS 共享；如需分开，在 [sls.credentials] / [arms.credentials] 中覆盖。RAM 授权需要 SLS 读权限和 AliyunARMSReadOnlyAccess。
• [sls.environments.<名称>]：环境名到 project/logstore 的映射，例如 [sls.environments.prd] 下配 project_name / logstore_name；工具也支持直接传 projectName + logstoreName。sls.default_environment 省略时取第一个环境。
• [sls.fields]：查询语句使用的索引字段名，默认 TID/serviceId/level/message。
• [sls] 查询保护：默认查询窗口、最大窗口、TID 查询窗口（默认 7 天）、SQL 最大窗口（默认 1 天）等均可配置。
• sls.region / arms.region 省略时继承 aliyun.region；两个 endpoint 省略时分别按 ${region}.log.aliyuncs.com 和 arms.${region}.aliyuncs.com 派生。

配置文件不存在、TOML 语法错误、出现未知键或字段缺失时，服务以 ALIYUN_CONFIG_INVALID 前缀报错并拒绝启动。文件含明文 AccessKey Secret，若对同组或其他用户可读，启动时会打印提示但不阻断。

从 1.x 升级

2.0 起配置只从 TOML 读取，.env 和全部 ALIYUN_* 环境变量（ALIYUN_MCP_CONFIG 除外）不再生效，dotenv 依赖已移除。按 config.example.toml 重写配置即可，注意三处结构变化：

• ALIYUN_SLS_ENVIRONMENTS 的 JSON 字符串改为 [sls.environments.<名称>] 表，字段名由 projectName / logstoreName 改为 project_name / logstore_name；
• ALIYUN_SLS_RETURN_FIELDS 的逗号分隔字符串改为 return_fields 数组；
• ALIYUN_SLS_* / ALIYUN_ARMS_* 前缀改为 [sls] / [arms] 段，键名去掉前缀并转为 snake_case。

未指定配置文件路径且检测到残留的 1.x 环境变量时，启动错误会附带迁移提示。

项目结构

src/
├── index.ts                  # CLI 入口（serve）
├── server/                   # Streamable HTTP（无状态）+ /health
├── shared/
│   ├── config/app-config.ts  # TOML 配置加载与校验
│   ├── logger/logger.ts      # JSON 日志（自动脱敏）
│   └── errors/errors.ts      # McpToolError / 安全错误输出
└── modules/
    ├── types.ts              # 模块契约（registerTools / healthCheck）
    ├── sls/                  # SLS 客户端、查询服务、工具注册
    └── arms/                 # ARMS 客户端、调用链分析、工具注册

新增模块时实现 AliyunMcpModule 并加入 modules/index.ts 即可，不影响 HTTP 层。

参考文档

SLS（日志服务）

• SDK（npm）：@alicloud/sls20201230
• API 总览：SLS OpenAPI（2020-12-30）
• 本项目用到的 API：GetLogsV2（日志查询与 SQL 分析）、GetHistograms（日志分布）
• 查询/分析语法：查询语法概述、分析语法（SQL）概述

ARMS（应用实时监控）

• SDK（npm）：@alicloud/arms20190808
• API 总览：ARMS OpenAPI（2019-08-08）
• 本项目用到的 API：GetTrace（调用链详情）、SearchTracesByPage（调用链搜索，支持 MinDuration/IsError）、SearchTraceAppByPage（应用列表）