wheel-size-mcp 0.4.0__tar.gz

wheel_size_mcp-0.4.0/.claude/skills/sync-tools-inventory/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: sync-tools-inventory
+description: "Sync tool descriptions from docs/tools-inventory.md to Python source files in src/ws_mcp/tools/. Use after editing the inventory doc to push changes to code."
+disable-model-invocation: true
+user-invocable: true
+allowed-tools: Read, Edit, Grep, Glob, Bash(git diff *), Bash(uv run ruff check *), Bash(uv run pytest *)
+effort: high
+---
+
+# Sync Tools Inventory → Code
+
+Synchronize tool docstrings and parameter descriptions from `docs/tools-inventory.md` (the single source of truth) into the Python tool source files.
+
+## Step 0: Drift Safety Check — ALWAYS RUN FIRST
+
+```bash
+uv run pytest tests/test_inventory_sync.py -q
+```
+
+This test compares both sides (docstrings + parameter descriptions, whitespace-normalized).
+
+- **All green** → doc and code are already in sync. Nothing to do; report that and stop.
+- **Failures** → read each reported diff and classify it:
+  - The doc side contains the edits the user just made → this is the change set to push to code. Proceed.
+  - The CODE side contains content absent from the doc, in sections the user did NOT just edit → **code is newer than the doc (reverse drift). STOP.** Do not overwrite it. Report the diff and ask the user to back-port code → doc first (or confirm the overwrite explicitly).
+
+Never skip this step: a doc→code sync over a stale doc silently destroys newer docstrings, and `ruff` will not catch it.
+
+## Step 1: Read Both Sides
+
+Read `docs/tools-inventory.md` and all four tool source files:
+
+| Inventory Section | Source File |
+|---|---|
+| `## Catalog` | `src/ws_mcp/tools/catalog.py` |
+| `## Search` | `src/ws_mcp/tools/search.py` |
+| `## Classified` | `src/ws_mcp/tools/classified.py` |
+| `## Utility` | `src/ws_mcp/tools/utility.py` |
+
+## Step 2: Parse Inventory Format
+
+Each tool in inventory.md follows this structure:
+
+```markdown
+### `tool_name`
+
+**API**: `GET /v2/endpoint/`
+
+**Docstring**:
+> Line 1 of docstring
+> Line 2 of docstring
+> ...
+
+**Parameters**:
+| Parameter | Type | Description |
+|----------|-----|----------|
+| `param_name` | `type` | Description text |
+```
+
+Format details:
+
+- **Heading suffixes**: a heading may carry a note after the closing backtick — e.g. `` ### `check_rim_fitment_for_vehicle` (composite) ``. The tool name is only what is inside the backticks.
+- **No parameters**: `list_regions` has `**Parameters**: none` instead of a table.
+- **Escaped pipes**: cells may contain `\|` (e.g. type `` `"concise" \| "full"` ``) — treat `\|` as a literal `|` inside the cell, not a column separator.
+- **Shared geometric block**: the `## Classified` section opens with a shared parameter table (marked "shared geometric parameters"). Tool tables reference it with the row `| *+ shared geometric parameters* | | see block above |` instead of repeating those rows. When comparing a tool's parameters, expand the shared block into its table.
+- **API lines** may have suffixes too (`+ MCP-side year filtering`) — informational only, not synced.
+
+Extract for each tool:
+- **Tool name**: from the backticks in the `### ` heading
+- **Docstring lines**: all `> ` prefixed lines under **Docstring** (strip the `> ` prefix; a bare `>` is a blank line; indentation after `> ` is preserved)
+- **Parameter names and descriptions**: from the "Parameter" and "Description" columns (strip backticks from names)
+
+## Step 3: Compare and Update Docstrings
+
+For each tool, find the function in the source file by matching `async def tool_name(`.
+
+**Docstring update rule**: Replace the entire `"""..."""` block under the function signature with the content from inventory. Preserve the indentation level (8 spaces for tool functions).
+
+Format:
+```python
+    async def tool_name(...) -> dict:
+        """First line of docstring.
+
+        Remaining lines of docstring.
+        Preserving blank lines from the inventory.
+        """
+```
+
+- The first `> ` line becomes the first line of the docstring (on same line as `"""`)
+- Subsequent `> ` lines follow with 8-space indentation
+- Empty `> ` lines (just `>`) become blank lines in the docstring
+- Close with `"""` on its own line at 8-space indent
+
+## Step 4: Compare and Update Parameter Descriptions
+
+For each parameter in the inventory table, find the matching `Field(description="...")` and update the description string. The Description column maps to the code **verbatim** — do not add or drop range/default annotations.
+
+**Where the Field lives depends on the module:**
+
+- `catalog.py`, `search.py`, `utility.py`: inline in the function signature — `param: Annotated[type, Field(description="...")]`.
+- `classified.py`: mostly in **module-level Annotated aliases** at the top of the file (`_BoltPattern`, `_RimDiameter`, `_Cb`, `_Sort`, …) shared by several tools. The doc's shared geometric block maps to these aliases. Editing an alias changes every tool that uses it — that is intended. If the doc asks for different descriptions of the same shared parameter in different tools, report a WARNING instead of editing (per-tool divergence requires restructuring the aliases first).
+
+**Update rule**: Replace only the `description="old text"` value inside `Field(...)`. Do NOT change the type annotation, default value, or other Field arguments (ge, le, etc.). Unescape `\|` → `|` when writing into Python strings.
+
+## Step 5: Detect Structural Changes
+
+Compare the set of parameter names in inventory (with the shared block expanded) vs code for each tool.
+
+- **New parameter in inventory but not in code**: Report as WARNING — cannot auto-add because type annotation, default value, and Field constraints are needed. List the parameter name and suggest the user add it manually.
+- **Parameter in code but removed from inventory**: Report as WARNING — do not auto-remove. List the parameter and ask the user to confirm deletion.
+
+## Step 6: Validate
+
+After all edits:
+
+1. `uv run ruff check src/ws_mcp/tools/` — no syntax/lint errors
+2. `uv run pytest tests/test_inventory_sync.py -q` — MUST be green now: doc and code are byte-consistent again
+3. Show a summary of all changes made:
+   - Which tools had docstring updates
+   - Which parameters had description updates
+   - Any structural warnings (added/removed params)
+
+## Step 7: Cross-File Consistency Check
+
+Tool behavior and parameter contracts are also duplicated in two places this skill does NOT edit:
+
+- `src/ws_mcp/server.py` — the FastMCP `instructions` block (workflows, critical rules, parameter requirements)
+- `README.md` — the "Available Tools" table
+
+After a sync, grep both for statements about the tools whose descriptions changed. If a synced change contradicts them (e.g. a parameter requirement changed), report the exact lines as WARNINGS for the user to update manually. Do not auto-edit these files.
+
+## Important Rules
+
+- NEVER proceed past Step 0 when code-side content is newer than the doc
+- NEVER change function signatures, return types, or logic — only docstrings and Field descriptions
+- NEVER change Field constraints (ge, le, etc.) — only the description string
+- NEVER change type annotations — only descriptions
+- Preserve existing indentation style in each file
+- If a tool exists in code but NOT in inventory — skip it, report as info
+- If a tool exists in inventory but NOT in code — report as WARNING
+- Use the Edit tool for all changes (not Write) to preserve file content

