内容
# 凤凰安全MCP服务器（橙色）
**为 [凤凰安全](https://phoenix.security) 平台提供的MCP（模型上下文协议）服务器。** 为 Claude、Cursor 和任何支持MCP的AI代理提供完整的可见性，涵盖您的安全态势 — 资产、漏洞、应用程序、风险 — **只需一个API密钥**。
构建于与 [凤凰安全命令行工具](https://github.com/Security-Phoenix-demo/Phoenix-Security-CLI) 相同的客户端库之上，涵盖凤凰安全REST API **企业版v1.27**。
## 您的AI代理可以执行的操作
**读取/分析（15种工具）**
- `phoenix_search_findings` — 每个v1.27筛选器：严重性、CVE、EPSS、SLA违规、扫描器、标签、团队…
- `phoenix_search_assets`、`phoenix_get_asset`、`phoenix_get_finding`
- `phoenix_list_applications`、`phoenix_get_application_posture` — 风险桶、阈值
- `phoenix_list_components`、`phoenix_get_component_posture`
- `phoenix_list_teams`、`phoenix_get_team_members`、`phoenix_list_users`
- `phoenix_api_gaps` — 告诉代理API **无法**执行的操作，并提供变通方法和所需的端点愿望清单（[完整规范](https://github.com/Security-Phoenix-demo/Phoenix-Security-CLI/blob/main/docs/REQUIRED_ENDPOINTS.md)），以便它永远不会猜测
- `phoenix_raw_api` — 经过身份验证的逃生通道，适用于任何 `/v1` 端点
- `phoenix_test_connection`
**写入/自动化（19种工具，通过 `PHOENIX_MCP_READ_ONLY=true` 禁用）**
- 资产生命周期：`phoenix_create_asset`、`phoenix_update_asset` （增量编辑）、`phoenix_enrich_asset`、`phoenix_add_asset_tags`
- 漏洞生命周期：`phoenix_add_finding` （增量）、`phoenix_close_finding` （合并变通方法、干预支持）、`phoenix_enrich_finding`、批量 `phoenix_import_assets`
- 结构：`phoenix_create_application`、`phoenix_update_application`、`phoenix_add_application_tags`、`phoenix_create_component`、`phoenix_add_component_rules`、`phoenix_link_repository`
- 人员：`phoenix_create_team`、`phoenix_add_team_members`、`phoenix_set_team_auto_link_tags`、`phoenix_create_user`、`phoenix_set_users_active`
安装后示例提示：
> *"哪些应用程序存在违反SLA的关键发现？按团队总结。*
> *"为 myorg/api:2.1 创建一个 CONTAINER 资产，标签为 env:prod，并将 org/api 存储库链接到 Payments 应用程序。*
> *"用三级笔记丰富 CVE-2024-3094 发现结果，并将严重性提升至 9.8。*
## 快速安装
需要 Python 3.10+ 和 [uv](https://docs.astral.sh/uv/) （或 pipx/pip）。
在凤凰安全平台下 **组织 → API 访问** 中创建 API 凭证。
### Claude 代码
```bash
claude mcp add phoenix-security \
-e PHOENIX_CLIENT_ID=您的客户端ID \
-e PHOENIX_CLIENT_SECRET=您的客户端密钥 \
-e PHOENIX_API_BASE_URL=https://api.securityphoenix.cloud \
-- uvx --from git+https://github.com/Security-Phoenix-demo/Pheonix-Security-Orange-MPC phoenix-mcp
```
### Claude 桌面版
添加到 `claude_desktop_config.json` （设置 → 开发者 → 编辑配置）：
```json
{
"mcpServers": {
"phoenix-security": {
"command": "uvx",
"args": ["--from", "git+https://github.com/Security-Phoenix-demo/Pheonix-Security-Orange-MPC", "phoenix-mcp"],
"env": {
"PHOENIX_CLIENT_ID": "您的客户端ID",
"PHOENIX_CLIENT_SECRET": "您的客户端密钥",
"PHOENIX_API_BASE_URL": "https://api.securityphoenix.cloud"
}
}
}
}
```
### Cursor / Windsurf / 其他MCP客户端
在客户端的MCP配置（例如 `.cursor/mcp.json` ）中使用相同的 `command`/`args`/`env` 格式。针对每个客户端的完整演练，以及pipx/pip和源码安装： **[docs/INSTALLATION.md](docs/INSTALLATION.md)**。
## AI平台技能
为 **Claude、ChatGPT（自定义GPT和MCP连接器）、OpenAI Codex和Cursor** 准备的技能包装了此服务器 + 命令行工具 — 包含共享的剧本，用于查找资产、漏洞、补丁、易受攻击的漏洞、应用程序报告、团队风险和资产/发现结果丰富： **[skills/](skills/)**。
对于ChatGPT连接器和其他远程客户端，服务器还通过HTTP运行：`phoenix-mcp --transport streamable-http --port 8848` （保持在TLS +身份验证之后；参见 [skills/chatgpt/README.md](skills/chatgpt/README.md)）。
## 配置
| 环境变量 | 必需 | 描述 |
| --- | --- | --- |
| `PHOENIX_CLIENT_ID` | ✅ | API客户端ID（组织 → API访问） |
| `PHOENIX_CLIENT_SECRET` | ✅ | API客户端密钥（创建时显示一次） |
| `PHOENIX_API_BASE_URL` | — | 默认 `https://api.securityphoenix.cloud`；演示：`https://api.demo.appsecphx.io`；PoC：`https://api.poc1.appsecphx.io`；专用：`https://api.<tenant>.securityphoenix.cloud` |
| `PHOENIX_MCP_READ_ONLY` | — | `true` = 禁用所有写入工具（建议首先启用） |
| `PHOENIX_MCP_MAX_ITEMS` | — | 列表结果的默认上限（默认100） |
| `PHOENIX_MCP_ENV_FILE` | — | `.env` 文件的显式路径，用于加载 |
凭证也可以存放在 **`.env` 文件**（`cp .env.example .env`，然后编辑）中 — 服务器自动从工作目录或父目录加载它，而不会覆盖实际环境变量。`.env` 被 git 忽略；请勿提交它。
## 设计笔记
- **干净的输入/输出边界** — 工具接受纯JSON参数并返回平台JSON；令牌处理、重试（`Retry-After` 感知）、分页和凤凰安全平台有效载荷怪癖均保留在内部。
- **间隙被标记，而不是隐藏** — 凤凰安全平台API无法执行的操作（每个发现状态更新、资产删除、应用程序删除等）通过 `phoenix_api_gaps` 公开，以便代理选择文档化的变通方法，而不是凭空捏造端点。
- **写入的最小意外** — 破坏性操作遵循只读模式；资产/发现写入通过导入管道，类似于官方凤凰安全平台工具。
## 开发
```bash
git clone https://github.com/Security-Phoenix-demo/Pheonix-Security-Orange-MPC
cd Pheonix-Security-Orange-MPC
uv venv && uv pip install -e ".[dev]"
pytest # 离线测试（模拟HTTP）
mcp dev phoenix_mcp/server.py # 交互式MCP检查器
```
## 许可证
MIT — 参见 [LICENSE](LICENSE)。
