zstack-mcp-server 0.1.0__tar.gz

zstack_mcp_server-0.1.0/.gitignore

@@ -0,0 +1,135 @@
+# ==========================
+# Python 核心忽略项
+# ==========================
+# 字节码编译文件 (Python 自动生成的缓存)
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C 扩展编译文件
+*.so
+
+# ==========================
+# 包分发与构建 (Distribution / Packaging)
+# ==========================
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# ==========================
+# 虚拟环境 (Virtual Environments)
+# ==========================
+# 常见的虚拟环境目录名
+venv/
+.venv/
+env/
+.env/
+ENV/
+env.bak/
+venv.bak/
+
+# ==========================
+# 单元测试与代码覆盖率 (Unit Test / Coverage)
+# ==========================
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# ==========================
+# IDE 与 编辑器配置 (IDE / Editor)
+# ==========================
+# VS Code
+.vscode/
+!.vscode/settings.json
+!.vscode/tasks.json
+!.vscode/launch.json
+!.vscode/extensions.json
+*.code-workspace
+
+# PyCharm / IntelliJ IDEA
+.idea/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# ==========================
+# 环境变量与敏感信息 (Environment Variables)
+# ==========================
+# 极其重要！防止 API Key 或数据库密码泄露
+.env
+.env.local
+.env.*
+config/zstack.env
+
+# ==========================
+# 常用框架特定文件
+# ==========================
+# Django
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+media/
+
+# Flask
+instance/
+.webassets-cache
+
+# Scrapy
+.scrapy
+
+# ==========================
+# 操作系统生成文件 (OS Generated)
+# ==========================
+# macOS
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Windows
+Thumbs.db
+ehthumbs.db
+Desktop.ini
+
+# ==========================
+# 类型检查 (Type Checking)
+# ==========================
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# ==========================
+# 文档生成 (Sphinx)
+# ==========================
+docs/_build/
+target/
+
+# ==========================
+# 本项目特定临时文件
+# ==========================
+run_complex_tests_output.json

zstack_mcp_server-0.1.0/PKG-INFO

