Alibaba Cloud Observability

Acesse produtos de observabilidade da Alibaba Cloud, como SLS, ARMS e CloudMonitor.

GitHub
167

Documentação

Servidor MCP de Observabilidade da Alibaba Cloud (versão Go)

中文 English

📌 Aviso importante

Este projeto foi reescrito em Go. Para usar a versão original em Python, acesse o diretório v1:

  • 📖 v1/README.md - Documentação da versão Python
  • 📦 A versão Python é instalada via pip install mcp-server-aliyun-observability

Implementação em Go do servidor MCP de Observabilidade da Alibaba Cloud, fornecendo acesso estruturado a dados do Log Service (SLS) e Cloud Monitor (CMS) da Alibaba Cloud para modelos de IA. Baseado no protocolo Model Context Protocol, integra-se perfeitamente a ferramentas de IA como Cursor, Kiro, Cline, Windsurf e outras.

Recursos

  • Suporte a três modos de transporte: stdio, SSE e streamable-http
  • Arquitetura modular de ferramentas: PaaS (Cloud Monitor 2.0), IaaS (acesso direto a SLS/CMS) e Shared
  • Análise flexível de expressões de tempo: tempo relativo, timestamps absolutos, estilo Grafana e palavras-chave predefinidas
  • Análise comparativa de dados de séries temporais: cálculos estatísticos, análise de tendências e pontuação de diferenças
  • Tratamento estruturado de erros: descrições de erros e sugestões de solução em inglês
  • Garantia de estabilidade: retry (backoff exponencial), circuit breaker e encerramento gracioso
  • Logs JSON estruturados (slog)
  • Binário único, zero dependências em tempo de execução

Início rápido

Download e instalação

Baixe o binário da sua plataforma na página de 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

Após a descompactação, você encontrará:

  • alibabacloud-observability-mcp-server - arquivo executável
  • config.yaml - arquivo de configuração padrão

Configuração de credenciais

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

Como obter AccessKey: Gerenciamento de AccessKey da Alibaba Cloud

Iniciar o serviço

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

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

Comandos CLI

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

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

Compilação a partir do código-fonte

git clone https://github.com/aliyun/alibabacloud-observability-mcp-server.git
cd alibabacloud-observability-mcp-server
make build

Configuração

A configuração usa uma estrutura de duas camadas:

  1. config.yaml - configuração do servidor (modo de transporte, logs, rede etc.)
  2. Arquivo .env ou variáveis de ambiente - credenciais e parâmetros de execução

Para detalhes sobre as opções de configuração, consulte os comentários em config.yaml.

Integração com ferramentas de IA

Modo streamable-http (recomendado)

  1. Configure config.yaml (defina server.transport: streamable-http)
  2. Inicie o serviço: ./bin/alibabacloud-observability-mcp-server start
  3. Configure mcp.json:
{
  "mcpServers": {
    "alibaba_cloud_observability": {
      "url": "http://localhost:8080"
    }
  }
}

Modo stdio

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

Conjunto de ferramentas

Ver a lista completa de ferramentas

Execute o comando abaixo para ver todas as ferramentas registradas:

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

Recursos pagos

As seguintes ferramentas de IA geram custos de STAROps a cada chamada:

FerramentaFunção
sls_text_to_sqlConversão de linguagem natural para SQL
sls_text_to_splConversão de linguagem natural para SPL
sls_sopAssistente de operações inteligentes do SLS
cms_natural_language_queryConsulta de dados em linguagem natural

Consulte os detalhes de cobrança em Documentação de cobrança do STAROps. Se não precisar de recursos de IA, você pode habilitar apenas as ferramentas gratuitas em enabled_tools de config.yaml.

Requisitos de permissão

ServiçoDocumentação de permissõesFerramentas aplicáveis
Log Service (SLS)Permissões do SLSsls_*
Application Real-Time Monitoring (ARMS)Permissões do ARMSumodel_*
Cloud Monitor (CMS)Permissões do CMScms_*

Permissões especiais: o uso de ferramentas de IA (como sls_text_to_sql e cms_natural_language_query) exige a concessão das permissões cms:CreateChat e cms:CreateThread do CMS.

Expressões de tempo

Todas as ferramentas de consulta de dados suportam formatos flexíveis de intervalo de tempo:

FormatoExemplo
Predefinições relativaslast_5m、last_1h、last_1d
Tempo relativonow()-1h、now-30m
Estilo Grafananow-15m~now-5m、now/d、now-1d/d
Timestamp absoluto1718451045 (segundos)、1718451045000 (milissegundos)
String de data e hora2024-01-01 00:00:00、2024-01-01T00:00:00Z

Estrutura do projeto

├── cmd/server/          # CLI 入口
├── pkg/
│   ├── client/          # SLS/CMS 客户端
│   ├── config/          # 配置管理
│   ├── server/          # MCP Server 核心
│   └── toolkit/         # 工具集（PaaS/IaaS/Shared）
└── v1/                  # Python 版本

Recomendações de segurança

  • O serviço não armazena AccessKeys; elas são usadas apenas em chamadas de API em tempo de execução
  • Nos modos SSE/HTTP, implemente seu próprio controle de acesso
  • Recomenda-se implantar em uma rede interna ou VPC, evitando exposição pública
  • Recomenda-se implantar com Function Compute (FC), acessível apenas dentro da VPC

Implantação automatizada com Skill

Este projeto fornece um Skill para Agentes de IA, permitindo implantação, inicialização e atualização por meio de instruções em linguagem natural.

Instalar o Skill

Opção 1: npx skills add (recomendado)

Instalador de skills de uso geral mantido pela Vercel Labs, com suporte a mais de 69 agentes de codificação:

# 全局安装（所有项目可用）
npx skills add aliyun/alibabacloud-observability-mcp-server

# 项目级安装（仅当前项目可用）
npx skills add aliyun/alibabacloud-observability-mcp-server --local

Opção 2: curl (sem necessidade de Node.js)

# 下载并安装 skill 到 ~/.claude/skills/
curl -fsSL https://raw.githubusercontent.com/aliyun/alibabacloud-observability-mcp-server/master/skills/deploy-observability/SKILL.md -o ~/.claude/skills/deploy-observability/SKILL.md

Opção 3: copiar do repositório do projeto

Se você já clonou este projeto:

# 全局安装
cp skills/deploy-observability/SKILL.md ~/.claude/skills/deploy-observability/

# 或项目级安装（在项目根目录下）
cp skills/deploy-observability/SKILL.md .claude/skills/deploy-observability/

Usar o Skill

Após instalar o skill, copie o conteúdo abaixo para um Agente de IA compatível com Skills (como Claude Code):

Primeira implantação:

请使用 deploy-observability skill 帮我完成以下操作：
1. 克隆项目到 ~/alibabacloud-observability-mcp-server
2. 下载依赖并构建
3. 复制 .env.example 为 .env，并提示我填写阿里云 AccessKey
4. 让我选择启动模式（stdio / sse / streamable-http）
5. 生成 JSON 配置，供我粘贴到 AI Agent 中使用

Atualização do projeto:

请使用 deploy-observability skill 帮我更新项目：
1. 拉取最新代码
2. 检测是否有依赖、配置或环境变量变更
3. 对比工具列表变化，告诉我新增/删除了哪些工具
4. 重新构建并重启服务

Para documentação detalhada de uso, consulte skills/deploy-observability/SKILL.md.

Licença

Este projeto segue a mesma licença da versão original em Python.