内容
# scm-mcp-server
Palo Alto Networks Strata Cloud Manager (SCM) 的 MCP 服务器，通过 stdio 将 SCM REST API 暴露给 Claude、Cursor 等 AI 助手。
**当前版本**：Batch 1 MVP，共 **111 个 MCP 工具**，覆盖对象管理、安全规则、安全配置文件、运维操作、IAM 五个域。
---
## 前置条件
- Python 3.11+
- SCM 租户凭据：Client ID、Client Secret、TSG ID
（SCM 控制台 → Identity → Service Accounts 创建）
---
## 安装
```bash
git clone <此仓库>
cd scm-mcp-server
pip install -e ".[dev]"
```
---
## 配置环境变量
```bash
cp .env.example .env
# 编辑 .env，填入真实凭据
```
`.env` 内容：
```
SCM_CLIENT_ID=您的客户端ID
SCM_CLIENT_SECRET=您的客户端密钥
SCM_TSG_ID=您的TSG ID
SCM_BASE_URL=https://api.strata.paloaltonetworks.com # 可选，此为默认值
```
---
## 连通性自检
配置凭据后先跑自检，验证 token 获取和 SCM API 可达：
```bash
python -m scm_mcp_server.check
```
预期输出：
```
[检查] 正常 token 获取成功（前8个字符：eyJ0eXAi...）
[检查] 正常 GET /config/operations/v1/jobs → HTTP 200
[检查] 所有检查通过。
```
---
## 运行
```bash
# 直接运行（stdio 模式，供 MCP 客户端连接）
python -m scm_mcp_server
# 用 MCP Inspector 调试
mcp dev scm_mcp_server/server.py
```
---
## 在 Claude Desktop 注册
编辑 `~/Library/Application Support/Claude/claude_desktop_config.json`：
```json
{
"mcpServers": {
"scm": {
"command": "python",
"args": ["-m", "scm_mcp_server"],
"cwd": "/绝对路径/to/scm-mcp-server",
"env": {
"SCM_CLIENT_ID": "您的客户端ID",
"SCM_CLIENT_SECRET": "您的客户端密钥",
"SCM_TSG_ID": "您的TSG ID"
}
}
}
}
```
重启 Claude Desktop，在对话中询问 "列出可用工具" 确认 `list_addresses` 等工具已加载。
---
## 在 Cursor 注册
创建或编辑 `.cursor/mcp.json`：
```json
{
"mcpServers": {
"scm": {
"command": "python",
"args": ["-m", "scm_mcp_server"],
"cwd": "/绝对路径/to/scm-mcp-server",
"env": {
"SCM_CLIENT_ID": "您的客户端ID",
"SCM_CLIENT_SECRET": "您的客户端密钥",
"SCM_TSG_ID": "您的TSG ID"
}
}
}
}
```
重启 Cursor，在 Composer 中输入 `@scm` 确认工具可用。
---
## 可用工具列表（共 111 个，Batch 1 MVP）
> 标注 ⚠️ 的工具为写操作，**立即生效，不可通过本工具回滚**。
### 对象核心 — 地址 / 服务 / 标签 / 应用组 / EDL（35 个）
| 操作 | 资源 |
|------|------|
| 列出 / 获取 | addresses, address_groups, services, service_groups, tags, application_groups, external_dynamic_lists |
| ⚠️ 创建 / 更新 / 删除 | 同上 7 类资源 |
### 安全规则 — 安全 / 解密 / 应用覆盖 / DoS 规则（23 个）
| 操作 | 资源 |
|------|------|
| 列出 / 获取 | security_rules, decryption_rules, app_override_rules, dos_protection_rules |
| ⚠️ 创建 / 更新 / 删除 | 同上 4 类规则 |
| ⚠️ 移动 | security_rules, decryption_rules, app_override_rules（调整规则顺序） |
### 安全配置文件 — 安全配置文件（33 个，只读）
列出 / 获取 操作，涵盖：
anti_spyware_profiles, anti_spyware_signatures, data_filtering_profiles, data_objects, decryption_exclusions, decryption_profiles, dns_security_profiles, dos_protection_profiles, file_blocking_profiles, http_header_profiles, profile_groups, url_access_profiles, url_categories, url_filtering_categories（仅列出）, vulnerability_protection_profiles, vulnerability_protection_signatures, wildfire_anti_virus_profiles
### 操作 — 配置版本与任务（8 个）
| 操作 | 工具 |
|------|------|
| 只读 | list_jobs, get_job, list_config_versions, get_config_version, get_running_config_version |
| ⚠️ 写 | load_config_version（加载版本）, push_candidate_config（**高风险**：下发到真实设备）, delete_candidate_config |
### IAM — 身份与访问管理（12 个）
| 操作 | 资源 |
|------|------|
| 列出 / 获取 | service_accounts, roles, access_policies |
| ⚠️ 创建 / 更新 / 删除 | service_accounts |
| ⚠️ 创建 / 删除 | access_policies |
| ⚠️ 重置 | reset_service_account_secret（重置密钥） |
完整入参/出参映射见 [DESIGN.md](DESIGN.md)。
---
## 开发与测试
```bash
# 运行全部单元测试
pytest -v
# 语法自检（AST 解析全部 .py）
python scripts/syntax_check.py
# 路由完整性验证（路由表 key == 描述符名称集合）
python scripts/route_integrity.py
# stdio 冒烟（需配置 .env 凭据）
python scripts/smoke_stdio.py
```
---
## OpenAPI 规范
工具的 schema 来源为 `../pan.dev/openapi-specs/scm/`（相对本仓库父目录）：
```
openapi-specs/scm/
auth/AuthService.yaml
config/
sase/objects/objects-june.yaml
sase/security/security-services-R2-2026.yaml
sase/operations/config-operations-march.yaml
iam/
ServiceAccounts.yaml Roles.yaml AccessPolicies.yaml
```
**禁止修改规范文件**；如需更新请从上游 `pan.dev` 仓库同步。
