알리바바 클라우드 관측성 MCP 서버 (Go 버전)

📌 중요 참고 사항
본 프로젝트는 Go 언어로 재작성되었습니다. 기존 Python 버전을 사용하려면 v1 디렉토리를 방문하십시오:
📖 v1/README.md - Python 버전 문서
📦 Python 버전은 pip install mcp-server-aliyun-observability를 통해 설치 가능

알리바바 클라우드 관측성 MCP 서버의 Go 구현체로, AI 모델에 알리바바 클라우드 로그 서비스(SLS) 및 클라우드 모니터링(CMS)에 대한 구조화된 데이터 액세스 기능을 제공합니다. Model Context Protocol 프로토콜을 기반으로 하며, Cursor, Kiro, Cline, Windsurf 등 AI 도구와 원활하게 통합됩니다.

특징

stdio, SSE, streamable-http 세 가지 전송 모드 지원
모듈형 도구 세트 아키텍처: PaaS(클라우드 모니터링 2.0), IaaS(SLS/CMS 직접 액세스), Shared
유연한 시간 표현식 파싱: 상대 시간, 절대 타임스탬프, Grafana 스타일, 사전 설정 키워드
시계열 데이터 비교 분석: 통계 계산, 추세 분석, 차이 점수 산정
구조화된 오류 처리: 영어 오류 설명 및 해결 방안 제안
안정성 보장: 재시도(지수 백오프), 서킷 브레이커, 우아한 종료
구조화된 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 관리

서비스 시작

# 以 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/ 디렉토리에 위치합니다.

설정

설정은 2단계 구조를 채택합니다:

config.yaml - 서버 설정(전송 모드, 로그, 네트워크 등)
.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 매개변수

매개변수	설명	기본값
`--config`	설정 파일 경로 지정	자동 검색
`--stdio`	stdio 전송 모드 강제 사용	false

환경 변수(자격 증명 및 런타임 매개변수)

환경 변수	설명	필수
`ALIBABA_CLOUD_ACCESS_KEY_ID`	AccessKey ID	아니오*
`ALIBABA_CLOUD_ACCESS_KEY_SECRET`	AccessKey Secret	아니오*
`ALIBABA_CLOUD_SECURITY_TOKEN`	STS Token(임시 자격 증명)	아니오
`ALIBABA_CLOUD_REGION`	기본 리전	아니오
`ALIBABA_CLOUD_WORKSPACE`	기본 워크스페이스(PaaS 도구 필요)	아니오

* AccessKey가 설정되지 않은 경우, 서비스는 자동으로 기본 자격 증명 체인을 사용하여 자격 증명을 획득합니다(ECS RAM Role, OIDC, 설정 파일 방식 등 지원). ECS, 함수 계산 등 클라우드 환경에서는 AccessKey를 수동으로 설정할 필요가 없습니다.

자격 증명 파싱 우선순위: CLI 매개변수 / .env 파일 > 셸 환경 변수 > 기본 자격 증명 체인.

💡 기본값 자동 채우기
ALIBABA_CLOUD_REGION 또는 ALIBABA_CLOUD_WORKSPACE가 설정된 경우, 도구 호출 시 regionId 또는 workspace 매개변수가 제공되지 않으면 서비스는 환경 변수의 값을 기본값으로 자동 사용합니다. 사용자가 명시적으로 전달한 값은 덮어쓰지 않습니다.

AI 도구 통합

Cursor / Kiro / Cline

streamable-http 모드(권장):

config.yaml 설정(server.transport: streamable-http 설정)
서비스 시작:

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

mcp.json 설정:

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

stdio 모드:

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 도구 세트(클라우드 모니터링 2.0, 권장)

통합 데이터 모델을 기반으로 하며, 도구 이름은 umodel_ 또는 cms_ 접두사를 가집니다. 총 16개의 도구.

엔티티 관리 도구

도구	설명	주요 매개변수
`umodel_get_entities`	엔티티 목록 가져오기	`workspace`, `domain`, `entity_set_name`, `regionId`(필수); `entity_filter`(선택)
`umodel_get_neighbor_entities`	엔티티 인접 관계 가져오기	`workspace`, `src_entity_domain`, `src_name`, `src_entity_ids`, `regionId`(필수)
`umodel_search_entities`	엔티티 검색	`workspace`, `search_text`, `regionId`(필수)

데이터 세트 관리 도구

