# model-advisor-mcp

**Repository Path**: mcp-projects/model-advisor-mcp

## Basic Information

- **Project Name**: model-advisor-mcp
- **Description**: Give your AI assistant real-time LLM/VLM knowledge
- **Primary Language**: TypeScript
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-11
- **Last Updated**: 2026-09-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# model-advisor-mcp

为 AI 助手提供实时的 LLM/VLM 模型选型能力：以 OpenRouter 为基座，叠加 models.dev 补充/兜底源（补齐未覆盖模型 + 回填缺失字段），聚合 8 个权威基准数据源与 OpenCode 订阅目录，通过 MCP（Model Context Protocol）以 stdio 方式对外提供查询、排行、对比、推荐、成本估算与项目选型等 8 个工具。

![license](https://img.shields.io/badge/license-MIT-blue.svg)
![node](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)
![mcp](https://img.shields.io/badge/protocol-MCP-8A2BE2.svg)
![npm version](https://img.shields.io/npm/v/@nreg/model-advisor-mcp)
![npm downloads](https://img.shields.io/npm/dm/@nreg/model-advisor-mcp)

> 文档版本：**1.0.0**（对应 `@nreg/model-advisor-mcp@1.0.0`，8 个工具齐备）

## 特性

- **8 个 MCP Tool**：`get_model_info` / `list_top_models` / `compare_models` / `recommend_model` / `estimate_cost` / `batch_get_pricing` / `select_model_for_project` / `whats_new`。
- **OpenRouter 基座 + models.dev 补充源 + 8 基准源 + OpenCode 订阅**：覆盖价格、上下文、模态、能力与基准分；OpenRouter 内置 Artificial Analysis 三指数、Design Arena 与 reasoning 档位；models.dev 补齐 OpenRouter 未覆盖的模型并回填缺失字段（不覆盖主定价）。
- **LLM + VLM 双类覆盖**：文本竞技场 ELO 与视觉竞技场 ELO 分开采集，视觉模型独立排序，避免文本分污染视觉选型。
- **成本/预算能力**：按每 1M token 单价估算调用成本；支持 OpenCode 订阅档（Zen 免费 / Go 付费）过滤与项目级选型。
- **中文生态友好**：能力榜/开源榜/安全榜直接消费 OpenCompass 官方数据，Kimi、GLM、Qwen、DeepSeek、豆包等国产模型具备完整基准覆盖。
- **单源失败不阻断**：OpenRouter 为必选基座，models.dev 作兜底源（OpenRouter 为空时撑场），其余基准源与订阅目录全部容错；任一源抓取失败仅降级该源，整体服务继续可用。
- **stale-while-revalidate 缓存**：内存缓存 + 过期兜底，上游故障时用旧数据顶住，避免整榜归零。
- **模糊匹配**：模型名规范化（provider 前缀、日期后缀、版本号、Claude 命名序）后多级匹配，并对 VL 模态做保护，防止视觉模型错误塌缩到文本基础模型。

## 数据源一览

| 数据源 | 内容 | 条目量 | 缓存 TTL |
|---|---|---:|---:|
| OpenRouter API | 基础目录：价格 / 上下文 / 模态 / 工具与推理能力，以及内置 AA 三指数 / Design Arena / reasoning 档位 | ~410 商用模型 | 1 小时 |
| models.dev API（补充/兜底源） | provider→models 嵌套结构；补齐 OpenRouter 未覆盖模型 + 回填缺失字段（缓存/推理/图像价、上下文、开源标记等），**不覆盖 input/output 主定价** | ~8124 模型 | 6 小时 |
| OpenCompass realtime-elo（text） | 文本竞技场人类偏好 ELO | 31 | 6 小时 |
| OpenCompass realtime-elo（vision） | 视觉竞技场 ELO | 20 | 6 小时 |
| OpenCompass 官方能力榜 | 旗舰模型：知识 / 推理 / 数学 / 代码 | 15 | 6 小时 |
| OpenCompass 开源能力榜 | 开源模型：HLE / AIME2025 / MMLU-Pro / LiveCodeBenchV6 / GPQA / IFEval | 48 | 6 小时 |
| SWE-bench Verified | 代码修复基准（取每个模型最高 resolved） | 78 | 6 小时 |
| Aider Polyglot | 多语言代码编辑基准（pass_rate_2） | 66 | 6 小时 |
| OpenVLM 综合视觉榜 | MMMU / MMBench / OCR / AI2D / MathVista | 281 | 6 小时 |
| VLM 官方能力榜 | 感知 / 空间 / 图表 / 推理 / 创作 / Agent | 22 | 6 小时 |
| OpenCompass 安全榜（text） | 文本安全对齐总分 | 46 | 6 小时 |
| OpenCompass 安全榜（vlm） | VLM 安全总分 | 45 | 6 小时 |
| OpenCode Zen（订阅目录） | 免费档可用模型 slug（经 `normalizeKey` 与 OpenRouter 匹配） | 70 | 6 小时 |
| OpenCode Go（订阅目录） | 付费档可用模型 slug（同上） | 37 | 6 小时 |

> 说明：上表按「OpenRouter 基座 + models.dev 补充源 + 8 个基准源 + OpenCode 订阅（Zen/Go 两端点）」统计（ELO 与安全榜各含 text + vision 两条 pipeline）。条目量为 2026-09 实测规模，上游榜单会随时间浮动。

### 新增数据能力

- **Artificial Analysis 三指数**（`aaIntelligence` / `aaCoding` / `aaAgentic`）：来自 OpenRouter `benchmarks.artificial_analysis`，为 0-100 指数分，无需付费 API key。
- **Design Arena ELO**（`designArenaElo`）：来自 OpenRouter `benchmarks.design_arena`，取所有条目中的最高 ELO。
- **reasoning 档位**：来自 OpenRouter `reasoning`，展示支持的推理档位与默认档位。
- **OpenCode 订阅归属**（`opencodeSubscription`：`zen` / `go` / `both`）：由 OpenCode Zen/Go 目录经规范化匹配后推得。
- **质量档**（`qualityTier`：`S`/`A`/`B`/`C`）：基于本项目全库百分位推导（综合百分位 ≥95→S、≥80→A、≥60→B、其余→C），不依赖任何硬编码静态表。

## 安装与配置

### 环境要求

- Node.js >= 18（依赖 `AbortSignal.timeout`）
- 可访问外网（需拉取各榜单数据）

### 方式一（推荐）：npm

**a) 直接用 npx（无需安装）**

```json
{
  "mcpServers": {
    "model-advisor": {
      "enabled": true,
      "type": "stdio",
      "command": ["npx", "-y", "@nreg/model-advisor-mcp@latest"]
    }
  }
}
```

**b) 全局安装后运行**

```bash
npm install -g @nreg/model-advisor-mcp
```

```json
{
  "mcpServers": {
    "model-advisor": {
      "enabled": true,
      "type": "stdio",
      "command": ["model-advisor-mcp"]
    }
  }
}
```

### 方式二：本地构建（开发调试用）

从源码构建（开发/调试）：

```bash
git clone <repository-url> model-advisor-mcp
cd model-advisor-mcp
npm install
npm run build
```

`bin` 入口为 `dist/cli.js`（`dist/index.js` 同样可直接运行）。在 MCP 客户端配置中加入：

```json
{
  "mcpServers": {
    "model-advisor": {
      "enabled": true,
      "type": "stdio",
      "command": ["node", "E:/work/nreg/ai-mcp/model-advisor-mcp/dist/cli.js"]
    }
  }
}
```

启动时服务会异步预热缓存（非阻塞，不阻塞 MCP 连接建立），首个请求若预热未完成会再次触发加载。

## 工具说明

服务注册 **8 个 MCP Tool**，返回值均为 Markdown 文本（`select_model_for_project` 额外提供 `structuredContent` 结构化输出）。

| 工具 | 用途 |
|---|---|
| `get_model_info` | 单模型详情（定价 / 基准 / 百分位 / 质量档 / 订阅 / 推理档位） |
| `list_top_models` | 按类别列出 Top 模型，支持订阅档与上下文/发布日期过滤 |
| `compare_models` | 2-5 个模型并排对比 |
| `recommend_model` | 按用途 + 预算 + 硬性需求推荐模型 |
| `estimate_cost` | 按 token 用量估算调用成本 |
| `batch_get_pricing` | 批量查询多模型价格与订阅信息 |
| `select_model_for_project` | 项目/任务级选型（三档 + 结构化输出） |
| `whats_new` | 按时间窗口列出近期新增模型 |

### get_model_info

获取单个模型的详细信息：定价、上下文、各来源基准分、全库百分位、质量档与能力特性，并可选附带 API 调用示例。支持模糊匹配，未命中时返回相近模型建议（前 5）。

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| `model` | string | 是 | — | 模型 ID 或名称，支持模糊匹配（如 `anthropic/claude-sonnet-4.6`、`gpt-5.2`、`kimi`） |
| `include_api_example` | boolean | 否 | `true` | 是否附带 API 示例（代码判据为 `!== false`） |
| `api_format` | enum | 否 | `openai_sdk` | API 示例格式：`openai_sdk` / `curl` / `python_requests` |

**调用示例**

```json
{ "model": "claude-sonnet-4.6", "api_format": "curl" }
```

输出摘录（Markdown）：

```markdown
## anthropic/claude-sonnet-4.6

**名称**: Claude Sonnet 4.6 | **供应商**: anthropic | **模态**: text+image→text | **系列**: claude | **质量档**: A 级
**OpenCode 订阅**: Go+Zen
**推理档位**: high, medium（默认 medium）

### 定价与上下文
| 指标 | 数值 |
|------|------|
| 输入 | $3.00 /1M tok |
| 输出 | $15.00 /1M tok |
| 上下文 | 200K |

### 基准: 代码类
| 基准 | 得分 |
|------|------|
| SWE-bench | 72.1% |
| Aider Polyglot | 65.4% |

### 基准: Artificial Analysis
| 基准 | 得分 |
|------|------|
| AA 智能指数 | 58.3% |
| AA 代码指数 | 54.1% |

### 全库百分位
| 类别 | 百分位 |
|---|---|
| 代码 | P96 |
| 通用 | P92 |
```

### list_top_models

按类别列出排名靠前的模型，返回紧凑 Markdown 表格（模型 / 价格 / 上下文 / 质量档 / OpenCode 订阅 / 关键基准 / 发布日期）。

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| `category` | enum | 是 | — | 类别：`coding` / `math` / `vision` / `general` / `cost-effective` / `open-source` / `speed` / `context-window` / `reasoning` |
| `limit` | number | 否 | `10` | 返回数量，范围 1-20 |
| `min_context` | number | 否 | — | 最小上下文窗口（token 数） |
| `min_release_date` | string | 否 | — | 最早发布日期（`YYYY-MM-DD`），早于此日期的模型被排除 |
| `subscription` | enum | 否 | — | 按 OpenCode 订阅档过滤：`go` / `zen` 表示该档可用（含 both），`both` 仅统计两档都可用 |
| `free_only` | boolean | 否 | — | 仅显示 OpenCode Zen 免费档可用的模型（OpenRouter 免费模型已在基座剔除） |

**调用示例**

```json
{ "category": "coding", "limit": 5, "min_context": 128000, "subscription": "zen" }
```

输出摘录：

```markdown
## Top 5: 代码

| # | 模型 | 输入 $/1M | 输出 $/1M | 上下文 | 质量档 | OpenCode 订阅 | 关键基准 | 发布日期 |
|------|------|------|------|------|------|------|------|------|
| 1 | anthropic/claude-sonnet-4.6 | $3.00 | $15.00 | 200K | [A] | Go+Zen | SWE-bench 72.1% | 2026-02-10 |
```

### compare_models

并排对比 2-5 个模型，行 = 指标（价格 / 上下文 / ELO / AA 三指数 / Design Arena / SWE-bench / Aider / 官方能力四维 / GPQA / MMMU / 安全 / 质量档 / 订阅），列 = 模型，每个指标的最优值加粗。命中不足 2 个时返回错误并附建议。

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| `models` | string[] | 是 | — | 模型 ID 或名称数组，长度 2-5，支持模糊匹配 |

**调用示例**

```json
{ "models": ["claude-sonnet-4.6", "gpt-5.2", "gemini-3-pro"] }
```

输出摘录：

```markdown
## 模型对比（3 个）

| 指标 | **anthropic/claude-sonnet-4.6** | **openai/gpt-5.2** | **google/gemini-3-pro** |
|------|------|------|------|
| 输入 $/1M | $3.00 | $2.50 | $3.50 |
| 输出 $/1M | $15.00 | $10.00 | $14.00 |
| 上下文 | 200K | 400K | **1M** |
| ELO（人类偏好） | 1382 | 1401 | **1425** |
| AA 智能指数 | 58.3% | **61.0%** | 59.7% |
| SWE-bench | **72.1%** | 68.3% | 66.5% |
| 质量档 | [A] | **[S]** | [A] |
| OpenCode 订阅 | Go+Zen | Go | Zen |
```

### recommend_model

按用途、预算与硬性要求推荐模型：先做硬性过滤，再按百分位与关键基准加权软打分排序，并为每个结果生成一句中文理由（含质量档与 OpenCode 订阅提示）。

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| `use_case` | enum | 是 | — | 用途：`coding` / `math` / `general` / `vision` / `creative` / `reasoning` / `cost-effective` |
| `max_input_price` | number | 否 | — | 输入价格上限（USD / 1M tokens） |
| `max_output_price` | number | 否 | — | 输出价格上限（USD / 1M tokens） |
| `min_context` | number | 否 | — | 最小上下文窗口（token 数） |
| `require_vision` | boolean | 否 | — | 必须支持视觉/图片输入 |
| `require_tools` | boolean | 否 | — | 必须支持函数/工具调用 |
| `require_open_source` | boolean | 否 | — | 必须为开源许可 |
| `budget` | enum | 否 | `any`（未传时归一化） | 预算档：`free`（OpenCode Zen 免费档可用）/ `low`（blended ≤ $1/1M）/ `any`（不限） |
| `requirements` | string[] | 否 | — | 硬性需求，如 `['vision','tools','open_source','reasoning','long context']` |
| `limit` | number | 否 | `3` | 返回数量，范围 1-20 |

**调用示例**

```json
{ "use_case": "coding", "budget": "low", "requirements": ["tools"], "limit": 3 }
```

输出摘录：

```markdown
## 推荐（用途：coding，预算：low）

| 排名 | 模型 | 综合分 | 输入 $/1M | 输出 $/1M | 上下文 | 质量档 | OpenCode 订阅 |
|------|------|------|------|------|------|------|------|
| 1 | anthropic/claude-sonnet-4.6 | 94.2 | $3.00 | $15.00 | 200K | A 级 | Go+Zen |

1. **anthropic/claude-sonnet-4.6** — SWE-bench 72.1%，官方代码 88.4%，代码分位 P96；支持工具调用，A 级，OpenCode Go+Zen，输入 $3.00/1M，上下文 200K。
```

### estimate_cost

估算指定 LLM 模型在给定 token 用量下的调用成本（USD）。按每 1M token 单价计算输入/输出/缓存/推理明细与总计，用于预算评估。支持模糊匹配模型名。

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| `model` | string | 是 | — | 模型 ID 或名称（支持模糊匹配） |
| `input_tokens` | number | 否 | — | 输入 token 数（非负整数） |
| `output_tokens` | number | 否 | — | 输出 token 数（非负整数） |
| `cache_read_tokens` | number | 否 | — | 缓存读取 token 数（非负整数，若模型有缓存价） |
| `cache_write_tokens` | number | 否 | — | 缓存写入 token 数（非负整数，若模型有缓存价） |
| `reasoning_tokens` | number | 否 | — | 推理 token 数（非负整数，若模型有推理价） |
| `requests` | number | 否 | `1` | 请求次数（正整数） |

**调用示例**

```json
{ "model": "anthropic/claude-sonnet-4.6", "input_tokens": 1000000, "output_tokens": 500000, "requests": 1 }
```

输出摘录：

```markdown
## 成本估算：anthropic/claude-sonnet-4.6
**名称**: Claude Sonnet 4.6 | **供应商**: anthropic | **质量档**: A 级

### 用量
- 输入 tokens: 1,000,000
- 输出 tokens: 500,000

### 成本明细（USD）
| 项目 | 单价 $/1M | 用量 | 小计 |
|------|-----------|------|------|
| 输入 | $3.00 | 1,000,000 | $3.000000 |
| 输出 | $15.00 | 500,000 | $7.500000 |

## 预估总成本
**$10.500000**
```

### batch_get_pricing

一次查询多个模型的价格信息，返回紧凑 Markdown 表格（输入/输出单价、上下文、质量档、OpenCode 订阅）。模型 ID 或名称支持模糊匹配，最多 50 个。

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| `model_ids` | string[] | 是 | — | 模型 ID 或名称数组（支持模糊匹配，1-50 个） |

**调用示例**

```json
{ "model_ids": ["claude-sonnet-4.6", "gpt-5.2", "kimi-k2"] }
```

输出摘录：

```markdown
## 批量价格查询（命中 3 / 请求 3）

| 模型 | 供应商 | 输入 $/1M | 输出 $/1M | 上下文 | 质量档 | OpenCode 订阅 |
|------|--------|------|------|------|------|------|
| anthropic/claude-sonnet-4.6 | anthropic | $3.00 | $15.00 | 200K | A 级 | Go+Zen |
| openai/gpt-5.2 | openai | $2.50 | $10.00 | 400K | S 级 | Go |
```

### select_model_for_project

根据项目/任务描述、硬性需求与预算档，选出「最佳综合 / 最便宜可选 / 最佳性价比」三档模型，并返回结构化结果（`structuredContent`）。用途由关键词自动推断（7 类 UseCase），过滤后按本项目打分排序。

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| `project` | string | 否 | — | 项目描述（与 `task` 至少提供一个） |
| `task` | string | 否 | — | 具体任务描述 |
| `requirements` | string[] | 否 | — | 硬性需求，如 `['vision','tools','open_source','long context']` |
| `budget` | enum | 否 | `any` | 预算档：`free` / `low` / `any` |
| `optimization_goal` | enum | 否 | `balanced` | 优化目标：`balanced`（性价比）/ `best`（能力最强）/ `cheapest`（最便宜） |
| `expected_usage` | object | 否 | — | 预期用量 `{ input_tokens?, output_tokens?, requests? }`（均为非负数/正数），提供后给出预估成本 |
| `limit` | number | 否 | `5` | 候选数量，范围 1-20 |

**调用示例**

```json
{
  "task": "重构一个 TypeScript 单体仓库并修复测试",
  "requirements": ["tools", "long context"],
  "budget": "low",
  "optimization_goal": "balanced",
  "expected_usage": { "input_tokens": 2000000, "output_tokens": 500000, "requests": 10 },
  "limit": 5
}
```

输出摘录（Markdown；同时返回 `structuredContent`）：

```markdown
## 选型结果（目标：balanced，预算：low）
项目/任务：- / 重构一个 TypeScript 单体仓库并修复测试；已应用需求：tools、long context

- **最佳综合**：anthropic/claude-sonnet-4.6（评分 94.2）
- **最便宜可选**：moonshot/kimi-k2（$0.90/1M）
- **最佳性价比**：anthropic/claude-sonnet-4.6（值分 88.5）

| 排名 | 模型 | 供应商 | 评分 | 值分 | 输入 $/1M | 输出 $/1M | 质量档 | 理由 |
|------|------|--------|------|------|------|------|------|------|
| 1 | anthropic/claude-sonnet-4.6 | anthropic | 94.2 | 88.5 | $3.00 | $15.00 | A | SWE-bench 72.1%… |
```

`structuredContent` 结构（字段为 snake_case）：

```json
{
  "query": { "project": null, "task": "…", "requirements": ["tools"], "budget": "low", "optimization_goal": "balanced" },
  "best_overall": { "id": "…", "name": "…", "score": 94.2, "valueScore": 88.5, "blended_price": 11.4, "est_cost": 13.5, "quality_tier": "A", "reasons": ["…"], "tradeoffs": ["…"] },
  "cheapest_acceptable": { "…": "…" },
  "best_value": { "…": "…" },
  "candidates": [{ "…": "…" }],
  "cost_basis": "expected_usage"
}
```

### whats_new

按时间窗口列出近期新增/发布的模型（基于发布日期 `releaseDate`），可选按类别过滤。时间格式如 `7d`（天）/`24h`（小时）/`2w`（周）。

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| `since` | string | 否 | `7d` | 时间窗口，格式如 `7d`（天）/ `24h`（小时）/ `2w`（周） |
| `category` | enum | 否 | — | 可选：仅看某类别（以其 Top 50 判定） |
| `limit` | number | 否 | `20` | 返回数量，最大 100 |

**调用示例**

```json
{ "since": "30d", "category": "coding", "limit": 10 }
```

输出摘录：

```markdown
## 5 个近期新增模型（最近 30d · coding）

1. OpenAI GPT-5.2 (openai/gpt-5.2) [S]
   openai | 输入 $2.50 | 上下文 400K | 发布 2026-09-01 | 订阅 Go
```

## 开发

```bash
npm install        # 安装依赖
npm run build      # tsup 构建到 dist/（双入口 index.ts + cli.ts，ESM + d.ts，--clean）
npm run dev        # tsx 直接运行 src/index.ts（开发调试）
npm test           # vitest run 单元测试
npm run smoke      # 冒烟测试：缓存覆盖检查 + MCP 端到端握手（需先 build）
npm run test:sources  # 逐个验证各源可达性 / 条目数 / 数据质量 / 交叉匹配率（需联网）
npm run test:published  # 发布后 e2e：npx 拉起 @latest，断言 8 工具并实测 get_model_info / estimate_cost
```

- `npm run smoke`：Part A 检查 warmup 后关键源（OpenRouter / ELO text / 官方能力榜 / OpenVLM）覆盖，任一 0 条判失败，并统计 AA 三指数 / OpenCode 订阅 / qualityTier 覆盖（静默归零可被观测）；Part B 以子进程方式走完 `initialize → notifications/initialized → tools/list`，验证构建产物与 8 个 tool 注册。
- `npm run test:sources`：是数据源的哨兵脚本，对上游改名、字段变更、网络故障做预警（含交叉匹配率阈值断言）。
- `npm run test:published`：发布后真机 e2e。默认拉起 `@nreg/model-advisor-mcp@latest`；本地也可用环境变量覆盖命令验证构建产物：`$env:MCP_TEST_COMMAND="node"; $env:MCP_TEST_ARGS="dist/cli.js"; node test-published-package.js`。
- **CI（`.github/workflows/ci.yml`）**：push / PR 到 `main` / `master` 时，以 Node 18/20/22 矩阵执行 `npm ci → npm run build → vitest run`；随后 `publish-dry-run` 任务用 `npm pack --dry-run` 检查发布物是否夹带 test/secret/env/dev.vars 等文件。
- **`socket.yml`**：Socket.dev 供应链策略。`networkAccess` / `shellAccess` / `envVars` / `usesEval` / `nativeCode` 记为 warn（npx 拉起子进程等属预期行为），`installScripts` / `telemetry` / `obfuscatedCode` 记为 error。

## 项目结构

```
model-advisor-mcp/
├── src/
│   ├── index.ts                 # 库入口（可执行）：stdio 连接、优雅停机、非阻塞预热
│   ├── cli.ts                   # CLI 入口（bin 目标 dist/cli.js）：createServer + stdio 连接
│   ├── server.ts                # createServer 工厂：装配 8 个 tool（cli/index 复用）
│   ├── types.ts                 # OpenRouter 响应类型、统一模型类型、类别/用途枚举、缓存与评分类型
│   ├── data/
│   │   ├── cache.ts             # InMemoryCache（TTL 过期删除 + stale 兜底 + freshness 信息）
│   │   ├── normalizer.ts        # normalizeKey / generateMatchKeys / buildKeyToId / findMatch，多源合并
│   │   ├── percentiles.ts       # 五类百分位计算（代码 / 数学 / 通用 / 视觉 / 性价比）
│   │   ├── quality.ts           # 基于百分位推导 qualityTier（S/A/B/C）+ 可选人工覆盖表
│   │   ├── registry.ts          # ModelRegistry：多源加载编排、Top 排序规则、四段匹配查询
│   │   ├── fetchers/            # 数据源抓取器
│   │   │   ├── openrouter.ts        # OpenRouter 模型目录（必选基座，解析 AA 三指数 / Design Arena / reasoning）
│   │   │   ├── models-dev.ts        # models.dev 补充/兜底源（未命中补入 + 缺失字段回填，不覆盖主定价）
│   │   │   ├── opencode.ts          # OpenCode Zen/Go 订阅目录（归属判定 zen/go/both）
│   │   │   ├── elo.ts               # OpenCompass realtime-elo（text + vision）
│   │   │   ├── ability-official.ts  # OpenCompass 官方能力榜
│   │   │   ├── ability-open-source.ts # OpenCompass 开源能力榜
│   │   │   ├── swe-bench.ts         # SWE-bench Verified
│   │   │   ├── aider.ts             # Aider Polyglot（内置极简 YAML 解析）
│   │   │   ├── vlm-leaderboard.ts   # OpenVLM 综合视觉榜
│   │   │   ├── vlm-official.ts      # VLM 官方能力榜
│   │   │   └── security.ts          # 安全榜（text + vlm）
│   │   └── static/
│   │       └── api-examples.ts  # OpenAI SDK / curl / python_requests 三种 API 示例模板
│   ├── tools/
│   │   ├── model-info.ts        # get_model_info
│   │   ├── list-top.ts          # list_top_models（订阅档 / 免费档过滤）
│   │   ├── compare.ts           # compare_models（含 AA / Design Arena / 质量档 / 订阅行）
│   │   ├── recommend.ts         # recommend_model（预算 / 需求 / limit）
│   │   ├── estimate.ts          # estimate_cost（每 1M token 计价）
│   │   ├── batch.ts             # batch_get_pricing
│   │   ├── select.ts            # select_model_for_project（outputSchema + structuredContent）
│   │   ├── select-scoring.ts    # 选型核心纯逻辑（三档 / 打分 / 理由）
│   │   ├── whats-new.ts         # whats_new（since 解析 + 发布时间过滤）
│   │   ├── requirements.ts      # 预算档 / 需求词 → 硬过滤器（共享）
│   │   ├── suggest.ts           # 未命中相近模型建议（共享）
│   │   └── formatters.ts        # 共享 Markdown 格式化与标签映射
│   └── __tests__/               # vitest 单元测试（normalizer / percentiles / openrouter / models-dev / opencode / quality / requirements / select-scoring）
├── scripts/
│   ├── smoke.ts                 # 冒烟测试（覆盖检查 + MCP 握手，断言 8 tool）
│   └── test-data-sources.ts     # 各源有效性 + 交叉匹配率测试
├── test-published-package.js    # 发布后 e2e（MCP SDK Client + StdioClientTransport）
├── .github/workflows/ci.yml     # CI：Node 18/20/22 矩阵 + build + vitest + 包洁净检查
├── socket.yml                   # Socket.dev 供应链配置
├── dist/                        # 构建产物（index.js / cli.js / *.d.ts）
├── package.json
├── tsconfig.json
├── LICENSE
└── README.md
```

## 数据源与排序原则

### 各类别排序依据

| 类别 | 排序依据（多级降序 / 过滤） |
|---|---|
| `coding` | SWE-bench Verified → Aider Polyglot → LiveCodeBenchV6 |
| `math` | 官方能力榜数学 → AIME2025 → MMLU-Pro |
| `vision` | 仅视觉模型：MMMU → VLM 官方榜（不含 Agent）→ 性价比 |
| `general` | 竞技场 ELO → 官方能力榜 Average |
| `cost-effective` | 排除免费模型，按 性能分 / blended 价格（`0.3×输入 + 0.7×输出`）降序 |
| `open-source` | 仅开源模型：竞技场 ELO 降序 → 价格升序 |
| `speed` | 输出价格升序（作为推理速度代理：越便宜通常越快） |
| `context-window` | 上下文长度降序 |
| `reasoning` | 仅支持推理的模型：GPQA-Diamond → 官方推理 → 竞技场 ELO |

> `list_top_models` 默认多取 `limit + 10` 条再应用过滤；存在订阅过滤（`subscription` / `free_only`）时多取 `limit + 50` 条，确保过滤后仍能补足请求数量。

### 匹配与容错

- **规范化匹配**：`normalizeKey` 统一小写、去 provider 前缀、去日期/thinking 后缀、空格转连字符、版本号 `4-6 → 4.6`；`generateMatchKeys` 额外生成 Claude 双向序变体；`findMatch` 做精确匹配 + 子串兜底。
- **保护规则**：子串匹配要求两侧键均 ≥ 6 字符，避免短茎误吞无关模型；带视觉 token（`vl` / `vision`）的名称不会塌缩到非视觉基础模型。
- **百分位与质量档**：对代码 / 数学 / 通用 / 视觉 / 性价比五类分别计算全库百分位；`qualityTier` 基于综合百分位（coding/math/general/vision 取最大）推导。
- **数据源监控**：`scripts/test-data-sources.ts` 是哨兵，除网络与条目数阈值外，核心是各源到 OpenRouter 基座的**交叉匹配率**（上游改名或换字段会导致命中率塌方），并对低比率源设置绝对命中数兜底。

## 许可

[MIT](./LICENSE) © 2026 model-advisor-mcp contributors