Wheel Fitment API

wheel-size-mcp

由 Wheel-Size.com（API 提供方）构建并维护的 Wheel Fitment API 官方 MCP 服务。让大模型 Agent 能够访问车辆车轮和轮胎兼容性数据。

可以向 AI 助手询问：

• “2024 款 Toyota Camry 的原厂车轮规格是什么？”
• “哪些车辆适配 5x114.3 18x8 ET35 轮毂？”
• “为 7Jx17 ET40 上的 225/50R17 计算加大尺寸选项”
• “为这个车轮生成产品卡片，并显示所有兼容车辆”

快速开始

1. 获取 API 密钥

在 developer.wheel-size.com 注册并复制 API 密钥。

2. 在 shell 中设置 API 密钥

添加到 ~/.zshrc（或 ~/.bashrc）：

export WHEELSIZE_API_KEY="your-api-key-here"

然后重新加载 shell：source ~/.zshrc

3. 添加到 AI 客户端

选择下方的客户端——每个配置代码块都可以直接复制粘贴。

Claude Code

claude mcp add wheel-size-api -- uvx wheel-size-mcp

也可以将其添加到项目根目录下的 .mcp.json：

{
  "mcpServers": {
    "wheel-size-api": {
      "command": "uvx",
      "args": ["wheel-size-mcp"],
      "env": {
        "WHEELSIZE_API_KEY": "${WHEELSIZE_API_KEY}"
      }
    }
  }
}

Claude Desktop

添加到 claude_desktop_config.json（macOS 上为 ~/Library/Application Support/Claude/claude_desktop_config.json，Windows 上为 %APPDATA%\Claude\claude_desktop_config.json）：

{
  "mcpServers": {
    "wheel-size-api": {
      "command": "uvx",
      "args": ["wheel-size-mcp"],
      "env": {
        "WHEELSIZE_API_KEY": "your-api-key-here"
      }
    }
  }
}

Cursor

添加到项目根目录下的 .cursor/mcp.json：

{
  "mcpServers": {
    "wheel-size-api": {
      "command": "uvx",
      "args": ["wheel-size-mcp"],
      "env": {
        "WHEELSIZE_API_KEY": "your-api-key-here"
      }
    }
  }
}

Windsurf

添加到 ~/.codeium/windsurf/mcp_config.json：

{
  "mcpServers": {
    "wheel-size-api": {
      "command": "uvx",
      "args": ["wheel-size-mcp"],
      "env": {
        "WHEELSIZE_API_KEY": "your-api-key-here"
      }
    }
  }
}

Zed

添加到 Zed 的 settings.json（Cmd+, → 打开设置）：

{
  "context_servers": {
    "wheel-size-api": {
      "command": {
        "path": "uvx",
        "args": ["wheel-size-mcp"],
        "env": {
          "WHEELSIZE_API_KEY": "your-api-key-here"
        }
      }
    }
  }
}

4. 重启客户端

MCP 服务会在客户端启动时自动运行。

远程服务（Streamable HTTP）

除了 stdio，服务还可以作为独立的 HTTP 服务运行——适合托管一个共享实例，而不是在每台机器上都安装 Python：

wheel-size-mcp --transport http --port 8000

MCP 端点位于 http://127.0.0.1:8000/mcp/。将支持 HTTP 的客户端指向该端点：

{
  "mcpServers": {
    "wheel-size-api": {
      "url": "http://127.0.0.1:8000/mcp/"
    }
  }
}

安全性：服务默认绑定到 127.0.0.1。WHEELSIZE_API_KEY 保存在服务端，因此任何能够访问该端口的人都会消耗你的 API 配额——只有在反向代理负责处理身份验证的情况下，才可以将服务暴露到 localhost 以外的地址（--host 0.0.0.0）。

可用工具（22 个）

目录 — 车辆查询