@@ -0,0 +1,302 @@
+Metadata-Version: 2.4
+Name: zstack-mcp-server
+Version: 0.1.0
+Summary: MCP Server for ZStack Cloud API - enables AI to dynamically query and execute 2000+ ZStack APIs
+Author-email: ZStack <support@zstack.io>
+License-Expression: MIT
+Keywords: ai,api,cloud,mcp,zstack
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: mcp[cli]>=1.0.0
+Description-Content-Type: text/markdown
+
+# ZStack MCP Server
+
+让 AI 能够动态查询和调用 ZStack Cloud 的 2000+ API 的 MCP Server。
+
+## 功能特性
+
+- **API 搜索**: 根据关键词搜索 ZStack API，支持模糊匹配
+- **API 描述**: 获取 API 的详细参数说明
+- **API 执行**: 执行 ZStack API 并返回结果
+- **监控指标搜索**: 搜索可用的监控指标
+- **监控数据获取**: 获取指定指标的监控数据
+
+## 安装
+
+```bash
+# 使用 pip 安装
+pip install -e .
+
+# 或者使用 uv
+uv pip install -e .
+```
+
+## 配置
+
+设置以下环境变量：
+
+```bash
+export ZSTACK_API_URL="http://localhost:8080"  # ZStack API 地址
+export ZSTACK_ALLOW_ALL_API="false"             # 是否允许写操作（可选，默认 false）
+
+# 认证方式一：用户名密码（会自动登录获取 Session）
+export ZSTACK_ACCOUNT="admin"                   # 账户名
+export ZSTACK_PASSWORD="your-password"          # 密码（明文）
+
+# 认证方式二：直接传入 SessionID（优先级更高，设置后忽略用户名密码）
+export ZSTACK_SESSION_ID="your-session-uuid"    # 已有的 Session UUID
+```
+
+### 认证方式说明
+
+| 方式 | 环境变量 | 说明 |
+|------|----------|------|
+| 用户名密码 | `ZSTACK_ACCOUNT` + `ZSTACK_PASSWORD` | 自动登录获取 Session |
+| Session ID | `ZSTACK_SESSION_ID` | 直接使用已有 Session（优先级更高） |
+
+> 💡 如果同时设置了 `ZSTACK_SESSION_ID` 和用户名密码，会优先使用 Session ID
+
+### 安全说明
+
+**默认情况下，只允许调用只读 API**，包括：
+- `Query*` - 查询类
+- `Get*` - 获取类  
+- `List*` - 列表类
+- `Describe*` - 描述类
+- `Check*` - 检查类
+- `Count*` - 计数类
+- 其他只读操作...
+
+如需调用写操作 API（如 `CreateVmInstance`、`DeleteVolume` 等），需要设置：
+```bash
+export ZSTACK_ALLOW_ALL_API="true"
+```
+
+⚠️ **警告**: 启用写操作后，AI 可以执行创建、删除、修改等危险操作，请谨慎使用！
+
+## 使用方式
+
+### 作为 MCP Server 运行
+
+```bash
+# 直接运行
+python -m zstack_mcp.server
+
+# 或使用入口点
+zstack-mcp
+```
+
+### SSE 模式运行
+
+默认使用 stdio 传输。若需 SSE 模式，可用命令行或环境变量切换：
+
+```bash
+# 命令行方式
+zstack-mcp --transport sse --host 0.0.0.0 --port 8000
+
+# 环境变量方式
+export MCP_TRANSPORT="sse"
+export MCP_HOST="0.0.0.0"
+export MCP_PORT="8000"
+export MCP_PATH="/sse"  # 可选
+zstack-mcp
+```
+
+> 说明：也兼容 `FASTMCP_HOST` / `FASTMCP_PORT` / `FASTMCP_MOUNT_PATH`（FastMCP 原生环境变量）
+
+### Streamable HTTP 模式运行
+
+```bash
+# 命令行方式
+zstack-mcp --transport streamable-http --host 0.0.0.0 --port 8000 --streamable-path /mcp
+
+# 环境变量方式
+export MCP_TRANSPORT="streamable-http"
+export MCP_HOST="0.0.0.0"
+export MCP_PORT="8000"
+export MCP_STREAMABLE_PATH="/mcp"  # 可选
+zstack-mcp
+```
+
+> 说明：也兼容 `FASTMCP_STREAMABLE_HTTP_PATH`
+
+### 在 Claude Desktop 中配置
+
+在 `claude_desktop_config.json` 中添加：
+
+**方式一：使用用户名密码**
+```json
+{
+  "mcpServers": {
+    "zstack": {
+      "command": "python",
+      "args": ["-m", "zstack_mcp.server"],
+      "env": {
+        "ZSTACK_API_URL": "http://your-zstack-server:8080",
+        "ZSTACK_ACCOUNT": "admin",
+        "ZSTACK_PASSWORD": "your-password",
+        "ZSTACK_ALLOW_ALL_API": "false"
+      }
+    }
+  }
+}
+```
+
+**方式二：使用 Session ID**
+```json
+{
+  "mcpServers": {
+    "zstack": {
+      "command": "python",
+      "args": ["-m", "zstack_mcp.server"],
+      "env": {
+        "ZSTACK_API_URL": "http://your-zstack-server:8080",
+        "ZSTACK_SESSION_ID": "your-session-uuid",
+        "ZSTACK_ALLOW_ALL_API": "false"
+      }
+    }
+  }
+}
+```
+
+> 💡 将 `ZSTACK_ALLOW_ALL_API` 设为 `"true"` 可启用写操作（创建/删除/修改等）
+
+## 可用工具
+
+### 1. search_api
+
+根据关键词搜索 ZStack API。
+
+**参数**:
+- `keywords` (list[str]): 搜索关键词，如 `["Query", "Vm"]`
+- `category` (str, 可选): 按分类过滤
+- `limit` (int, 默认 15): 最多返回数量
+
+### 2. describe_api
+
+获取指定 API 的详细参数说明。
+
+**参数**:
+- `api_name` (str): API 名称，如 `"QueryVmInstance"`
+
+### 3. execute_api
+
+执行 ZStack API。
+
+**参数**:
+- `api_name` (str): API 名称
+- `parameters` (dict): API 参数
+
+### 4. search_metric
+
+搜索可用的监控指标。
+
+**参数**:
+- `keywords` (list[str]): 搜索关键词
+- `namespace` (str, 可选): 按命名空间过滤（支持模糊匹配，如 `vm`/`host`）
+- `limit` (int, 默认 20): 最多返回数量
+- `match_mode` (str, 默认 `or`): 关键词匹配模式（`and`/`or`）
+- `prefer_namespaces` (list[str], 可选): 优先排序的命名空间列表（默认 `["ZStack/VM","ZStack/Host"]`）
+
+> 💡 提示：不确定 namespace 时可先不传，返回结果会带 namespace 值供选择
+> 💡 默认 `match_mode=or`（多关键词并集）；如需交集请显式传 `and`
+> 💡 指标名称在不同 namespace 可能重名，建议指定 `namespace` 或 `prefer_namespaces` 以确保排序优先
+
+### 5. get_metric_data
+
+获取监控数据。
+
+**参数**:
+- `namespace` (str): 命名空间
+- `metric_name` (str): 指标名称
+- `start_time` (str|int, 可选): 开始时间 (ISO 或秒级时间戳)
+- `end_time` (str|int, 可选): 结束时间 (ISO 或秒级时间戳)
+- `period` (int, 默认 60): 采样周期(秒)
+- `labels` (list[str]|dict, 可选): 标签过滤，如 `["VMUuid=xxx"]` 或 `{"VMUuid":"xxx"}`
+- `summary_only` (bool, 可选): 仅返回统计信息（点数/最大/最小/平均/方差/标准差）
+
+**数据量提示**:
+- 返回点数估算：`ceil((end_time - start_time) / period) * series_count`
+- `series_count` 为不同 label 组合数量；不传 `labels` 时可能返回多组序列
+- 建议通过缩短时间范围、增大 `period` 或增加 `labels` 过滤避免输出过大
+
+### 6. get_metric_summary
+
+获取监控指标的聚合 TopN（按 label_key 分组）。
+
+**参数**:
+- `namespace` (str): 命名空间
+- `metric_name` (str): 指标名称
+- `label_key` (str): 标签键，如 `VMUuid`/`HostUuid`
+- `metric_names` (list[str], 可选): 多指标合并（如 in/out）
+- `start_time` (str|int, 可选): 开始时间 (ISO 或秒级时间戳)
+- `end_time` (str|int, 可选): 结束时间 (ISO 或秒级时间戳)
+- `period` (int, 默认 60): 采样周期(秒)
+- `aggregate` (str, 默认 max): 单指标聚合方式 (max/avg/sum/min)
+- `combine` (str, 默认 sum): 多指标合并方式 (sum/avg/max/min)
+- `threshold_op` (str, 可选): 阈值比较符 (>,>=,<,<=,==,!=)
+- `threshold_value` (number, 可选): 阈值数值
+- `top_n` (int, 默认 10): 返回条数
+- `resolve_resource` (str, 可选): `vm` 或 `host`，用于解析名称
+
+## Query API 条件语法
+
+对于 Query 类 API，`conditions` 参数支持以下操作符：
+
+| 操作符 | 含义 | 示例 |
+|--------|------|------|
+| `=` | 等于 | `name=test` |
+| `!=` | 不等于 | `state!=Deleted` |
+| `>` | 大于 | `cpuNum>4` |
+| `>=` | 大于等于 | `memorySize>=1073741824` |
+| `<` | 小于 | `createDate<2024-01-01` |
+| `<=` | 小于等于 | |
+| `?=` | 模糊匹配(LIKE，部分版本为 `like`) | `name?=%test%` |
+| `!?=` | 模糊不匹配 | |
+| `~=` | 正则匹配 | `name~=.*test.*` |
+| `!~=` | 正则不匹配 | |
+| `=null` | 为空 | `description=null` |
+| `!=null` | 不为空 | |
+| `in` | 在列表中 | `state?=Running,Stopped` |
+| `not in` | 不在列表中 | `state!?=Deleted,Destroyed` |
+
+**conditions 格式**:
+```json
+{
+    "conditions": [
+        {"name": "uuid", "op": "=", "value": "xxx"},
+        {"name": "state", "op": "in", "value": "Running,Stopped"}
+    ]
+}
+```
+
+## 示例交互
+
+用户问: "帮我查一下 UUID 为 ae6e57a0 开头的 VM 的详情"
+
+AI 会:
+1. 调用 `search_api(keywords=["Query", "Vm", "Instance"])`
+2. 调用 `describe_api(api_name="QueryVmInstance")`
+3. 调用 `execute_api(api_name="QueryVmInstance", parameters={"conditions": [{"name": "uuid", "op": "?=", "value": "ae6e57a0%"}]})`
+
+## 开发
+
+```bash
+# 安装开发依赖
+pip install -e ".[dev]"
+
+# 运行测试
+pytest
+```
+
+## License
+
+MIT
+

