@sebamomann/plants-mcp 1.7.0 → 1.8.0

package/CHANGELOG.md

@@ -3,6 +3,25 @@
 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.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,12 +60,13 @@ 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.
+**33 tools** over your collection: 19 that read it, 14 that write to it.
 
 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
@@ -98,7 +99,7 @@ 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.
 
 | Situation | HTTP | What the assistant sees |
 |---|---|---|
@@ -247,7 +248,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 +266,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 |

package/dist/index.js

@@ -245,7 +245,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 +254,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,6 +302,24 @@ 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"));

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.8.0",
+  "description": "MCP server for the Sprig plant app: 33 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.",
   "type": "module",
   "license": "MIT",
   "author": "sebamomann <github@sebamomann.de>",