/deploy-observability

name: deploy-observability
description: "Deploy, start, and update the Alibaba Cloud Observability MCP Server (阿里云可观测 MCP Server). Use this skill whenever the user mentions deploying, installing, starting, updating, or configuring the observability MCP server, Alibaba Cloud SLS/CMS MCP tools, or wants to connect Alibaba Cloud monitoring to their AI coding agent. Also trigger when the user says things like 'set up MCP server', 'install observability tools', 'deploy aliyun MCP', 'configure SLS MCP', or 'update MCP server tools'."

Deploy Alibaba Cloud Observability MCP Server

Overview

This skill guides users through deploying and managing the Alibaba Cloud Observability MCP Server. It covers:

• **First-time deployment** — clone, build, configure credentials, start, generate agent config
• **Docker deployment** — containerized setup for servers
• **Project update** — pull latest code, detect changes, rebuild, report new tools

The server provides 60+ tools for Alibaba Cloud Log Service (SLS), CloudMonitor (CMS), and AI-powered observability. It can run locally (stdio) or as a remote HTTP service (sse/streamable-http).

Phase 0: Pre-flight Checks

Before starting any deployment, run these checks to understand the environment:

Detect Existing Installation

# Check if already installed in common locations
for dir in ~/alibabacloud-observability-mcp-server ~/.alibabacloud-observability-mcp-server /opt/alibabacloud-observability-mcp-server; do
  if [ -d "$dir" ] && [ -f "$dir/bin/alibabacloud-observability-mcp-server" ]; then
    echo "Found installation at: $dir"
    "$dir/bin/alibabacloud-observability-mcp-server" version
  fi
done

If an existing installation is found, ask the user: > 检测到已有安装，是否要更新？还是全新安装到其他位置？

Check Go Environment

go version 2>/dev/null && echo "Go OK" || echo "Go NOT FOUND"

If Go is not installed: > Go 未安装（需要 >= 1.23）。请前往 https://go.dev/dl/ 下载安装，或使用包管理器： > - macOS: `brew install go` > - Ubuntu/Debian: `sudo apt install golang-go` > - CentOS: `sudo yum install golang`

Check Network

curl -s --connect-timeout 5 https://github.com > /dev/null && echo "GitHub OK" || echo "GitHub UNREACHABLE"

If GitHub is unreachable (common in China): > GitHub 无法访问。请检查网络连接，或使用镜像站： > - `git clone https://ghproxy.com/https://github.com/aliyun/alibabacloud-observability-mcp-server.git`

---

Phase 1: First-Time Deployment

Ask the user where to install (default: `~/Projects/alibabacloud-observability-mcp-server`).

There are two ways to get the binary. Let the user choose:

Step 1.1a — Download Pre-built Binary (fastest, recommended)

# macOS arm64 (M1/M2/M3/M4)
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
cd alibabacloud-observability-mcp-server

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

**⚠️ macOS "无法验证开发者"提示：** 首次运行时，macOS 可能阻止执行并提示"无法验证开发者"。解决方法： 1. 系统设置 → 隐私与安全性 → 找到被阻止的文件 → 点击"仍然允许" 2. 或者在终端运行：`xattr -d com.apple.quarantine bin/alibabacloud-observability-mcp-server`

Step 1.1b — Clone and Build from Source

git clone https://github.com/aliyun/alibabacloud-observability-mcp-server.git <install_path>
cd <install_path>

**Optional: Pin to a specific release version:**

# List available versions
git tag -l 'go/v*'

# Checkout a specific version
git checkout go/v0.1.8

Build:

go mod tidy
make build
chmod +x bin/alibabacloud-observability-mcp-server

Verify:

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

If `make build` fails:

• Check Go version: `go version` (needs >= 1.23)
• Try `go mod download` first
• Check for C compiler issues (should not be needed — pure Go)

Step 1.2 — Configure Credentials

cp .env.example .env

Present the credential table to the user:

| 环境变量 | 说明 | 必需 | |---------|------|------| | `ALIBABA_CLOUD_ACCESS_KEY_ID` | 阿里云 AccessKey ID | 是* | | `ALIBABA_CLOUD_ACCESS_KEY_SECRET` | 阿里云 AccessKey Secret | 是* | | `ALIBABA_CLOUD_REGION` | 默认地域 | 否（默认 cn-hangzhou） | | `ALIBABA_CLOUD_WORKSPACE` | 默认工作空间 | 否 | | `ALIBABA_CLOUD_SECURITY_TOKEN` | STS 临时凭证 | 否 |

> \* 如果在 ECS/FC 上运行且已配置 RAM Role，可以跳过 AccessKey，服务会自动使用默认凭据链。

Tell the user: > 请编辑 `.env` 文件，填入你的阿里云 AccessKey。 > 获取方式：https://ram.console.aliyun.com/manage/ak

**Wait for the user to confirm they've filled in the credentials.**

Step 1.3 — Choose Transport Mode

Ask the user to choose:

| 模式 | 说明 | 适用场景 | |------|------|---------| | **stdio** | 标准输入输出 | IDE 集成（Cursor / Claude Code 等），本地使用 | | **sse** | Server-Sent Events | 远程 HTTP 访问 | | **streamable-http** | HTTP 流式传输 | 远程 HTTP 访问（推荐生产环境） |

**If stdio:** Tell the user: > stdio 模式通常由 IDE 自动启动，无需手动运行。直接跳到 Step 1.4 生成配置。

**If sse or streamable-http:**

Edit `config.yaml`:

server:
  transport: streamable-http  # 或 sse
  host: 0.0.0.0
  port: 8180

Start the server:

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

Verify:

curl http://localhost:8180/health

If health check fails:

• Check logs (stderr output)
• Verify `.env` has valid credentials
• Check if port 8180 is already in use: `lsof -i :8180`

Step 1.4 — Generate Agent Integration Config

Ask the user which AI agent they want to connect to, then generate the config.

**For streamable-http / sse mode (remote server):**

{
  "mcpServers": {
    "alibaba_cloud_observability": {
      "url": "http://<server_ip>:8180"
    }
  }
}

**For stdio mode (local):**

{
  "mcpServers": {
    "alibaba_cloud_observability": {
      "command": "<install_path>/bin/alibabacloud-observa