Alibaba Cloud Observability MCP Server (версия на Go)

📌 Важное примечание

Этот проект был переписан на языке Go. Если вам нужна оригинальная версия на Python, пожалуйста, перейдите в каталог v1:

• 📖 v1/README.md — документация версии на Python

• 📦 Версия на Python устанавливается через pip install mcp-server-aliyun-observability

Реализация Alibaba Cloud Observability MCP Server на языке Go предоставляет AI-моделям возможности структурированного доступа к данным Alibaba Cloud Log Service (SLS) и Cloud Monitor (CMS). Основан на протоколе Model Context Protocol и может быть бесшовно интегрирован с такими AI-инструментами, как Cursor, Kiro, Cline, Windsurf и другими.

Характеристики

• Поддержка трех режимов передачи: stdio, SSE, streamable-http

• Модульная архитектура набора инструментов: PaaS (Cloud Monitor 2.0), IaaS (прямой доступ к SLS/CMS), Shared

• Гибкий парсинг временных выражений: относительное время, абсолютные метки времени, стиль Grafana, предустановленные ключевые слова

• Сравнительный анализ временных рядов: статистические вычисления, анализ трендов, оценка различий

• Структурированная обработка ошибок: описания ошибок на английском языке и рекомендации по их устранению

• Обеспечение стабильности: повторные попытки (экспоненциальная задержка), автоматический выключатель (circuit breaker), корректное завершение работы

• Структурированные JSON-логи (slog)

• Единый бинарный файл, отсутствие зависимостей среды выполнения

Related MCP server: Alibaba Cloud RDS OpenAPI MCP Server

Быстрый старт

Загрузка и установка

Загрузите бинарный файл для вашей платформы со страницы 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

После распаковки вы получите:

• alibabacloud-observability-mcp-server — исполняемый файл

• config.yaml — файл конфигурации по умолчанию

Настройка учетных данных

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

Как получить AccessKey: Управление AccessKey в Alibaba Cloud

Запуск службы

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

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

CLI команды

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

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

Сборка из исходного кода

Предварительные требования

• Go 1.23+

Сборка

# 克隆仓库
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

Сгенерированный бинарный файл находится в каталоге bin/.

Конфигурация

Конфигурация имеет двухуровневую структуру:

1. config.yaml — конфигурация сервера (режим передачи, логи, сеть и т.д.)

2. Файл .env или переменные окружения — учетные данные и параметры среды выполнения

Файл конфигурации

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

Путь поиска config.yaml: текущий каталог → ./config/

Файл .env загружается из текущего каталога и подходит для хранения учетных данных, которые не следует добавлять в систему контроля версий.

Структура 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"

Выборочное использование инструментов

По умолчанию toolkit.scope управляет включением инструментов по категориям (all/paas/iaas). Если требуется более тонкая настройка, можно использовать toolkit.enabled_tools для указания списка инструментов, которые необходимо включить:

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

Когда enabled_tools не пуст, будут зарегистрированы только инструменты из списка, остальные будут недоступны. scope по-прежнему определяет, какие модули набора инструментов загружаются, а enabled_tools дополнительно фильтрует их на этой основе.

Полный список инструментов и описание категорий см. в шаблоне комментариев в config.yaml.

Параметры CLI

Переменные окружения (учетные данные и параметры среды выполнения)

• Если AccessKey не настроен, служба автоматически использует цепочку учетных данных по умолчанию (поддерживаются ECS RAM Role, OIDC, файлы конфигурации и т.д.). В облачных средах, таких как ECS или Function Compute, вручную настраивать AccessKey не требуется.

Приоритет разрешения учетных данных: параметры CLI / файл .env > переменные окружения оболочки > цепочка учетных данных по умолчанию.

💡 Автоматическое заполнение значений по умолчанию

Если установлены ALIBABA_CLOUD_REGION или ALIBABA_CLOUD_WORKSPACE, и при вызове инструмента не предоставлены параметры regionId или workspace, служба автоматически использует значения из переменных окружения. Явно переданные пользователем значения не будут перезаписаны.

Интеграция с AI-инструментами

Cursor / Kiro / Cline

Режим streamable-http (рекомендуется):

1. Настройте config.yaml (установите server.transport: streamable-http)

2. Запустите службу:

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

3. Настройте mcp.json:

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

Режим stdio:

1. Настройте 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>"
      }
    }
  }
}

