# Reported issues for CellarTracker

Pod holds 17 of 33 problems reported by people outside the maintainer team. Issues filed by the project's own owners, members and collaborators are excluded entirely — a maintainer's release checklist is not a warning to a prospective user.

Back to [CellarTracker](/mcp/cellartracker).

## Most discussed

### MCP surface modernization: tool annotations, structured output, pagination

## Context (2026-07-11 audit) - backlog, split before implementing

The server predates several MCP surface conventions:

1. **Tool annotations**: no `readOnlyHint`/`openWorldHint` hints. All 8 data tools are read-only - annotating lets clients display trust signals. Cheap.
2. **Structured output**: all tools return preformatted text only. Adding `structuredContent` with output schemas would let clients compute over results instead of re-parsing prose. Consider the SDK's `registerTool` API (titl

[Read the thread](https://github.com/slavins-co/cellartracker-mcp/issues/54) · 2026-07-11 · closed · 5 comments

### Docs sync: skill tool names, missing tools, README wishlist ratings claim

## Context (2026-07-11 audit)

Documentation drifted from the implementation:

1. `skills/cellartracker-data/SKILL.md` lists tools with **underscores** (`search_cellar`, `drinking_recommendations`, ...) but the server registers **hyphens** (`search-cellar`). 
2. The same skill's tool list omits `consumption-history` and `tasting-notes` (added in PR #10).
3. The skill says CSVs are "UTF-8 encoded (converted from windows-1252 by export script)" - a reference to the retired Python-era export script

[Read the thread](https://github.com/slavins-co/cellartracker-mcp/issues/53) · 2026-07-11 · closed · 2 comments

### Small robustness batch: scoped cache deletion, score rounding, date-parse warning

## Context (2026-07-11 audit)

Three small independent fixes, batched for one session:

**(a) Scoped cache deletion.** `clearUserData()` (src/config.ts:150-167) unlinks **every** file in the cache dir. If a user points `CT_CACHE_DIR` at a shared directory, `clear-user-data` wipes unrelated files. Restrict deletion to known table CSVs (`<Table>_*.csv` for the 8 table prefixes, timestamped + `_latest`).

**(b) Score rounding.** `formatScores()` (src/server.ts:35) emits raw floats - live output inc

[Read the thread](https://github.com/slavins-co/cellartracker-mcp/issues/46) · 2026-07-11 · closed · 2 comments

### Add .mcpb Desktop Extension for Claude Desktop

The plugin currently only works in Claude Code (via the marketplace). Claude Desktop uses a separate extension system based on `.mcpb` bundles — a ZIP archive containing a manifest, server implementation, and bundled dependencies.

## Goal

Package the MCP server as a `.mcpb` Desktop Extension so Claude Desktop users can install with one click.

## What .mcpb requires

- `manifest.json` — extension metadata, server config, env var prompts
- Bundled server code + dependencies (self-contained, no 

[Read the thread](https://github.com/slavins-co/cellartracker-mcp/issues/12) · 2026-03-13 · closed · 2 comments

### recent-deliveries: hint most-recent delivery when the default window is empty

## Problem

`recent-deliveries` defaults to the last 30 days. When nothing arrived recently it returns "No deliveries in this window." — which reads as "broken" on first run. (Live-verified: newest delivery on this account is 2026-04-26, so the no-arg call returns empty today.)

## Proposal

When the window is empty, surface the most-recent delivery date so the user knows to widen the range:
> No deliveries in the last 30 days. Most recent delivery was 2026-04-26 — pass `date_from` to widen the 

[Read the thread](https://github.com/slavins-co/cellartracker-mcp/issues/71) · 2026-07-11 · closed · 1 comment

### Add an 'incoming orders' tool over the Pending table

## Background

The `Pending` table (in-transit / not-yet-delivered orders) is fetched on every refresh but no tool exposes it. The 2026-07-11 audit initially assumed PR #39 (`recent-deliveries`) covered this, but #39 correctly queries the `Purchase` table's delivered rows ("what landed") — the opposite of `Pending` ("what's coming"). So `Pending` remains unexposed.

## Proposal

Add a tool (e.g. `incoming-orders`) over the `Pending` table listing wines ordered but not yet received.

## Design no

[Read the thread](https://github.com/slavins-co/cellartracker-mcp/issues/70) · 2026-07-11 · closed · 1 comment

### Add CellarTracker deep links (iWine) to tool output

## Context (2026-07-11 audit)

The server is read-only by design (confirmed decision, 2026-07-11: the only write path is unsanctioned scraping that breaks against CellarTracker's WAF). Deep links keep that stance while making manual edits one click away: after Claude recommends a bottle, the user can jump straight to its CellarTracker page to log a consumption or edit.

`iWine` is the universal key and is present in all export tables.

## Fix

- Append a wine-page URL to entries in `search-cella

[Read the thread](https://github.com/slavins-co/cellartracker-mcp/issues/52) · 2026-07-11 · closed · 1 comment

### Add pro-reviews tool backed by the ProReview table

## Context (2026-07-11 audit)

`ProReview` (manually entered professional reviews) is a documented xlquery table, not fetched. Only valuable for users who enter pro reviews - hence low priority - but it completes coverage of the sanctioned read surface alongside the FoodTags issue.

## Fix

- Add `ProReview` to `TABLES`; add a tool to search pro reviews by wine/critic/score (join to List via iWine).
- Discover and document the column set on first authenticated pull.
- Empty-table case must retur

[Read the thread](https://github.com/slavins-co/cellartracker-mcp/issues/51) · 2026-07-11 · open · 1 comment

## Most recent

### Add food-pairing tool backed by the FoodTags table

## Context (2026-07-11 audit)

`FoodTags` is one of the 12 documented xlquery export tables (verified against the official export doc and the reference Python client) but is not fetched. Food pairing is a natural conversational query ("what should I open with roast chicken?") that currently has no data path.

## Fix

- Add `FoodTags` to `TABLES` in src/exporter.ts (params: `Table: "FoodTag"` - note the Python client uses singular `FoodTag`; verify the exact value with one authenticated pull).
- 

[Read the thread](https://github.com/slavins-co/cellartracker-mcp/issues/50) · 2026-07-11 · open · 1 comment

### Add bottle-level tool over the Bottles table

## Context (2026-07-11 audit)

The `Bottles` table (raw per-bottle view including `BottleState`) is fetched on every refresh but **no tool exposes it** - pure fetch cost today. Per-bottle queries (size/format, barcode, state, bin-level detail) currently have no answer path.

## Fix

Add a tool (e.g. `bottle-details`) over the already-cached `Bottles` table: filter by wine name, location/bin, size, BottleState; sensible result cap consistent with other tools.

## Notes

- ~~Sequencing: review/mer

[Read the thread](https://github.com/slavins-co/cellartracker-mcp/issues/49) · 2026-07-11 · closed · 1 comment

### Diacritic-insensitive search: 'rhone' should match 'Rhône'

## Context (2026-07-11 audit, live-confirmed)

`search-cellar region="rhone"` returns **no results**; `region="Rhône"` returns 3 wines. Wine data is saturated with diacritics (Côte, Rhône, Grüner, Châteauneuf) and US keyboards do not produce them - so the most natural queries silently miss.

Cause: `search()` (src/query.ts:44-55) compares with plain `.toLowerCase().includes()`. Same issue in the region geo-field filter inside `search-cellar` (src/server.ts:139-145) and the `get-wishlist` query f

[Read the thread](https://github.com/slavins-co/cellartracker-mcp/issues/48) · 2026-07-11 · closed · 1 comment

### Add retry with backoff to fetchTable

## Context (2026-07-11 audit)

`fetchTable()` (src/exporter.ts:45) makes a single attempt with a 60s timeout. Any transient network hiccup or 5xx surfaces immediately as a tool error, and with 8 tables fetched in parallel the odds of one transient failure per refresh are non-trivial (see also the partial-refresh staleness issue, which this compounds).

## Fix

- Retry network errors and HTTP 5xx: 2 retries with jittered exponential backoff (e.g. ~1s, ~3s).
- Never retry `AuthError` (or 4xx).
- K

[Read the thread](https://github.com/slavins-co/cellartracker-mcp/issues/47) · 2026-07-11 · closed · 1 comment

### Auth-failure detection: match CellarTracker's not-logged-in marker instead of any-HTML sniff

## Context (2026-07-11 audit)

`fetchTable()` (src/exporter.ts:97) throws `AuthError` whenever the response body starts with `<`. CellarTracker also returns HTML for maintenance pages and server errors - so an outage tells users their password is wrong, which is misleading and may cause them to churn credentials.

Platform research confirmed the actual auth-failure signature: the returned HTML contains the literal string:

    You are currently not logged into CellarTracker.

This is what the re

[Read the thread](https://github.com/slavins-co/cellartracker-mcp/issues/45) · 2026-07-11 · closed · 1 comment

### Dedupe concurrent cache refreshes (in-flight promise)

## Context (2026-07-11 audit, code-level)

Every tool handler starts with `getFreshPaths()` (src/server.ts:25). MCP clients (Claude) routinely issue tool calls in parallel. On a cold or expired cache, N concurrent tool calls each trigger their own `exportAll()` - up to **8×N simultaneous credentialed GETs** against CellarTracker, a small operation whose rate-limit/lockout policy is undocumented (research could not verify any published limits; their ToS page blocks automated reading).

## Fix

Mo

[Read the thread](https://github.com/slavins-co/cellartracker-mcp/issues/44) · 2026-07-11 · closed · 1 comment

### Surface server version in refresh-data output

## Context (2026-07-11 audit)

No user-visible way exists to see which version/build is actually running. The stale-dist defect (see the build-staleness issue) went unnoticed for ~4 months partly because nothing in tool output reveals the running version. The MCP initialize handshake carries the version but users never see it.

## Fix

`src/server.ts` already loads `version` from `package.json` via `createRequire`. Append a line to the `refresh-data` tool output, e.g. `Server: cellartracker-mcp 

[Read the thread](https://github.com/slavins-co/cellartracker-mcp/issues/42) · 2026-07-11 · closed · 1 comment

### Build staleness: add npm prepare script and rebuild dist

## Context (2026-07-11 audit, live-confirmed)

The running plugin on the maintainer's machine served code compiled **Mar 14 21:43** while `src/query.ts` received the #35/#37 fixes at **22:21 the same night** - the fixes never reached the running server for ~4 months. Live effect: `cellar-stats group_by=color` returned row counts (Red 32 / White 25, sum 57) instead of quantities (Red 36 / White 28, sum 64).

Root cause chain:
1. Local `dist/` was never rebuilt after the src fix.
2. The plugin `.m

[Read the thread](https://github.com/slavins-co/cellartracker-mcp/issues/40) · 2026-07-11 · closed · 1 comment

### Fix: server.ts hardcoded version not checked by verify-versions

## Problem

`server.ts:104` hardcodes `version: "0.2.6"`. The `verify-versions` script checks 4 files (package.json, manifest.json, plugin.json, marketplace.json) but not this one. It will drift on the next version bump.

## Fix

Either:
- Read the version from `package.json` at runtime (e.g., `import` or `readFileSync`), or
- Add `server.ts` as a 5th check in the `verify-versions` script

[Read the thread](https://github.com/slavins-co/cellartracker-mcp/issues/36) · 2026-03-15 · closed · 1 comment

The remaining reports are on [the project's issue tracker](https://github.com/slavins-co/cellartracker-mcp/issues).