wheel_size_mcp-0.4.0/.github/workflows/ci.yml

@@ -0,0 +1,28 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --dev
+
+      - name: Lint
+        run: uv run ruff check .
+
+      - name: Unit tests
+        run: uv run pytest -m "not integration"

wheel_size_mcp-0.4.0/.gitignore

@@ -0,0 +1,37 @@
+# Python bytecode
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Build / packaging
+*.egg-info/
+*.egg
+.eggs/
+dist/
+build/
+
+# Virtual environments
+.venv/
+venv/
+
+# Environment variables
+.env
+
+# Tool caches
+.pytest_cache/
+.ruff_cache/
+.playwright-mcp/
+
+# AI assistant configs
+CLAUDE.md
+.mcp.json
+claudedocs/
+.claude/settings.local.json
+.codex-review/
+
+# OS files
+.DS_Store
+
+# Symlinks to external repos (local dev convenience — never publish)
+# NB: no trailing slash — must match the SYMLINK, not just a directory
+/development

wheel_size_mcp-0.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 WHEEL SIZE KZ LLP
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

wheel_size_mcp-0.4.0/PKG-INFO

@@ -0,0 +1,286 @@
+Metadata-Version: 2.4
+Name: wheel-size-mcp
+Version: 0.4.0
+Summary: MCP server for Wheel Fitment API — enables Claude Code and LLM agents to query vehicle wheel/tire compatibility data
+Project-URL: Homepage, https://www.wheel-size.com
+Project-URL: Repository, https://github.com/driveate/wheel-size-mcp
+Project-URL: Issues, https://github.com/driveate/wheel-size-mcp/issues
+Project-URL: Documentation, https://developer.wheel-size.com
+Project-URL: API Reference, https://api.wheel-size.com/v2/openapi/
+Author-email: WHEEL SIZE KZ LLP <info@wheel-size.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: claude-code,fastmcp,mcp,wheel-fitment,wheel-size
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.12
+Requires-Dist: fastmcp>=3.4.1
+Requires-Dist: httpx>=0.27
+Description-Content-Type: text/markdown
+
+# wheel-size-mcp
+
+<!-- mcp-name: io.github.driveate/wheel-size-mcp -->
+
+The **official** MCP server for the [Wheel Fitment API](https://api.wheel-size.com/v2/openapi/) — built and maintained by [Wheel-Size.com](https://www.wheel-size.com), the API provider. Gives LLM agents access to vehicle wheel and tire compatibility data.
+
+Ask your AI assistant things like:
+- "What are the OEM wheel specs for a 2024 Toyota Camry?"
+- "Which vehicles fit 5x114.3 18x8 ET35 rims?"
+- "Calculate plus-size options for 225/50R17 on 7Jx17 ET40"
+- "Generate a product card for this wheel showing all compatible vehicles"
+
+## Quick Start
+
+### 1. Get an API key
+
+Sign up at [developer.wheel-size.com](https://developer.wheel-size.com) and copy your API key.
+
+### 2. Set the API key in your shell
+
+Add to your `~/.zshrc` (or `~/.bashrc`):
+
+```bash
+export WHEELSIZE_API_KEY="your-api-key-here"
+```
+
+Then reload your shell: `source ~/.zshrc`
+
+### 3. Add to your AI client
+
+Choose your client below — each config block is copy-paste ready.
+
+#### Claude Code
+
+```bash
+claude mcp add wheel-size-api -- uvx wheel-size-mcp
+```
+
+Or add to `.mcp.json` in your project root:
+
+```json
+{
+  "mcpServers": {
+    "wheel-size-api": {
+      "command": "uvx",
+      "args": ["wheel-size-mcp"],
+      "env": {
+        "WHEELSIZE_API_KEY": "${WHEELSIZE_API_KEY}"
+      }
+    }
+  }
+}
+```
+
+#### Claude Desktop
+
+Add to `claude_desktop_config.json` (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, `%APPDATA%\Claude\claude_desktop_config.json` on Windows):
+
+```json
+{
+  "mcpServers": {
+    "wheel-size-api": {
+      "command": "uvx",
+      "args": ["wheel-size-mcp"],
+      "env": {
+        "WHEELSIZE_API_KEY": "your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+#### Cursor
+
+Add to `.cursor/mcp.json` in your project root:
+
+```json
+{
+  "mcpServers": {
+    "wheel-size-api": {
+      "command": "uvx",
+      "args": ["wheel-size-mcp"],
+      "env": {
+        "WHEELSIZE_API_KEY": "your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+#### Windsurf
+
+Add to `~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "wheel-size-api": {
+      "command": "uvx",
+      "args": ["wheel-size-mcp"],
+      "env": {
+        "WHEELSIZE_API_KEY": "your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+#### Zed
+
+Add to your Zed `settings.json` (Cmd+, → Open Settings):
+
+```json
+{
+  "context_servers": {
+    "wheel-size-api": {
+      "command": {
+        "path": "uvx",
+        "args": ["wheel-size-mcp"],
+        "env": {
+          "WHEELSIZE_API_KEY": "your-api-key-here"
+        }
+      }
+    }
+  }
+}
+```
+
+### 4. Restart your client
+
+The MCP server starts automatically when the client launches.
+
+## Remote Server (Streamable HTTP)
+
+Besides stdio, the server can run as a standalone HTTP service — useful for hosting one shared instance instead of installing Python on every machine:
+
+```bash
+wheel-size-mcp --transport http --port 8000
+```
+
+The MCP endpoint is served at `http://127.0.0.1:8000/mcp/`. Point HTTP-capable clients at it:
+
+```json
+{
+  "mcpServers": {
+    "wheel-size-api": {
+      "url": "http://127.0.0.1:8000/mcp/"
+    }
+  }
+}
+```
+
+**Security**: the server binds to `127.0.0.1` by default. The `WHEELSIZE_API_KEY` lives on the server side, so anyone who can reach the port consumes your API quota — expose it beyond localhost (`--host 0.0.0.0`) only behind a reverse proxy that handles authentication.
+
+## Available Tools (21)
+
+### Catalog — vehicle lookup
+
+| Tool | Description |
+|------|-------------|
+| `ws_list_makes` | List all manufacturers. **Start here.** |
+| `ws_list_models` | Models for a make (e.g. Toyota → Camry, Corolla…). |
+| `ws_list_years` | Available years for a make/model. |
+| `ws_list_generations` | Generations for a make/model (alternative to years). |
+| `ws_list_modifications` | Trims for a specific vehicle (e.g. 2.0i, 3.0 V6…). |
+| `ws_list_regions` | Market regions (USDM, EUDM, JDM…). |
+
+### Search — fitment data
+
+| Tool | Description |
+|------|-------------|
+| `ws_search_by_vehicle` | OEM wheel/tire specs for a vehicle. Requires `modification` or `region`, plus `year` or `generation` (unless `modification` is given). |
+| `ws_search_by_rim` | Find vehicles compatible with a rim (exact specs or min/max ranges). |
+| `ws_search_by_tire` | Find vehicles by metric tire size, with speed/load/staggered filters and refinement facets. |
+| `ws_search_by_hf_tire` | Find vehicles by high-flotation (LT) inch size (e.g. 31x10.50R15). |
+| `ws_check_rim_fitment_for_vehicle` | "Will these rims fit my 2020 Civic?" — one-call fitment check. |
+| `ws_check_tire_fitment_for_vehicle` | Same for a metric tire size. |
+| `ws_check_hf_tire_fitment_for_vehicle` | Same for a high-flotation tire size. |
+| `ws_calculate_upsteps` | Plus/minus sizing calculator with width/diameter tolerances. |
+
+### Classified — product cards for e-commerce
+
+| Tool | Description |
+|------|-------------|
+| `ws_find_tires_for_rim` | Compatible tire sizes for a rim spec. |
+| `ws_find_vehicles_for_rim` | Vehicles that fit a given rim (geometric 2D filtering). |
+| `ws_find_vehicle_modifications_for_rim` | Drill down into trims for a specific generation. |
+| `ws_find_vehicles_for_tire` | Vehicles that use a specific tire size. |
+| `ws_find_vehicles_for_package` | Vehicles compatible with a rim + tire combo. |
+| `ws_find_vehicle_modifications_for_package` | Drill down into trims for a rim + tire package. |
+
+### Utility
+
+| Tool | Description |
+|------|-------------|
+| `ws_get_spec_metadata` | Computed geometry, population stats, and intelligence hints for any spec. |
+
+## MCP Prompts
+
+Pre-built workflow prompts that guide LLM agents through multi-step operations:
+
+| Prompt | Description |
+|--------|-------------|
+| `vehicle_fitment_lookup` | Complete catalog→search chain for a vehicle description |
+| `rim_compatibility_check` | Metadata→classified flow for rim compatibility |
+| `product_card_generation` | E-commerce product card workflow for wheels/packages |
+
+## Environment Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `WHEELSIZE_API_KEY` | **Yes** | — | API key from [developer.wheel-size.com](https://developer.wheel-size.com) |
+| `API_BASE_URL` | No | `https://api.wheel-size.com` | API base URL |
+| `API_HOST_HEADER` | No | — | Host header override (only needed for local Docker routing) |
+| `MCP_TRANSPORT` | No | `stdio` | `stdio` or `http` (same as `--transport`) |
+| `MCP_HOST` | No | `127.0.0.1` | Bind address for http transport (same as `--host`) |
+| `MCP_PORT` | No | `8000` | Port for http transport (same as `--port`) |
+
+## API Terms of Service
+
+Search tools (`ws_search_by_vehicle`, `ws_search_by_rim`, `ws_search_by_tire`, `ws_search_by_hf_tire`, and the `ws_check_*_fitment_for_vehicle` checks) **must be initiated by real users** per [API Terms of Usage](https://developer.wheel-size.com/api-tos). Do not call in autonomous agent loops. Catalog, classified, utility tools and `ws_calculate_upsteps` have no such restriction.
+
+## Evals
+
+[`tests/test_questions.json`](tests/test_questions.json) contains 89 natural-language questions across 12 categories (catalog navigation, fitment lookups, reverse searches, fitment checks, upstep calculation, e-commerce product cards, spec metadata, multi-step workflows, edge cases, tool selection). Each entry includes `expected_tools`, optional `expected_params` / `expected_params_search`, and a free-text `tests` note.
+
+`evals/run_evals.py` feeds these questions to a real Claude model with the MCP tools attached, records which tools it calls with which parameters, and grades them against the expectations — catching regressions in tool descriptions and server instructions:
+
+```bash
+# 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
+```
+
+Grading is deterministic (no LLM judge): every expected tool must be called (multiset — repeats counted, extra navigation calls allowed), and some single call must carry the expected parameters. Questions without machine-checkable expectations are reported as SKIP and excluded from the pass rate. The default model is pinned (`claude-sonnet-5`) so pass-rate history stays comparable; override with `--model`.
+
+The eval runner is **not** part of pytest or CI — it bills the Anthropic API. The grading logic itself is unit-tested in CI (`tests/test_eval_grading.py`). ToS note: every question simulates a user-initiated request, so the search-tool restriction is respected.
+
+## Development
+
+```bash
+# 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
+```
+
+**Note on tests**: integration tests run against a private test instance of the API and auto-skip when it is unreachable. External contributors should rely on the unit suite (`pytest -m "not integration"`), which mocks all HTTP and is what CI runs on every push and pull request.