aldoleiva1/MCP-Svr-OpenVulnAPI

# Cisco PSIRT OpenVuln MCP Server 一个生产级的 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 服务器，通过 PSIRT OpenVuln API v2 查询 Cisco 安全公告。它使用 Python 和 FastMCP 构建，使 Claude Desktop 和 Kiro 等 LLM 驱动的界面能够搜索、过滤和分析 Cisco 漏洞数据。 ## 功能 - **15 个 MCP 工具**，覆盖所有 Cisco PSIRT OpenVuln API v2 端点 - **OAuth2 身份验证**，支持自动 token 缓存和刷新（client_credentials 流程） - **多层速率限制** — 5 次调用/秒，30 次调用/分钟，5,000 次调用/天（客户端执行） - **服务端 429 重试** — 支持 Retry-After 头的自动重试（最多 3 次尝试） - 所有参数均提供**输入验证**，并带有描述性的错误信息 - 所有列表端点均支持**分页**（page_index，page_size） - **针对 LLM 优化的响应** — 一致的结构化封装，支持摘要截断 - **传输不可知** — 支持 stdio（默认）和 SSE 传输 - **结构化错误处理** — 带有用户友好消息的分类错误 ## 前置条件 - **Python 3.10+** - **Cisco API Console 凭证**（client_id 和 client_secret） — 参见 [获取 Cisco API 凭证](#getting-cisco-api-credentials) ## 安装说明 1. **克隆仓库：** git clone cd openvuln-mcp-server 2. **创建虚拟环境：** python -m venv venv source venv/bin/activate # 在 Windows 上使用：venv\Scripts\activate 3. **安装依赖：** pip install -r requirements.txt 4. **配置凭证：** cp .env.example .env 编辑 `.env` 并填入您的 Cisco API 凭证： CISCO_CLIENT_ID=your_client_id_here CISCO_CLIENT_SECRET=your_client_secret_here ## 获取 Cisco API 凭证 1. 前往 [Cisco API Console](https://apidocs-prod.cisco.com/) 并登录（或创建账户） 2. 注册一个新应用 3. 为您的应用启用 **"Cisco PSIRT openVuln API"** 4. 复制生成的 `client_id` 和 `client_secret` 5. 将它们添加到您的 `.env` 文件中，或作为环境变量传递 每个用户的凭证是独立的 —— Cisco 端的速率限制是按 client_id 进行跟踪的。 ## 使用方法 ### stdio 模式（默认） 用于本地 MCP 集成（Claude Desktop, Kiro）的标准传输： ``` python main.py ``` ### SSE 模式 用于 Web 或远程集成的基于 HTTP 的 Server-Sent Events 传输： ``` python main.py --transport sse --port 8080 ``` ## MCP 客户端配置 ### Claude Desktop / Kiro (stdio) 添加到您的 MCP 客户端配置文件中： ``` { "mcpServers": { "cisco-openvuln": { "command": "python", "args": ["main.py"], "cwd": "/path/to/openvuln-mcp-server", "env": { "CISCO_CLIENT_ID": "your_client_id", "CISCO_CLIENT_SECRET": "your_client_secret" } } } } ``` ### SSE 客户端 ``` { "mcpServers": { "cisco-openvuln": { "url": "http://localhost:8080/sse" } } } ``` ## 可用工具 | # | 工具 | 描述 | 关键参数 | |---|------|-------------|----------------| | 1 | `get_all_advisories` | 检索所有已发布的公告（支持分页） | `page_index`, `page_size` | | 2 | `get_advisory_by_id` | 根据 Cisco 公告 ID 查找特定公告 | `advisory_id`（最多 100 个字符） | | 3 | `get_advisory_by_cve` | 根据 CVE 标识符查找公告 | `cve_id`（CVE-YYYY-NNNNN 格式） | | 4 | `get_advisory_by_bug_id` | 根据 Cisco Bug ID 查找公告 | `bug_id`（CSCxxNNNNN 格式） | | 5 | `get_latest_advisories` | 获取最近发布的 N 条公告 | `number`（1–100，默认为 5） | | 6 | `get_advisories_by_severity` | 根据严重级别过滤公告 | `severity`（critical/high/medium/low/informational） | | 7 | `get_advisories_by_severity_first_published` | 根据严重级别和首次发布日期范围过滤 | `severity`, `start_date`, `end_date` | | 8 | `get_advisories_by_severity_last_published` | 根据严重级别和最后更新日期范围过滤 | `severity`, `start_date`, `end_date` | | 9 | `get_advisories_by_first_published` | 查找在特定日期范围内首次发布的公告 | `start_date`, `end_date`（YYYY-MM-DD） | | 10 | `get_advisories_by_last_published` | 查找在特定日期范围内最后更新的公告 | `start_date`, `end_date`（YYYY-MM-DD） | | 11 | `get_advisories_by_product` | 根据产品名称搜索公告 | `product_name` | | 12 | `get_advisories_by_year` | 获取特定年份发布的公告 | `year`（1995–当前年份） | | 13 | `get_advisories_by_os_version` | 查找特定 OS 类型和版本的公告 | `os_type`, `version`, `platform_alias`（可选） | | 14 | `get_os_version_data` | 获取可用的 OS 版本元数据 | `os_type` | | 15 | `get_platform_aliases` | 列出特定 OS 类型的平台别名 | `os_type`（仅限 nxos/asa/ftd/fxos） | 所有返回列表的工具均支持 `page_index`（1–100）和 `page_size`（1–100）分页参数。 ## 运行测试 运行完整的测试套件： ``` pytest ``` 运行覆盖率测试： ``` pytest --cov=src --cov-report=term-missing ``` 运行特定的测试文件： ``` pytest tests/test_validators.py ``` 运行基于属性的测试（Hypothesis）： ``` pytest tests/ -k "property" ``` ## 速率限制 服务器执行客户端速率限制，以保持在 Cisco API 配额范围内： | 层级 | 限制 | 执行方式 | |------|-------|-------------| | 每秒 | 5 次调用/秒 | 请求间至少间隔 200ms | | 每分钟 | 30 次调用/分钟 | 滚动的 60 秒滑动窗口 | | 每天 | 5,000 次调用/天 | 日历日计数器，在 UTC 时间 00:00 重置 | 当达到速率限制时： - **每秒/每分钟**：服务器会自动休眠，直到允许下一次请求 - **每天**：返回错误，指出每日配额已耗尽，并附带距离重置的剩余秒数 - **服务端 429**：使用 `Retry-After` 头进行最多 3 次重试（如果不存在则默认为 60 秒） ## 项目结构 ``` openvuln-mcp-server/ ├── main.py # Entry point: loads env, parses args, starts server ├── src/ │ ├── __init__.py │ ├── server.py # FastMCP server and 15 tool registrations │ ├── oauth2_client.py # OAuth2 client_credentials with token caching │ ├── rate_limiter.py # Multi-tier rate limiter │ ├── api_client.py # HTTP client with auth, rate limiting, retry │ ├── validators.py # Input validation functions │ ├── response_formatter.py # LLM-optimized response formatting │ ├── constants.py # URLs, limits, validation rules │ └── exceptions.py # Custom exception hierarchy ├── tests/ │ ├── test_validators.py │ ├── test_oauth2_client.py │ ├── test_rate_limiter.py │ ├── test_api_client.py │ ├── test_response_formatter.py │ └── test_tools.py ├── .env.example # Credentials template ├── requirements.txt # Python dependencies └── README.md ``` ## 许可证 该项目基于 [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0) 授权。

标签：LLM集成, MCP服务, OAuth2, Python, RESTful API, 实时处理, 提示词优化, 无后门, 漏洞查询, 逆向工具