# 克隆仓库
git clone https://github.com/touful/touful-vuln-search-mcp.git
cd touful-vuln-search-mcp

# 安装依赖（含 socks 代理支持）
pip install -e .

NVD_API_KEY=your_nvd_api_key_here        # 必需，从 https://nvd.nist.gov/developers 申请
GITHUB_TOKEN=your_github_token_here       # 可选，提高 GitHub 搜索限额
# HTTP_PROXY=socks5://127.0.0.1:7890      # 可选，网络受限时启用

# HTTP 传输（默认）
python -m src.server --transport http --host 127.0.0.1 --port 8080

# stdio 模式（Claude Desktop / Cursor 集成）
python -m src.server --transport stdio

{
  "mcpServers": {
    "touful-vuln-search": {
      "command": "python",
      "args": ["-m", "src.server", "--transport", "stdio"],
      "cwd": "/path/to/touful-vuln-search-mcp",
      "env": {
        "NVD_API_KEY": "your-key",
        "GITHUB_TOKEN": "ghp_xxx",
        "HTTP_PROXY": "socks5://127.0.0.1:7890"
      }
    }
  }
}

touful-vuln-search-mcp/
├── src/
│   ├── server.py            # FastMCP 服务入口，10 个工具定义
│   ├── config.py            # 配置管理（环境变量/API端点）
│   └── clients/
│       ├── base.py          # 公共基类（统一错误处理）
│       ├── http_utils.py    # HTTP 工具（直连→代理回退）
│       ├── nvd_client.py    # NVD API 客户端（aiolimiter 限速）
│       ├── osv_client.py    # OSV API 客户端
│       ├── epss_client.py   # EPSS API 客户端
│       ├── kev_client.py    # CISA KEV 客户端
│       └── exploit_client.py   # Exploit 搜索客户端
├── tests/                   # 测试脚本
│   ├── check_config.py      # 配置检查
│   ├── check_tools.py       # 工具可用性检查
│   ├── integration_test.py  # 集成测试
│   └── test_osv_format.py   # OSV 格式测试
├── scripts/                 # 工具和测试脚本
│   ├── check_cve_2024_1234.py    # CVE 状态检查示例
│   ├── test_clients.py           # 客户端功能测试
│   ├── test_mcp_tools.py         # MCP 工具注册验证
│   ├── test_proxy_fallback.py    # 代理回退验证
│   ├── test_llm_robustness.py    # LLM 输入健壮性测试
│   └── ...                       # 其他验证脚本
├── docs/                    # 文档
├── pyproject.toml
├── .env.example
├── .gitignore
└── README.md

# 检查配置是否正确
python tests/check_config.py

# 检查 MCP 工具是否可用
python tests/check_tools.py

# 集成测试
python tests/integration_test.py

# OSV 格式测试
python tests/test_osv_format.py