Примечание: в режиме stdio, если config.yaml отсутствует, будут использованы встроенные значения по умолчанию.

Наборы инструментов

Всего 33 инструмента, разделенных на три уровня.

Набор инструментов PaaS (Cloud Monitor 2.0, рекомендуется)

Основан на унифицированной модели данных, имена инструментов имеют префикс umodel_ или cms_. Всего 16 инструментов.

Инструменты управления сущностями

Инструменты управления наборами данных

Инструменты запроса данных

Набор инструментов IaaS (прямой доступ к SLS/CMS)

Прямой доступ к базовым API, имена инструментов имеют префикс sls_ или cms_. Всего 14 инструментов.

Инструменты SLS

Инструменты CMS

Набор инструментов Shared

Всего 3 инструмента.

Временные выражения

Все инструменты запроса данных поддерживают гибкие форматы временных диапазонов:

Расширенные функции

Сравнительный анализ временных рядов

umodel_get_metrics и umodel_get_golden_metrics поддерживают сравнение временных рядов через параметр 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"
)

Результат содержит:

• current: статистика текущего периода (max, min, avg, count)

• compare: статистика сравниваемого периода

• diff: анализ изменений (trend, avg_change, avg_change_percent)

• diff_score: оценка различий (0-1, чем больше, тем значительнее разница)

Режимы расширенного анализа

umodel_get_metrics поддерживает четыре режима анализа:

Структура проекта

├── 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

Разработка

# 构建
make build

# 运行测试
make test

# 代码检查
make lint

# 清理构建产物
make clean

Тестирование

Проект использует стратегию трех уровней: модульное тестирование + тестирование свойств + регрессионное тестирование:

• Модульное тестирование: табличное тестирование, покрытие конкретных примеров и граничных условий

• Тестирование свойств: использование gopter для проверки общих свойств корректности для всех входных данных

• Регрессионное тестирование: интеграционное тестирование (//go:build integration), сравнение согласованности параметров с версией на Python, требуются реальные учетные данные 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

Стандарты разработки AI-агентов

См. docs/AGENTS.md, включая описание структуры проекта, соглашения о стиле кода, процесс добавления новых инструментов, стандарты тестирования и т.д.

Требования к правам доступа

Чтобы MCP Server мог успешно получать доступ к вашим ресурсам наблюдаемости Alibaba Cloud и управлять ими, необходимо настроить следующие права:

Ключ доступа Alibaba Cloud (AccessKey)

• Для работы службы требуются действительные учетные данные Alibaba Cloud, поддерживаются следующие способы (в порядке приоритета):

  1. AccessKey ID + AccessKey Secret (передаются через файл .env, переменные окружения или параметры CLI)

  2. Временные учетные данные STS (установка переменной окружения ALIBABA_CLOUD_SECURITY_TOKEN)

  3. Автоматическое обнаружение цепочки учетных данных по умолчанию (ECS RAM Role, OIDC, файлы конфигурации учетных данных и т.д.)

• Для получения и управления AccessKey см. официальную документацию по управлению AccessKey в Alibaba Cloud

Авторизация RAM

Пользователь или роль RAM, связанные с AccessKey, должны иметь права, необходимые для доступа к соответствующим облачным службам.

Настоятельно рекомендуется следовать «принципу минимальных привилегий»: предоставляйте только минимально необходимый набор прав для запуска инструментов MCP, которые вы планируете использовать.

В зависимости от инструментов, которые вы собираетесь использовать, обратитесь к следующей документации для настройки прав:

Описание специальных прав:

• Использование инструментов генерации SQL (например, sls_text_to_sql) требует отдельного предоставления права sls:CallAiTools

• Использование функции запроса на естественном языке (cms_natural_language_query) требует предоставления прав: cms:CreateChat, cms:CreateThread, cms:GetThread, cms:ListThreads

Рекомендации по безопасности

• Служба не хранит AccessKey, они используются только во время выполнения для вызовов API

• В режиме SSE/HTTP обязательно обеспечьте контроль доступа к точке входа

• Рекомендуется развертывание во внутренней сети или VPC, избегайте прямого доступа из публичной сети

• Никогда не выставляйте конечную точку сервера с настроенным AccessKey в публичную сеть без аутентификации

• Рекомендуется использовать Alibaba Cloud Function Compute (FC) для развертывания с настройкой доступа только внутри VPC

Лицензия

Данный проект следует той же лицензии, что и оригинальная версия на Python.