도구	설명	주요 매개변수
`umodel_list_data_set`	데이터 세트 나열	`workspace`, `domain`, `entity_set_name`, `regionId`(필수); `data_set_types`(선택)
`umodel_search_entity_set`	엔티티 세트 검색	`workspace`, `search_text`, `regionId`(필수)
`umodel_get_entity_set`	엔티티 세트 스키마 정의 가져오기	`domain`, `entity_set_name`, `workspace`, `regionId`(필수); `detail`(선택)
`umodel_list_related_entity_set`	관련 엔티티 세트 나열	`workspace`, `domain`, `entity_set_name`, `regionId`(필수)

데이터 쿼리 도구

도구	설명	주요 매개변수
`umodel_get_metrics`	지표 데이터 쿼리	`workspace`, `domain`, `entity_set_name`, `metric_domain_name`, `metric`, `regionId`(필수); `analysis_mode`(basic/cluster/forecast/anomaly_detection), `offset`(시계열 비교), `time_range`(선택)
`umodel_get_golden_metrics`	골든 지표 쿼리	`workspace`, `domain`, `entity_set_name`, `regionId`(필수); `offset`, `time_range`(선택)
`umodel_get_relation_metrics`	관계 지표 쿼리	`workspace`, `src_domain`, `src_entity_set_name`, `relation_type`, `direction`(in/out), `metric`, `metric_set_domain`, `regionId`(필수); `dest_entity_set_name`(선택)
`umodel_get_logs`	로그 데이터 쿼리	`workspace`, `domain`, `entity_set_name`, `log_set_domain`, `log_set_name`, `regionId`(필수); `time_range`, `limit`(선택)
`umodel_get_events`	이벤트 데이터 쿼리	`workspace`, `domain`, `entity_set_name`, `event_set_domain`, `event_set_name`, `regionId`(필수); `time_range`, `limit`(선택)
`umodel_get_traces`	추적 데이터 쿼리	`workspace`, `domain`, `entity_set_name`, `trace_set_domain`, `trace_set_name`, `trace_ids`, `regionId`(필수); `time_range`(선택)
`umodel_search_traces`	추적 검색	`workspace`, `domain`, `entity_set_name`, `trace_set_domain`, `trace_set_name`, `regionId`(필수); `conditions`, `limit`, `time_range`(선택)
`umodel_get_profiles`	성능 프로파일링 데이터 쿼리	`workspace`, `domain`, `entity_set_name`, `profile_set_domain`, `profile_set_name`, `entity_ids`, `regionId`(필수); `time_range`, `limit`(선택)
`cms_natural_language_query`	자연어 데이터 쿼리	`query`, `workspace`, `regionId`(필수); `time_range`(선택)

IaaS 도구 세트(SLS/CMS 직접 액세스)

기본 API에 직접 액세스하며, 도구 이름은 sls_ 또는 cms_ 접두사를 가집니다. 총 14개의 도구.

SLS 도구

도구	설명	주요 매개변수
`sls_list_projects`	프로젝트 나열	`regionId`(필수); `project`(선택, 퍼지 검색)
`sls_list_logstores`	로그 저장소 나열	`project`, `regionId`(필수)
`sls_text_to_sql`	자연어를 SQL로 변환	`text`, `project`, `logStore`, `regionId`(필수)
`sls_text_to_sql_old`	자연어를 SQL로 변환(구버전, Python 버전 호환)	`text`, `project`, `logStore`, `regionId`(필수)
`sls_text_to_promql`	자연어를 PromQL로 변환	`text`, `project`, `metricStore`, `regionId`(필수)
`sls_text_to_spl`	자연어를 SPL로 변환	`text`, `project`, `logStore`, `data_sample`, `regionId`(필수)
`sls_execute_sql`	SQL 쿼리 실행	`project`, `logStore`, `query`, `regionId`(필수); `from_time`, `to_time`(선택)
`sls_execute_spl`	네이티브 SPL 쿼리 실행	`query`, `workspace`, `regionId`(필수); `from_time`, `to_time`(선택)
`sls_get_context_logs`	로그 컨텍스트 가져오기	`project`, `logStore`, `pack_id`, `pack_meta`, `regionId`(필수); `back_lines`, `forward_lines`(선택)
`sls_log_explore`	로그 탐색 분석	`project`, `logStore`, `logField`, `regionId`(필수); `from_time`, `to_time`, `filter_query`, `groupField`(선택)
`sls_log_compare`	로그 비교 분석	`project`, `logStore`, `logField`, `regionId`(필수); `test_from_time`, `test_to_time`, `control_from_time`, `control_to_time`, `filter_query`, `groupField`(선택)
`sls_sop`	SLS 운영 보조 도구	`text`, `regionId`(필수)

CMS 도구

도구	설명	주요 매개변수
`cms_execute_promql`	PromQL 쿼리 실행	`project`, `metricStore`, `query`, `regionId`(필수); `from_time`, `to_time`(선택)
`cms_text_to_promql`	자연어를 PromQL로 변환	`text`, `project`, `metricStore`, `regionId`(필수)

