@sebamomann/plants-mcp 1.9.0 → 2.0.0

package/CHANGELOG.md

@@ -3,6 +3,65 @@
 Notable changes to `@sebamomann/plants-mcp`. Versioning is semver against the **tool surface** —
 see the table in `AGENTS.md` for what counts as major, minor, and patch.
 
+## 2.0.0 — 2026-09-15
+
+**Plant identity moves to a shared, community-maintained global catalog.** 56 tools registered
+overall (22 read, 17 write, 17 admin). This is a **major** bump — see `docs/mcp-server.md`'s
+"Breaking changes in 2.0.0" section for the full list; summary:
+
+- **`plantTypeId` is now a global catalog id everywhere it appears** (`list_plants`, `get_plant`,
+  `create_plant`, `update_plant`) — a legacy per-user type id cached before this release does not
+  refer to the same row. Re-resolve any cached id via `list_plant_types`/`search_plant_types`.
+- **`list_plant_types` now serves the shared global catalog**, not a per-user list.
+- **New tools:**
+  - `search_plant_types` — fuzzy search the global catalog by name (any locale) or botanical name.
+    Same underlying endpoint as `list_plant_types`; `query` is required here, optional there.
+  - `get_plant_type` — one type's fact sheet: identity, names by locale, parent/cultivar children,
+    effective catalog facts with each field's source (`"own"`/`"inherited"`), approved image URLs,
+    and the caller's own plant count. A `MERGED` id transparently resolves to its survivor.
+- **`create_plant`'s `plantTypeId` is now optional** — omit it (or pass `null`) to add an
+  "unidentified" plant; `nickname` is then required, matching the app's plant form.
+- **`update_plant` gained `plantTypeId` and `nickname`** — re-identify a plant, or make it
+  unidentified (`plantTypeId: null` + a `nickname`).
+- **`get_plant`'s `plantType` field is replaced by `type`** —
+  `{ plantTypeId, nickname, displayName, botanicalName, typeStatus, isUnidentified }`. `list_plants`
+  rows changed the same way.
+- **`get_plant` gained `typeFacts`** — the type's effective light/water/feeding need, toxicity,
+  climate, growth, substrate/propagation, and family/native region.
+- **`get_plant`'s six schedule fields are no longer raw values** — each is now
+  `{ value, source: "plant"|"type"|"none", typeValue }`.
+- **`update_plant_care` no longer accepts `sunRequirement`/`waterRequirement`** — both are type-only
+  facts now, read via `get_plant`'s `typeFacts` or `get_plant_type`.
+- **`null` on `update_plant_care`'s watering/fertilizing-cycle fields now means "follow the type"**
+  instead of "no schedule" — the tool's zod schema now accepts `null` for those four fields, which
+  it previously rejected. A value equal to the type's value is stored as `null` too, so the plant
+  keeps following later changes to the type; `update_plant` switching `plantTypeId` moves values
+  that followed the old type onto the new one (or, to no type, writes them in).
+- **`list_plants`'s `sort=commonName` is renamed `sort=displayName`** (resolved in memory — no
+  longer a database column) and its `search` now matches the plant's nickname and its type's names
+  in every locale, not a legacy `PlantType.commonName` column.
+- **`GlobalPlantTypeStatus` gained a `REJECTED` value** — an admin can reject a user-created
+  `UNVERIFIED` type in the app (required note, plus a merge/unlink outcome for its plants); the
+  row persists, analogous to `MERGED`. `list_plant_types`/`search_plant_types` never return one;
+  `get_plant_type` on a rejected id behaves like `MERGED` (redirects when the outcome was a merge).
+  `admin_get_plant_type`'s `status` can now be `"REJECTED"`. No new tool triggers this yet — see
+  `docs/mcp-server.md`'s roadmap (`admin_reject_plant_type`).
+
+## 1.10.0 — 2026-09-15
+
+**Wishlist tools.** Four tools total — 54 registered overall (20 read, 17 write, 17 admin):
+
+- `list_wishlist` — the caller's wishlist: each wish's plant type (display/botanical name,
+  `typeStatus`) when set, or a free-text `name` fallback, plus dated `notes` and
+  `ownedLivingCount` (how many `LIVING` plants of that type the caller already has).
+- `add_to_wishlist` (write) — add a wish by `plantTypeId` or free-text `name`. Never creates a
+  second wish for a type the caller already has — returns the existing one instead
+  (`duplicate: true`).
+- `add_wishlist_note` (write) — add a dated note to a wish (price, where to get it, a shop link).
+- `remove_from_wishlist` (write) — remove a wish. Not counted as a "destructive" tool in the sense
+  `delete_watering_event`/`delete_fertilization_event` are — a wish carries no collection history,
+  and is trivially re-added.
+
 ## 1.9.0 — 2026-09-15
 
 **Admin keys can now read, directly edit, merge, and review the shared global plant type catalog.**

package/README.md

@@ -60,17 +60,21 @@ needs a running Sprig instance and an API key from it. Start at the
 
 ## What an assistant can do
 
-**50 tools** over your collection: 19 that read it, 14 that write to it. **17 admin tools** are also
+**56 tools** over your collection: 22 that read it, 17 that write to it. **17 admin tools** are also
 available — but only to a key created by an admin — for finding and understanding duplicates in the
 shared global plant type catalog, restructuring its genus/species/cultivar tree, and (6 read-only, 11
 that write) reading, directly editing, merging, and reviewing proposals and duplicate candidates in
 that catalog. See **Admin tools** below.
 
