@sebamomann/plants-mcp 1.7.0 → 1.9.0

package/CHANGELOG.md

@@ -3,6 +3,93 @@
 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.
 
+## 1.9.0 — 2026-09-15
+
+**Admin keys can now read, directly edit, merge, and review the shared global plant type catalog.**
+Seventeen tools total for an `admin`-scoped key — 50 registered overall (19 read, 14 write, 17
+admin: 6 read-only, 11 that write) — registered only for a key that carries the `admin` scope (a
+`whoami` call at startup decides; a non-admin key's session never sees them):
+
+- `admin_list_plant_types` — filtered/paged catalog rows: status, fuzzy search, genus, a species'
+  cultivar children, a missing field, or open proposals.
+- `admin_get_plant_type` — one type's full detail: identity/status, parent/children, names,
+  own/inherited/effective values, plant and user counts, open proposals, open duplicate
+  candidates, image count, and its recent change log. A merged type still resolves —
+  `mergedIntoId` names the redirect.
+- `admin_get_plant_type_field_schema` — every guidance field's kind, bounds, allowed values, and
+  what a scale value or unit means, derived from the same registry the app validates writes
+  against.
+- `admin_list_duplicate_candidates` — the duplicate-detection queue: matched rule, score, and the
+  fields where a pair actually disagrees.
+- `admin_list_plant_type_proposals` — the proposal review queue, each changed field carrying the
+  type's current value and a `stale` flag using the exact check a human reviewer's accept button
+  re-runs.
+- `admin_preview_plant_type_merge` — the same comparison the admin merge confirmation dialog
+  loads: both sides' values, the per-field carry-over plan and its defaults for both directions,
+  counts that would move, and the guard error for either direction, if any.
+
+**Five write tools**, added alongside the reads above, every description prefixed `ADMIN WRITE:`
+and every one requiring a non-empty `note` recorded on the type's change log:
+
+- `admin_create_plant_type` — add a new type: genus (required), species, cultivar, an initial name
+  list, catalog field values, and status (defaults `VERIFIED`). A cultivar attaches to its existing
+  species-level parent automatically; a missing parent is reported (`missingParentBotanicalKey`)
+  rather than auto-created. When the new type is itself species-level, existing orphans waiting for
+  it re-parent automatically (`adoptedOrphanIds`).
+- `admin_update_plant_type_fields` — patch a type's own catalog field values; a value set to `null`
+  clears it back to inherited.
+- `admin_set_plant_type_names` — replace a type's full name list.
+- `admin_update_plant_type_botanical_identity` — edit genus/species/cultivar, which re-derives
+  `parentId` and re-parents orphans the same way creation does. A `botanical_key_conflict` (HTTP
+  409, `conflictingTypeId`) means the target identity already exists — the intended response is
+  `admin_preview_plant_type_merge` and a merge in the app, not forcing the edit through.
+- `admin_verify_plant_type` — promote an `UNVERIFIED` type to `VERIFIED`.
+
+**Six more write tools**, added alongside the five above, closing the gap the previous
+release still left UI-only — merging duplicates and reviewing proposals/duplicate candidates:
+
+- `admin_merge_plant_types` — merge `sourceId` into `targetId`. **Irreversible**: `sourceId` becomes
+  a `MERGED` redirect and every plant, name, image, cultivar child, pending proposal, legacy
+  mapping, and open duplicate candidate that pointed at it moves onto `targetId`.
+  `admin_preview_plant_type_merge` — call it first — already existed; this is the write half.
+  `fieldChoices` picks a side only for the fields the preview lists as conflicting.
+- `admin_accept_plant_type_proposal` — accept a pending proposal in full or (via `fields`) in part.
+  A field whose current value has moved on since the proposal was filed fails the whole call with
+  HTTP 409 (`details.staleFields`) rather than an `allowStale` override.
+- `admin_deny_plant_type_proposal` — deny a pending proposal. Never touches the type's own change
+  log — a denial is private to its author and the reviewer.
+- `admin_deny_plant_type_proposals` — bulk-deny every `PENDING` proposal on one type, optionally by
+  `origin`, for clearing a batch of migration-filed proposals in one call.
+- `admin_dismiss_duplicate_candidate` — dismiss an `OPEN` duplicate pair as not a duplicate. `note`
+  is required for a consistent tool contract but **not stored**: the candidate row has no column
+  for one.
+- `admin_rescan_duplicate_candidates` — re-run duplicate detection against the live catalog and
+  reconcile the queue; no note needed, since it makes no decision.
+
+Still UI-only, not covered by this release: nothing that was already exposed as a read here.
+Deleting/unlinking a type, image review, and the AI plausibility check remain deliberately
+excluded, not just deferred — see the "Admin catalog surface" section of `docs/mcp-server.md` for
+why.
+
+## 1.8.0 — 2026-08-08
+
+**Plants can now be created, propagated, and merged from here.** Four new tools — 33 total (19
+read, 14 write):
+
+- `create_plant` — one plant of an existing `plantTypeId` (from `list_plant_types`; creating a
+  plant *type* is still UI-only). `reference: true` creates the `EXTERNAL` lineage anchor added in
+  1.7.0, so a cutting from someone else's plant can finally name its actual mother plant.
+- `propagate_plant` — 1–10 cuttings of a plant, each parent-linked and starting `PROPAGATING`,
+  copying the parent's type, location, fertilizer and care schedule.
+- `merge_plants` — merge living plants into an existing survivor (`survivorPlantId`) or a new one
+  seeded from a plant's care config (`createNewFrom`). Non-destructive: sources become `MERGED` and
+  keep their own care history, so the survivor starts with an empty one.
+- `unmerge_plant` — reverses a merge for one source plant, back to `LIVING`.
+
+`update_plant` also gained **`parentPlantId`**, which makes propagation lineage writable after the
+fact (and clearable with `null`). It runs the app's own cycle check, so a plant cannot be made a
+descendant of itself. Lineage was already readable via `get_plant`; this closes the write half.
+
 ## 1.7.0 — 2026-08-08
 
 **New plant status: `EXTERNAL` (reference plant).** A plant somebody else owns, recorded only as

package/README.md

@@ -60,17 +60,22 @@ needs a running Sprig instance and an API key from it. Start at the
 
 ## What an assistant can do
 
-**29 tools** over your collection: 19 that read it, 10 that write to it.
+**50 tools** over your collection: 19 that read it, 14 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, and deleting a watering or fertilization event.
+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.
 
 **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
 server deliberately cannot do** below). Reads need only the `read` scope that every key has;
