deploy-observability

Alibaba Cloud Observability MCP サーバーのデプロイ

概要

このスキルでは、Alibaba Cloud Observability MCP サーバーのデプロイと管理について説明します。以下を扱います。

• 初回デプロイ — クローン、ビルド、認証情報の設定、起動、エージェント設定の生成
• Docker デプロイ — サーバー向けのコンテナ化されたセットアップ
• プロジェクトの更新 — 最新コードの取得、変更の検出、再ビルド、新しいツールの報告

このサーバーは、Alibaba Cloud Log Service（SLS）、CloudMonitor（CMS）、AI を活用したオブザーバビリティ向けに 60 以上のツールを提供します。ローカル（stdio）またはリモート HTTP サービス（sse/streamable-http）として実行できます。

フェーズ 0：事前確認

デプロイを開始する前に、環境を把握するため次の確認を実行します。

既存のインストールを検出する

# 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

既存のインストールが見つかった場合は、ユーザーに確認します。

既存のインストールが検出されました。更新しますか？それとも別の場所に新規インストールしますか？

Go 環境を確認する

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

Go がインストールされていない場合：

Go がインストールされていません（>= 1.23 が必要です）。https://go.dev/dl/ からダウンロードしてインストールするか、パッケージマネージャーを使用してください。

• macOS：brew install go
• Ubuntu/Debian：sudo apt install golang-go
• CentOS：sudo yum install golang

ネットワークを確認する

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

GitHub にアクセスできない場合（中国でよく発生します）：

GitHub にアクセスできません。ネットワーク接続を確認するか、ミラーサイトを使用してください。

• git clone https://ghproxy.com/https://github.com/aliyun/alibabacloud-observability-mcp-server.git

---

フェーズ 1：初回デプロイ

インストール先をユーザーに尋ねます（デフォルト：~/Projects/alibabacloud-observability-mcp-server）。

バイナリを入手する方法は 2 つあります。ユーザーに選んでもらいます。

ステップ 1.1a — ビルド済みバイナリをダウンロードする（最速・推奨）

# 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

ステップ 1.1b — ソースからクローンしてビルドする

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

任意：特定のリリースバージョンに固定する：

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

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

ビルドします：

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

確認します：

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

make build が失敗する場合：

• Go のバージョンを確認します：go version（>= 1.23 が必要です）
• まず go mod download を試します
• C コンパイラーに関する問題がないか確認します（純粋な Go なので、通常は必要ありません）

ステップ 1.2 — 認証情報を設定する

cp .env.example .env

認証情報の表をユーザーに提示します。

環境変数	説明	必須
ALIBABA_CLOUD_ACCESS_KEY_ID	Alibaba Cloud AccessKey ID	はい*
ALIBABA_CLOUD_ACCESS_KEY_SECRET	Alibaba Cloud AccessKey Secret	はい*
ALIBABA_CLOUD_REGION	デフォルトのリージョン	いいえ（デフォルトは cn-hangzhou）
ALIBABA_CLOUD_WORKSPACE	デフォルトのワークスペース	いいえ
ALIBABA_CLOUD_SECURITY_TOKEN	STS 一時認証情報	いいえ

* ECS/FC 上で実行し、RAM Role が設定済みの場合は、AccessKey を省略できます。サービスはデフォルトの認証情報チェーンを自動的に使用します。

ユーザーに伝えます。

.env ファイルを編集し、Alibaba Cloud AccessKey を入力してください。 取得方法：https://ram.console.aliyun.com/manage/ak

ユーザーが認証情報を入力したことを確認するまで待ちます。

ステップ 1.3 — トランスポートモードを選択する

ユーザーに選んでもらいます。

モード	説明	用途
stdio	標準入出力	IDE 連携（Cursor / Claude Code など）、ローカルでの使用
sse	Server-Sent Events	リモート HTTP アクセス
streamable-http	HTTP ストリーミング	リモート HTTP アクセス（本番環境に推奨）

stdio の場合： ユーザーに伝えます。

stdio モードは通常 IDE によって自動起動されるため、手動で実行する必要はありません。ステップ 1.4 に進み、設定を生成してください。

sse または streamable-http の場合：

config.yaml を編集します。

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

サーバーを起動します。

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

確認します。

curl http://localhost:8180/health

ヘルスチェックに失敗した場合：

• ログを確認します（stderr の出力）
• .env に有効な認証情報が設定されていることを確認します
• ポート 8180 がすでに使用されていないか確認します：lsof -i :8180

ステップ 1.4 — エージェント連携設定を生成する

接続する AI エージェントをユーザーに尋ね、その設定を生成します。

streamable-http / sse モードの場合（リモートサーバー）：

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

stdio モードの場合（ローカル）：

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

設定を貼り付ける場所をユーザーに伝えます。

エージェント	設定ファイルのパス
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 エージェントに貼り付けてください。リモートサーバーの場合は、<server_ip> を実際の IP アドレスに置き換えてください。

Step 1.5 — 有料ツールに関する警告

重要：ユーザーが作業を終える前に、有料ツールについて知らせてください：

⚠️ 有料ツールに関する注意

以下の 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 によるデプロイ（代替方法）

コンテナ化されたデプロイ（サーバー、CI/CD など）を希望するユーザー向け：

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

または 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

確認：

curl http://localhost:8180/health

Docker によるデプロイ後、Step 1.5 と同じ手順で、URL に http://<server_ip>:8180 を指定してエージェントの設定を生成してください。

---

Phase 2：プロジェクトの更新

ユーザーが既存のデプロイを更新する場合：

Step 2.1 — インストール先を確認する

ユーザーがインストール先のパスを知らない場合：

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

Step 2.2 — 現在の状態を記録する

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 — 最新のコードを取得する

git pull origin master
go mod tidy

Step 2.4 — 変更を検出して報告する

以下を確認し、結果を分かりやすく提示してください：

1. 依存関係の変更：

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

2. 設定の変更：

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

.env.example に変更がある場合は、新しい変数を示し、ユーザーに .env の更新を依頼してください。

3. ツールを再ビルドして比較する：

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 — 概要を報告する

分かりやすい概要を提示してください：

📦 更新完成

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

サーバーが実行中だった場合は、同じトランスポートモードで再起動してください。

---

トラブルシューティング

問題	解決策
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> を実行するか、ポートを変更してください
ヘルスチェックでエラーが返される	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 で無料ツールのみを有効にしてください