@sebamomann/plants-mcp 2.5.0 → 2.5.1

package/CHANGELOG.md

@@ -3,6 +3,16 @@
 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.
 
+## 2.5.1 — 2026-09-20
+
+**Richer admin dashboard status.** Tool count unchanged (76 overall). A **patch** bump — the
+`admin_get_dashboard_status` response gains four optional groups, nothing renamed or removed:
+
+- `growth`, `community`, `trade`, `content` — accounts by status and care-active users, community
+  activity per week and open reports with age, aggregate deal/offer counts (never money or parties),
+  and photo/plant/analysis/notification totals. Each is independently `{ available: false }` when
+  its reads failed. See `docs/mcp-server.md`'s "Admin dashboard status".
+
 ## 2.5.0 — 2026-09-16
 
 **Past problem diagnoses.** 76 tools registered overall (27 read, 31 write, 18 admin). A **minor**

package/README.md

@@ -10,7 +10,7 @@ just ask:
 
 ## Quick start
 
-**1. Get an API key.** In Sprig: **Account → API keys → Generate**. It is shown once — copy it
+**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
 access level later without re-issuing it.
 
@@ -46,7 +46,7 @@ Requires **Node.js 20 or newer**. Nothing to install by hand: `npx` fetches the
 time your client starts the server.
 
 > 💡 The app has this guide built in, with your key and server address already filled in:
-> **Account → API keys → How to connect an assistant**.
+> **Account → Settings → API keys → How to connect an assistant**.
 
 ## What is Sprig?
 
@@ -580,7 +580,7 @@ registers these tools when the response's `scopes` includes `admin`.
 | `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_get_dashboard_status` | `GET /api/v1/admin/dashboard` | none — review-queue counts + oldest-item age, catalog health, weekly activity, and operational facts (counts only, never a secret) |