Shared 도구 세트

총 3개의 도구.

도구	설명	주요 매개변수
`list_workspace`	워크스페이스 나열	`regionId`(필수)
`list_domains`	엔티티 도메인 나열	`workspace`, `regionId`(필수)
`introduction`	서비스 소개	매개변수 없음

시간 표현식

모든 데이터 쿼리 도구는 유연한 시간 범위 형식을 지원합니다:

형식	예시
상대 사전 설정	`last_5m`, `last_1h`, `last_3d`, `last_1w`, `last_1M`, `last_1y`
상대 시간	`now()-1h`, `now-30m`, `now()-7d`
Grafana 스타일	`now-15m~now-5m`, `now/d`, `now-1d/d`
키워드	`today`, `yesterday`
절대 타임스탬프	`1718451045`(초), `1718451045000`(밀리초)
날짜 시간 문자열	`2024-01-01 00:00:00`, `2024-01-01T00:00:00Z`

고급 기능

시계열 비교 분석

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는 네 가지 분석 모드를 지원합니다:

모드	설명	출력 필드
`basic`	원시 시계열 데이터(기본값)	`__ts__`, `__value__`, `__labels__`
`cluster`	K-Means 시계열 클러스터링	`__cluster_index__`, `__entities__`, `__sample_value__`
`forecast`	시계열 예측(1-5일 과거 데이터 필요)	`__forecast_ts__`, `__forecast_value__`, `__forecast_lower/upper_value__`
`anomaly_detection`	이상 탐지(1-3일 데이터 필요)	`__anomaly_list_`, `__anomaly_msg__`, `__value_min/max/avg__`

프로젝트 구조

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

테스트

프로젝트는 단위 테스트 + 속성 테스트 + 회귀 테스트의 3트랙 전략을 채택합니다:

단위 테스트: 테이블 기반 테스트, 구체적인 예시 및 경계 조건 커버
속성 테스트: gopter를 사용하여 모든 입력에 걸친 일반적인 정확성 속성 검증
회귀 테스트: 통합 테스트(//go:build integration), Python 버전 매개변수 일관성 비교, 실제 알리바바 클라우드 자격 증명 필요

# 运行所有单元测试
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 Agent 개발 규격

docs/AGENTS.md를 참조하십시오. 프로젝트 구조 설명, 코드 스타일 약속, 도구 추가 프로세스, 테스트 규격 등이 포함되어 있습니다.

권한 요구 사항

MCP 서버가 알리바바 클라우드 관측성 리소스에 성공적으로 액세스하고 조작할 수 있도록 하려면 다음 권한을 설정해야 합니다:

알리바바 클라우드 액세스 키(AccessKey)

서비스 실행에는 유효한 알리바바 클라우드 자격 증명이 필요하며, 다음 방식을 지원합니다(우선순위 순):
1. AccessKey ID + AccessKey Secret(.env 파일, 환경 변수 또는 CLI 매개변수를 통해 전달)
2. STS 임시 자격 증명(ALIBABA_CLOUD_SECURITY_TOKEN 환경 변수 설정)
3. 기본 자격 증명 체인 자동 발견(ECS RAM Role, OIDC, 자격 증명 설정 파일 등)
AccessKey 획득 및 관리는 알리바바 클라우드 AccessKey 관리 공식 문서를 참조하십시오.

RAM 권한 부여

AccessKey와 연결된 RAM 사용자 또는 역할은 관련 클라우드 서비스 액세스에 필요한 권한을 반드시 부여받아야 합니다.

"최소 권한 원칙"을 따를 것을 강력히 권장합니다: 사용하려는 MCP 도구를 실행하는 데 필요한 최소 권한 세트만 부여하십시오.

사용하려는 도구에 따라 다음 문서를 참조하여 권한을 설정하십시오:

서비스	권한 문서	설명
로그 서비스(SLS)	SLS 권한 설명	`sls_*` 도구 필요
애플리케이션 실시간 모니터링(ARMS)	ARMS 권한 설명	`umodel_*` 도구 필요
클라우드 모니터링(CMS)	CMS 권한 설명	`cms_*` 도구 필요

특수 권한 설명:

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가 설정된 서버 엔드포인트를 공용 인터넷에 노출하지 마십시오.
알리바바 클라우드 함수 계산(FC)을 사용하여 배포하고 VPC 내에서만 액세스하도록 설정하는 것을 권장합니다.

라이선스

본 프로젝트는 기존 Python 버전과 동일한 라이선스 계약을 따릅니다.