工具	描述
ws_list_makes	列出所有制造商。从这里开始。
ws_list_models	列出某个品牌的车型（例如 Toyota → Camry、Corolla……）。
ws_list_years	列出某品牌和车型的可用年份。
ws_list_generations	列出某品牌和车型的世代（可替代年份）。
ws_list_modifications	列出特定车辆的配置（例如 2.0i、3.0 V6……）。
ws_list_regions	列出市场区域（USDM、EUDM、JDM……）。

搜索 — 适配数据

工具	描述
ws_search_by_vehicle	查询车辆的原厂车轮/轮胎规格。需要 modification 或 region，以及 year 或 generation（除非提供了 modification）。
ws_search_by_rim	查找与轮毂兼容的车辆（精确规格或最小/最大范围）。
ws_search_by_tire	按公制轮胎尺寸查找车辆，可使用速度、负载、前后配胎筛选条件和细化维度。
ws_search_by_hf_tire	按高浮力（LT）英寸尺寸查找车辆（例如 31x10.50R15）。
ws_check_rim_fitment_for_vehicle	“这些轮毂适配我的 2020 款 Civic 吗？”——一次调用即可检查适配情况。
ws_check_tire_fitment_for_vehicle	公制轮胎尺寸的适配检查。
ws_check_hf_tire_fitment_for_vehicle	高浮力轮胎尺寸的适配检查。
ws_calculate_upsteps	加大/减小尺寸计算器：非对称直径范围（steps_min/steps_max）、每种直径的数量，以及宽度/直径公差。

分类 — 电商产品卡片

工具	描述
ws_find_tires_for_rim	适用于某轮毂规格的轮胎尺寸。
ws_find_vehicles_for_rim	适配指定轮毂的车辆（几何 2D 筛选）。
ws_find_vehicle_modifications_for_rim	深入查看特定代系的车型配置。
ws_find_vehicles_for_tire	使用指定轮胎尺寸的车辆。
ws_find_vehicle_modifications_for_tire	深入查看使用该轮胎的某一代系车型配置。
ws_find_vehicles_for_package	适配轮毂与轮胎组合的车辆。
ws_find_vehicle_modifications_for_package	深入查看适配轮毂与轮胎套装的车型配置。

实用工具

工具	描述
ws_get_spec_metadata	任意规格的计算几何数据、总体统计数据和智能提示。

发动机和动力总成数据

自 2026-09-15 API 发布起，ws_list_modifications、ws_search_by_vehicle 和 ws_check_*_fitment_for_vehicle 工具返回的每一条车型配置数据都包含两个并列数据块：

• engine — 旧版数据块 {fuel, capacity, type, power, code}，保持不变。engine.power 是主要功率数据，其来源取决于电气化级别（仅燃烧发动机车辆和轻度混合动力车辆取燃烧发动机功率，全混合动力、插电式混合动力和电动车取系统功率）。engine.fuel 是显示用字符串；应使用动力总成燃料代码进行分组和筛选。
• powertrain — combustion_engine、electrification_level、primary_fuel、secondary_fuel、engine_power、system_power、engine_power_secondary、motors。ws_search_by_vehicle 按 API 原样返回此数据块（功率对象为 {kW, PS, hp}，燃料引用为 {code, title}）；列表和适配检查工具则返回精简摘要（hp 功率数据、燃料代码、motors [{axle, hp, code}]），以控制令牌用量。

枚举和燃料代码中的缺省词是数据，并非错误：not_applicable（不适用 — BEV 没有发动机）、not_reported（适用，但尚未记录）、unknown（电气化级别和燃料均未记录）。engine_power 仅指燃烧发动机功率，也是大多数其他车辆数据提供商发布为“功率”的数据（对于双燃料车辆，在填充 engine_power_secondary 期间，它仍可能是两个发动机额定功率中较高的那个）；system_power 是制造商声明的整个动力总成功率，通常在全混合动力、插电式混合动力以及每根车轴都有电机的电动车之外为 null，且绝不能通过相加发动机和电机功率来推算。

