@sebamomann/plants-mcp 2.13.0 → 3.1.0

package/CHANGELOG.md

@@ -3,6 +3,81 @@
 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.
 
+## 3.1.0 — 2026-10-19
+
+**New tool `mark_watering_due`.** Tool count 82 (was 81). A **minor** bump:
+
+- `mark_watering_due` (`POST /api/v1/care/due-today`, `plantId`) is the "needs water" answer to an
+  autumn "Prüfen" check: it records no watering but marks the plant due today, so it appears in
+  `list_due_care` `tasks`. Cleared by the next watering; replaced by `dismiss_transition_check` or a
+  snooze; if not acted on the plant reads as overdue from the next day.
+- Additive: care-snooze timeline entries carry `reason` (`dueToday` for these marks, `stillWet` for
+  "noch feucht" skips, otherwise `null`).
+
+## 3.0.0 — 2026-10-04
+
+**`noFertilizerThisSeason` is renamed `fertilizingNotStarted`.** Tool count unchanged (81). A **major**
+bump — an accepted argument value was removed:
+
+- `list_care_recommendations` no longer returns `noFertilizerThisSeason` ("no feeding since the
+  season started", which fired on day one of every season). The new type `fertilizingNotStarted`
+  fires only for a plant with a fertilizer and an active fertilizing cycle that has **never** been
+  fertilized, once a full cycle has passed since feeding could have started (acquisition, the end of
+  a repotting rest, or the end of a winter pause). Cuttings are excluded.
+- `dismiss_care_recommendation`'s `type` enum: `noFertilizerThisSeason` → `fertilizingNotStarted`.
+  Old dismissals of the removed type no longer apply to anything.
+- Additive: `wateringCycleMismatch.values` gains `season` (`"summer"`/`"winter"`), the column the
+  suggestion is expressed in. The mismatch is now judged against the cycle in effect when each
+  interval started (season, gradual season ramp, controlled climate), so a season change alone no
+  longer makes a plant look off-cycle.
+- `list_notifications`: a `CHANGELOG_PUBLISHED` row may now carry `messageKey:
+  "changelogPublishedSummary"` with `values: { summary }` (that day's summary) instead of
+  `changelogPublished` with `{ count }`.
+
+## 2.16.0 — 2026-10-04
+
+**Autumn "Prüfen" checks: `list_due_care` gains `checks`, new `dismiss_transition_check`.** Tool count
+81 (was 80). A **minor** bump — one new tool and one additive response field:
+
+- `list_due_care` returns an additive `checks` array — `{ plantId, name, lastWateredAt, checkSince,
+  regularDueAt }` — for plants whose watering interval grew with the autumn season change while the
+  plant may dry out at its summer pace. A question, not a task: not in `tasks`/`counts`. Existing
+  fields are unchanged.
+- New write tool `dismiss_transition_check` (`plantId`): answers a check with "noch feucht", hiding
+  it until its regular due date without moving that date. The other answer ("dry") is
+  `record_watering`.
+
+## 2.15.0 — 2026-10-04
+
+**`update_plant_care` gains `keepWinterCare`; `get_plant` reports the effective schedule.** Tool count
+unchanged (80). A **minor** bump — one new optional argument and new response fields:
+
+- `update_plant_care` accepts `keepWinterCare: boolean`. A plant in a controlled-climate location
+  follows its summer watering and fertilizing cycle all year; `keepWinterCare: true` brings the
+  winter cycle back for both. The stored winter values are never cleared by it.
+- `get_plant` returns `keepWinterCare`, the location's `controlledClimate` (inside `location`) and a
+  new top-level `followsSummerYearRound` boolean.
+- **Behaviour change in `get_plant`:** its six schedule fields now show what scheduling actually uses.
+  For a plant that follows its summer cycle all year, the winter fields
+  (`wateringFrequencyWinterDays`, `wateringFrequencyWinter`, `fertilizingCycleWinterWeeks`) are the
+  *effective* (summer) values, not the stored winter ones. Nothing changes for plants outside a
+  controlled-climate location.
+- `update_plant_care`'s result includes `keepWinterCare`.
+
+## 2.14.0 — 2026-10-04
+
+**New tool: `update_location`; `create_location` gains `controlledClimate`.** Tool count 79 → 80
+(28 read, 34 write, 18 admin). A **minor** bump — one new write tool and one new optional argument:
+
+- `PATCH /api/v1/locations/:id` takes any of `name`, `parentId` (`null` = top level) and
+  `controlledClimate`; only the fields present change. Shares its core with the location detail
+  page's save action, so cycle checks on `parentId` behave identically.
+- `controlledClimate` marks a place with constant light and warmth (e.g. a plant cabinet): plants
+  placed directly there follow their summer watering and fertilizing cycle all year, unless the
+  plant opts back into winter care. `create_location` accepts it too.
+- `list_locations` now returns `controlledClimate` per location (a new response field — no
+  change needed by callers).
+
 ## 2.13.0 — 2026-09-30
 
 **New tool: `merge_soils`.** Tool count 78 → 79 (28 read, 33 write, 18 admin). A **minor** bump —

package/README.md

@@ -8,7 +8,14 @@ just ask:
 > *"Which plants am I behind on?"*
 > *"Log that I watered everything on the windowsill."*
 
-## Quick start
+> **Using Claude (claude.ai, the mobile app, Claude Desktop or Claude Code)?** Connect to the
+> remote endpoint instead and sign in, no key to copy: add a custom connector with the URL
+> `https://plants.sebamomann.de/api/mcp`, leave the OAuth fields empty and sign in to Sprig
+> (in Claude Code: `claude mcp add --transport http sprig https://plants.sebamomann.de/api/mcp`,
+> then `/mcp`). This package stays for **local stdio setups** with an API key, and API keys also
+> work as a header against the remote endpoint for scripts.
+
+## Quick start (local, with an API key)
 
 **1. Get an API key.** In Sprig: **Account → Settings → API keys → Generate**. It is shown once — copy it
 then. Pick read-only unless you actually want the assistant logging care; you can change a key's
@@ -60,7 +67,7 @@ needs a running Sprig instance and an API key from it. Start at the
 
 ## What an assistant can do
 
-**79 tools** over your collection: 28 that read it, 33 that write to it. **18 admin tools** are also
+**82 tools** over your collection: 28 that read it, 36 that write to it. **18 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, reading, directly
 editing, merging, and reviewing proposals and duplicate candidates in that catalog, and (7 read-only,
@@ -112,7 +119,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 28 read tools.
-- **`write`** — opt-in when you create the key. Gates the 33 write tools.
+- **`write`** — opt-in when you create the key. Gates the 36 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 18 admin catalog tools — 7 read-only, 11 that write — see **Admin tools** below. `admin` alone
@@ -174,7 +181,13 @@ facts (light, water, feeding need, toxicity, climate, growth, substrate/propagat
 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.
+instead of a raw value — see **Breaking changes in 2.0.0** below. They show what scheduling actually
+uses: for a plant in a controlled-climate location without `keepWinterCare`, the winter fields equal the
+summer values, and `followsSummerYearRound` is `true` (also returned: `keepWinterCare` and
+`location.controlledClimate`). `inWinterRest` is `true` while the plant is in its winter rest (its type's
+`winterRest` fact is set, it is winter — roughly late October to mid-March — and it does not follow its summer
+cycle year-round): such a plant drops leaves and wants almost no water or fertilizer on purpose, so don't treat
+it as declining.
 
 ### Per-plant history
 
@@ -200,10 +213,10 @@ overrides the Apr–Sep default), `locationId`.
 
 | Tool | Endpoint | Extra arguments | Answers |
 |---|---|---|---|
-| `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_due_care` | `GET /api/v1/care/due` | `windowDays` (0–60, default 0 = that day only), `includeOverdue` (default true) | "What should I do today?" Also carries the additive `checks` array (autumn "Prüfen" questions — see `dismiss_transition_check`). |
 | `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, fertilizer pause after repotting, repotting overdue, stale photos |
+| `list_care_recommendations` | `GET /api/v1/care/recommendations` | none | Detected problems: cycle mismatch, chronic lateness, fertilizing never started, fertilizer pause after repotting, repotting overdue, stale photos |
 
 Five things to know when reading schedule results:
 
@@ -215,7 +228,8 @@ Five things to know when reading schedule results:
   they never appear in `tasks`, `days[]` or `neverLogged` at all. Instead, `list_due_care` and
   `get_care_calendar` each carry a `reservoirChecks` array of `{ plantId, nextCheckAt,
   daysUntilCheck, confidence }` — a *predicted* next check, the median gap between that plant's own
-  last few refills (reservoir) or hydro entries, not a schedule the user configured. `nextCheckAt` is
+  last few refills (reservoir) or hydro entries, checked ~15% of it early (at least a day), not a
+  schedule the user configured. `nextCheckAt` is
   a `YYYY-MM-DD` day like `nextDue`; `daysUntilCheck` is negative once it has passed; `confidence` is
   `"rough"` below three observed gaps and `"established"` from there on. The array ignores
   `windowDays`/`days` — every plant with a prediction is always in it — and a plant with fewer than
@@ -362,7 +376,7 @@ tools** → **Catalogs** below) lets a write-scoped key add it.
 
 ## Write tools
 
-**All 31 ordinary write tools require a `write`-scoped key**; a read-only key gets HTTP 403. Every
+**All 32 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
@@ -419,7 +433,7 @@ it is — that backlog is not the watering's doing.
 
 | 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`), `wateringFrequencySummer`/`wateringFrequencyWinter` (labels), `wateringFrequencySummerDays`/`wateringFrequencyWinterDays` (1–365), `wateringNotes`, `fertilizingCycleSummerWeeks`/`fertilizingCycleWinterWeeks` (0–52), `fertilizerPercent` (0–1000), `fertilizingNotes` |
+| `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`, `keepWinterCare` (boolean — winter cycle despite a controlled-climate location) |
 | `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
@@ -529,11 +543,28 @@ The two edit tools take an **`entryId`, not a `plantId`** — get it from `list_
 | Tool | Endpoint | Arguments |
 |---|---|---|
 | `dismiss_care_recommendation` | `POST /api/v1/care/recommendations/dismiss` | `plantId`, `type`, `fingerprint` — **all required** |
+| `dismiss_transition_check` | `POST /api/v1/care/transition-checks/dismiss` | `plantId` **(required)** — a plant listed in `checks` of `list_due_care` |
+| `mark_watering_due` | `POST /api/v1/care/due-today` | `plantId` **(required)** — marks the plant's watering due today without recording one |
+
+`mark_watering_due` is the "needs water" answer to an autumn "Prüfen" check (and works for any plant
+that looks thirsty): it records **no** watering, it pulls the plant's due date forward to today, so
+the plant shows up in `list_due_care` `tasks` (and in the app's care plan, counts and reminders)
+with the usual answers. The next watering clears the mark; a later `dismiss_transition_check` or
+snooze replaces it; if nobody acts, the plant reads as overdue from the next day. Idempotent while
+the mark stands. Returns `{ plantId, dueOn }`.
+
+`dismiss_transition_check` answers an autumn "Prüfen" check with "noch feucht": as the season changes
+to winter the watering interval grows, so a plant that dries out at its summer pace would go
+unreminded for longer. `list_due_care` lists such plants in `checks`
+(`{ plantId, name, lastWateredAt, checkSince, regularDueAt }`) from the day the summer-pace watering
+would have been due until the regular due date. The dismissal hides the check until then and never
+moves the due date; a new watering reopens the question. The other answer, "dry", is a plain
+`record_watering`.
 
 Pass all three **exactly as returned by `list_care_recommendations`**. The `fingerprint` identifies
 that specific occurrence, so dismissing one never suppresses a later, different recurrence.
 
-Dismissible `type` values: `wateringOftenLate`, `fertilizingOftenLate`, `noFertilizerThisSeason`,
+Dismissible `type` values: `wateringOftenLate`, `fertilizingOftenLate`, `fertilizingNotStarted`,
 `recentlyRepottedAvoidFertilizer`, `noRecentPhoto`, `propagationCheckDue`, `possibleDecline`.
 `wateringCycleMismatch` is **not** dismissible — it is a configuration contradiction, fixed by
 editing the plant rather than hidden.
@@ -593,7 +624,8 @@ mirror (opening the page already marks everything read).
 
 | Tool | Endpoint | Arguments |
 |---|---|---|
-| `create_location` | `POST /api/v1/locations` | `name` **(required)**, `parentId` (an owned location, to nest under) |
+| `create_location` | `POST /api/v1/locations` | `name` **(required)**, `parentId` (an owned location, to nest under), `controlledClimate` (plants there follow their summer watering/fertilizing cycle year-round unless they opt back into winter care) |
+| `update_location` | `PATCH /api/v1/locations/:id` | `locationId` **(required)**, `name`, `parentId` (`null` = top level), `controlledClimate` — only the fields passed change |
 | `create_soil` | `POST /api/v1/soils` | `name` **(required)**, `notes`, `items` (`{ componentName, parts }[]`, each component upserted by name) |
 | `merge_soils` | `POST /api/v1/soils/merge` | `sourceId` **(required)**, `targetId` **(required)** |
 | `create_fertilizer` | `POST /api/v1/fertilizers` | `name` **(required)**, `npk`, `baseDosePerLiterMl` (0–100) |
@@ -846,7 +878,7 @@ npm run mcp:typecheck  # also part of the root `npm run check`
 To point a client at your checkout, use `"command": "node", "args": ["/…/plants/mcp/dist/index.js"]`
 — or skip the build with `"command": "npx", "args": ["tsx", "/…/plants/mcp/src/index.ts"]`.
 
-The whole server is `mcp/src/index.ts`. `mcp/AGENTS.md` has the architecture rules; the canonical
+The tools live in `app/_lib/mcp/tools.ts`; `mcp/src/index.ts` is only the stdio wrapper. `mcp/AGENTS.md` has the architecture rules; the canonical
 spec for the tool surface is `docs/mcp-server.md` at the repo root.
 
 ## Security

package/dist/app/_lib/mcp/apiClient.js

@@ -0,0 +1,103 @@
+/**
+ * The shared HTTP proxy every tool in `tools.ts` is built on: `apiGet` for reads,
+ * `apiSend` for writes. Kept in its own module so it can be unit-tested in isolation,
+ * away from the `McpServer` and transport wiring.
+ *
+ * Both functions take the API base URL and key as a config object rather than
+ * reading them from `process.env` themselves, so a test can point them at a mocked
+ * `fetch` with fixture values, and a transport can build one client per request.
+ *
+ * No `@/` alias and nothing Next-specific here: the stdio build compiles this file too.
+ */
+export function createApiClient({ apiUrl, apiKey }) {
+    async function apiGet(path, query = {}) {
+        const url = new URL(`${apiUrl}${path}`);
+        for (const [key, value] of Object.entries(query)) {
+            if (value !== undefined && value !== "")
+                url.searchParams.set(key, String(value));
+        }
+        let res;
+        try {
+            res = await fetch(url, {
+                headers: {
+                    Authorization: `Bearer ${apiKey}`,
+                    Accept: "application/json",
+                },
+            });
+        }
+        catch (err) {
+            return {
+                content: [{ type: "text", text: `Network error calling ${url.pathname}: ${String(err)}` }],
+                isError: true,
+            };
+        }
+        const body = await res.text();
+        if (!res.ok) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Request to ${url.pathname} failed (HTTP ${res.status}): ${body || res.statusText}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        // Pretty-print JSON when possible, otherwise return raw text.
+        let text = body;
+        try {
+            text = JSON.stringify(JSON.parse(body), null, 2);
+        }
+        catch {
+            // leave as-is
+        }
+        return { content: [{ type: "text", text }] };
+    }
+    /**
+     * Sends a JSON body to a mutating endpoint. Requires an API key with the
+     * `write` scope — a read-only key gets a 403 surfaced back to the model verbatim
+     * so it can tell the user their key can't write. `DELETE` sends no body.
+     */
+    async function apiSend(method, path, body) {
+        const url = new URL(`${apiUrl}${path}`);
+        let res;
+        try {
+            res = await fetch(url, {
+                method,
+                headers: {
+                    Authorization: `Bearer ${apiKey}`,
+                    Accept: "application/json",
+                    ...(body ? { "Content-Type": "application/json" } : {}),
+                },
+                ...(body ? { body: JSON.stringify(body) } : {}),
+            });
+        }
+        catch (err) {
+            return {
+                content: [{ type: "text", text: `Network error calling ${url.pathname}: ${String(err)}` }],
+                isError: true,
+            };
+        }
+        const text = await res.text();
+        if (!res.ok) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Request to ${url.pathname} failed (HTTP ${res.status}): ${text || res.statusText}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        let pretty = text;
+        try {
+            pretty = JSON.stringify(JSON.parse(text), null, 2);
+        }
+        catch {
+            // leave as-is
+        }
+        return { content: [{ type: "text", text: pretty }] };
+    }
+    return { apiGet, apiSend };
+}