zstack_mcp_server-0.1.0/README.md

@@ -0,0 +1,284 @@
+# ZStack MCP Server
+
+让 AI 能够动态查询和调用 ZStack Cloud 的 2000+ API 的 MCP Server。
+
+## 功能特性
+
+- **API 搜索**: 根据关键词搜索 ZStack API，支持模糊匹配
+- **API 描述**: 获取 API 的详细参数说明
+- **API 执行**: 执行 ZStack API 并返回结果
+- **监控指标搜索**: 搜索可用的监控指标
+- **监控数据获取**: 获取指定指标的监控数据
+
+## 安装
+
+```bash
+# 使用 pip 安装
+pip install -e .
+
+# 或者使用 uv
+uv pip install -e .
+```
+
+## 配置
+
+设置以下环境变量：
+
+```bash
+export ZSTACK_API_URL="http://localhost:8080"  # ZStack API 地址
+export ZSTACK_ALLOW_ALL_API="false"             # 是否允许写操作（可选，默认 false）
+
+# 认证方式一：用户名密码（会自动登录获取 Session）
+export ZSTACK_ACCOUNT="admin"                   # 账户名
+export ZSTACK_PASSWORD="your-password"          # 密码（明文）
+
+# 认证方式二：直接传入 SessionID（优先级更高，设置后忽略用户名密码）
+export ZSTACK_SESSION_ID="your-session-uuid"    # 已有的 Session UUID
+```
+
+### 认证方式说明
+
+| 方式 | 环境变量 | 说明 |
+|------|----------|------|
+| 用户名密码 | `ZSTACK_ACCOUNT` + `ZSTACK_PASSWORD` | 自动登录获取 Session |
+| Session ID | `ZSTACK_SESSION_ID` | 直接使用已有 Session（优先级更高） |
+
+> 💡 如果同时设置了 `ZSTACK_SESSION_ID` 和用户名密码，会优先使用 Session ID
+
+### 安全说明
+
+**默认情况下，只允许调用只读 API**，包括：
+- `Query*` - 查询类
+- `Get*` - 获取类  
+- `List*` - 列表类
+- `Describe*` - 描述类
+- `Check*` - 检查类
+- `Count*` - 计数类
+- 其他只读操作...
+
+如需调用写操作 API（如 `CreateVmInstance`、`DeleteVolume` 等），需要设置：
+```bash
+export ZSTACK_ALLOW_ALL_API="true"
+```
+
+⚠️ **警告**: 启用写操作后，AI 可以执行创建、删除、修改等危险操作，请谨慎使用！
+
+## 使用方式
+
+### 作为 MCP Server 运行
+
+```bash
+# 直接运行
+python -m zstack_mcp.server
+
+# 或使用入口点
+zstack-mcp
+```
+
+### SSE 模式运行
+
+默认使用 stdio 传输。若需 SSE 模式，可用命令行或环境变量切换：
+
+```bash
+# 命令行方式
+zstack-mcp --transport sse --host 0.0.0.0 --port 8000
+
+# 环境变量方式
+export MCP_TRANSPORT="sse"
+export MCP_HOST="0.0.0.0"
+export MCP_PORT="8000"
+export MCP_PATH="/sse"  # 可选
+zstack-mcp
+```
+
+> 说明：也兼容 `FASTMCP_HOST` / `FASTMCP_PORT` / `FASTMCP_MOUNT_PATH`（FastMCP 原生环境变量）
+
+### Streamable HTTP 模式运行
+
+```bash
+# 命令行方式
+zstack-mcp --transport streamable-http --host 0.0.0.0 --port 8000 --streamable-path /mcp
+
+# 环境变量方式
+export MCP_TRANSPORT="streamable-http"
+export MCP_HOST="0.0.0.0"
+export MCP_PORT="8000"
+export MCP_STREAMABLE_PATH="/mcp"  # 可选
+zstack-mcp
+```
+
+> 说明：也兼容 `FASTMCP_STREAMABLE_HTTP_PATH`
+
+### 在 Claude Desktop 中配置
+
+在 `claude_desktop_config.json` 中添加：
+
+**方式一：使用用户名密码**
+```json
+{
+  "mcpServers": {
+    "zstack": {
+      "command": "python",
+      "args": ["-m", "zstack_mcp.server"],
+      "env": {
+        "ZSTACK_API_URL": "http://your-zstack-server:8080",
+        "ZSTACK_ACCOUNT": "admin",
+        "ZSTACK_PASSWORD": "your-password",
+        "ZSTACK_ALLOW_ALL_API": "false"
+      }
+    }
+  }
+}
+```
+
+**方式二：使用 Session ID**
+```json
+{
+  "mcpServers": {
+    "zstack": {
+      "command": "python",
+      "args": ["-m", "zstack_mcp.server"],
+      "env": {
+        "ZSTACK_API_URL": "http://your-zstack-server:8080",
+        "ZSTACK_SESSION_ID": "your-session-uuid",
+        "ZSTACK_ALLOW_ALL_API": "false"
+      }
+    }
+  }
+}
+```
+
+> 💡 将 `ZSTACK_ALLOW_ALL_API` 设为 `"true"` 可启用写操作（创建/删除/修改等）
+
+## 可用工具
+
+### 1. search_api
+
+根据关键词搜索 ZStack API。
+
+**参数**:
+- `keywords` (list[str]): 搜索关键词，如 `["Query", "Vm"]`
+- `category` (str, 可选): 按分类过滤
+- `limit` (int, 默认 15): 最多返回数量
+
+### 2. describe_api
+
+获取指定 API 的详细参数说明。
+
+**参数**:
+- `api_name` (str): API 名称，如 `"QueryVmInstance"`
+
+### 3. execute_api
+
+执行 ZStack API。
+
+**参数**:
+- `api_name` (str): API 名称
+- `parameters` (dict): API 参数
+
+### 4. search_metric
+
+搜索可用的监控指标。
+
+**参数**:
+- `keywords` (list[str]): 搜索关键词
+- `namespace` (str, 可选): 按命名空间过滤（支持模糊匹配，如 `vm`/`host`）
+- `limit` (int, 默认 20): 最多返回数量
+- `match_mode` (str, 默认 `or`): 关键词匹配模式（`and`/`or`）
+- `prefer_namespaces` (list[str], 可选): 优先排序的命名空间列表（默认 `["ZStack/VM","ZStack/Host"]`）
+
+> 💡 提示：不确定 namespace 时可先不传，返回结果会带 namespace 值供选择
+> 💡 默认 `match_mode=or`（多关键词并集）；如需交集请显式传 `and`
+> 💡 指标名称在不同 namespace 可能重名，建议指定 `namespace` 或 `prefer_namespaces` 以确保排序优先
+
+### 5. get_metric_data
+
+获取监控数据。
+
+**参数**:
+- `namespace` (str): 命名空间
+- `metric_name` (str): 指标名称
+- `start_time` (str|int, 可选): 开始时间 (ISO 或秒级时间戳)
+- `end_time` (str|int, 可选): 结束时间 (ISO 或秒级时间戳)
+- `period` (int, 默认 60): 采样周期(秒)
+- `labels` (list[str]|dict, 可选): 标签过滤，如 `["VMUuid=xxx"]` 或 `{"VMUuid":"xxx"}`
+- `summary_only` (bool, 可选): 仅返回统计信息（点数/最大/最小/平均/方差/标准差）
+
+**数据量提示**:
+- 返回点数估算：`ceil((end_time - start_time) / period) * series_count`
+- `series_count` 为不同 label 组合数量；不传 `labels` 时可能返回多组序列
+- 建议通过缩短时间范围、增大 `period` 或增加 `labels` 过滤避免输出过大
+
+### 6. get_metric_summary
+
+获取监控指标的聚合 TopN（按 label_key 分组）。
+
+**参数**:
+- `namespace` (str): 命名空间
+- `metric_name` (str): 指标名称
+- `label_key` (str): 标签键，如 `VMUuid`/`HostUuid`
+- `metric_names` (list[str], 可选): 多指标合并（如 in/out）
+- `start_time` (str|int, 可选): 开始时间 (ISO 或秒级时间戳)
+- `end_time` (str|int, 可选): 结束时间 (ISO 或秒级时间戳)
+- `period` (int, 默认 60): 采样周期(秒)
+- `aggregate` (str, 默认 max): 单指标聚合方式 (max/avg/sum/min)
+- `combine` (str, 默认 sum): 多指标合并方式 (sum/avg/max/min)
+- `threshold_op` (str, 可选): 阈值比较符 (>,>=,<,<=,==,!=)
+- `threshold_value` (number, 可选): 阈值数值
+- `top_n` (int, 默认 10): 返回条数
+- `resolve_resource` (str, 可选): `vm` 或 `host`，用于解析名称
+
+## Query API 条件语法
+
+对于 Query 类 API，`conditions` 参数支持以下操作符：
+
+| 操作符 | 含义 | 示例 |
+|--------|------|------|
+| `=` | 等于 | `name=test` |
+| `!=` | 不等于 | `state!=Deleted` |
+| `>` | 大于 | `cpuNum>4` |
+| `>=` | 大于等于 | `memorySize>=1073741824` |
+| `<` | 小于 | `createDate<2024-01-01` |
+| `<=` | 小于等于 | |
+| `?=` | 模糊匹配(LIKE，部分版本为 `like`) | `name?=%test%` |
+| `!?=` | 模糊不匹配 | |
+| `~=` | 正则匹配 | `name~=.*test.*` |
+| `!~=` | 正则不匹配 | |
+| `=null` | 为空 | `description=null` |
+| `!=null` | 不为空 | |
+| `in` | 在列表中 | `state?=Running,Stopped` |
+| `not in` | 不在列表中 | `state!?=Deleted,Destroyed` |
+
+**conditions 格式**:
+```json
+{
+    "conditions": [
+        {"name": "uuid", "op": "=", "value": "xxx"},
+        {"name": "state", "op": "in", "value": "Running,Stopped"}
+    ]
+}
+```
+
+## 示例交互
+
+用户问: "帮我查一下 UUID 为 ae6e57a0 开头的 VM 的详情"
+
+AI 会:
+1. 调用 `search_api(keywords=["Query", "Vm", "Instance"])`
+2. 调用 `describe_api(api_name="QueryVmInstance")`
+3. 调用 `execute_api(api_name="QueryVmInstance", parameters={"conditions": [{"name": "uuid", "op": "?=", "value": "ae6e57a0%"}]})`
+
+## 开发
+
+```bash
+# 安装开发依赖
+pip install -e ".[dev]"
+
+# 运行测试
+pytest
+```
+
+## License
+
+MIT
+