@sebamomann/plants-mcp 1.2.0 → 1.7.0

package/CHANGELOG.md

@@ -3,6 +3,49 @@
 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.7.0 — 2026-08-08
+
+**New plant status: `EXTERNAL` (reference plant).** A plant somebody else owns, recorded only as
+an anchor for propagation lineage — never cared for, no care settings, not part of the collection.
+`list_plants` accepts it (and `SPLIT`, which the enum had been missing) as a `status` filter, and
+`collection_stats` now excludes `EXTERNAL` plants from every count and total, matching the app's
+`/stats` page. No tool added or removed.
+
+## 1.6.0 — 2026-08-04
+
+**Plants can now carry freeform tags.** `update_plant` gained a `tags` argument (replaces the
+full list; `null`/`[]` clears it) and `list_plants` gained a `tag` filter (exact match). Tags are
+a plain string list on the plant, not a separate catalog — no new id-resolution tool needed.
+`get_plant`/`list_plants` responses also now include `tags` (no doc change required for that half,
+per the "added response fields are safe" rule — the argument additions are what make this minor).
+
+## 1.5.0 — 2026-08-04
+
+**`list_care_recommendations` gained a new recommendation type: `repotDue`.** Fires when a living,
+non-propagating plant hasn't been repotted in over 2 years — anchored to the latest potting event,
+or to `acquiredAt`/`createdAt` if it's never been repotted at all. Dismissible, same as the other
+info-severity recommendations. No tool added or removed, so this is a minor bump for the new
+response value, not a new tool. The stale-photo recommendation's threshold also dropped from 90 to
+60 days — same field shape, just a tighter default.
+
+## 1.4.0 — 2026-08-04
+
+**New tool: `sitter_briefing`.** Printable care sheet for the caller's current or next
+`sitter`-mode vacation: per-plant sitter instructions, watering notes, cycle and next-due state,
+plus the day-by-day watering schedule for the trip. Optional `locationId` narrows the plant list
+to one location. Returns `{ hasVacation: false }` when there is no upcoming or running sitter
+vacation — read-only, never creates or modifies one. Backed by a new
+`GET /api/v1/vacation/sitter-briefing` endpoint, reusing the same data-loading logic as the public
+`/p/:token` sitter page.
+
+## 1.3.0 — 2026-08-04
+
+**New tool: `collection_stats`.** Counts and totals across the whole collection — plants by
+status, by location, and by plant type; total spend (`price`) and total revenue (`soldPrice` on
+sold plants); acquisitions bucketed by month. Backed by a new `GET /api/v1/collection/stats`
+endpoint. Answers questions like "how many plants do I have" or "how much have I spent" without
+listing every plant and counting client-side.
+
 ## 1.2.0 — 2026-08-03
 
 **`update_plant_care` gained two new optional arguments: `wateringMode` and `fertilizingMode`.**

package/README.md

@@ -60,7 +60,7 @@ needs a running Sprig instance and an API key from it. Start at the
 
 ## What an assistant can do
 
-**27 tools** over your collection: 17 that read it, 10 that write to it.
+**29 tools** over your collection: 19 that read it, 10 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.
@@ -97,7 +97,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 17 read tools.
+- **`read`** — on every key. Gates all 19 read tools.
 - **`write`** — opt-in when you create the key. Gates the 10 write tools.
 
 | Situation | HTTP | What the assistant sees |
@@ -132,11 +132,13 @@ 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`, `search` (type name / notes), `limit` (1–200), `offset`, `sort` |
+| `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 |
 
-`status` is one of `LIVING`, `DEAD`, `GIFTED`, `LOST`, `SOLD`, `TRADED`, `MERGED`; `lifecycle` is
-`PROPAGATING` or `ESTABLISHED`.
+`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`.
 
 ### Per-plant history
 
@@ -164,7 +166,7 @@ overrides the Apr–Sep default), `locationId`.
 | `list_due_care` | `GET /api/v1/care/due` | `windowDays` (0–60, default 0 = that day only), `includeOverdue` (default true) | "What should I do today?" |
 | `list_overdue_care` | `GET /api/v1/care/overdue` | — | "What have I fallen behind on?" — most overdue first, with days late |
 | `get_care_calendar` | `GET /api/v1/care/calendar` | `days` (1–60, default 14) | Day-by-day projection plus an overdue group |
-| `list_care_recommendations` | `GET /api/v1/care/recommendations` | none | Detected problems: cycle mismatch, chronic lateness, missed seasonal fertilizing, recent repotting, stale photos |
+| `list_care_recommendations` | `GET /api/v1/care/recommendations` | none | Detected problems: cycle mismatch, chronic lateness, missed seasonal fertilizing, fertilizer pause after repotting, repotting overdue, stale photos |
 
 Three things to know when reading schedule results:
 
@@ -185,6 +187,28 @@ Use this instead of looping the per-plant tools when the question is about a **t
 ("what did I water last week?") rather than one plant. Newest first, each entry tagged with a
 `kind` and naming its plant. Does **not** include acquisitions, gifts, sales, or trades.
 
