Metadata-Version: 2.4
Name: alibabacloud-observability-cloud-sso-mcp
Version: 0.3.0
Summary: aliyun observability mcp server
Requires-Python: >=3.10
Requires-Dist: alibabacloud-credentials>=1.0.1
Requires-Dist: alibabacloud-sls20201230==5.7.0
Requires-Dist: click
Requires-Dist: mcp>=1.3.0
Requires-Dist: pydantic>=2.10.0
Requires-Dist: python-dotenv
Requires-Dist: rich>=14.1.0
Requires-Dist: tenacity>=8.0.0
Description-Content-Type: text/markdown

## 阿里云可观测MCP服务
<p align="center">
  <a href="./README.md"><img alt="中文自述文件" src="https://img.shields.io/badge/简体中文-d9d9d9""></a>
  <a href="./README_EN.md"><img alt="英文自述文件" src="https://img.shields.io/badge/English-d9d9d9")
</p>

### 简介
git 
阿里云可观测 MCP服务，提供了一系列访问阿里云可观测各产品的工具能力，覆盖产品包含阿里云日志服务SLS、阿里云云监控等，任意支持 MCP 协议的智能体助手都可快速接入。

目前提供的 MCP 工具以阿里云日志服务为主，其他产品会陆续支持，工具详细如下:

### 版本记录
可以查看 [CHANGELOG.md](./CHANGELOG.md)

### 常见问题
可以查看 [FAQ.md](./FAQ.md)

### 工具列表
#### 日志相关
| 工具名称 | 用途 | 关键参数 | 最佳实践 |  
|---------|------|---------|---------|  
| `sls_list_projects` | 列出SLS项目，支持模糊搜索和分页 | `projectName`：项目名称（可选，模糊搜索）<br>`limit`：返回项目数量上限（默认50，范围1-100）<br>`regionId`：阿里云区域ID | - 在不确定可用项目时，首先使用此工具<br>- 使用合理的`limit`值避免返回过多结果 |  
| `sls_list_logstores` | 列出项目内的日志存储，支持名称模糊搜索 | `project`：SLS项目名称（必需）<br>`logStore`：日志存储名称（可选，模糊搜索）<br>`limit`：返回结果数量上限（默认10）<br>`isMetricStore`：是否筛选指标存储<br>`logStoreType`：日志存储类型<br>`regionId`：阿里云区域ID | - 确定项目后使用此工具查找相关日志存储<br>- 可通过`logStoreType`筛选特定类型日志存储 |  
| `sls_describe_logstore` | 检索日志存储的结构和索引信息 | `project`：SLS项目名称（必需）<br>`logStore`：SLS日志存储名称（必需）<br>`regionId`：阿里云区域ID | - 在查询前使用此工具了解可用字段及其类型<br>- 检查所需字段是否启用了索引 |  
| `sls_execute_sql_query` | 在指定时间范围内对日志存储执行SQL查询 | `project`：SLS项目名称（必需）<br>`logStore`：SLS日志存储名称（必需）<br>`query`：SQL查询语句（必需）<br>`fromTimestampInSeconds`：查询开始时间戳（必需）<br>`toTimestampInSeconds`：查询结束时间戳（必需）<br>`limit`：返回结果数量上限（默认10）<br>`regionId`：阿里云区域ID | - 使用适当的时间范围优化查询性能<br>- 限制返回结果数量避免获取过多数据 |  
| `sls_translate_text_to_sql_query` | 将自然语言描述转换为SLS SQL查询语句 | `text`：查询的自然语言描述（必需）<br>`project`：SLS项目名称（必需）<br>`logStore`：SLS日志存储名称（必需）<br>`regionId`：阿里云区域ID | - 适用于不熟悉SQL语法的用户<br>- 对于复杂查询，可能需要优化生成的SQL |  
| `sls_diagnose_query` | 诊断SLS查询问题，提供失败原因分析 | `query`：待诊断的SLS查询（必需）<br>`errorMessage`：查询失败的错误信息（必需）<br>`project`：SLS项目名称（必需）<br>`logStore`：SLS日志存储名称（必需）<br>`regionId`：阿里云区域ID | - 查询失败时使用此工具了解根本原因<br>- 根据诊断建议修改查询语句 |  