-Reads cover plants, watering and fertilization history, the full care timeline, photo metadata,
-health entries, the derived care schedule, collection-wide activity, and the lookup catalogs.
-Writes cover recording waterings and fertilizings, health notes, dismissing care recommendations,
-editing a plant's care schedule or settings, adding a plant, propagating one, merging plants
-together and reversing that merge, and deleting a watering or fertilization event.
+Reads cover plants, the shared global plant type catalog, watering and fertilization history, the
+full care timeline, photo metadata, health entries, the derived care schedule, collection-wide
+activity, the wishlist, and the lookup catalogs. Writes cover recording waterings and fertilizings,
+health notes, dismissing care recommendations, editing a plant's identity/care schedule/settings,
+adding a plant (identified or not), propagating one, merging plants together and reversing that
+merge, deleting a watering or fertilization event, and managing the wishlist (add, note, remove).
+
+**Plant identity moved to a shared, community-maintained catalog in 2.0.0** — see **Breaking changes
+in 2.0.0** below before upgrading a client that stored a `plantTypeId`.
 
 **Deleting a plant, a photo, or a catalog entry is not possible from here** — that stays UI-only.
 `delete_watering_event` and `delete_fertilization_event` are the two exceptions (see **What this
@@ -102,8 +106,8 @@ healthy server, not a hang — press Ctrl-C.
 
 The scope lives on the API key, is enforced by the app, and cannot be widened from this side.
 
-- **`read`** — on every key. Gates all 19 read tools.
-- **`write`** — opt-in when you create the key. Gates the 14 write tools.
+- **`read`** — on every key. Gates all 22 read tools.
+- **`write`** — opt-in when you create the key. Gates the 17 write tools.
 - **`admin`** — only offered when the key's creator is themselves an admin, and only while they
   still are one (the app re-checks this on every admin-tool call, not just at key creation). Gates
   the 17 admin catalog tools — 6 read-only, 11 that write — see **Admin tools** below. `admin` alone
@@ -124,11 +128,13 @@ point of the scope split.
 
 Not oversights — deliberate limits:
 
-- **No deletes, except two.** Deleting a plant, a photo, or a catalog entry stays UI-only — the
-  blast radius of a misunderstood delete there is a multi-year history, and retiring a plant is a
-  *status* change instead. `delete_watering_event` and `delete_fertilization_event` are the
-  exceptions: a mis-logged event has no such reversible alternative, so those two are destructive
-  and **cannot be undone**.
+- **No deletes of collection history, except two.** Deleting a plant, a photo, or a catalog entry
+  stays UI-only — the blast radius of a misunderstood delete there is a multi-year history, and
+  retiring a plant is a *status* change instead. `delete_watering_event` and
+  `delete_fertilization_event` are the exceptions: a mis-logged event has no such reversible
+  alternative, so those two are destructive and **cannot be undone**. `remove_from_wishlist` is a
+  third delete, but not in the same sense — a wish is a personal to-do item with no history to
+  lose, trivially re-added with `add_to_wishlist` if removed by mistake.
 - **No sales or trades.** Those records name a second person who never consented to your API key.
 - **No share-link creation.** Minting a public URL for your collection is a decision for the UI.
 - **No cross-user access.** Ownership comes from the key; a tool has no way to even express
@@ -143,14 +149,24 @@ Not oversights — deliberate limits:
 | Tool | Endpoint | Arguments |
 |---|---|---|
 | `whoami` | `GET /api/v1/me` | none — who the key belongs to |
-| `list_plants` | `GET /api/v1/plants` | all optional: `status`, `lifecycle`, `locationId`, `plantTypeId`, `soilId`, `fertilizerId`, `tag` (exact match), `search` (type name / notes), `limit` (1–200), `offset`, `sort` |
-| `get_plant` | `GET /api/v1/plants/:id` | `id` **(required)** — full detail: catalogs, care config, lineage, recent events |
+| `list_plants` | `GET /api/v1/plants` | all optional: `status`, `lifecycle`, `locationId`, `plantTypeId` (a **global** catalog id), `soilId`, `fertilizerId`, `tag` (exact match), `search` (nickname / type names / notes), `limit` (1–200), `offset`, `sort` (`displayName`\|`createdAt`\|`updatedAt`\|`acquiredAt`) |
+| `get_plant` | `GET /api/v1/plants/:id` | `id` **(required)** — full detail: identity (`type`), `typeFacts`, catalogs, care config, lineage, recent events |
 
 `status` is one of `LIVING`, `DEAD`, `GIFTED`, `LOST`, `SOLD`, `TRADED`, `MERGED`, `SPLIT`,
 `EXTERNAL`; `lifecycle` is `PROPAGATING` or `ESTABLISHED`. `EXTERNAL` is a **reference plant** —
 somebody else's plant, recorded only as an anchor for propagation lineage. It is never cared for,
 never appears in due/overdue care, and is excluded from `collection_stats`.
 
+Each plant's identity is a `type` object (replacing the old `plantType`):
+`{ plantTypeId, nickname, displayName, botanicalName, typeStatus, isUnidentified }`.
+`plantTypeId` is `null` for an "unidentified" plant — one with no catalog type, just a `nickname`.
+`get_plant` additionally returns `typeFacts` — the type's effective (inheritance-resolved) catalog
+facts (light, water, feeding need, toxicity, climate, growth, substrate/propagation, family/native
+region), keyed by the same field names `get_plant_type` uses — and its six schedule fields
+(`wateringFrequencySummerDays`/`WinterDays`, `wateringFrequencySummer`/`Winter`,
+`fertilizingCycleSummerWeeks`/`WinterWeeks`) as `{ value, source: "plant"|"type"|"none", typeValue }`
+instead of a raw value — see **Breaking changes in 2.0.0** below.
+
 ### Per-plant history
 
 All five take the same arguments: `id` **(required)**, `limit` (1–500), `offset`. Newest first.
@@ -220,23 +236,53 @@ the trip. Returns `{ hasVacation: false }` when there's no upcoming or running s
 this tool never creates or modifies one. `locationId` narrows the plant list to one location; the
 schedule always covers the whole vacation.
 
+### Wishlist
+
+| Tool | Endpoint | Arguments |
+|---|---|---|
+| `list_wishlist` | `GET /api/v1/wishlist` | none |
+
+Plants the caller wants but doesn't own yet. Each entry carries `plantTypeId` (when it's a global
+catalog type, with its display/botanical name and `typeStatus`) or a free-text `name` fallback for
+a species not yet in the catalog, a `notes` array (dated, e.g. price or where to get it), and
+`ownedLivingCount` — how many `LIVING` plants of that type the caller already has.
+
 ### Catalogs
 