+| `admin_get_dashboard_status` | `GET /api/v1/admin/dashboard` | none — review-queue counts + oldest-item age, catalog health, weekly activity, operational facts (counts only, never a secret), plus optional growth/community/trade/content aggregates (no money, no user details) |
 
 `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
@@ -597,7 +597,7 @@ changed field `stale` when the type's value has moved on since the proposal was
 check a human reviewer's accept button re-runs, so an assistant sees the same warning.
 
 `admin_get_dashboard_status` is the one admin tool that isn't about the catalog — it returns the same
-aggregate the app's own `/admin` dashboard shows, for "what needs me, and is anything wrong" in one
+aggregate the app's own `/admin` dashboard shows (including the growth, community, trade and content blocks, each optional and individually `{ available: false }` if its read failed; trade is aggregate counts only, never a price or a party), for "what needs me, and is anything wrong" in one
 call instead of several. Some values are legitimately absent rather than zero: a review-queue item's
 `age` comes back `{ kind: "unknown" }` when its type has no creation timestamp to measure from
 (pending user registrations), and `operations.appliedMigrationsCount` can be `null` when that guarded
@@ -768,6 +768,6 @@ spec for the tool surface is `docs/mcp-server.md` at the repo root.
   variable, so it never lands in the tool arguments a model can see or echo. Treat it like a
   password.
 - Prefer a **read-only key** unless you specifically want an assistant logging care.
-- Revoke a key any time from **Account → API keys**; requests with it start returning 401
+- Revoke a key any time from **Account → Settings → API keys**; requests with it start returning 401
   immediately.
 - All data is scoped to the key's owner. Another user's data returns 404.

package/dist/apiClient.js

@@ -0,0 +1,103 @@
+/**
+ * The shared HTTP proxy every tool in `index.ts` is built on: `apiGet` for reads,
+ * `apiSend` for writes. Pulled into its own module so it can be unit-tested in
+ * isolation — `index.ts` has top-level side effects (env var validation that calls
+ * `process.exit`, `McpServer` construction, ~76 tool registrations, stdio connect)
+ * that make it unsafe to import directly in a test.
+ *
+ * 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 instead of needing real environment variables.
+ */
+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 };
+}

package/dist/index.js

@@ -3,6 +3,7 @@ import { readFileSync } from "node:fs";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
+import { createApiClient } from "./apiClient.js";
 /**
  * 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
@@ -31,95 +32,7 @@ if (!API_KEY) {
     console.error("[plants-mcp] Missing PLANT_API_KEY environment variable.");
     process.exit(1);
 }
-async function apiGet(path, query = {}) {
-    const url = new URL(`${API_URL}${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 ${API_KEY}`,
-                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(`${API_URL}${path}`);
-    let res;
-    try {
-        res = await fetch(url, {
-            method,
-            headers: {
-                Authorization: `Bearer ${API_KEY}`,
-                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 }] };
-}
+const { apiGet, apiSend } = createApiClient({ apiUrl: API_URL, apiKey: API_KEY });
 const server = new McpServer({ name: "plants-mcp", version: VERSION });
 // --- Identity ---------------------------------------------------------------
 server.tool("whoami", "Return the authenticated user for the configured API key.", async () => apiGet("/api/v1/me"));
@@ -613,7 +526,7 @@ function registerAdminTools() {
         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", {}));
-    server.tool("admin_get_dashboard_status", "ADMIN: the instance's operational status in one call — the same aggregate the app's own /admin dashboard shows. Four groups: reviewQueue (pending proposals, pending submitted images, open duplicate candidates, unverified types, and pending user registrations — each with its count and the age in days of its oldest item), catalogHealth (verified/unverified split, types with no care values at all, orphan cultivars, types with no plants, low-completeness types, and plants still unidentified), activity (new plants, care events logged, and contributions submitted/decided, per trailing week over the last several weeks), and operations (push-enabled users, pending email verifications, active API keys, and the applied migration count — counts only, never a secret, token, key or hash). No arguments; always reads the whole instance. Some values are legitimately absent rather than zero: a queue's age comes back as 'unknown' when its item type has no creation timestamp to measure from (pending user registrations have no such column), and the applied-migration count can be null when that guarded read failed — neither is a fabricated number. Read-only; nothing here writes. Requires an admin-scoped API key.", async () => apiGet("/api/v1/admin/dashboard"));
+    server.tool("admin_get_dashboard_status", "ADMIN: the instance's operational status in one call — the same aggregate the app's own /admin dashboard shows. Four groups: reviewQueue (pending proposals, pending submitted images, open duplicate candidates, unverified types, and pending user registrations — each with its count and the age in days of its oldest item), catalogHealth (verified/unverified split, types with no care values at all, orphan cultivars, types with no plants, low-completeness types, and plants still unidentified), activity (new plants, care events logged, and contributions submitted/decided, per trailing week over the last several weeks), and operations (push-enabled users, pending email verifications, active API keys, and the applied migration count — counts only, never a secret, token, key or hash). Four more optional groups follow, each independently `{ available: false }` when its reads failed: growth (accounts by status, care-active users over 7/30 days, active users with no plant, users with push or an API key — sign-ups per week are not tracked), community (posts/comments/reactions per week, open reports with age, muted users, follows, active share links), trade (aggregate deal and offer counts by status, sold vs gifted vs traded, wishlist size — never prices, money or parties), and content (photos and 30-day growth, living vs archived plants, plant analyses, AI plausibility checks, notifications sent vs read over 30 days). No arguments; always reads the whole instance. Some values are legitimately absent rather than zero: a queue's age comes back as 'unknown' when its item type has no creation timestamp to measure from (pending user registrations have no such column), and the applied-migration count can be null when that guarded read failed — neither is a fabricated number. Read-only; nothing here writes. Requires an admin-scoped API key.", async () => apiGet("/api/v1/admin/dashboard"));
 }
 /**
  * Calls `/api/v1/me` once at startup to decide whether this key carries the

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sebamomann/plants-mcp",
-  "version": "2.5.0",
-  "description": "MCP server for the Sprig plant app: 76 tools to read a plant collection, browse the shared global plant type catalog, log care (watering, fertilizing, repotting, refills, hydro events), edit a plant's identity/care/lifecycle status, add, propagate or merge plants, snooze a due date, manage a wishlist and notifications, watch a plant type for changes, check vacation status, read past problem diagnoses, create a location/soil/fertilizer/pot, and contribute a new species to the catalog. Read-only by default; writes need a write-scoped API key. Two tools can delete a watering/fertilization event; nothing else deletes collection history. 18 more tools read, edit, merge and review the shared global plant type catalog and the instance's operational status for an admin-scoped key.",
+  "version": "2.5.1",
+  "description": "MCP server for the Sprig plant app: 76 tools to read a plant collection, browse the shared global plant type catalog, log care (watering, fertilizing, repotting, refills, hydro events), edit a plant's identity/care/lifecycle status, add, propagate or merge plants, snooze a due date, manage a wishlist and notifications, watch a plant type for changes, check vacation status, read past problem diagnoses, create a location/soil/fertilizer/pot, and contribute a new species to the catalog. Read-only by default; writes need a write-scoped API key. Two tools can delete a watering/fertilization event; nothing else deletes collection history. 18 more tools read, edit, merge and review the shared global plant type catalog and the instance's operational status (queues, catalog health, activity, growth, community, trade and content aggregates) for an admin-scoped key.",
   "type": "module",
   "license": "MIT",
   "author": "sebamomann <github@sebamomann.de>",
@@ -44,6 +44,8 @@
     "dev": "tsx src/index.ts",
     "typecheck": "tsc --noEmit",
     "check:docs": "node scripts/check-tool-docs.mjs",
+    "test": "vitest run",
+    "test:watch": "vitest",
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
@@ -52,6 +54,7 @@
   },
   "devDependencies": {
     "@types/node": "^26.1.1",
-    "typescript": "^6.0.3"
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10"
   }
 }