##### 指标相关

| 工具名称 | 用途 | 关键参数 | 最佳实践 |  
|---------|------|---------|---------|  
| `cms_translate_text_to_promql` | 将自然语言描述转换为PromQL查询语句 | `text`: 要转换的自然语言文本（必需）<br>`project`: SLS项目名称（必需）<br>`metricStore`: SLS指标存储名称（必需）<br>`regionId`: 阿里云区域ID（必需） | - 提供清晰、具体的指标描述<br>- 如已知，可在描述中提及特定的指标名称、标签或操作<br>- 排除项目或指标存储名称本身<br>- 检查并优化生成的查询以提高准确性和性能 |


### 权限要求

为了确保 MCP Server 能够成功访问和操作您的阿里云可观测性资源，您需要配置以下权限：

1.  **凭据配置**：
    *   服务使用[默认凭据链进行登录](https://www.alibabacloud.com/help/zh/sdk/developer-reference/v2-manage-python-access-credentials#62bf90d04dztq)，支持 Cloud SSO 等方式。
    *   请确保运行环境已正确配置阿里云凭据（如通过 `aliyun configure` 命令配置 Cloud SSO）。

2.  **RAM 授权 (重要)**：
    *   关联的 RAM 用户或角色**必须**被授予访问相关云服务所需的权限。
    *   **强烈建议遵循"最小权限原则"**：仅授予运行您计划使用的 MCP 工具所必需的最小权限集，以降低安全风险。
    *   根据您需要使用的工具，参考以下文档进行权限配置：
        *   **日志服务 (SLS)**：如果您需要使用 `sls_*` 相关工具，请参考 [日志服务权限说明](https://help.aliyun.com/zh/sls/overview-8)，并授予必要的读取、查询等权限。
    * 特殊权限说明，如果使用了SQL生成之类的工具，需要单独授予`sls:CallAiTools`的权限
    *   请根据您的实际应用场景，精细化配置所需权限。

  

### 使用说明


在使用 MCP Server 之前，需要先配置阿里云凭据（推荐使用 Cloud SSO），请参考 [默认凭据链](https://www.alibabacloud.com/help/zh/sdk/developer-reference/v2-manage-python-access-credentials#62bf90d04dztq)


#### 使用 uvx 安装运行
> ⚠️ 需要 Python 3.10 及以上版本，推荐使用 [uv](https://docs.astral.sh/uv/) 作为包管理器。

1. 使用 uvx 命令启动（可以指定版本号，会自动拉取对应依赖）：
```bash
uvx --from 'alibabacloud-observability-cloud-sso-mcp==0.3.0' alibabacloud-observability-cloud-sso-mcp
```

2. 使用 uvx 命令启动（默认最新版本）：

```bash
uvx run alibabacloud-observability-cloud-sso-mcp
```

可通过命令行传递指定参数:
- `--log-level` 指定日志级别，可选值为 `DEBUG`、`INFO`、`WARNING`、`ERROR`，默认值为 `INFO`

### 从源码安装

```bash
# clone 源码
git clone git@github.com:aliyun/alibabacloud-observability-mcp-server.git
# 进入源码目录
cd alibabacloud-observability-mcp-server
# 安装依赖
uv sync
# 运行
uv run alibabacloud-observability-cloud-sso-mcp
```


### AI 工具集成

#### Cursor，Cline 等集成
1. 使用 stdio 启动方式
   直接从源码目录启动,注意
    1. 需要指定 `--directory` 参数,指定源码目录，最好是绝对路径
    2. uv命令 最好也使用绝对路径，如果使用了虚拟环境，则需要使用虚拟环境的绝对路径
```json
{
  "mcpServers": {
    "alibaba_cloud_observability": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/your/alibabacloud-observability-mcp-server",
        "run",
        "alibabacloud-observability-cloud-sso-mcp"
      ]
    }
  }
}
```
2. 使用 stdio 启动方式-从 module 启动
```json
{
  "mcpServers": {
    "alibaba_cloud_observability": {
      "command": "uv",
      "args": [
        "run",
        "alibabacloud-observability-cloud-sso-mcp"
      ]
    }
  }
}
```