ws_list_modifications 的 fuel 筛选器接受燃料代码（biodiesel_blend, cng, diesel, e100, electric, ethanol_blend, flex_fuel, h2, hybrid, lpg, petrol, petrol_cng, petrol_lpg）；单个值会匹配旧版 engine.fuel、主要燃料或次要燃料，也可以直接传入从 powertrain.primary_fuel / secondary_fuel 读取的实际代码。仍接受 natural-gas 等旧拼法；缺省词（not_applicable、not_reported、unknown）以及其他任何值都会导致 400 错误。

MCP 提示词

预构建的工作流提示词，用于引导大模型 Agent 执行多步骤操作：

提示词	描述
vehicle_fitment_lookup	针对车辆描述的完整目录→搜索链
rim_compatibility_check	用于轮毂适配的元数据→分类流程
product_card_generation	车轮／套装的电商产品卡片工作流

环境变量

变量	必填	默认值	说明
WHEELSIZE_API_KEY	是	—	来自 developer.wheel-size.com 的 API 密钥
API_BASE_URL	否	https://api.wheel-size.com	API 基础 URL
API_HOST_HEADER	否	—	Host 请求头覆盖值（仅本地 Docker 路由时需要）
MCP_TRANSPORT	否	stdio	stdio 或 http（与 --transport 相同）
MCP_HOST	否	127.0.0.1	http 传输的绑定地址（与 --host 相同）
MCP_PORT	否	8000	http 传输的端口（与 --port 相同）

API 服务条款

搜索工具（ws_search_by_vehicle、ws_search_by_rim、ws_search_by_tire、ws_search_by_hf_tire、ws_check_*_fitment_for_vehicle 检查）和分类工具（ws_find_*）必须由真实用户发起，具体规定见 API 使用条款。不得在自主 Agent 循环或批量数据生成中调用这些工具。目录工具、实用工具和 ws_calculate_upsteps 不受此限制。

评测

tests/test_questions.json 包含 12 个类别中的 89 个自然语言问题（目录导航、适配查询、反向搜索、适配检查、升级尺寸计算、电商产品卡片、规格元数据、多步骤工作流、边缘情况、工具选择）。每个条目都包含 expected_tools、可选的 expected_params / expected_params_search，以及自由文本 tests 注释。

evals/run_evals.py 会将这些问题提交给一个附带 MCP 工具的真实 Claude 模型，记录它调用了哪些工具及其参数，并根据预期进行评分，从而发现工具描述和服务端指令中的回归问题：

# needs ANTHROPIC_API_KEY and a reachable Wheel Fitment API; costs money
uv sync --group evals
uv run --group evals python evals/run_evals.py                  # all questions
uv run --group evals python evals/run_evals.py -n 10            # smoke run
uv run --group evals python evals/run_evals.py --category catalog_flow
uv run --group evals python evals/run_evals.py --json report.json --min-pass 0.8

评分是确定性的（不使用 LLM 评判）：每个预期工具都必须被调用（按多重集计数——重复调用也计入，允许额外的导航调用），并且至少有一次调用必须携带预期参数。不具备机器可检查预期的问题会标记为 SKIP，且不计入通过率。默认模型已固定为 claude-sonnet-5，以便通过率历史记录保持可比；可使用 --model 覆盖。

评测运行器不属于 pytest 或 CI——它会产生 Anthropic API 费用。评分逻辑本身在 CI 中通过单元测试进行测试（tests/test_eval_grading.py）。服务条款说明：每个问题都模拟用户发起的请求，因此符合搜索工具限制。

开发

# Install dev dependencies
uv sync --dev

# Unit tests (no API needed — this is what CI runs)
uv run pytest -m "not integration"

# Full test suite (requires a private API instance, see note below)
uv run pytest

# Lint
uv run ruff check .

# Run server (stdio)
wheel-size-mcp

测试说明：集成测试针对 API 的私有测试实例运行，并会在无法访问该实例时自动跳过。外部贡献者应运行单元测试套件（pytest -m "not integration"），该套件会模拟所有 HTTP 请求，也是 CI 在每次推送和拉取请求时运行的测试。