Alibaba Cloud Observability MCP Server (Go-Version)

📌 Wichtiger Hinweis

Dieses Projekt wurde mit Go neu implementiert. Wenn Sie die ursprüngliche Python-Version verwenden möchten, besuchen Sie bitte das Verzeichnis v1:

• 📖 v1/README.md - Dokumentation der Python-Version

• 📦 Die Python-Version kann über pip install mcp-server-aliyun-observability installiert werden

Die Go-Implementierung des Alibaba Cloud Observability MCP Servers bietet KI-Modellen Zugriff auf strukturierte Daten des Alibaba Cloud Log Service (SLS) und Cloud Monitor (CMS). Basierend auf dem Model Context Protocol lässt es sich nahtlos in KI-Tools wie Cursor, Kiro, Cline, Windsurf usw. integrieren.

Funktionen

• Unterstützt drei Übertragungsmodi: stdio, SSE, streamable-http

• Modulare Toolset-Architektur: PaaS (Cloud Monitor 2.0), IaaS (direkter Zugriff auf SLS/CMS), Shared

• Flexible Analyse von Zeitausdrücken: relative Zeit, absolute Zeitstempel, Grafana-Stil, vordefinierte Schlüsselwörter

• Analyse von Zeitreihendaten: statistische Berechnungen, Trendanalysen, Differenzbewertung

• Strukturierte Fehlerbehandlung: englische Fehlerbeschreibungen und Lösungsvorschläge

• Stabilitätsgarantie: Wiederholungsversuche (exponentielles Backoff), Circuit Breaker, geordnetes Herunterfahren

• Strukturierte JSON-Protokollierung (slog)

• Einzelne Binärdatei, keine Laufzeitabhängigkeiten

Related MCP server: Alibaba Cloud RDS OpenAPI MCP Server

Schnellstart

Download und Installation

Laden Sie die Binärdatei für die entsprechende Plattform von der Releases-Seite herunter:

# 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

Nach dem Entpacken sind enthalten:

• alibabacloud-observability-mcp-server - Ausführbare Datei

• config.yaml - Standardkonfigurationsdatei

Anmeldedaten konfigurieren

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

So erhalten Sie den AccessKey: Alibaba Cloud AccessKey Management

Dienst starten

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

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

CLI-Befehle

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

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

Aus Quellcode erstellen

Voraussetzungen

• Go 1.23+

Erstellen

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

Die erstellte Binärdatei befindet sich im Verzeichnis bin/.

Konfiguration

Die Konfiguration verwendet eine zweistufige Struktur:

1. config.yaml - Serverkonfiguration (Übertragungsmodus, Protokollierung, Netzwerk usw.)

2. .env-Datei oder Umgebungsvariablen - Anmeldedaten und Laufzeitparameter

Konfigurationsdatei

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

Suchpfad für config.yaml: aktuelles Verzeichnis → ./config/

Die .env-Datei wird aus dem aktuellen Verzeichnis geladen und eignet sich zum Speichern von Anmeldedaten, die nicht in die Versionskontrolle eingecheckt werden sollten.

Struktur von 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"

Feinabstimmung der Tool-Auswahl

Standardmäßig steuert toolkit.scope die Aktivierung von Tools nach Kategorie (all/paas/iaas). Wenn eine feinere Steuerung erforderlich ist, können Sie mit toolkit.enabled_tools eine Liste der zu aktivierenden Tools angeben:

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

Wenn enabled_tools nicht leer ist, werden nur die Tools aus der Liste registriert, die anderen sind nicht verfügbar. scope bestimmt weiterhin, welche Toolkit-Module geladen werden; enabled_tools filtert diese zusätzlich.

Die vollständige Liste der Tools und Klassifizierungen finden Sie in den Kommentarvorlagen in config.yaml.

CLI-Parameter

Umgebungsvariablen (Anmeldedaten und Laufzeitparameter)

* Wenn kein AccessKey konfiguriert ist, verwendet der Dienst automatisch die Standard-Anmeldedatenkette, um Anmeldedaten abzurufen (unterstützt ECS RAM Role, OIDC, Konfigurationsdateien usw.). In Cloud-Umgebungen wie ECS oder Function Compute ist keine manuelle Konfiguration des AccessKey erforderlich.

Priorität der Anmeldedatenauflösung: CLI-Parameter / .env-Datei > Shell-Umgebungsvariablen > Standard-Anmeldedatenkette.

💡 Automatische Ausfüllung von Standardwerten

Wenn ALIBABA_CLOUD_REGION oder ALIBABA_CLOUD_WORKSPACE festgelegt sind, verwendet der Dienst diese Werte automatisch als Standard, falls sie beim Tool-Aufruf nicht angegeben wurden. Explizit übergebene Werte werden nicht überschrieben.

KI-Tool-Integration

Cursor / Kiro / Cline

streamable-http-Modus (empfohlen):

1. config.yaml konfigurieren (setzen Sie server.transport: streamable-http)

2. Dienst starten:

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

3. mcp.json konfigurieren:

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

stdio-Modus:

1. mcp.json konfigurieren:

{
  "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>"
      }
    }
  }
}

Hinweis: Im stdio-Modus werden die integrierten Standardwerte verwendet, falls config.yaml nicht existiert.

Toolsets

Insgesamt 33 Tools, unterteilt in drei Ebenen.

PaaS-Toolsets (Cloud Monitor 2.0, empfohlen)

