# 1. 安装依赖（仅需 @modelcontextprotocol/sdk）
npm install

# 2. 配置密钥（可选，详见下方"API Key 配置"；不配置则走免费兜底链路）
cp keys.example.json keys.json   # Windows: copy keys.example.json keys.json

# 3. 离线自检（零网络、零额度消耗）
node scripts/test/verify.mjs offline

# 4. 在 MCP 客户端注册（把路径换成你的实际绝对路径）
#    { "mcpServers": { "smart-search": { "command": "node", "args": ["<本仓库路径>/index.js"] } } }

# 5. 完成——LLM 即可调用 smart_search 等 8 个工具

                    ┌────────────────────────┐
                    │ smart_search(query)    │
                    └───────────┬────────────┘
                                ▼
                   【场景意图识别 / mode 指定】
                                ▼
  ┌───────────────────────────────────────────────────────────┐
  │ 梯队一：商业引擎双主力并发聚合 (Promise.allSettled)        │
  │                                                           │
  │  Exa + Firecrawl  /  Tavily + Brave  /  ...               │
  │  ├─ 双方成功 → 合并去重、交错排序返回                      │
  │  ├─ 单方失败 → 并发搭档结果已足够，不追加消耗              │
  │  └─ 双方全灭 → 按场景顺位尝试剩余商业引擎                  │
  └─────────────────────────────┬─────────────────────────────┘
                                │ (仅当所有商业引擎均不可用时)
                                ▼
  ┌───────────────────────────────────────────────────────────┐
  │ 梯队二：免 Key 免费引擎终极兜底防线                        │
  │                                                           │
  │  1. DuckDuckGo (HTML / 4.5s 极速超时，失败后冷却记忆)      │
  │          │                                                │
  │          ▼ (国内阻断或超时，冷却期直接跳过免等待)           │
  │  2. 微软必应 Bing (免 Key，国内毫秒级直连，真实落地页)     │
  └───────────────────────────────────────────────────────────┘

smart-search-mcp/
├── index.js               # MCP Server 主入口（场景路由、并发聚合、容灾控制）
├── keys.example.json      # API 密钥配置模板（复制为 keys.json 使用，真实密钥不入库）
├── .env.example           # 环境变量键名模板（复制/参考用，本服务不自动加载 .env）
├── package.json           # 项目元数据与依赖（唯一运行时依赖：MCP SDK）
├── scripts/test/verify.mjs  # 可重复执行的验证脚本（离线单元 / 免Key实连 / 商业冒烟）
├── docs/                  # 架构与调研文档（02 容灾设计、04 已否决方向、05 额度横评等）
├── CONTRIBUTING.md        # 贡献指南：环境、测试、架构红线、安全要求
├── LICENSE                # MIT
└── README.md

cp keys.example.json keys.json   # Windows 下: copy keys.example.json keys.json
# 编辑 keys.json，填入真实值（占位符 YOUR_XXX_API_KEY_HERE 会被程序视为未配置）

{
  "exa": "你的Exa密钥",
  "tavily": "你的Tavily密钥",
  "brave": "你的Brave密钥",
  "firecrawl": "你的Firecrawl密钥"
}

npm install          # 唯一运行时依赖 @modelcontextprotocol/sdk

node scripts/test/verify.mjs            # 全部：离线单元 + 免Key实连 + 商业冒烟（耗 2 次额度）
node scripts/test/verify.mjs offline    # 仅离线单元（零网络请求）
node scripts/test/verify.mjs free       # 仅免Key链路实连（零额度消耗）
node scripts/test/verify.mjs commercial # 仅商业并发聚合冒烟（耗 2 次额度）

{
  "mcpServers": {
    "smart-search": {
      "command": "node",
      "args": ["<项目绝对路径>/index.js"]
    }
  }
}