deploy-observability

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

Tell the user where to paste the config:

Agent	配置文件路径
Cursor	Settings → MCP → Add Server（UI 操作）
Claude Code	~/.claude/settings.json 或项目 .claude/settings.json
Kiro	Settings → MCP Servers（UI 操作）
Windsurf	Settings → MCP Configuration
Cline	.cline/mcp_settings.json 在项目根目录

将以上 JSON 配置粘贴到你的 AI Agent 中。如果是远程服务器，将 <server_ip> 替换为实际 IP 地址。

Step 1.5 — Paid Tools Warning

IMPORTANT: Inform the user about paid tools before they finish:

⚠️ 付费工具提醒

以下 AI 智能工具每次调用会产生 STAROps 费用：

• sls_text_to_sql — 自然语言转 SQL
• sls_text_to_spl — 自然语言转 SPL
• sls_sop — SLS 智能运维助手
• cms_natural_language_query — 自然语言数据查询

如果不需要 AI 能力，可以在 config.yaml 的 enabled_tools 中仅启用免费工具，避免意外费用。

计费详情：https://www.aliyun.com/price/product#/starops/detail

---

Phase 1b: Docker Deployment (alternative)

For users who prefer containerized deployment (servers, CI/CD, etc.):

Build and Run with Docker

# Build image
docker build -t observability-mcp-server .

# Run with environment variables
docker run -d \
  --name observability-mcp \
  -p 8180:8180 \
  -e ALIBABA_CLOUD_ACCESS_KEY_ID=<your_key> \
  -e ALIBABA_CLOUD_ACCESS_KEY_SECRET=<your_secret> \
  -e ALIBABA_CLOUD_REGION=cn-hangzhou \
  observability-mcp-server

Or use Docker Compose

# Create .env file with credentials
cat > .env << 'EOF'
ALIBABA_CLOUD_ACCESS_KEY_ID=<your_key>
ALIBABA_CLOUD_ACCESS_KEY_SECRET=<your_secret>
ALIBABA_CLOUD_REGION=cn-hangzhou
EOF

# Start
docker-compose up -d

Verify:

curl http://localhost:8180/health

After Docker deployment, generate the agent config using http://<server_ip>:8180 as the URL (same as Step 1.5).

---

Phase 2: Project Update

When the user wants to update an existing deployment:

Step 2.1 — Locate Installation

If the user doesn't know the install path:

# Search for existing installations
find ~ -maxdepth 3 -name "alibabacloud-observability-mcp-server" -type d 2>/dev/null

Step 2.2 — Record Current State

cd <install_path>

# Save current version and tool list
./bin/alibabacloud-observability-mcp-server version > /tmp/version_before.txt 2>/dev/null || true
./bin/alibabacloud-observability-mcp-server tools > /tmp/tools_before.txt 2>/dev/null || true

Step 2.3 — Pull Latest Code

git pull origin master
go mod tidy

Step 2.4 — Detect Changes and Report

Run these checks and present results clearly:

1. Dependency changes:

git diff HEAD@{1} --name-only 2>/dev/null | grep -E 'go\.(mod|sum)' && echo "DEPENDENCIES CHANGED" || echo "No dependency changes"

2. Config changes:

git diff HEAD@{1} -- config.yaml .env.example 2>/dev/null

If .env.example changed, show new variables and ask the user to update .env.

3. Rebuild and compare tools:

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

# Compare tool lists
diff /tmp/tools_before.txt /tmp/tools_after.txt 2>/dev/null || true

Step 2.5 — Report Summary

Present a clear summary:

📦 更新完成

版本: <old_version> → <new_version>
依赖: 有变更 / 无变更
配置: 需要更新 .env / 无需更新
工具变更:
  ✅ 新增 N 个工具: tool_a, tool_b, ...
  ❌ 移除 N 个工具: tool_x, ...
服务状态: 需要手动重启 / 已在运行

If the server was running, restart with the same transport mode.

---

Troubleshooting

问题	解决方案
command not found: go	安装 Go >= 1.23: https://go.dev/dl/
credentials not configured	编辑 .env，填入 AccessKey ID 和 Secret
config file not found	确保 config.yaml 存在于项目目录
address already in use	lsof -i :8180 查看占用进程，kill -9 <PID> 或改端口
Health check 返回错误	检查 stderr 日志，验证 .env 中凭证是否正确
git clone 超时	国内用户尝试镜像: https://ghproxy.com/https://github.com/...
go mod tidy 失败	检查网络连接，设置 GOPROXY: export GOPROXY=https://goproxy.cn,direct
构建报 undefined 错误	go mod tidy 重新下载依赖
permission denied	chmod +x bin/alibabacloud-observability-mcp-server
付费工具产生意外费用	在 config.yaml 中用 enabled_tools 仅启用免费工具