Servidor MCP de Observabilidad de Alibaba Cloud (Versión Go)

📌 Nota importante

Este proyecto ha sido reescrito en lenguaje Go. Si necesita utilizar la versión original en Python, visite el directorio v1:

• 📖 v1/README.md - Documentación de la versión en Python

• 📦 La versión en Python se instala mediante pip install mcp-server-aliyun-observability

Implementación en lenguaje Go del servidor MCP de observabilidad de Alibaba Cloud, que proporciona a los modelos de IA capacidades de acceso a datos estructurados para Alibaba Cloud Log Service (SLS) y CloudMonitor (CMS). Basado en el protocolo Model Context Protocol, se integra perfectamente con herramientas de IA como Cursor, Kiro, Cline, Windsurf, entre otras.

Características

• Soporta tres modos de transporte: stdio, SSE y streamable-http

• Arquitectura de conjunto de herramientas modular: PaaS (CloudMonitor 2.0), IaaS (acceso directo a SLS/CMS), Shared

• Análisis flexible de expresiones de tiempo: tiempo relativo, marcas de tiempo absolutas, estilo Grafana, palabras clave preestablecidas

• Análisis comparativo de datos de series temporales: cálculos estadísticos, análisis de tendencias, puntuación de diferencias

• Manejo estructurado de errores: descripciones de errores en inglés y sugerencias de solución

• Garantía de estabilidad: reintentos (retroceso exponencial), disyuntores, apagado elegante

• Registro JSON estructurado (slog)

• Binario único, sin dependencias en tiempo de ejecución

Related MCP server: Alibaba Cloud RDS OpenAPI MCP Server

Inicio rápido

Descarga e instalación

Descargue el binario correspondiente a su plataforma desde la página de Releases:

# Linux amd64
wget https://github.com/aliyun/alibabacloud-observability-mcp-server/releases/latest/download/alibabacloud-observability-mcp-server-linux-amd64.tar.gz
tar -xzf alibabacloud-observability-mcp-server-linux-amd64.tar.gz

# macOS arm64 (M1/M2)
wget https://github.com/aliyun/alibabacloud-observability-mcp-server/releases/latest/download/alibabacloud-observability-mcp-server-darwin-arm64.tar.gz
tar -xzf alibabacloud-observability-mcp-server-darwin-arm64.tar.gz

Tras descomprimir, incluye:

• alibabacloud-observability-mcp-server - Archivo ejecutable

• config.yaml - Archivo de configuración predeterminado

Configuración de credenciales

# 设置阿里云 AccessKey
export ALIBABA_CLOUD_ACCESS_KEY_ID=<your_access_key_id>
export ALIBABA_CLOUD_ACCESS_KEY_SECRET=<your_access_key_secret>

Cómo obtener la AccessKey: Gestión de AccessKey de Alibaba Cloud

Iniciar el servicio

# 以 stdio 模式启动（MCP 客户端直接调用）
./alibabacloud-observability-mcp-server start --stdio

# 以网络模式启动（默认 transport 在 config.yaml 中配置）
./alibabacloud-observability-mcp-server start --config config.yaml

Comandos CLI

# 查看版本信息
./alibabacloud-observability-mcp-server version

# 列出所有已注册工具
./alibabacloud-observability-mcp-server tools

Construcción desde el código fuente

Requisitos previos

• Go 1.23+

Construcción

# 克隆仓库
git clone https://github.com/aliyun/alibabacloud-observability-mcp-server.git
cd alibabacloud-observability-mcp-server

# 构建当前平台
make build

# 构建所有平台（linux/darwin/windows × amd64/arm64）
make build-all

El binario generado se encuentra en el directorio bin/.

Configuración

La configuración adopta una estructura de dos niveles:

1. config.yaml - Configuración del servidor (modo de transporte, registros, red, etc.)

2. Archivo .env o variables de entorno - Credenciales y parámetros de tiempo de ejecución

Archivo de configuración

cp config.yaml config.yaml.bak       # 备份默认配置（可选）
cp .env.example .env                  # 凭证（AccessKey）

Ruta de búsqueda de config.yaml: directorio actual → ./config/

El archivo .env se carga desde el directorio actual, adecuado para almacenar información de credenciales que no debe enviarse al control de versiones.

Estructura de config.yaml

# 服务器配置
server:
  transport: streamable-http  # stdio, sse, streamable-http
  host: "0.0.0.0"
  port: 8080

# 日志配置
logging:
  level: info                 # debug, info, warn, error
  debug_mode: false

# 工具集配置
toolkit:
  scope: all                  # all, paas, iaas
  # 精细化工具选择（可选，非空时仅注册列表中的工具）
  # enabled_tools:
  #   - list_workspace
  #   - umodel_get_entities
  #   - sls_execute_sql

# 网络配置
network:
  max_retry: 1
  retry_wait_seconds: 1
  read_timeout_ms: 610000
  connect_timeout_ms: 30000