+### Collection-wide aggregates
+
+| Tool | Endpoint | Arguments |
+|---|---|---|
+| `collection_stats` | `GET /api/v1/collection/stats` | none |
+
+Counts by status, location, and plant type; total spend (`price`) and total revenue (`soldPrice`
+on sold plants); acquisitions bucketed by month. Use this instead of listing every plant when the
+question is a count or a total, not which specific plants. Every status is included except
+`EXTERNAL` (reference plants aren't yours) — no `MERGED` filter — matching the app's own `/stats`
+page.
+
+| Tool | Endpoint | Arguments |
+|---|---|---|
+| `sitter_briefing` | `GET /api/v1/vacation/sitter-briefing` | `locationId` (optional) |
+
+Printable care sheet for the caller's current or next `sitter`-mode vacation: per-plant sitter
+instructions, watering notes, cycle and next-due state, and the day-by-day watering schedule for
+the trip. Returns `{ hasVacation: false }` when there's no upcoming or running sitter vacation —
+this tool never creates or modifies one. `locationId` narrows the plant list to one location; the
+schedule always covers the whole vacation.
+
 ### Catalogs
 
 For resolving the ids the filters take. No arguments.
@@ -223,7 +247,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`, `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` |
 
 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).

package/dist/index.js

@@ -121,14 +121,15 @@ server.tool("whoami", "Return the authenticated user for the configured API key.
 // --- Plants -----------------------------------------------------------------
 server.tool("list_plants", "List the user's plants, with optional filters. Returns plant summaries.", {
     status: z
-        .enum(["LIVING", "DEAD", "GIFTED", "LOST", "SOLD", "TRADED", "MERGED"])
+        .enum(["LIVING", "DEAD", "GIFTED", "LOST", "SOLD", "TRADED", "MERGED", "SPLIT", "EXTERNAL"])
         .optional()
-        .describe("Filter by plant status."),
+        .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."),
     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."),
     limit: z.number().int().min(1).max(200).optional().describe("Max results (pagination)."),
     offset: z.number().int().min(0).optional().describe("Result offset (pagination)."),
@@ -183,7 +184,7 @@ server.tool("get_care_calendar", "Day-by-day care schedule over a date range, pl
     ...careArgs,
     days: z.number().int().min(1).max(60).optional().describe("Number of days to project (default 14, max 60)."),
 }, async (args) => apiGet("/api/v1/care/calendar", args));
-server.tool("list_care_recommendations", "Care problems detected across the collection: watering-cycle mismatches, chronic lateness, missed seasonal fertilizing, recent repotting, stale photos. Returns i18n message keys plus their values, not rendered text. Dismissed recommendations are excluded.", async () => apiGet("/api/v1/care/recommendations"));
+server.tool("list_care_recommendations", "Care problems detected across the collection: watering-cycle mismatches, chronic lateness, missed seasonal fertilizing, a fertilizer pause right after repotting, repotting overdue (2+ years, or never), stale photos. Returns i18n message keys plus their values, not rendered text. Dismissed recommendations are excluded.", async () => apiGet("/api/v1/care/recommendations"));
 // --- Collection-wide activity ----------------------------------------------
 server.tool("list_recent_activity", "What was actually done across the whole collection, newest first: waterings, fertilizations, refills, hydro events, repottings, health notes, photos. Each entry is tagged with a kind and names its plant. Use this instead of calling the per-plant event tools in a loop when the question is about a time period ('what did I water last week?') rather than one plant. Does not include acquisitions, gifts, sales, or trades.", {
     since: z.string().optional().describe("Only events at or after this ISO date/timestamp, e.g. '2026-07-01'."),
@@ -195,6 +196,11 @@ server.tool("list_recent_activity", "What was actually done across the whole col
     limit: z.number().int().min(1).max(500).optional().describe("Max results (pagination)."),
     offset: z.number().int().min(0).optional().describe("Result offset (pagination)."),
 }, async ({ kinds, ...rest }) => apiGet("/api/v1/activity", { ...rest, kinds: kinds?.join(",") }));
+// --- Collection-wide aggregates ---------------------------------------------
+server.tool("collection_stats", "Counts and totals across the whole collection: how many plants by status (living, dead, gifted, sold, traded), by location, and by plant type; total spend (sum of price) and total revenue (sum of soldPrice for sold plants); acquisitions bucketed by month. Use this instead of listing every plant when the question is a count or a total, not which specific plants.", async () => apiGet("/api/v1/collection/stats"));
+server.tool("sitter_briefing", "Printable care sheet for the caller's current or next sitter-covered vacation: per-plant sitter instructions, watering notes, watering cycle and next-due state, plus the day-by-day watering schedule for the trip. Returns { hasVacation: false } when there is no upcoming or running vacation in 'sitter' mode. Read-only — does not create or modify a vacation.", {
+    locationId: z.number().int().optional().describe("Only include plants in this location (id from list_locations). Omit for every plant on the vacation."),
+}, async (args) => apiGet("/api/v1/vacation/sitter-briefing", args));
 // --- Care logging (writes) --------------------------------------------------
 /**
  * Mutating tools. These require an API key with the `write` scope; a read-only
@@ -239,13 +245,14 @@ 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, or sitter instructions. Omitted fields keep their current value; null unassigns a catalog entry or clears notes/instructions. Requires a write-scoped API key.", {
+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.", {
     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."),
     fertilizerId: z.number().int().positive().nullable().optional().describe("New fertilizer id, from list_fertilizers. null unassigns it."),
     quantity: z.number().int().min(0).max(9999).nullable().optional().describe("How many plants this row represents."),
     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."),
 }, 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.", {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sebamomann/plants-mcp",
-  "version": "1.2.0",
-  "description": "MCP server for the Sprig plant app: 27 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.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.",
   "type": "module",
   "license": "MIT",
   "author": "sebamomann <github@sebamomann.de>",