-For resolving the ids the filters take. No arguments.
+For resolving the ids the filters take.
 
-| Tool | Endpoint |
-|---|---|
-| `list_locations` | `GET /api/v1/locations` |
-| `list_plant_types` | `GET /api/v1/plant-types` |
-| `list_soils` | `GET /api/v1/soils` |
-| `list_fertilizers` | `GET /api/v1/fertilizers` |
+| Tool | Endpoint | Arguments |
+|---|---|---|
+| `list_locations` | `GET /api/v1/locations` | none |
+| `list_plant_types` | `GET /api/v1/plant-types` | all optional: `query` (fuzzy search), `status` (`UNVERIFIED`\|`VERIFIED`), `inMyCollection`, `limit` (1–200), `offset` |
+| `search_plant_types` | `GET /api/v1/plant-types` | `query` **(required)**, plus the same optional filters/paging as `list_plant_types` |
+| `get_plant_type` | `GET /api/v1/plant-types/:id` | `id` **(required)** — one type's fact sheet |
+| `list_soils` | `GET /api/v1/soils` | none |
+| `list_fertilizers` | `GET /api/v1/fertilizers` | none |
+
+**`list_plant_types` is the shared, community-maintained global catalog** — the same for every
+user, not a per-user list. `list_plant_types` and `search_plant_types` are the same endpoint and
+reader; they exist as two tools because browsing (no `query`) and searching (`query` required) are
+different intents for a model to reach for, even though the underlying call is identical.
+`inMyCollection: true` narrows to types the caller has at least one `LIVING` plant of — each row's
+`viewerPlantsCount` says how many. A `MERGED` or `REJECTED` type never appears in either list.
+
+`get_plant_type` returns `{ id, status, mergedIntoId, displayName, botanicalName, names, parent,
+children, facts: { values, sources }, images, viewerPlantsCount, changeLog }`. `facts.values` are
+the effective (inheritance-resolved) catalog values — the same field keys `get_plant`'s `typeFacts`
+uses; `facts.sources` says `"own"` or `"inherited"` per field. `images` are approved URLs only. A
+`MERGED` id **transparently resolves to its survivor** here (unlike the admin
+`admin_get_plant_type`, which returns the redirect stub) — there is nothing for a non-admin caller
+to do with the stub itself. A `REJECTED` id behaves the same way when its outcome was a merge
+(`mergedIntoId` set); otherwise it resolves to the type's own now-`REJECTED` row, since there's no
+survivor to point to.
 
 ---
 
 ## Write tools
 
-**All ten require a `write`-scoped key**; a read-only key gets HTTP 403. Every description starts
-with `WRITE:` so a model cannot mistake one for a read.
+**All 17 ordinary write tools require a `write`-scoped key**; a read-only key gets HTTP 403. Every
+description starts with `WRITE:` so a model cannot mistake one for a read.
 
 ### Care logging
 
@@ -257,21 +303,35 @@ thing per plant.
 
 | Tool | Endpoint | Arguments |
 |---|---|---|
-| `update_plant_care` | `PATCH /api/v1/plants/:id/care` | `plantId` **(required)**, plus any of `wateringMode` (`scheduled`\|`reservoir`\|`hydro`), `fertilizingMode` (`scheduled`\|`with_watering`), `sunRequirement` (1–4), `waterRequirement` (1–3), `wateringFrequencySummer`/`wateringFrequencyWinter` (labels), `wateringFrequencySummerDays`/`wateringFrequencyWinterDays` (1–365), `wateringNotes`, `fertilizingCycleSummerWeeks`/`fertilizingCycleWinterWeeks` (0–52), `fertilizerPercent` (0–1000), `fertilizingNotes` |
-| `update_plant` | `PATCH /api/v1/plants/:id` | `plantId` **(required)**, plus any of `locationId`, `soilId`, `fertilizerId`, `quantity` (0–9999), `notes`, `tags` (replaces the full list), `sitterInstructions`, `parentPlantId` |
+| `update_plant_care` | `PATCH /api/v1/plants/:id/care` | `plantId` **(required)**, plus any of `wateringMode` (`scheduled`\|`reservoir`\|`hydro`), `fertilizingMode` (`scheduled`\|`with_watering`), `wateringFrequencySummer`/`wateringFrequencyWinter` (labels), `wateringFrequencySummerDays`/`wateringFrequencyWinterDays` (1–365), `wateringNotes`, `fertilizingCycleSummerWeeks`/`fertilizingCycleWinterWeeks` (0–52), `fertilizerPercent` (0–1000), `fertilizingNotes` |
+| `update_plant` | `PATCH /api/v1/plants/:id` | `plantId` **(required)**, plus any of `plantTypeId`, `nickname`, `locationId`, `soilId`, `fertilizerId`, `quantity` (0–9999), `notes`, `tags` (replaces the full list), `sitterInstructions`, `parentPlantId` |
 
 Both take a `plantId` and edit **only the fields you pass** — an omitted field keeps its current
 value, `null` clears it (unassigns a catalog id, or blanks a text field).
 