# 本地化配置
locale:
  timezone: Asia/Shanghai
  language: zh-CN

# 运行时默认值（可选）
# 优先级: 环境变量 > .env 文件 > config.yaml
runtime:
  region: cn-hangzhou
  # workspace: ""

# 端点覆盖（可选，用于内网访问）
# endpoints:
#   sls:
#     cn-hongkong: "cn-hongkong-intranet.log.aliyuncs.com"
#   cms:
#     cn-hongkong: "cms.cn-hongkong.aliyuncs.com"

Selección detallada de herramientas

De forma predeterminada, toolkit.scope controla la habilitación de herramientas por categoría (all/paas/iaas). Si necesita un control más granular, puede usar toolkit.enabled_tools para especificar la lista de herramientas que desea habilitar:

toolkit:
  scope: all
  enabled_tools:
    - list_workspace
    - list_domains
    - umodel_get_entities
    - umodel_get_metrics
    - sls_execute_sql

Cuando enabled_tools no está vacío, solo se registrarán las herramientas de la lista; el resto no estará disponible. scope sigue determinando qué módulos de toolkit se cargan, y enabled_tools filtra aún más sobre esta base.

Para obtener la lista completa de herramientas y explicaciones de clasificación, consulte la plantilla de comentarios en config.yaml.

Parámetros CLI

Variables de entorno (credenciales y parámetros de tiempo de ejecución)

* Cuando no se configura una AccessKey, el servicio utilizará automáticamente la cadena de credenciales predeterminada para obtener credenciales (admite ECS RAM Role, OIDC, archivos de configuración, etc.). En entornos de nube como ECS o Function Compute, no es necesario configurar manualmente la AccessKey.

Prioridad de resolución de credenciales: Parámetros CLI / archivo .env > variables de entorno del shell > cadena de credenciales predeterminada.

💡 Relleno automático de valores predeterminados

Cuando se establecen ALIBABA_CLOUD_REGION o ALIBABA_CLOUD_WORKSPACE, si no se proporcionan los parámetros regionId o workspace en la llamada a la herramienta, el servicio utilizará automáticamente los valores de las variables de entorno como valores predeterminados. Los valores pasados explícitamente por el usuario no serán sobrescritos.

Integración con herramientas de IA

Cursor / Kiro / Cline

Modo streamable-http (recomendado):

1. Configure config.yaml (establezca server.transport: streamable-http)

2. Inicie el servicio:

./bin/alibabacloud-observability-mcp-server start

3. Configure mcp.json:

{
  "mcpServers": {
    "alibaba_cloud_observability": {
      "url": "http://localhost:8080"
    }
  }
}

Modo stdio:

1. Configure mcp.json:

{
  "mcpServers": {
    "alibaba_cloud_observability": {
      "command": "./bin/alibabacloud-observability-mcp-server",
      "args": ["start", "--stdio"],
      "env": {
        "ALIBABA_CLOUD_ACCESS_KEY_ID": "<your_access_key_id>",
        "ALIBABA_CLOUD_ACCESS_KEY_SECRET": "<your_access_key_secret>"
      }
    }
  }
}

Nota: En el modo stdio, si config.yaml no existe, se utilizarán los valores predeterminados integrados.

Conjunto de herramientas

Un total de 33 herramientas, divididas en tres niveles.

Conjunto de herramientas PaaS (CloudMonitor 2.0, recomendado)

Basado en un modelo de datos unificado, los nombres de las herramientas tienen el prefijo umodel_ o cms_. Un total de 16 herramientas.

Herramientas de gestión de entidades

Herramientas de gestión de conjuntos de datos

Herramientas de consulta de datos

Conjunto de herramientas IaaS (acceso directo a SLS/CMS)

Acceso directo a la API subyacente, los nombres de las herramientas tienen el prefijo sls_ o cms_. Un total de 14 herramientas.

Herramientas SLS

Herramientas CMS

Conjunto de herramientas Shared

Un total de 3 herramientas.

Expresiones de tiempo

Todas las herramientas de consulta de datos admiten formatos de rango de tiempo flexibles:

Funciones avanzadas

Análisis comparativo de series temporales

umodel_get_metrics y umodel_get_golden_metrics admiten la comparación de series temporales a través del parámetro offset:

# 对比当前1小时与1天前的数据
umodel_get_metrics(
    domain="apm", entity_set_name="apm.service",
    metric_domain_name="apm.metric.apm.service", metric="request_count",
    time_range="last_1h", offset="1d"
)

Los resultados devueltos incluyen:

• current: Estadísticas del período actual (max, min, avg, count)

• compare: Estadísticas del período de comparación

• diff: Análisis de cambios (trend, avg_change, avg_change_percent)

• diff_score: Puntuación de diferencia (0-1, cuanto mayor sea, más significativa es la diferencia)