-writes need a key created with the `write` scope.
+writes need a key created with the `write` scope; the admin tools need the separate `admin` scope.
 
 Every tool is a thin proxy over the app's `/api/v1/*` REST API. Results are scoped to the key's
 owner, and the server holds no logic of its own — which is why it stays correct as the app grows.
@@ -98,7 +103,13 @@ 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 10 write tools.
+- **`write`** — opt-in when you create the key. Gates the 14 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
+  is enough for the write ones too (not also `write` — the three scopes are independent grants). An
+  admin's key is created with `read`+`write`+`admin` together, so it also works with every ordinary
+  tool.
 
 | Situation | HTTP | What the assistant sees |
 |---|---|---|
@@ -247,7 +258,7 @@ 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` |
+| `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` |
 
 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).
@@ -265,6 +276,37 @@ recommendation's own text says "edit the plant," and the mode causing the mismat
 `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.
 
+`update_plant`'s `parentPlantId` records lineage after the fact — the plant this one was propagated
+from. It must be one of your own plants (an `EXTERNAL` reference plant counts) and cannot be one of
+this plant's own descendants, which would close a cycle in the lineage graph. When the cuttings
+don't exist yet, `propagate_plant` creates them *and* sets the link in one call.
+
+### Plant lifecycle
+
+| Tool | Endpoint | Arguments |
+|---|---|---|
+| `create_plant` | `POST /api/v1/plants` | `plantTypeId` **(required)**, `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.
+
+`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 —
+so a cutting you were given can name its actual mother plant instead of just starting from nowhere.
+
+`merge_plants` is for rows that turned out to be the same plant, or cuttings potted together. It is
+**reversible and non-destructive**: the sources become `MERGED`, keep their own care history, and
+record which plant they went into, which is what `unmerge_plant` reads to put one back. Two
+consequences worth knowing before you call it: the survivor starts with an **empty care history**
+(events stay on the sources rather than moving), and `unmerge_plant` restores **one** plant per
+call. All sources must be `LIVING`, and `survivorPlantId` must not also appear in `sourcePlantIds`.
+
+Unmerging leaves the survivor in place. If the merge created it via `createNewFrom` and you no
+longer want it, deleting that plant is a UI action.
+
 ### Health entries
 
 | Tool | Endpoint | Arguments |
@@ -318,6 +360,121 @@ the response, not just the HTTP status.
 
 ---
 
