Metadata-Version: 2.4
Name: aliyun-sls-mcp-py
Version: 0.1.3
Summary: MCP Server for Alibaba Cloud SLS (Log Service) - Pure Python
Author: dong_tech
License: MIT
Keywords: ai,aliyun,llm,log,mcp,model-context-protocol,sls
Requires-Python: >=3.10
Requires-Dist: aliyun-log-python-sdk>=0.8.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# Aliyun SLS MCP Server (Pure Python)

阿里云 SLS (日志服务) MCP Server - 纯 Python 实现

## 特点

- **纯 Python**: 无需 Node.js/npm
- **零安装**: 通过 `uvx` 或 `pipx` 直接运行
- **轻量级**: 仅依赖 `mcp` 和 `aliyun-log-python-sdk`
- **FastMCP**: 使用官方 Python SDK 的高级 API

## 安装与使用

### 方式一: uvx (推荐)

```bash
# 直接运行 (自动安装依赖)
export SLS_ENDPOINT=cn-hangzhou.log.aliyuncs.com
export SLS_ACCESS_KEY_ID=your-access-key-id
export SLS_ACCESS_KEY_SECRET=your-access-key-secret
export SLS_PROJECT=your-project

uvx aliyun-sls-mcp-py
```

### 方式二: pipx

```bash
pipx run aliyun-sls-mcp-py
```

### 方式三: pip 安装

```bash
pip install aliyun-sls-mcp-py

# 运行
SLS_ENDPOINT=xxx SLS_ACCESS_KEY_ID=xxx SLS_ACCESS_KEY_SECRET=xxx SLS_PROJECT=xxx \
    aliyun-sls-mcp-py
```

### 方式四: Claude Desktop 配置

编辑 `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "aliyun-sls": {
      "command": "uvx",
      "args": ["aliyun-sls-mcp-py"],
      "env": {
        "SLS_ENDPOINT": "cn-hangzhou.log.aliyuncs.com",
        "SLS_ACCESS_KEY_ID": "your-access-key-id",
        "SLS_ACCESS_KEY_SECRET": "your-access-key-secret",
        "SLS_PROJECT": "your-project",
        "SLS_LOGSTORE": "your-default-logstore"
      }
    }
  }
}
```

### 方式五: Cursor IDE 配置

编辑 `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "aliyun-sls": {
      "command": "uvx",
      "args": ["aliyun-sls-mcp-py"],
      "env": {
        "SLS_ENDPOINT": "cn-hangzhou.log.aliyuncs.com",
        "SLS_ACCESS_KEY_ID": "your-access-key-id",
        "SLS_ACCESS_KEY_SECRET": "your-access-key-secret",
        "SLS_PROJECT": "your-project"
      }
    }
  }
}
```

## 环境变量

| 变量名 | 必填 | 说明 |
|--------|------|------|
| `SLS_ENDPOINT` | 是 | SLS 服务端点，如 `cn-hangzhou.log.aliyuncs.com` |
| `SLS_ACCESS_KEY_ID` | 是 | 阿里云 AccessKey ID |
| `SLS_ACCESS_KEY_SECRET` | 是 | 阿里云 AccessKey Secret |
| `SLS_PROJECT` | 是 | SLS 项目名称 |
| `SLS_LOGSTORE` | 否 | 默认日志库名称 |

## 提供的工具

### 1. list_logstores

列出当前项目下所有的日志库

```
无需参数
```

### 2. query_logs

查询 SLS 日志（支持分页）

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `query` | string | 是 | SLS 查询语句 |
| `logstore` | string | 否 | 日志库名称 |
| `from_time` | string | 否 | 开始时间 (默认 -1h) |
| `to_time` | string | 否 | 结束时间 (默认 now) |
| `limit` | int | 否 | 每页条数 (默认 100, 最大 500) |
| `offset` | int | 否 | 偏移量 (默认 0) |

### 3. search_keyword

搜索包含关键字的日志

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `keyword` | string | 是 | 搜索关键字 |
| `logstore` | string | 否 | 日志库名称 |
| `from_time` | string | 否 | 开始时间 (默认 -24h) |
| `to_time` | string | 否 | 结束时间 (默认 now) |
| `limit` | int | 否 | 每页条数 (默认 20) |
| `offset` | int | 否 | 偏移量 (默认 0) |

### 4. analyze_errors

分析错误日志

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `logstore` | string | 否 | 日志库名称 |
| `from_time` | string | 否 | 开始时间 (默认 -24h) |
| `to_time` | string | 否 | 结束时间 (默认 now) |
| `top_n` | int | 否 | 返回前N个高频错误 (默认 10) |

## 提供的资源

- `sls://config` - 当前 SLS 配置信息
- `sls://help` - SLS 查询语法帮助
- `sls://logstores` - 所有日志库列表

## 提供的提示词

- `analyze_errors_prompt` - 错误日志分析提示词
- `search_logs_prompt` - 日志搜索提示词

## 时间格式支持

支持多种时间格式:

| 格式 | 示例 | 说明 |
|------|------|------|
| 相对时间 | `-1h`, `-30m`, `-7d` | 1小时前、30分钟前、7天前 |
| 当前时间 | `now` | 当前时间戳 |
| ISO 格式 | `2024-01-01T00:00:00` | ISO 8601 格式 |
| Unix 时间戳 | `1704067200` | 秒或毫秒时间戳 |

## 开发

```bash
# 克隆项目
git clone https://github.com/dongmaowei/aliyun-sls-mcp-py.git
cd aliyun-sls-mcp-py

# 使用 uv 创建虚拟环境
uv venv
source .venv/bin/activate  # Linux/macOS
# .venv\Scripts\activate   # Windows

# 安装依赖
uv sync

# 开发模式运行
uv run mcp dev src/aliyun_sls_mcp_py/server.py

# 直接运行
uv run python -m aliyun_sls_mcp_py.server
```

## 测试

```bash
# 运行测试
uv run pytest

# 测试 MCP 服务器
uv run mcp dev src/aliyun_sls_mcp_py/server.py
```

## 发布到 PyPI

```bash
# 安装构建工具
uv pip install build twine

# 构建
python -m build

# 上传到 PyPI
twine upload dist/*

# 或使用 uv
uv publish
```

## 三种方案对比

| 特性 | Python + npm 混合 | 纯 Node.js | 纯 Python |
|------|------------------|------------|-----------|
| **依赖** | Python + uv + npm | Node.js | Python + uv |
| **启动** | `npx -y @scope/pkg` | `npx -y @scope/pkg` | `uvx pkg` |
| **包大小** | 较大 | 小 | 中 |
| **开发效率** | 高 | 中 | 高 |
| **SDK 成熟度** | FastMCP | 底层 API | FastMCP |
| **适用场景** | npm 生态用户 | 前端团队 | Python 生态用户 |

## License

MIT
