内容
# 思科安全访问MCP服务器
思科安全访问的社区 **模型上下文协议（MCP）** 服务器。
它向与MCP兼容的AI客户端（如Cursor、Claude Desktop、VS Code GitHub Copilot等）公开思科安全访问的REST API，作为按思科自己的资源类别分组的工具精选目录：管理、部署、调查、策略和报告。
> **状态：** v1.1 + 复合批次1和2 — 5个类别 / 44个模块 / 185个工具。
> 请参阅 [`安装.md`](./install.md) 了解构建日志和每个阶段的进度。
## 为什么是社区DevNet服务器
本仓库的结构是作为思科DevNet社区MCP服务器托管的，遵循 [`CiscoDevNet/devnet-template`](https://github.com/CiscoDevNet/devnet-template) 布局。标准模板文件（`AGENTS.md`、`CODE_OF_CONDUCT.md`、`CONTRIBUTING.md`、`LICENSE`、`README.md`、`SECURITY.md`）存在并符合该模板。
此外，[`install.md`](./install.md) 是一个工作日志，记录了构建服务器的每个步骤、故障排除笔记和添加的工具增强功能。它故意保留在树中，以便未来的贡献者可以看到推理过程。
## 快速开始
```bash
# 1. 克隆并安装（使用uv）
git clone https://github.com/sdntechforum/Secure_Access.git
cd Secure_Access
uv sync
# 2. 通过环境变量提供思科安全访问API凭证（在安全访问仪表板中管理 > API密钥）
export SECURE_ACCESS_API_KEY=...
export SECURE_ACCESS_API_SECRET=...
# 3. 运行服务器（stdio传输，默认）
uv run cisco-secure-access-mcp
```
有关客户端配置（Cursor / Claude Desktop / VS Code）、Docker用法、完整的工具列表和支持的环境变量列表，请参阅 [`AGENTS.md`](./AGENTS.md)。
## 认证概览
- 面向 `POST https://api.sse.cisco.com/auth/v2/token` 的OAuth 2.0客户端凭证流。
- 在内存中缓存的Bearer令牌，并在其1小时到期前刷新。
- 凭证仅从环境变量中读取 — 绝不从CLI标志或提交的文件中读取。
- 通过 `SECURE_ACCESS_ORG_ID` （作为 `X-Umbrella-OrgId` 发送）支持多组织/MSSP。
- 一组单独的、可选的管理员凭证用于控制少量管理其他API密钥的工具。
有关如何生成API密钥，请参阅 [思科安全访问 — API身份验证](https://developer.cisco.com/docs/cloud-security/secure-access-api-authentication/)。
## 工具目录
此服务器公开的每个MCP工具的完整目录 — 按思科的类别分类法（管理/部署/调查/策略/报告）分组，具有API路径、签名、单行描述和 **实时验证状态** — 位于 [TOOLS.md](./TOOLS.md)。
概览：**185个工具**，跨越 **5个类别** / **44个模块**。**0个提示**，**0个资源** — 这是一个仅限工具的MCP服务器。
要直接从注册代码重新生成目录（无需手动维护的列表）：
```bash
python scripts/dump_catalog.py # 人类可读的文本
python scripts/dump_catalog.py --json # 机器可读的JSON
```
要重新运行实时验证（需要思科安全访问API密钥+密钥）：
```bash
pytest -m integration tests/integration/test_list_coverage.py -v
```
> **社区评估者状态说明：** 截至2026-05-04，对真实安全访问租户的覆盖率扫描发现，约32个47可达的列表端点返回 `404 no Route matched`，这表明许多工具模块中的v1.1 `API_BASE`路径与实时思科表面不匹配。身份验证+客户端+重试层是万无一失的（每个2xx都进行了端到端测试），而管理/部署/调查/策略/报告每个类别都有至少一个经过验证的模块。有关哪些模块已验证或需要路径修复，请参见 [`install.md`](./install.md) 阶段9（2026-05-04后续）和 [`TOOLS.md`](./TOOLS.md）。**欢迎贡献。**
## 仓库布局
```
.
├── AGENTS.md # 安装 + 工具目录 + 环境变量（如果您是AI代理，请先阅读此文件）
├── CODE_OF_CONDUCT.md # 思科DevNet模板（未更改）
├── CONTRIBUTING.md # 思科DevNet模板（项目名称已填写）
├── LICENSE # Apache-2.0（思科DevNet模板）
├── README.md # 本文件
├── SECURITY.md # 思科DevNet模板（项目名称已填写）
├── TOOLS.md # 完整的工具目录（185个工具，每个模块的验证状态）
├── install.md # 构建日志 — 阶段、故障排除、增强功能
├── pyproject.toml # 包元数据 + 入口点
├── Dockerfile # 可选的次要分发
├── .env.example # 记录的环境变量；绝不能是真实的秘密
├── scripts/
│ └── dump_catalog.py # 从实时注册表中生成TOOLS.md内容
├── src/cisco_secure_access_mcp/
│ ├── server.py # FastMCP入口点（stdio默认）
│ ├── auth.py # OAuth2客户端凭证 + 令牌缓存
│ ├── client.py # 基于httpx的REST客户端（仅TLS、重试感知）
│ ├── config.py # 环境变量加载 + 验证
│ ├── errors.py # SDK / HTTP错误 → MCP错误
│ ├── logging.py # 具有秘密删除的结构化JSON日志
│ ├── registry.py # 从每个类别中发现和注册工具
│ └── tools/
│ ├── admin/ # admin_* — 管理资源
│ ├── deployments/ # deploy_* — 部署资源
│ ├── investigate/ # investigate_* — 调查资源（v1.1）
│ ├── policies/ # policy_* — 策略资源
│ └── reports/ # report_* — 报告资源（v1.1）
└── tests/
├── unit/ # 离线；模拟HTTP和时钟
└── integration/ # 可选；需要真实的DevNet沙箱凭证
```
## 运行测试
```bash
# 仅限单元测试 — 快速、完全离线（默认）
uv run pytest
# 针对真实安全访问租户的实时冒烟测试 — 仅限选择加入
export SECURE_ACCESS_API_KEY=...
export SECURE_ACCESS_API_SECRET=...
# 可选：SECURE_ACCESS_ORG_ID, SECURE_ACCESS_BASE_URL
uv run pytest -m integration tests/integration
```
这些冒烟测试设计为只读：它们在每个类别中执行列表/获取端点（以及针对 `cisco.com` 的一次调查领域分类调用），绝不改变组织。如果需要，可以使用 `SECURE_ACCESS_INTEGRATION_TEST_DOMAIN=example.com` 重写测试域。
## 安全
此仓库遵循 `.cursor` 中的安全规则（参数化、无硬编码凭证、具有删除的Structured JSON日志、强制TLS 1.2+、distroless样式容器强化等）。要报告漏洞，请参阅 [`SECURITY.md`](./SECURITY.md)。
## 许可证
Apache License 2.0 — 请参阅 [`LICENSE`](./LICENSE)。