+## Admin tools (admin-scoped keys only)
+
+**17 tools** over the shared, community-maintained global plant type catalog — every plant's
+species/cultivar entry, one catalog for the whole app rather than per-user. They need the `admin`
+scope (see **Permissions & scopes** above), so a non-admin key's session never even sees them: the
+server calls `whoami` once at startup and only registers these tools when the response's `scopes`
+includes `admin`.
+
+### Read-only (6)
+
+| 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_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` |
+| `admin_preview_plant_type_merge` | `GET /api/v1/admin/plant-types/merge-preview` | `sourceId`, `targetId` **(both required)** — the per-field carry-over plan and merge guard for both directions |
+
+`admin_list_plant_types` returns compact rows only (no full field values) — call `admin_get_plant_type`
+for one type's complete fact sheet. Its `search` is fuzzy, the same matcher the admin catalog list
+uses in the app. `missingField` and `hasOpenProposals` are the two filters built for finding
+cleanup work: types with a gap in their data, and types with a change proposal still waiting on a
+human.
+
+`admin_get_plant_type_field_schema` is never hand-written — it reads off the same registry the app
+validates writes against, so a value an assistant reads back from `admin_get_plant_type` (or would
+write) can always be checked against real bounds/enum values first.
+
+`admin_list_plant_type_proposals` and `admin_get_plant_type`'s `openProposals` both mark each
+changed field `stale` when the type's value has moved on since the proposal was filed — the exact
+check a human reviewer's accept button re-runs, so an assistant sees the same warning.
+
+### Write (11)
+
+Every description starts with `ADMIN WRITE:`, and **every one of these requires a non-empty `note`**
+— it is recorded on the type's change log entry, so a catalog edit made by an assistant is always
+traceable back to why — except `admin_dismiss_duplicate_candidate` (required for consistency but not
+actually stored — see below) and `admin_rescan_duplicate_candidates` (no note at all — it makes no
+decision). `admin` alone is enough to call these (not also `write` — the three API-key scopes are
+independent grants).
+
+| Tool | Endpoint | Arguments |
+|---|---|---|
+| `admin_create_plant_type` | `POST /api/v1/admin/plant-types` | `genus` **(required)**, `species`, `cultivar`, `names` (initial full list), `values` (initial catalog fields), `status` (`UNVERIFIED`\|`VERIFIED`, default `VERIFIED`), `note` **(required)** |
+| `admin_update_plant_type_fields` | `PATCH /api/v1/admin/plant-types/:id/fields` | `id` **(required)**, `values` **(required,** partial — a key set to `null` clears it back to inherited**)**, `note` **(required)** |
+| `admin_set_plant_type_names` | `PUT /api/v1/admin/plant-types/:id/names` | `id` **(required)**, `names` **(required,** the complete replacement list**)**, `note` **(required)** |
+| `admin_update_plant_type_botanical_identity` | `PATCH /api/v1/admin/plant-types/:id/identity` | `id` **(required)**, `genus`, `species`, `cultivar`, `note` **(required)** |
+| `admin_verify_plant_type` | `POST /api/v1/admin/plant-types/:id/verify` | `id` **(required)**, `note` **(required)** |
+| `admin_merge_plant_types` | `POST /api/v1/admin/plant-types/merge` | `sourceId` **(required)**, `targetId` **(required)**, `fieldChoices` (per-field `"source"`\|`"target"`), `note` **(required)** |
+| `admin_accept_plant_type_proposal` | `POST /api/v1/admin/plant-types/proposals/:id/accept` | `id` **(required)**, `fields` (subset to accept — omit for all), `note` **(required)** |
+| `admin_deny_plant_type_proposal` | `POST /api/v1/admin/plant-types/proposals/:id/deny` | `id` **(required)**, `note` **(required)** |
+| `admin_deny_plant_type_proposals` | `POST /api/v1/admin/plant-types/proposals/deny` | `typeId` **(required)**, `origin` (`user`\|`migration`), `note` **(required)** |
+| `admin_dismiss_duplicate_candidate` | `POST /api/v1/admin/plant-types/duplicates/:id/dismiss` | `id` **(required)**, `note` **(required, not stored — see below)** |
+| `admin_rescan_duplicate_candidates` | `POST /api/v1/admin/plant-types/duplicates/rescan` | none |
+
+Each of the first six (identity/creation edits and merge) returns `{ type: <the same shape as
+admin_get_plant_type>, ... }`, plus whatever the operation adds (`changed`, `changes`,
+`adoptedOrphanIds`, `missingParentBotanicalKey`, or — for merge — the move counts). The proposal and
+duplicate tools return only the review outcome (see below); they don't reshape a type's own record
+the way an edit does.
+
+`admin_create_plant_type`'s `cultivar` attaches the new type under the existing species-level type
+with the matching `genus`/`species` key, named as `parentId` in the response. If that species
+doesn't exist yet, `parentId` comes back `null` and `missingParentBotanicalKey` names the key to
+create first (call `admin_create_plant_type` again, without a cultivar) — a cultivar's parent is
+never auto-created. When the new type is itself species-level, any existing type with no parent
+whose own key implies this one as parent is automatically re-parented onto it — returned as
+`adoptedOrphanIds` — which is how creating a missing species repairs the tree instead of leaving its
+cultivars stranded.
+
+`admin_update_plant_type_botanical_identity` re-parents orphans the same way when an edit makes a
+type species-level, and shares the same conflict rule as creation: a `botanical_key_conflict`
+(HTTP 409, `conflictingTypeId` in the error's `details`) means another live type already owns the
+resulting identity — call `admin_preview_plant_type_merge` and merge the two rather than forcing the
+edit through. It also refuses to turn a type with cultivar children into a cultivar itself (v1's
+tree is only two levels deep).
+
+`admin_update_plant_type_fields` shares the field registry with the read tools — call
+`admin_get_plant_type_field_schema` first for valid keys and bounds — and returns which fields
+actually changed. Don't set a cultivar's value to the same thing it already inherits; leave it
+`null` so it keeps inheriting instead of freezing a copy that drifts from the parent later.
+
+`admin_set_plant_type_names` always replaces the **full** list — call `admin_get_plant_type` first
+and send its complete `names` array back with your change, or names you leave out are dropped.
+
+**`admin_merge_plant_types` is irreversible.** `sourceId` becomes a `MERGED` redirect stub, and every
+plant, name, image, cultivar child, pending proposal, legacy mapping, and open duplicate candidate
+that pointed at it moves onto `targetId`. Always call `admin_preview_plant_type_merge` first — same
+comparison a human admin would see. `targetId` keeps its own identity, `parentId`, status, and cover
+image; `fieldChoices` only picks a side for the fields the preview lists as `conflict`/`onlySource` —
+everything else the plan defaults to adopting happens regardless.
+
+**`admin_accept_plant_type_proposal`** accepts in full (omit `fields`, status `ACCEPTED`) or in part
+(an explicit subset, status `PARTIAL` unless it happens to cover everything). A field whose current
+value moved on since the proposal was filed fails the whole call with HTTP 409
+(`details.staleFields`) unless it's excluded from `fields` — there is no `allowStale` override here
+like the admin UI's "accept anyway" checkbox; handle that field with `admin_update_plant_type_fields`
+and retry without it, or deny the proposal. **`admin_deny_plant_type_proposal`** never writes a
+change log entry on the type — a denial is private to the proposal's author and reviewer.
+**`admin_deny_plant_type_proposals`** is the bulk variant for clearing every `PENDING` proposal on one
+type at once (optionally by `origin`), for a batch of migration-filed proposals.
+
+**`admin_dismiss_duplicate_candidate`'s `note` is required but not stored anywhere** —
+`PlantTypeDuplicateCandidate` has no column for one; the requirement exists only for a consistent
+tool contract, not a change log entry. A dismissed pair never resurfaces, even from
+**`admin_rescan_duplicate_candidates`**, which re-runs detection against the whole live catalog and
+reconciles the queue — the same "Rescan" button in the admin Duplicates tab, for when catalog edits
+since the last migration run mean the queue is stale.
+
+Deleting/unlinking a type, reviewing images, and the advisory AI plausibility check are deliberately
+excluded even from the roadmap — see docs/mcp-server.md's Admin catalog surface section for why.
+
+---
+
 ## Responses and errors
 
 Tools return the API's JSON **verbatim**, pretty-printed. Nothing is reshaped, renamed, or

package/dist/index.js

@@ -6,7 +6,12 @@ import { z } from "zod";
 /**
  * MCP server for the Sprig plant app: reads the collection, and — with a
  * write-scoped key — logs care, edits a plant, and deletes a watering or
- * fertilization event. Plants, photos, and catalog entries stay UI-only.
+ * fertilization event. Plants and photos stay UI-only. An admin-scoped key
+ * additionally sees tools over the shared global plant type catalog
+ * (`admin_*`, registered conditionally — see `registerAdminToolsIfPermitted`):
+ * reads, creating and editing catalog entries directly, and (since this
+ * increment) merging duplicate types and reviewing proposals and duplicate
+ * candidates.
  *
  * Every tool is a thin proxy over the app's `/api/v1/*` REST endpoints,
  * authenticated with a per-user API key sent as `Authorization: Bearer <key>`.
@@ -245,7 +250,7 @@ server.tool("update_plant_care", "WRITE: edit a plant's care schedule — wateri
     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, or sitter instructions. Omitted fields keep their current value; null unassigns a catalog entry, clears notes/instructions, or empties the tag list. Requires a write-scoped API key.", {
+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.", {
     plantId: z.number().int().positive().describe("Plant id."),
     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."),
@@ -254,6 +259,7 @@ server.tool("update_plant", "WRITE: edit a plant's location, soil, fertilizer, q
     notes: z.string().max(5000).nullable().optional().describe("Free-text notes."),
     tags: z.array(z.string().max(40)).nullable().optional().describe("Replaces the plant's full tag list (freeform labels, not a catalog). null or [] clears all tags."),
     sitterInstructions: z.string().max(500).nullable().optional().describe("Care instructions shown on a sitter link."),
+    parentPlantId: z.number().int().positive().nullable().optional().describe("The plant this one was propagated from — use it to record lineage after the fact. Must be one of the user's own plants (including an EXTERNAL reference plant) and must not be a descendant of this plant, which would form a cycle. null detaches it from its current parent. To create the cuttings in the first place, prefer propagate_plant."),
 }, async ({ plantId, ...body }) => apiSend("PATCH", `/api/v1/plants/${plantId}`, body));
 server.tool("add_health_entry", "WRITE: add a manual health note to one plant — an observation (e.g. 'new leaf unfurling') or an issue (e.g. 'spider mites on undersides'). Requires a write-scoped API key.", {
     plantId: z.number().int().positive().describe("Plant id."),
@@ -301,13 +307,194 @@ server.tool("delete_fertilization_event", "WRITE: delete a fertilization event f
     plantId: z.number().int().positive().describe("Plant id."),
     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."),
+    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 }));
+server.tool("propagate_plant", "WRITE: create cuttings/offsets of a plant. Each new plant is linked back to the parent as its lineage, copies the parent's type, location, fertilizer and care schedule, and starts as PROPAGATING (not yet established). Prefer this over create_plant when the new plants came from an existing one — it records the parent link that create_plant would leave you to set separately. Requires a write-scoped API key.", {
+    plantId: z.number().int().positive().describe("The parent plant the cuttings came from."),
+    count: z.number().int().min(1).max(10).optional().describe("How many propagations to create. Defaults to 1, max 10."),
+}, async ({ plantId, count }) => apiSend("POST", `/api/v1/plants/${plantId}/propagations`, { count }));
+server.tool("merge_plants", "WRITE: merge several living plants into one — for rows that turned out to be the same plant, or cuttings potted together. Pass exactly one of survivorPlantId (an existing plant absorbs the others) or createNewFrom (a new plant is created, seeded from that plant's care config). The source plants are NOT deleted: they become MERGED, keep their own care history, and point at the survivor, so unmerge_plant reverses this. Note that care events stay on the source plants rather than moving to the survivor — the survivor starts with an empty history. All sources must currently be LIVING. Requires a write-scoped API key.", {
+    sourcePlantIds: z.array(z.number().int().positive()).min(1).max(200).describe("The plants being merged away. All must be LIVING. Must not contain survivorPlantId."),
+    survivorPlantId: z.number().int().positive().optional().describe("An existing plant that absorbs the sources. Mutually exclusive with createNewFrom."),
+    createNewFrom: z.number().int().positive().optional().describe("Create a new plant as the survivor, copying type, location, soil, fertilizer and care schedule from this plant id (usually one of the sources). Mutually exclusive with survivorPlantId."),
+}, async (body) => apiSend("POST", "/api/v1/plants/merge", { ...body }));
+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`));
 // --- 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"));
 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) -------------
+/**
+ * Tools over the shared, community-maintained plant type catalog — finding
+ * and understanding duplicates, restructuring the genus/species/cultivar
+ * tree, creating and editing catalog entries directly, and (since this
+ * increment) merging two types, reviewing a proposal, and dismissing or
+ * rescanning duplicate candidates. Every description starts with `ADMIN:`
+ * for a read or `ADMIN WRITE:` for a write; `check-tool-docs.mjs` classifies
+ * a tool by that prefix (`WRITE:` for an ordinary write tool, `ADMIN WRITE:`
+ * for an admin write, `ADMIN:` for an admin read, anything else an ordinary
+ * read) — see the comment at the top of that script.
+ *
+ * These are registered conditionally — see `registerAdminToolsIfPermitted`
+ * below — so a non-admin key's session never sees a tool it can't call.
+ * Every `ADMIN WRITE:` tool requires a non-empty `note`, recorded on the
+ * catalog's change log so an assistant's edit is always traceable, with two
+ * exceptions: `admin_dismiss_duplicate_candidate` requires one for
+ * consistency but has nowhere to store it (see its own description), and
+ * `admin_rescan_duplicate_candidates` needs none at all (no decision is
+ * being made). The same `admin` scope covers both the reads and the writes
+ * here (not also `write`; the three API-key scopes are independent grants,
+ * see docs/mcp-server.md's Scopes section).
+ */
+function registerAdminTools() {
+    server.tool("admin_list_plant_types", "ADMIN: list types in the shared global plant type catalog, with filters for finding gaps and problems (missing data, no open proposals reviewed yet). Compact rows only — no full field values; use admin_get_plant_type for one type's full fact sheet. Requires an admin-scoped API key.", {
+        status: z.enum(["UNVERIFIED", "VERIFIED", "MERGED"]).optional().describe("Filter by review status. Defaults to every non-MERGED type."),
+        search: z.string().optional().describe("Fuzzy search over names (all locales) and the botanical name."),
+        genus: z.string().optional().describe("Filter to an exact genus (case-insensitive)."),
+        parentId: z.number().int().optional().describe("Filter to the cultivar children of this species-level type id."),
+        missingField: z
+            .string()
+            .optional()
+            .describe("A catalog field key (from admin_get_plant_type_field_schema) — only types with no own value for it."),
+        hasOpenProposals: z.boolean().optional().describe("true: only types with a pending proposal awaiting review."),
+        limit: z.number().int().min(1).max(200).optional().describe("Max results (pagination)."),
+        offset: z.number().int().min(0).optional().describe("Result offset (pagination)."),
+    }, async (args) => apiGet("/api/v1/admin/plant-types", { ...args, hasOpenProposals: args.hasOpenProposals?.toString() }));
+    server.tool("admin_get_plant_type", "ADMIN: full detail for one global plant type: identity and status, parent/children, names, own/inherited/effective catalog values, plant and user counts, open proposals awaiting review, open duplicate candidates, image count, and its recent change log. A MERGED type still resolves — its own row persists — so `mergedIntoId` names the type it was merged into; follow it rather than treating this as a 404. Requires an admin-scoped API key.", { id: z.number().int().describe("Global plant type id.") }, async ({ id }) => apiGet(`/api/v1/admin/plant-types/${id}`));
+    server.tool("admin_get_plant_type_field_schema", "ADMIN: the catalog field registry — every editable guidance field's key, kind, bounds, allowed enum/vocabulary values, whether it's a closed scale and what each scale value means, and its unit/group. Call this before writing any field value with admin_update_plant_type_fields; it is also how to read admin_get_plant_type's own/inherited/effective values correctly. Requires an admin-scoped API key.", async () => apiGet("/api/v1/admin/plant-types/fields"));
+    server.tool("admin_list_duplicate_candidates", "ADMIN: the duplicate-candidate queue — pairs of types the catalog's duplicate detection flagged as possibly the same plant, with the matched rule and the catalog fields where they actually disagree. Defaults to OPEN (unreviewed) candidates. Requires an admin-scoped API key.", {
+        status: z.enum(["OPEN", "DISMISSED", "MERGED"]).optional().describe("Defaults to OPEN."),
+        limit: z.number().int().min(1).max(200).optional().describe("Max results (pagination)."),
+        offset: z.number().int().min(0).optional().describe("Result offset (pagination)."),
+    }, async (args) => apiGet("/api/v1/admin/plant-types/duplicates", args));
+    server.tool("admin_list_plant_type_proposals", "ADMIN: the proposal review queue — per-field change requests filed against a type, each with the type's current value and a `stale` flag when the type changed since the proposal was filed. Defaults to PENDING. Requires an admin-scoped API key.", {
+        status: z.enum(["PENDING", "ACCEPTED", "PARTIAL", "DENIED", "WITHDRAWN"]).optional().describe("Defaults to PENDING."),
+        origin: z.enum(["user", "migration"]).optional().describe("Filter by who filed the proposal."),
+        typeId: z.number().int().optional().describe("Only proposals for this plant type id."),
+        limit: z.number().int().min(1).max(200).optional().describe("Max results (pagination)."),
+        offset: z.number().int().min(0).optional().describe("Result offset (pagination)."),
+    }, async (args) => apiGet("/api/v1/admin/plant-types/proposals", args));
+    server.tool("admin_preview_plant_type_merge", "ADMIN: preview merging two catalog types before doing it with admin_merge_plant_types. Returns both sides' identity/own values, the per-field carry-over plan and its defaults for both merge directions, counts that would move, and a guard error naming why a direction is disallowed, if any. Always call this before merging — the merge itself is irreversible. Requires an admin-scoped API key.", {
+        sourceId: z.number().int().describe("The type that would be merged away."),
+        targetId: z.number().int().describe("The type that would survive."),
+    }, async ({ sourceId, targetId }) => apiGet("/api/v1/admin/plant-types/merge-preview", { sourceId, targetId }));
+    const catalogFieldValues = z
+        .record(z.string(), z.union([z.string(), z.number(), z.boolean(), z.array(z.string()), z.null()]))
+        .describe("Field values keyed by field name — call admin_get_plant_type_field_schema first for valid keys, kinds, and bounds. null clears a value.");
+    const catalogNameEntry = z.object({
+        name: z.string().min(1).describe("The name text."),
+        locale: z.enum(["de", "en"]).nullable().describe("'de', 'en', or null for any other language."),
+        isPrimary: z.boolean().describe("Whether this is the display name shown for its locale."),
+    });
+    server.tool("admin_create_plant_type", "ADMIN WRITE: create a new type in the shared global plant type catalog. genus is required; species/cultivar are optional and determine the botanical identity key. Setting cultivar attaches the new type as a cultivar under the existing species-level type with the matching genus|species key, if one exists — parentId in the response names it. If no such species exists yet, parentId comes back null and missingParentBotanicalKey names the key to create first (call this tool again without a cultivar, then retry): a cultivar's parent is never auto-created. When the new type is itself species-level (no cultivar), any existing type with no parent whose own key implies this one as parent is automatically re-parented onto it — returned as adoptedOrphanIds — which is how creating a missing species repairs the tree. Fails with a 409 conflict (conflictingTypeId in the error details) when another live type already owns the resulting identity; call admin_preview_plant_type_merge and merge them in the app instead of forcing this. status defaults to VERIFIED (an admin vouching for the new type); pass UNVERIFIED to leave it for review. note is required and recorded on the change log. Requires an admin-scoped API key.", {
+        genus: z.string().min(1).describe("Genus, required."),
+        species: z.string().nullable().optional().describe("Species epithet. Omit or null for a genus-only/unidentified-species type."),
+        cultivar: z.string().nullable().optional().describe("Cultivar name. Setting this makes the new type a cultivar attached under the matching species-level type."),
+        names: z.array(catalogNameEntry).optional().describe("Initial full name list. Defaults to none."),
+        values: catalogFieldValues.optional().describe("Optional initial catalog field values."),
+        status: z.enum(["UNVERIFIED", "VERIFIED"]).optional().describe("Review status. Defaults to VERIFIED."),
+        note: z.string().min(1).describe("Required note, recorded on the new type's change log."),
+    }, async ({ names, values, status, note, ...identity }) => apiSend("POST", "/api/v1/admin/plant-types", { ...identity, names, values, status, note }));
+    server.tool("admin_update_plant_type_fields", "ADMIN WRITE: edit a global plant type's own catalog field values. Call admin_get_plant_type_field_schema first for valid keys/bounds, and admin_get_plant_type to see current own/inherited/effective values. values is a partial patch — only the keys you pass change. Set a key to null to clear the type's own value so it inherits from its parent chain again; do not set a cultivar's value to the same thing it already inherits, since that freezes a copy that will drift from the parent later — leave it null instead. Returns which fields actually changed. note is required and recorded on the change log. Requires an admin-scoped API key.", {
+        id: z.number().int().describe("Global plant type id."),
+        values: catalogFieldValues,
+        note: z.string().min(1).describe("Required note, recorded on the change log."),
+    }, async ({ id, values, note }) => apiSend("PATCH", `/api/v1/admin/plant-types/${id}/fields`, { values, note }));
+    server.tool("admin_set_plant_type_names", "ADMIN WRITE: replace a global plant type's full name list. This is a full replacement, not a patch — call admin_get_plant_type first and send its complete names array back with your change, or names you leave out are dropped. isPrimary picks the display name shown per locale ('de'/'en'/null for other); at most one primary per locale. note is required and recorded on the change log. Requires an admin-scoped API key.", {
+        id: z.number().int().describe("Global plant type id."),
+        names: z.array(catalogNameEntry).describe("The complete replacement name list."),
+        note: z.string().min(1).describe("Required note, recorded on the change log."),
+    }, async ({ id, names, note }) => apiSend("PUT", `/api/v1/admin/plant-types/${id}/names`, { names, note }));
+    server.tool("admin_update_plant_type_botanical_identity", "ADMIN WRITE: edit a global plant type's genus/species/cultivar. This also moves the type in the tree: parentId is re-derived from the new genus|species key, attaching to the matching species-level type if one exists. When the edit makes the type species-level, any existing orphaned type whose own key implies this one as parent is automatically re-parented onto it, returned as adoptedOrphanIds — same as admin_create_plant_type. Fails with a 409 conflict (conflictingTypeId in the error details) when another live type already owns the resulting identity — that means these are duplicates: call admin_preview_plant_type_merge and merge them in the app instead of forcing this edit. Refuses to turn a type with cultivar children into a cultivar itself. note is required and recorded on the change log. Requires an admin-scoped API key.", {
+        id: z.number().int().describe("Global plant type id."),
+        genus: z.string().nullable().describe("New genus, or null to clear it (only valid when the type still has a name to fall back on as its identity)."),
+        species: z.string().nullable().describe("New species epithet, or null."),
+        cultivar: z.string().nullable().describe("New cultivar name, or null."),
+        note: z.string().min(1).describe("Required note, recorded on the change log."),
+    }, async ({ id, genus, species, cultivar, note }) => apiSend("PATCH", `/api/v1/admin/plant-types/${id}/identity`, { genus, species, cultivar, note }));
+    server.tool("admin_verify_plant_type", "ADMIN WRITE: promote an UNVERIFIED global plant type to VERIFIED. note is required and recorded on the change log. Requires an admin-scoped API key.", {
+        id: z.number().int().describe("Global plant type id."),
+        note: z.string().min(1).describe("Required note, recorded on the change log."),
+    }, async ({ id, note }) => apiSend("POST", `/api/v1/admin/plant-types/${id}/verify`, { note }));
+    const catalogFieldChoices = z
+        .record(z.string(), z.enum(["source", "target"]))
+        .describe("Keyed by field name — picks which side wins for a catalog field admin_preview_plant_type_merge lists as conflict/onlySource. Omit a field (or omit this whole argument) to take the plan's own default for it.");
+    server.tool("admin_merge_plant_types", "ADMIN WRITE: merge sourceId into targetId in the shared global plant type catalog. This is IRREVERSIBLE: sourceId becomes a MERGED redirect stub, and every plant, name, image, cultivar child, pending proposal, legacy mapping, and open duplicate candidate that pointed at it moves onto targetId. Always call admin_preview_plant_type_merge first — it shows the exact same comparison a human admin would see (both sides' values, the per-field carry-over plan and its defaults, counts that would move, and why a direction might be disallowed) before you commit to this. targetId keeps its own identity, parentId, status, and cover image unchanged; fieldChoices only picks which side's value wins for the catalog fields the preview lists as conflict or onlySource — everything else the plan defaults to adopting happens regardless of fieldChoices. Returns the survivor's full detail (same shape as admin_get_plant_type) plus the move counts. note is required and recorded on the change log of both types. Requires an admin-scoped API key.", {
+        sourceId: z.number().int().describe("The type that will be merged away (becomes a MERGED redirect)."),
+        targetId: z.number().int().describe("The type that will survive and receive everything from sourceId."),
+        note: z.string().min(1).describe("Required note, recorded on the change log of both types."),
+        fieldChoices: catalogFieldChoices.optional(),
+    }, async ({ sourceId, targetId, note, fieldChoices }) => apiSend("POST", "/api/v1/admin/plant-types/merge", { sourceId, targetId, note, fieldChoices }));
+    server.tool("admin_accept_plant_type_proposal", "ADMIN WRITE: accept a pending proposal against a global plant type, in full or in part. Omitting fields accepts every field the proposal changed (status ACCEPTED); passing an explicit subset accepts only those (status PARTIAL, unless the subset happens to cover everything proposed). If a field's current value has moved on since the proposal was filed, accepting it fails the whole call with a 409 naming the stale fields (details.staleFields) — there is no override here; either handle that field by hand (e.g. admin_update_plant_type_fields) and retry with fields excluding it, or deny the proposal instead. Returns the type's full detail (post-accept) plus which fields actually changed. note is required and recorded on the change log. Requires an admin-scoped API key.", {
+        id: z.number().int().describe("Proposal id, from admin_list_plant_type_proposals."),
+        fields: z
+            .array(z.string())
+            .optional()
+            .describe("Subset of the proposal's changed fields to accept. Omit to accept all of them."),
+        note: z.string().min(1).describe("Required note, recorded on the change log."),
+    }, async ({ id, fields, note }) => apiSend("POST", `/api/v1/admin/plant-types/proposals/${id}/accept`, { fields, note }));
+    server.tool("admin_deny_plant_type_proposal", "ADMIN WRITE: deny a pending proposal against a global plant type. Never writes a change log entry on the type itself — a denied proposal is private to its author and the reviewer — and never touches the type's own field values. note is required. Requires an admin-scoped API key.", {
+        id: z.number().int().describe("Proposal id, from admin_list_plant_type_proposals."),
+        note: z.string().min(1).describe("Required note (recorded on the proposal, not the type's change log)."),
+    }, async ({ id, note }) => apiSend("POST", `/api/v1/admin/plant-types/proposals/${id}/deny`, { note }));
+    server.tool("admin_deny_plant_type_proposals", "ADMIN WRITE: deny every PENDING proposal on one global plant type at once, optionally narrowed to one origin — useful for clearing a batch of migration-filed proposals in one call instead of denying them one at a time. A proposal that stopped being PENDING between the lookup and its turn is silently skipped rather than failing the whole call; every other failure aborts the batch. note is required, applied to every denial. Requires an admin-scoped API key.", {
+        typeId: z.number().int().describe("Global plant type id."),
+        origin: z.enum(["user", "migration"]).optional().describe("Only deny proposals filed by this origin. Omit to deny every PENDING proposal regardless of origin."),
+        note: z.string().min(1).describe("Required note, applied to every denial."),
+    }, async ({ typeId, origin, note }) => apiSend("POST", "/api/v1/admin/plant-types/proposals/deny", { typeId, origin, note }));
+    server.tool("admin_dismiss_duplicate_candidate", "ADMIN WRITE: dismiss an OPEN duplicate candidate as 'not actually a duplicate', without merging it. It never comes back — a previously dismissed pair is excluded from every future admin_rescan_duplicate_candidates run. note is required for consistency with every other admin write here, but is NOT stored anywhere: the duplicate-candidate row has no field to keep it in. Requires an admin-scoped API key.", {
+        id: z.number().int().describe("Duplicate candidate id, from admin_list_duplicate_candidates."),
+        note: z.string().min(1).describe("Required, but not persisted — see the tool description."),
+    }, async ({ id, note }) => apiSend("POST", `/api/v1/admin/plant-types/duplicates/${id}/dismiss`, { note }));
+    server.tool("admin_rescan_duplicate_candidates", "ADMIN WRITE: re-run duplicate detection against the whole live catalog and reconcile the duplicate-candidate queue — the same 'Rescan' button the admin Duplicates tab has, for when catalog edits (new types, merges, name or identity changes) since the last migration run mean the queue no longer reflects what a fresh scan would produce. A previously dismissed or already-merged pair never comes back. No note needed: this only rebuilds the queue, there is no reviewable decision to leave a reason for. Returns how many candidates were added, updated, and removed. Requires an admin-scoped API key.", async () => apiSend("POST", "/api/v1/admin/plant-types/duplicates/rescan", {}));
+}
+/**
+ * Calls `/api/v1/me` once at startup to decide whether this key carries the
+ * `admin` scope, and registers the admin catalog tools only when it does —
+ * so a non-admin key's session never even sees a tool it could not call
+ * (rather than registering it and letting every call fail with 403). A
+ * failed whoami call (network error, invalid key — `apiGet`'s own retry-free
+ * failure modes) is logged to stderr and registers no admin tools, the same
+ * as a confirmed non-admin key: better to under-register than to guess.
+ */
+async function registerAdminToolsIfPermitted() {
+    let res;
+    try {
+        res = await fetch(new URL(`${API_URL}/api/v1/me`), {
+            headers: { Authorization: `Bearer ${API_KEY}`, Accept: "application/json" },
+        });
+    }
+    catch (err) {
+        console.error(`[plants-mcp] Could not reach ${API_URL}/api/v1/me to check for admin access: ${String(err)}. Admin tools not registered.`);
+        return;
+    }
+    if (!res.ok) {
+        console.error(`[plants-mcp] /api/v1/me returned HTTP ${res.status}; admin tools not registered.`);
+        return;
+    }
+    let body;
+    try {
+        body = await res.json();
+    }
+    catch {
+        console.error("[plants-mcp] /api/v1/me returned an unreadable response; admin tools not registered.");
+        return;
+    }
+    const scopes = body?.scopes;
+    if (Array.isArray(scopes) && scopes.includes("admin")) {
+        registerAdminTools();
+    }
+}
 // --- Boot -------------------------------------------------------------------
 async function main() {
+    await registerAdminToolsIfPermitted();
     const transport = new StdioServerTransport();
     await server.connect(transport);
     console.error(`[plants-mcp] v${VERSION} connected. API base: ${API_URL}`);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sebamomann/plants-mcp",
-  "version": "1.7.0",
-  "description": "MCP server for the Sprig plant app: 29 tools to read a plant collection, log care, and edit a plant. Read-only by default; writes need a write-scoped API key. Two tools can delete a watering/fertilization event; nothing else is destructive.",
+  "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.",
   "type": "module",
   "license": "MIT",
   "author": "sebamomann <github@sebamomann.de>",