@sebamomann/plants-mcp 3.0.0 → 3.1.0

package/CHANGELOG.md

@@ -3,6 +3,17 @@
 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**

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
 
-**81 tools** over your collection: 28 that read it, 35 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 35 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
@@ -177,7 +184,10 @@ region), keyed by the same field names `get_plant_type` uses — and its six sch
 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`).
+`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
 
@@ -218,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
@@ -533,6 +544,14 @@ The two edit tools take an **`entryId`, not a `plantId`** — get it from `list_
 |---|---|---|
 | `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
@@ -859,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 };
+}