Basierend auf einem einheitlichen Datenmodell, Toolnamen mit dem Präfix umodel_ oder cms_. Insgesamt 16 Tools.

Entitätsverwaltungstools

Datensatzverwaltungstools

Datenabfragetools

IaaS-Toolsets (direkter Zugriff auf SLS/CMS)

Direkter Zugriff auf die zugrunde liegende API, Toolnamen mit dem Präfix sls_ oder cms_. Insgesamt 14 Tools.

SLS-Tools

CMS-Tools

Shared-Toolsets

Insgesamt 3 Tools.

Zeitausdrücke

Alle Datenabfragetools unterstützen flexible Zeitbereichsformate:

Erweiterte Funktionen

Zeitreihen-Vergleichsanalyse

umodel_get_metrics und umodel_get_golden_metrics unterstützen Zeitreihenvergleiche über den offset-Parameter:

# 对比当前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"
)

Die Ergebnisse enthalten:

• current: Statistik des aktuellen Zeitraums (max, min, avg, count)

• compare: Statistik des Vergleichszeitraums

• diff: Analyse der Änderungen (trend, avg_change, avg_change_percent)

• diff_score: Differenzbewertung (0-1, je höher, desto signifikanter der Unterschied)

Erweiterte Analysemodi

umodel_get_metrics unterstützt vier Analysemodi:

Projektstruktur

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

Entwicklung

# 构建
make build

# 运行测试
make test

# 代码检查
make lint

# 清理构建产物
make clean

Tests

Das Projekt verwendet eine Drei-Wege-Strategie: Unit-Tests + Eigenschaftstests + Regressionstests:

• Unit-Tests: Tabellengesteuerte Tests, die spezifische Beispiele und Randbedingungen abdecken

• Eigenschaftstests: Verwendung von gopter, um allgemeine Korrektheitseigenschaften über alle Eingaben hinweg zu verifizieren

• Regressionstests: Integrationstests (//go:build integration), Vergleich der Parameterkonsistenz mit der Python-Version, erfordert echte Alibaba Cloud-Anmeldedaten

# 运行所有单元测试
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

Entwicklungsrichtlinien für KI-Agenten

Siehe docs/AGENTS.md, enthält Erläuterungen zur Projektstruktur, Code-Stil-Konventionen, Prozess für neue Tools, Testspezifikationen usw.

Berechtigungsanforderungen

Um sicherzustellen, dass der MCP Server erfolgreich auf Ihre Alibaba Cloud Observability-Ressourcen zugreifen und diese verwalten kann, müssen Sie die folgenden Berechtigungen konfigurieren:

Alibaba Cloud AccessKey

• Der Dienst benötigt für den Betrieb gültige Alibaba Cloud-Anmeldedaten, die auf folgende Weise unterstützt werden (nach Priorität sortiert):

  1. AccessKey ID + AccessKey Secret (über .env-Datei, Umgebungsvariablen oder CLI-Parameter übergeben)

  2. STS temporäre Anmeldedaten (Umgebungsvariable ALIBABA_CLOUD_SECURITY_TOKEN setzen)

  3. Automatische Erkennung der Standard-Anmeldedatenkette (ECS RAM Role, OIDC, Anmeldedaten-Konfigurationsdateien usw.)

• Informationen zum Abrufen und Verwalten von AccessKeys finden Sie in der offiziellen Dokumentation zur Alibaba Cloud AccessKey-Verwaltung

RAM-Autorisierung

Dem mit dem AccessKey verknüpften RAM-Benutzer oder der Rolle muss die erforderliche Berechtigung für den Zugriff auf die relevanten Cloud-Dienste erteilt werden.

Es wird dringend empfohlen, dem "Prinzip der geringsten Rechte" zu folgen: Erteilen Sie nur die minimal erforderliche Berechtigungsmenge, die für die Ausführung der geplanten MCP-Tools erforderlich ist.

Informationen zur Berechtigungskonfiguration finden Sie je nach den zu verwendenden Tools in den folgenden Dokumenten:

Besondere Berechtigungshinweise:

• Die Verwendung von SQL-Generierungstools (wie sls_text_to_sql) erfordert die separate Erteilung der Berechtigung sls:CallAiTools

• Die Verwendung der Abfragefunktion in natürlicher Sprache (cms_natural_language_query) erfordert die Erteilung von: cms:CreateChat, cms:CreateThread, cms:GetThread, cms:ListThreads

Sicherheitsempfehlungen

• Der Dienst speichert keine AccessKeys, diese werden nur zur Laufzeit für API-Aufrufe verwendet

• Stellen Sie im SSE/HTTP-Modus sicher, dass Sie die Zugriffskontrolle für die Endpunkte selbst verwalten

• Es wird empfohlen, den Dienst in einem internen Netzwerk oder einer VPC bereitzustellen, um eine direkte Exposition gegenüber dem öffentlichen Internet zu vermeiden

• Setzen Sie niemals einen Serverendpunkt mit konfiguriertem AccessKey ohne Authentifizierung dem öffentlichen Internet aus

• Es wird empfohlen, Alibaba Cloud Function Compute (FC) für die Bereitstellung zu verwenden und den Zugriff nur innerhalb der VPC zu konfigurieren

Lizenz

Dieses Projekt unterliegt derselben Lizenzvereinbarung wie die ursprüngliche Python-Version.