Modos de análisis avanzado

umodel_get_metrics admite cuatro modos de análisis:

Estructura del proyecto

├── cmd/server/          # CLI 入口（cobra）
├── pkg/
│   ├── client/          # SLS/CMS 客户端封装
│   ├── config/          # 配置管理（viper + sync.Once）
│   ├── endpoint/        # 端点解析
│   ├── errors/          # 结构化错误与错误码映射
│   ├── logger/          # 结构化日志（slog）
│   ├── server/          # MCP Server 核心（传输层、生命周期、健康检查）
│   ├── stability/       # 重试与熔断器
│   ├── timeparse/       # 时间表达式解析
│   └── toolkit/         # 工具集接口与注册中心
│       ├── paas/        # PaaS 工具集（umodel_*、cms_natural_language_query）
│       ├── iaas/        # IaaS 工具集（sls_*、cms_execute_promql、cms_text_to_promql）
│       └── shared/      # Shared 工具集（list_workspace、list_domains、introduction）
├── v1/                  # Python 版本（历史参考）
├── Makefile
├── go.mod
└── go.sum

Desarrollo

# 构建
make build

# 运行测试
make test

# 代码检查
make lint

# 清理构建产物
make clean

Pruebas

El proyecto adopta una estrategia de tres vías: pruebas unitarias + pruebas de propiedades + pruebas de regresión:

• Pruebas unitarias: pruebas basadas en tablas, que cubren ejemplos específicos y condiciones de contorno

• Pruebas de propiedades: uso de gopter para verificar propiedades de corrección general en todas las entradas

• Pruebas de regresión: pruebas de integración (//go:build integration), comparando la consistencia de los parámetros con la versión de Python, requiere credenciales reales de Alibaba Cloud

# 运行所有单元测试
go test ./... -v

# 仅运行属性测试
go test ./... -run TestProperty_

# 运行回归测试（需要配置环境变量）
ALIBABA_CLOUD_ACCESS_KEY_ID=xxx \
ALIBABA_CLOUD_ACCESS_KEY_SECRET=xxx \
ALIBABA_CLOUD_REGION=cn-hongkong \
ALIBABA_CLOUD_WORKSPACE=xxx \
go test -tags=integration ./pkg/toolkit/... -v

Especificaciones de desarrollo de agentes de IA

Consulte docs/AGENTS.md, que incluye explicaciones de la estructura del proyecto, convenciones de estilo de código, procesos para agregar nuevas herramientas, especificaciones de prueba, etc.

Requisitos de permisos

Para garantizar que el servidor MCP pueda acceder y operar con éxito sus recursos de observabilidad de Alibaba Cloud, debe configurar los siguientes permisos:

Clave de acceso de Alibaba Cloud (AccessKey)

• El servicio requiere credenciales válidas de Alibaba Cloud para ejecutarse, admitiendo los siguientes métodos (ordenados por prioridad):

  1. AccessKey ID + AccessKey Secret (pasado a través del archivo .env, variables de entorno o parámetros CLI)

  2. Credenciales temporales STS (establecer la variable de entorno ALIBABA_CLOUD_SECURITY_TOKEN)

  3. Descubrimiento automático de la cadena de credenciales predeterminada (ECS RAM Role, OIDC, archivos de configuración de credenciales, etc.)

• Para obtener y gestionar AccessKey, consulte la documentación oficial de gestión de AccessKey de Alibaba Cloud

Autorización RAM

El usuario o rol RAM asociado con la AccessKey debe tener los permisos necesarios para acceder a los servicios en la nube relacionados.

Se recomienda encarecidamente seguir el "principio de menor privilegio": otorgue solo el conjunto mínimo de permisos necesarios para ejecutar las herramientas MCP que planea utilizar.

Según las herramientas que necesite utilizar, consulte la siguiente documentación para la configuración de permisos:

Explicación de permisos especiales:

• El uso de herramientas de generación de SQL (como sls_text_to_sql) requiere la concesión por separado del permiso sls:CallAiTools

• El uso de la función de consulta en lenguaje natural (cms_natural_language_query) requiere la concesión de: cms:CreateChat, cms:CreateThread, cms:GetThread, cms:ListThreads

Recomendaciones de seguridad

• El servicio no almacena AccessKey, solo se utiliza en tiempo de ejecución para llamadas a la API

• En el modo SSE/HTTP, asegúrese de implementar su propio control de acceso en el punto de entrada

• Se recomienda desplegar en una red interna o dentro de una VPC para evitar la exposición directa a la red pública

• Nunca exponga un punto final de servicio configurado con AccessKey a la red pública sin autenticación

• Se recomienda utilizar Alibaba Cloud Function Compute (FC) para el despliegue y configurarlo para acceso solo dentro de la VPC

Licencia

Este proyecto sigue el mismo acuerdo de licencia que la versión original en Python.