-`update_plant_care`'s watering fields (other than `sunRequirement`) only take effect while the
-plant's watering is on a schedule — a reservoir/hydro plant has no cycle for them to configure, so
-they're silently ignored for one. The fertilizing-cycle fields are likewise ignored while the plant
-fertilizes with every watering rather than on its own cycle. Passing `wateringMode`/`fertilizingMode`
-in the **same call** as the fields they gate checks against the *new* mode, not the current one — so
-switching a plant to `"reservoir"` while also setting a watering cycle just drops that cycle rather
-than saving it. `careMode` (a legacy mirror of `wateringMode`) updates itself; it isn't a field you set.
-This is also the tool that actually fixes a `wateringCycleMismatch` recommendation — that
-recommendation's own text says "edit the plant," and the mode causing the mismatch lives here.
+**`update_plant_care` no longer accepts `sunRequirement`/`waterRequirement`** — light and water need
+are type-only facts now (`get_plant`'s `typeFacts`, or `get_plant_type`). `null` on
+`wateringFrequencySummerDays`/`WinterDays`, `wateringFrequencySummer`/`Winter`, or
+`fertilizingCycleSummerWeeks`/`WinterWeeks` now means **"follow the type"** — the plant's effective
+schedule falls back to its type's suggested value (see `get_plant`'s `typeValue` on each schedule
+field) rather than having no schedule at all; `null` on `wateringNotes`/`fertilizingNotes` still just
+clears the note.
+
+The watering fields only take effect while the plant's watering is on a schedule — a reservoir/hydro
+plant has no cycle for them to configure, so they're silently ignored for one. The fertilizing-cycle
+fields are likewise ignored while the plant fertilizes with every watering rather than on its own
+cycle. Passing `wateringMode`/`fertilizingMode` in the **same call** as the fields they gate checks
+against the *new* mode, not the current one — so switching a plant to `"reservoir"` while also
+setting a watering cycle just drops that cycle rather than saving it. `careMode` (a legacy mirror of
+`wateringMode`) updates itself; it isn't a field you set. This is also the tool that actually fixes a
+`wateringCycleMismatch` recommendation — that recommendation's own text says "edit the plant," and
+the mode causing the mismatch lives here.
+
+`update_plant`'s `plantTypeId` points the plant at a **global** catalog type (from
+`list_plant_types`/`search_plant_types`; a `MERGED` id transparently resolves to its survivor); `null`
+makes the plant "unidentified". `nickname` is required whenever the plant's state *after* this edit
+has no type — set together with `plantTypeId: null`, or already unidentified and not gaining a type
+in this same call.
 
 `update_plant`'s `locationId`/`soilId`/`fertilizerId` must be one of **your own** catalog ids (from
 `list_locations`/`list_soils`/`list_fertilizers`) — an unowned or unknown id is rejected.
@@ -285,13 +345,16 @@ don't exist yet, `propagate_plant` creates them *and* sets the link in one call.
 
 | Tool | Endpoint | Arguments |
 |---|---|---|
-| `create_plant` | `POST /api/v1/plants` | `plantTypeId` **(required)**, `reference` (default `false`), `parentPlantId` |
+| `create_plant` | `POST /api/v1/plants` | `plantTypeId` (optional — omit/`null` for unidentified), `nickname` (required when unidentified), `reference` (default `false`), `parentPlantId` |
 | `propagate_plant` | `POST /api/v1/plants/:id/propagations` | `plantId` **(required)**, `count` (1–10, default 1) |
 | `merge_plants` | `POST /api/v1/plants/merge` | `sourcePlantIds` **(required,** 1–200**)**, plus **exactly one of** `survivorPlantId` or `createNewFrom` |
 | `unmerge_plant` | `POST /api/v1/plants/:id/unmerge` | `plantId` **(required)** |
 
-`create_plant` needs an **existing** `plantTypeId` from `list_plant_types` — creating a plant *type*
-is still a UI action, so if the species isn't in your catalog yet, that step happens in the app.
+`create_plant`'s `plantTypeId` is now **optional**: pass an existing global type id (from
+`list_plant_types`/`search_plant_types`) when the species is known, or omit it (or pass `null`) to
+add an "unidentified" plant — `nickname` is then required, matching the app's plant form. Creating a
+plant *type* is still a UI action, so if the species isn't in the catalog yet, that step happens in
+the app; an unidentified plant can always be identified there later.
 
 `reference: true` creates an `EXTERNAL` plant: somebody else's, recorded only so lineage has a real
 node to point at. It gets no acquisition date, no care schedule, and no place in collection stats —
@@ -333,6 +396,17 @@ Dismissible `type` values: `wateringOftenLate`, `fertilizingOftenLate`, `noFerti
 `recentlyRepottedAvoidFertilizer`, `noRecentPhoto`. `wateringCycleMismatch` is **not** dismissible —
 it is a configuration contradiction, fixed by editing the plant rather than hidden.
 
+### Wishlist
+
+| Tool | Endpoint | Arguments |
+|---|---|---|
+| `add_to_wishlist` | `POST /api/v1/wishlist` | `plantTypeId` or `name` — at least one required |
+| `add_wishlist_note` | `POST /api/v1/wishlist/:id/notes` | `wishId` **(required)**, `text` **(required,** 1–500 chars**)** |
+| `remove_from_wishlist` | `DELETE /api/v1/wishlist/:id` | `wishId` **(required)** |
+
+`add_to_wishlist` never creates a second wish for a type the caller already has — it returns the
+existing one instead (`duplicate: true`), rather than erroring or silently doubling it up.
+
 ### Deleting events
 
 | Tool | Endpoint | Arguments |
@@ -340,7 +414,9 @@ it is a configuration contradiction, fixed by editing the plant rather than hidd
 | `delete_watering_event` | `DELETE /api/v1/plants/:id/watering-events/:eventId` | `plantId`, `eventId` — both **required** |
 | `delete_fertilization_event` | `DELETE /api/v1/plants/:id/fertilization-events/:eventId` | `plantId`, `eventId` — both **required** |
 
-**These are the only destructive tools in this server, and neither can be undone.** Take `eventId`
+**These are the only tools that delete collection history, and neither can be undone.** (`remove_from_wishlist`
+also deletes a row, but a wish carries no history — see **What this server deliberately cannot do**
+above.) Take `eventId`
 from `list_watering_events` / `list_fertilization_events` / `list_care_events`. For a reservoir or
 hydro plant, `delete_watering_event` deletes its refill/top-up event instead — the same routing
 `record_watering` uses on the write side.
@@ -372,8 +448,8 @@ includes `admin`.
 
 | Tool | Endpoint | Arguments |
 |---|---|---|
-| `admin_list_plant_types` | `GET /api/v1/admin/plant-types` | all optional: `status` (`UNVERIFIED`\|`VERIFIED`\|`MERGED`, defaults to every non-MERGED type), `search` (names + botanical), `genus`, `parentId` (a species-level type's cultivar children), `missingField` (a field key from `admin_get_plant_type_field_schema` — only types missing it), `hasOpenProposals`, `limit` (1–200), `offset` |
-| `admin_get_plant_type` | `GET /api/v1/admin/plant-types/:id` | `id` **(required)** — full detail: identity/status, parent/children, names, own/inherited/effective values, plant/user counts, open proposals, open duplicate candidates, image count, recent change log |
+| `admin_list_plant_types` | `GET /api/v1/admin/plant-types` | all optional: `status` (`UNVERIFIED`\|`VERIFIED`\|`MERGED`, defaults to every live type — excludes both `MERGED` and `REJECTED`; a `REJECTED` type has no filter value of its own here yet), `search` (names + botanical), `genus`, `parentId` (a species-level type's cultivar children), `missingField` (a field key from `admin_get_plant_type_field_schema` — only types missing it), `hasOpenProposals`, `limit` (1–200), `offset` |
+| `admin_get_plant_type` | `GET /api/v1/admin/plant-types/:id` | `id` **(required)** — full detail: identity/status (including `REJECTED`, for an admin-rejected user-created type — see `mergedIntoId`), parent/children, names, own/inherited/effective values, plant/user counts, open proposals, open duplicate candidates, image count, recent change log |
 | `admin_get_plant_type_field_schema` | `GET /api/v1/admin/plant-types/fields` | none — every guidance field's kind, bounds, allowed values, and what a scale value or unit means |
 | `admin_list_duplicate_candidates` | `GET /api/v1/admin/plant-types/duplicates` | `status` (`OPEN`\|`DISMISSED`\|`MERGED`, defaults to `OPEN`), `limit` (1–200), `offset` |
 | `admin_list_plant_type_proposals` | `GET /api/v1/admin/plant-types/proposals` | `status` (defaults to `PENDING`), `origin` (`user`\|`migration`), `typeId`, `limit` (1–200), `offset` |
@@ -490,6 +566,34 @@ can act on them or explain them to you:
 
 A non-JSON body is passed through as raw text rather than being swallowed.
 
+## Breaking changes in 2.0.0
+
+Plant identity moved from a per-user catalog to a shared, community-maintained one. If your client
+(or a cached tool call) held onto a `plantTypeId` from before this release, it needs re-resolving —
+the id spaces are unrelated. The full rationale is in the app's `docs/mcp-server.md`; the mechanical
+changes:
+
+- **`plantTypeId` means a global catalog id everywhere it appears** (`list_plants`, `get_plant`,
+  `create_plant`, `update_plant`) — not the old per-user type id. Re-resolve any id you cached before
+  this release via `list_plant_types`/`search_plant_types`.
+- **`list_plant_types` now serves the global catalog**, not the caller's own types — every caller
+  sees the same rows now, differing only in `viewerPlantsCount`.
+- **New: `search_plant_types` and `get_plant_type`** — see **Catalogs** above.
+- **`plantTypeId` is now optional on `create_plant` and `update_plant`** — omit it (or pass `null`)
+  for an "unidentified" plant. `nickname` becomes required whenever the plant ends up with no type.
+- **`get_plant`'s `plantType` field is replaced by `type`** — see its row above for the new shape
+  (`plantTypeId`, `nickname`, `displayName`, `botanicalName`, `typeStatus`, `isUnidentified`).
+  `list_plants` rows changed the same way.
+- **`get_plant` gained `typeFacts`** (the type's effective light/water/feeding need, toxicity,
+  climate, growth, substrate/propagation, family/native region).
+- **`get_plant`'s six schedule fields are no longer raw values** — each is now
+  `{ value, source, typeValue }`. A consumer reading e.g. `plant.wateringFrequencySummerDays` as a
+  number directly will break; read `.value` instead.
+- **`update_plant_care` no longer accepts `sunRequirement`/`waterRequirement`** — both are type-only
+  facts now.
+- **`null` on `update_plant_care`'s watering/fertilizing-cycle fields now means "follow the type"**,
+  not "no schedule" — see that tool's row above.
+
 ## Versioning
 
 Semver against the **tool surface**, which is this package's public API:

package/dist/index.js

@@ -131,16 +131,16 @@ server.tool("list_plants", "List the user's plants, with optional filters. Retur
         .describe("Filter by plant status. EXTERNAL is a reference plant: somebody else's plant, recorded only as an anchor for propagation lineage — never cared for and not part of the collection's totals."),
     lifecycle: z.enum(["PROPAGATING", "ESTABLISHED"]).optional().describe("Filter by lifecycle stage."),
     locationId: z.number().int().optional().describe("Filter by location id."),
-    plantTypeId: z.number().int().optional().describe("Filter by plant type (species) id."),
+    plantTypeId: z.number().int().optional().describe("Filter by global plant type id, from list_plant_types/search_plant_types/get_plant."),
     soilId: z.number().int().optional().describe("Filter by soil id."),
     fertilizerId: z.number().int().optional().describe("Filter by fertilizer id."),
     tag: z.string().optional().describe("Filter by exact tag (case-sensitive)."),
-    search: z.string().optional().describe("Free-text search over plant type name / notes."),
+    search: z.string().optional().describe("Free-text search over the plant's nickname, its type's names, and notes."),
     limit: z.number().int().min(1).max(200).optional().describe("Max results (pagination)."),
     offset: z.number().int().min(0).optional().describe("Result offset (pagination)."),
-    sort: z.string().optional().describe("Sort key, e.g. 'name', 'createdAt', 'updatedAt'."),
+    sort: z.enum(["displayName", "createdAt", "updatedAt", "acquiredAt"]).optional().describe("Sort key. 'displayName' sorts by the plant's resolved name (nickname, or its type's name); the rest sort newest first."),
 }, async (args) => apiGet("/api/v1/plants", args));
-server.tool("get_plant", "Get one plant with full detail: catalogs (type, location, soil, fertilizer), care config, and recent event summaries.", { id: z.number().int().describe("Plant id.") }, async ({ id }) => apiGet(`/api/v1/plants/${id}`));
+server.tool("get_plant", "Get one plant with full detail: identity (type, nickname, display name, botanical name, unidentified state — see 'type'), typeFacts (the type's effective light/water/feeding need, toxicity, climate, growth, substrate/propagation, family/native region — using the catalog field keys from get_plant_type), catalogs (location, soil, fertilizer), care config, and recent event summaries. The six schedule fields (wateringFrequencySummerDays/WinterDays, wateringFrequencySummer/Winter, fertilizingCycleSummerWeeks/WinterWeeks) are each { value, source: 'plant'|'type'|'none', typeValue } — value is what scheduling/display use, source says where it came from, typeValue is what the type would say even when the plant overrides it.", { id: z.number().int().describe("Plant id.") }, async ({ id }) => apiGet(`/api/v1/plants/${id}`));
 // --- Events connected to a plant -------------------------------------------
 const eventArgs = {
     id: z.number().int().describe("Plant id."),
@@ -234,24 +234,24 @@ server.tool("record_fertilization", "WRITE: log a fertilization for one or more
         .describe("Strength as a percentage of the base dose; defaults to each plant's own."),
     fertilizedAt: optionalPlantDate(""),
 }, async (args) => apiSend("POST", "/api/v1/care/fertilization", { ...args }));
-server.tool("update_plant_care", "WRITE: edit a plant's care schedule — watering mode, days/labels, sun and water requirement, fertilizing mode, cycles and percent, and the watering/fertilizing notes. Omitted fields keep their current value; null clears a notes/label field. Watering fields other than sunRequirement are ignored while the plant's watering isn't on a schedule (reservoir/hydro), and the fertilizing-cycle fields are ignored while it fertilizes with every watering — there's no cycle to configure in either case. If wateringMode/fertilizingMode is part of this same call, that check runs against the NEW mode, not the plant's current one — e.g. switching to 'reservoir' while also passing a watering cycle ignores that cycle. Use this (not update_plant) to fix a 'wateringCycleMismatch' recommendation where the mode itself is wrong. Requires a write-scoped API key.", {
+server.tool("update_plant_care", "WRITE: edit a plant's care schedule — watering mode, days/labels, fertilizing mode, cycles and percent, and the watering/fertilizing notes. Omitted fields keep their current value. null on wateringFrequencySummerDays/WinterDays, wateringFrequencySummer/Winter, or fertilizingCycleSummerWeeks/WinterWeeks means 'follow the type' — the plant's effective schedule then falls back to its type's suggested value (see get_plant's typeFacts / the schedule fields' typeValue) instead of having no schedule at all; a value equal to the type's suggested value is stored the same way (it follows the type). null on wateringNotes/fertilizingNotes just clears the note. Watering fields are ignored while the plant's watering isn't on a schedule (reservoir/hydro), and the fertilizing-cycle fields are ignored while it fertilizes with every watering — there's no cycle to configure in either case. If wateringMode/fertilizingMode is part of this same call, that check runs against the NEW mode, not the plant's current one — e.g. switching to 'reservoir' while also passing a watering cycle ignores that cycle. sunRequirement/waterRequirement are no longer settable here — light and water need are type-only facts now (get_plant's typeFacts, or get_plant_type). Use this (not update_plant) to fix a 'wateringCycleMismatch' recommendation where the mode itself is wrong. Requires a write-scoped API key.", {
     plantId: z.number().int().positive().describe("Plant id."),
     wateringMode: z.enum(["scheduled", "reservoir", "hydro"]).optional().describe("How this plant is watered: on a schedule, from a reservoir, or in water/hydro culture."),
     fertilizingMode: z.enum(["scheduled", "with_watering"]).optional().describe("How this plant is fertilized: on its own cycle, or automatically with every watering."),
-    sunRequirement: z.number().int().min(1).max(4).optional().describe("1 (low light) to 4 (full sun)."),
-    waterRequirement: z.number().int().min(1).max(3).optional().describe("1 (low) to 3 (high). Ignored unless watering is scheduled."),
-    wateringFrequencySummer: z.string().max(50).nullable().optional().describe("Free-text summer watering label, e.g. 'twice a week'. Ignored unless watering is scheduled."),
-    wateringFrequencySummerDays: z.number().int().min(1).max(365).optional().describe("Summer watering interval in days. Ignored unless watering is scheduled."),
-    wateringFrequencyWinter: z.string().max(50).nullable().optional().describe("Free-text winter watering label. Ignored unless watering is scheduled."),
-    wateringFrequencyWinterDays: z.number().int().min(1).max(365).optional().describe("Winter watering interval in days. Ignored unless watering is scheduled."),
+    wateringFrequencySummer: z.string().max(50).nullable().optional().describe("Free-text summer watering label, e.g. 'twice a week'. null follows the type's guidance. Ignored unless watering is scheduled."),
+    wateringFrequencySummerDays: z.number().int().min(1).max(365).nullable().optional().describe("Summer watering interval in days. null follows the type's suggested days. Ignored unless watering is scheduled."),
+    wateringFrequencyWinter: z.string().max(50).nullable().optional().describe("Free-text winter watering label. null follows the type's guidance. Ignored unless watering is scheduled."),
+    wateringFrequencyWinterDays: z.number().int().min(1).max(365).nullable().optional().describe("Winter watering interval in days. null follows the type's suggested days. Ignored unless watering is scheduled."),
     wateringNotes: z.string().max(500).nullable().optional().describe("Free-text watering notes. Ignored unless watering is scheduled."),
-    fertilizingCycleSummerWeeks: z.number().int().min(0).max(52).optional().describe("Summer fertilizing interval in weeks. Ignored while fertilizing is 'with every watering'."),
-    fertilizingCycleWinterWeeks: z.number().int().min(0).max(52).optional().describe("Winter fertilizing interval in weeks. Ignored while fertilizing is 'with every watering'."),
+    fertilizingCycleSummerWeeks: z.number().int().min(0).max(52).nullable().optional().describe("Summer fertilizing interval in weeks. null follows the type's suggested weeks. Ignored while fertilizing is 'with every watering'."),
+    fertilizingCycleWinterWeeks: z.number().int().min(0).max(52).nullable().optional().describe("Winter fertilizing interval in weeks. null follows the type's suggested weeks. Ignored while fertilizing is 'with every watering'."),
     fertilizerPercent: z.number().int().min(0).max(1000).optional().describe("Strength as a percentage of the base dose."),
     fertilizingNotes: z.string().max(500).nullable().optional().describe("Free-text fertilizing notes."),
 }, async ({ plantId, ...body }) => apiSend("PATCH", `/api/v1/plants/${plantId}/care`, body));
-server.tool("update_plant", "WRITE: edit a plant's location, soil, fertilizer, quantity, notes, tags, sitter instructions, or parent plant. Omitted fields keep their current value; null unassigns a catalog entry, clears notes/instructions, empties the tag list, or detaches the plant from its parent. Requires a write-scoped API key.", {
+server.tool("update_plant", "WRITE: edit a plant's type, nickname, location, soil, fertilizer, quantity, notes, tags, sitter instructions, or parent plant. Omitted fields keep their current value; null unassigns a catalog entry, clears notes/instructions, empties the tag list, or detaches the plant from its parent — and for plantTypeId, makes the plant 'unidentified'. nickname is required whenever the plant's state after this edit has no type (whether because plantTypeId is set to null here, or was already null and nickname isn't being set to something non-empty) — see plantIdentity's validatePlantNickname. Requires a write-scoped API key.", {
     plantId: z.number().int().positive().describe("Plant id."),
+    plantTypeId: z.number().int().positive().nullable().optional().describe("New global plant type id, from list_plant_types/search_plant_types/get_plant. A MERGED id transparently resolves to its survivor. null makes the plant unidentified — nickname is then required."),
+    nickname: z.string().max(100).nullable().optional().describe("The plant's own name, shown instead of the type's name when set. Required when the plant has (or is becoming) unidentified."),
     locationId: z.number().int().positive().nullable().optional().describe("New location id, from list_locations. null unassigns it."),
     soilId: z.number().int().positive().nullable().optional().describe("New soil id, from list_soils. null unassigns it."),
     fertilizerId: z.number().int().positive().nullable().optional().describe("New fertilizer id, from list_fertilizers. null unassigns it."),
@@ -308,8 +308,9 @@ server.tool("delete_fertilization_event", "WRITE: delete a fertilization event f
     eventId: z.number().int().positive().describe("Event id, from list_fertilization_events or list_care_events."),
 }, async ({ plantId, eventId }) => apiSend("DELETE", `/api/v1/plants/${plantId}/fertilization-events/${eventId}`));
 // --- Plant lifecycle (writes) ------------------------------------------------
-server.tool("create_plant", "WRITE: add a new plant to the collection. plantTypeId is required and must be an existing type — call list_plant_types first and pick the matching one; creating a new plant type is not possible here and stays a UI action. Set reference: true to record somebody else's plant (status EXTERNAL): it is not one of the user's own plants, gets no acquisition date and no care schedule, and is excluded from collection stats — its purpose is to be a real node that propagation lineage can point at. Requires a write-scoped API key.", {
-    plantTypeId: z.number().int().positive().describe("Plant type id, from list_plant_types."),
+server.tool("create_plant", "WRITE: add a new plant to the collection. plantTypeId is now optional (omit it, or pass null, to create an 'unidentified' plant) — call list_plant_types/search_plant_types first and pick the matching one when the species is known; creating a new plant type is not possible here and stays a UI action. nickname is required whenever plantTypeId is omitted/null, matching the app's plant form. Set reference: true to record somebody else's plant (status EXTERNAL): it is not one of the user's own plants, gets no acquisition date and no care schedule, and is excluded from collection stats — its purpose is to be a real node that propagation lineage can point at. Requires a write-scoped API key.", {
+    plantTypeId: z.number().int().positive().nullable().optional().describe("Global plant type id, from list_plant_types/search_plant_types. Omit (or pass null) for an unidentified plant — a MERGED id transparently resolves to its survivor."),
+    nickname: z.string().max(100).optional().describe("The plant's own name. Required when plantTypeId is omitted or null."),
     reference: z.boolean().optional().describe("true creates an EXTERNAL reference plant (somebody else's, a lineage anchor only). Defaults to false: a LIVING plant of the user's own."),
     parentPlantId: z.number().int().positive().optional().describe("Optional: the plant this one was propagated from."),
 }, async (body) => apiSend("POST", "/api/v1/plants", { ...body }));
@@ -325,9 +326,46 @@ server.tool("merge_plants", "WRITE: merge several living plants into one — for
 server.tool("unmerge_plant", "WRITE: reverse a merge for one plant — takes a MERGED plant back to LIVING and clears its link to the survivor. Undoes one source at a time, so call it per plant to fully reverse a multi-plant merge. The survivor is left in place; delete it in the UI if it was created by the merge and is no longer wanted. Requires a write-scoped API key.", {
     plantId: z.number().int().positive().describe("The MERGED plant to restore."),
 }, async ({ plantId }) => apiSend("POST", `/api/v1/plants/${plantId}/unmerge`));
+// --- Wishlist ----------------------------------------------------------
+/**
+ * The caller's personal wishlist (R2-15) — plants they want but don't own
+ * yet, either a global catalog type (`plantTypeId`) or a free-text name
+ * fallback for a species not in the catalog. Unlike sales/trades, wishes
+ * are never exposed-but-excluded: they're the caller's own data, about
+ * their own collection, so there's no second-person consent concern.
+ */
+server.tool("list_wishlist", "List the caller's wishlist: each wish's plant type (when set) with its display/botanical name, or a free-text name fallback, plus notes and how many LIVING plants of that type the caller already owns.", async () => apiGet("/api/v1/wishlist"));
+server.tool("add_to_wishlist", "WRITE: add a wish — a global catalog type (plantTypeId, from list_plant_types/search results) or a free-text name for a species not in the catalog yet. At least one is required. Never creates a second wish for a type the caller already has — returns the existing one instead (duplicate: true). Requires a write-scoped API key.", {
+    plantTypeId: z.number().int().positive().optional().describe("An existing global plant type id."),
+    name: z.string().max(100).optional().describe("Free-text name fallback, for a species not yet in the catalog."),
+}, async ({ plantTypeId, name }) => apiSend("POST", "/api/v1/wishlist", { plantTypeId, name }));
+server.tool("add_wishlist_note", "WRITE: add a dated note to a wish — price, where to get it, a shop link, etc. Requires a write-scoped API key.", {
+    wishId: z.number().int().positive().describe("Wish id, from list_wishlist."),
+    text: z.string().min(1).max(500).describe("The note text."),
+}, async ({ wishId, text }) => apiSend("POST", `/api/v1/wishlist/${wishId}/notes`, { text }));
+server.tool("remove_from_wishlist", "WRITE: remove a wish (e.g. once it's been fulfilled by a new plant). Requires a write-scoped API key.", {
+    wishId: z.number().int().positive().describe("Wish id, from list_wishlist."),
+}, async ({ wishId }) => apiSend("DELETE", `/api/v1/wishlist/${wishId}`));
 // --- Catalogs (for resolving filter ids) -----------------------------------
 server.tool("list_locations", "List the user's locations.", async () => apiGet("/api/v1/locations"));
-server.tool("list_plant_types", "List the user's plant types (species taxonomy).", async () => apiGet("/api/v1/plant-types"));
+/**
+ * R2-12: the global plant type catalog, shared by every user — not a
+ * per-user list any more. `list_plant_types` and `search_plant_types` are
+ * deliberately the same underlying endpoint/reader (`GET /api/v1/plant-types`
+ * — see `docs/mcp-server.md`'s "Catalog reads" section): browsing and
+ * searching are the same fuzzy-filtered, paged list, just with `query`
+ * required for one and optional for the other, so a model reaching for
+ * either gets the same result shape and paging behavior.
+ */
+const publicPlantTypeListArgs = {
+    status: z.enum(["UNVERIFIED", "VERIFIED"]).optional().describe("Filter by review status. Defaults to every live type (both)."),
+    inMyCollection: z.boolean().optional().describe("true: only types the caller has at least one LIVING plant of."),
+    limit: z.number().int().min(1).max(200).optional().describe("Max results (pagination)."),
+    offset: z.number().int().min(0).optional().describe("Result offset (pagination)."),
+};
+server.tool("list_plant_types", "Browse the shared global plant type catalog — every plant's species/cultivar entry, one catalog for the whole app. Pass query to search by name/botanical; omit it to just browse (optionally filtered by status/inMyCollection). Compact rows only — no full field values or facts; use get_plant_type for one type's fact sheet. A MERGED type never appears here — see get_plant_type for how an id that was since merged resolves.", { query: z.string().optional().describe("Fuzzy search over names (all locales) and the botanical name."), ...publicPlantTypeListArgs }, async (args) => apiGet("/api/v1/plant-types", { ...args, inMyCollection: args.inMyCollection?.toString() }));
+server.tool("search_plant_types", "Fuzzy search the shared global plant type catalog by name (all locales) or botanical name — the search-first counterpart to list_plant_types (same endpoint, query required here). Use this when the caller named a species/plant and you need its id, e.g. before create_plant or update_plant.", { query: z.string().min(1).describe("Search text — a common name in any language, or a botanical name."), ...publicPlantTypeListArgs }, async (args) => apiGet("/api/v1/plant-types", { ...args, inMyCollection: args.inMyCollection?.toString() }));
+server.tool("get_plant_type", "Get one global plant type's fact sheet: identity and status, names by locale, parent/cultivar children, effective catalog facts (light, water, feeding need, toxicity, climate, growth, substrate/propagation, family/native region) with each field's source ('own' vs. 'inherited' from an ancestor), approved image URLs, and how many of the caller's own LIVING plants use it. A MERGED id transparently resolves to its survivor (mergedIntoId is still reported) rather than returning a redirect stub — unlike the admin equivalent.", { id: z.number().int().describe("Global plant type id, from list_plant_types/search_plant_types/get_plant.") }, async ({ id }) => apiGet(`/api/v1/plant-types/${id}`));
 server.tool("list_soils", "List the user's soils.", async () => apiGet("/api/v1/soils"));
 server.tool("list_fertilizers", "List the user's fertilizers.", async () => apiGet("/api/v1/fertilizers"));
 // --- Admin: global plant type catalog (admin-scoped keys only) -------------

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sebamomann/plants-mcp",
-  "version": "1.9.0",
-  "description": "MCP server for the Sprig plant app: 50 tools to read a plant collection, log care, edit a plant, and add, propagate or merge plants. Read-only by default; writes need a write-scoped API key. Two tools can delete a watering/fertilization event; nothing else is destructive. 17 more tools read, edit, merge and review the shared global plant type catalog for an admin-scoped key.",
+  "version": "2.0.0",
+  "description": "MCP server for the Sprig plant app: 56 tools to read a plant collection, browse the shared global plant type catalog, log care, edit a plant, add, propagate or merge plants, and manage a wishlist. Read-only by default; writes need a write-scoped API key. Two tools can delete a watering/fertilization event; nothing else deletes collection history. 17 more tools read, edit, merge and review the shared global plant type catalog for an admin-scoped key.",
   "type": "module",
   "license": "MIT",
   "author": "sebamomann <github@sebamomann.de>",