@sebamomann/plants-mcp 0.1.0

package/README.md

@@ -0,0 +1,108 @@
+# plants-mcp
+
+[MCP](https://modelcontextprotocol.io) server for the **Sprig** plant app. It lets a Claude agent query
+your plant collection — plants, watering/fertilization events, the full care timeline, photos, health
+entries, the care schedule, and lookup catalogs — and, with a write-scoped key, record waterings,
+fertilizings, and health notes. It talks to the app's `/api/v1/*` REST API, authenticated with a
+**per-user API key**.
+
+Reads need only the `read` scope (every key has it). The write tools — `record_watering`,
+`record_fertilization`, `add_health_entry` — need a key with the `write` scope, chosen when you create
+the key. There are no destructive tools: nothing deletes plants, events, or history.
+
+## Setup
+
+1. **Generate an API key** in the app: **Account → API Keys → Generate**. Pick **Read-only** or
+   **Read & write** (write is needed for the logging tools). Copy it (it's shown once).
+2. **Install.** Published on npm, so no clone is needed — `npx` fetches it on demand:
+   ```sh
+   npx @sebamomann/plants-mcp
+   ```
+   To work on it locally instead, clone the repo and build:
+   ```sh
+   cd plants-mcp
+   npm install
+   npm run build
+   ```
+3. **Configure** via environment variables (see `.env.example`):
+   - `PLANT_API_URL` — base URL of the running app (`http://localhost:3000` or your deployed site).
+   - `PLANT_API_KEY` — the `sprig_live_…` key from step 1.
+
+## Register with Claude
+
+Add to your MCP client config (e.g. Claude Code / Claude Desktop). Example:
+
+```json
+{
+  "mcpServers": {
+    "plants": {
+      "command": "npx",
+      "args": ["-y", "@sebamomann/plants-mcp"],
+      "env": {
+        "PLANT_API_URL": "http://localhost:3000",
+        "PLANT_API_KEY": "sprig_live_..."
+      }
+    }
+  }
+}
+```
+
+To run a local checkout instead, point at the build output —
+`"command": "node", "args": ["/…/plants-mcp/dist/index.js"]` — or skip the build and use `tsx`:
+`"command": "npx", "args": ["tsx", "/…/plants-mcp/src/index.ts"]`.
+
+## Tools
+
+| Tool | Endpoint | Purpose |
+|---|---|---|
+| `whoami` | `GET /api/v1/me` | Identify the authenticated user |
+| `list_plants` | `GET /api/v1/plants` | List plants with filters (status, lifecycle, location, type, soil, fertilizer, search, pagination, sort) |
+| `get_plant` | `GET /api/v1/plants/:id` | Full detail for one plant |
+| `list_watering_events` | `GET /api/v1/plants/:id/watering-events` | Watering history |
+| `list_fertilization_events` | `GET /api/v1/plants/:id/fertilization-events` | Fertilization history |
+| `list_care_events` | `GET /api/v1/plants/:id/events` | Combined care timeline (typed by `kind`) |
+| `list_photos` | `GET /api/v1/plants/:id/photos` | Photo metadata |
+| `list_health_entries` | `GET /api/v1/plants/:id/health` | Health / AI-analysis entries |
+| `list_due_care` | `GET /api/v1/care/due` | What needs water/fertilizer now — overdue plus the given day, optional look-ahead window |
+| `list_overdue_care` | `GET /api/v1/care/overdue` | Only past-due work, most overdue first, with days late |
+| `get_care_calendar` | `GET /api/v1/care/calendar` | Day-by-day schedule over a range, plus an overdue group |
+| `list_care_recommendations` | `GET /api/v1/care/recommendations` | Detected care problems (cycle mismatch, chronic lateness, seasonal gaps, stale photos) |
+| `list_recent_activity` | `GET /api/v1/activity` | Collection-wide care activity over a date range, typed by `kind` — use instead of looping the per-plant event tools |
+| `list_locations` | `GET /api/v1/locations` | Location catalog |
+| `list_plant_types` | `GET /api/v1/plant-types` | Plant-type (species) catalog |
+| `list_soils` | `GET /api/v1/soils` | Soil catalog |
+| `list_fertilizers` | `GET /api/v1/fertilizers` | Fertilizer catalog |
+
+### Write tools (require the `write` scope)
+
+| Tool | Endpoint | Purpose |
+|---|---|---|
+| `record_watering` | `POST /api/v1/care/watering` | Log a watering for one or more plants (bulk); reservoir/hydro routed to refill/top-up |
+| `record_fertilization` | `POST /api/v1/care/fertilization` | Log a fertilization for one or more plants (bulk) |
+| `add_health_entry` | `POST /api/v1/plants/:id/health` | Add a manual observation or issue note to a plant |
+| `update_health_entry` | `PATCH /api/v1/health-entries/:id` | Edit an existing entry's kind, text, category, or severity |
+| `resolve_health_entry` | `PATCH /api/v1/health-entries/:id` | Mark an entry resolved, or reopen it |
+| `dismiss_care_recommendation` | `POST /api/v1/care/recommendations/dismiss` | Hide one recommendation occurrence, by `plantId` + `type` + `fingerprint` |
+
+Writes are **idempotent per day**: a plant already watered/fertilized on the target day is skipped and
+returned in a `skipped` list rather than logged twice, so a retried call never shifts the care schedule.
+Unknown plant ids come back in an `invalid` list. A read-only key calling a write tool gets HTTP 403.
+
+There are **no destructive tools**. Nothing here deletes a plant, an event, a photo, or a catalog entry;
+resolving and dismissing are both reversible, and retiring a plant is a status change. Deletion stays in
+the UI on purpose.
+
+The collection's **sales and trades are deliberately not exposed** — not as reads, not as writes. They
+involve a second user and are out of scope for an assistant acting on the owner's key.
+
+All results are scoped to the key's owner; another user's data returns 404 and a bad/missing/revoked key
+returns 401.
+
+The `care/*` tools return schedule state the server derives from the same helpers the app's own
+calendar uses — season, care mode, and snoozes are already applied. Prefer them over recomputing due
+dates from raw event lists. They cover `LIVING` plants only.
+
+## Security
+
+- The key is sent only to `PLANT_API_URL` as a bearer token. Keep it secret; treat it like a password.
+- Revoke a key any time from **Account → API Keys**; requests with it immediately start returning 401.

package/dist/index.js

@@ -0,0 +1,261 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+/**
+ * Read-only MCP server for the Sprig plant app.
+ *
+ * Every tool is a thin proxy over the app's `/api/v1/*` REST endpoints,
+ * authenticated with a per-user API key sent as `Authorization: Bearer <key>`.
+ * Tools forward their arguments as query params and return the API's JSON
+ * verbatim, so they stay correct even if the API response shape evolves.
+ */
+const API_URL = (process.env.PLANT_API_URL ?? "http://localhost:3000").replace(/\/+$/, "");
+const API_KEY = process.env.PLANT_API_KEY;
+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.
+ */
+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",
+                "Content-Type": "application/json",
+            },
+            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 server = new McpServer({ name: "plants-mcp", version: "0.1.0" });
+// --- Identity ---------------------------------------------------------------
+server.tool("whoami", "Return the authenticated user for the configured API key.", async () => apiGet("/api/v1/me"));
+// --- 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"])
+        .optional()
+        .describe("Filter by plant status."),
+    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."),
+    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)."),
+    sort: z.string().optional().describe("Sort key, e.g. 'name', 'createdAt', 'updatedAt'."),
+}, async (args) => apiGet("/api/v1/plants", args));
+server.tool("get_plant", "Get one plant with full detail: catalogs (type, location, soil, fertilizer), care config, and recent event summaries.", { id: z.number().int().describe("Plant id.") }, async ({ id }) => apiGet(`/api/v1/plants/${id}`));
+// --- Events connected to a plant -------------------------------------------
+const eventArgs = {
+    id: z.number().int().describe("Plant id."),
+    limit: z.number().int().min(1).max(500).optional().describe("Max results (pagination)."),
+    offset: z.number().int().min(0).optional().describe("Result offset (pagination)."),
+};
+server.tool("list_watering_events", "List watering events for a plant, most recent first.", eventArgs, async ({ id, ...q }) => apiGet(`/api/v1/plants/${id}/watering-events`, q));
+server.tool("list_fertilization_events", "List fertilization events for a plant, most recent first.", eventArgs, async ({ id, ...q }) => apiGet(`/api/v1/plants/${id}/fertilization-events`, q));
+server.tool("list_care_events", "List the combined care timeline for a plant (watering, fertilization, refill, hydro, potting, snoozes), each tagged with a kind, most recent first.", eventArgs, async ({ id, ...q }) => apiGet(`/api/v1/plants/${id}/events`, q));
+server.tool("list_photos", "List photo metadata for a plant (urls, takenAt), most recent first.", eventArgs, async ({ id, ...q }) => apiGet(`/api/v1/plants/${id}/photos`, q));
+server.tool("list_health_entries", "List health and AI-analysis entries for a plant, most recent first.", eventArgs, async ({ id, ...q }) => apiGet(`/api/v1/plants/${id}/health`, q));
+// --- Care schedule (calendar) ----------------------------------------------
+/**
+ * Derived schedule state, computed server-side from the same helpers the app's
+ * own calendar uses. Prefer these over reconstructing due dates from raw event
+ * lists: they account for season, care mode, and snoozes.
+ */
+const careArgs = {
+    date: z
+        .string()
+        .regex(/^\d{4}-\d{2}-\d{2}$/)
+        .optional()
+        .describe("Day to evaluate against, as YYYY-MM-DD. Defaults to today."),
+    season: z
+        .enum(["summer", "winter"])
+        .optional()
+        .describe("Override the season (Apr–Sep is summer). Defaults to the season of `date`."),
+    locationId: z.number().int().optional().describe("Only consider plants in this location."),
+};
+server.tool("list_due_care", "What needs water or fertilizer now: overdue work plus anything due on the given day. Use `windowDays` to look ahead. This is the right tool for 'what should I do today?'.", {
+    ...careArgs,
+    windowDays: z
+        .number()
+        .int()
+        .min(0)
+        .max(60)
+        .optional()
+        .describe("Also include work due within this many days after `date`. 0 (default) = that day only."),
+    includeOverdue: z
+        .boolean()
+        .optional()
+        .describe("Include already-overdue work (default true)."),
+}, async (args) => apiGet("/api/v1/care/due", { ...args, includeOverdue: args.includeOverdue?.toString() }));
+server.tool("list_overdue_care", "Only work whose due date has already passed, most overdue first, with how many days each is late. Use for 'what have I fallen behind on?'.", careArgs, async (args) => apiGet("/api/v1/care/overdue", args));
+server.tool("get_care_calendar", "Day-by-day care schedule over a date range, plus an overdue group. Each plant appears on its next due day only — this projects the current schedule rather than simulating future waterings.", {
+    ...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"));
+// --- 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'."),
+    until: z.string().optional().describe("Only events at or before this ISO date/timestamp."),
+    kinds: z
+        .array(z.enum(["watering", "fertilization", "refill", "hydro", "potting", "health", "photo"]))
+        .optional()
+        .describe("Restrict to these event kinds. Defaults to all of them."),
+    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(",") }));
+// --- Care logging (writes) --------------------------------------------------
+/**
+ * Mutating tools. These require an API key with the `write` scope; a read-only
+ * key returns HTTP 403. They are idempotent per day — a plant already
+ * watered/fertilized on the target day is skipped, not logged twice — and
+ * accept many plants at once, so prefer one bulk call over a loop.
+ */
+const optionalPlantDate = (label) => z
+    .string()
+    .regex(/^\d{4}-\d{2}-\d{2}/)
+    .optional()
+    .describe(`When it happened, ISO date (YYYY-MM-DD). Defaults to now. Cannot be in the future. ${label}`);
+server.tool("record_watering", "WRITE: log a watering for one or more plants. Reservoir/hydro plants are recorded as a refill/top-up automatically, and plants that fertilize with watering also get a fertilization logged. Plants already watered that day are skipped. Requires a write-scoped API key.", {
+    plantIds: z.array(z.number().int().positive()).min(1).max(200).describe("Plant ids to water."),
+    wateredAt: optionalPlantDate(""),
+}, async ({ plantIds, wateredAt }) => apiSend("POST", "/api/v1/care/watering", { plantIds, wateredAt }));
+server.tool("record_fertilization", "WRITE: log a fertilization for one or more plants. fertilizerId and fertilizerPercent default to each plant's own settings when omitted. Plants already fertilized that day are skipped. Requires a write-scoped API key.", {
+    plantIds: z.array(z.number().int().positive()).min(1).max(200).describe("Plant ids to fertilize."),
+    fertilizerId: z.number().int().positive().optional().describe("Override fertilizer; defaults to each plant's own."),
+    fertilizerPercent: z
+        .number()
+        .int()
+        .min(0)
+        .max(1000)
+        .optional()
+        .describe("Strength as a percentage of the base dose; defaults to each plant's own."),
+    fertilizedAt: optionalPlantDate(""),
+}, async (args) => apiSend("POST", "/api/v1/care/fertilization", { ...args }));
+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."),
+    kind: z.enum(["observation", "issue"]).describe("'observation' for a neutral note, 'issue' for a problem."),
+    text: z.string().min(1).max(1000).describe("The note text."),
+    category: z.string().max(80).optional().describe("Optional short label, e.g. 'pests', 'growth'."),
+    severity: z.enum(["low", "medium", "high"]).optional().describe("For issues: how serious."),
+}, async ({ plantId, kind, text, category, severity }) => apiSend("POST", `/api/v1/plants/${plantId}/health`, { kind, text, category, severity }));
+server.tool("update_health_entry", "WRITE: edit an existing health entry's content. Omitted fields keep their current value. Takes the entry id from list_health_entries, not a plant id. Requires a write-scoped API key.", {
+    entryId: z.number().int().positive().describe("Health entry id, from list_health_entries."),
+    kind: z.enum(["observation", "issue"]).optional().describe("Change the entry kind."),
+    text: z.string().min(1).max(1000).optional().describe("Replacement note text."),
+    category: z.string().max(80).optional().describe("Replacement short label, e.g. 'pests'."),
+    severity: z.enum(["low", "medium", "high"]).optional().describe("For issues: how serious."),
+}, async ({ entryId, ...body }) => apiSend("PATCH", `/api/v1/health-entries/${entryId}`, body));
+server.tool("resolve_health_entry", "WRITE: mark a health entry resolved (the issue is over), or reopen a resolved one by passing resolved=false. Reversible either way. Takes the entry id from list_health_entries. Requires a write-scoped API key.", {
+    entryId: z.number().int().positive().describe("Health entry id, from list_health_entries."),
+    resolved: z.boolean().default(true).describe("true to resolve, false to reopen."),
+}, async ({ entryId, resolved }) => apiSend("PATCH", `/api/v1/health-entries/${entryId}`, { resolved }));
+server.tool("dismiss_care_recommendation", "WRITE: hide one care recommendation, as the Improvements page does. Pass plantId, type, and fingerprint exactly as returned by list_care_recommendations — the fingerprint identifies this specific occurrence, so a later recurrence of the same problem still surfaces. Note 'wateringCycleMismatch' cannot be dismissed: it is a config contradiction, fixed by editing the plant. Requires a write-scoped API key.", {
+    plantId: z.number().int().positive().describe("Plant id the recommendation belongs to."),
+    type: z
+        .enum([
+        "wateringOftenLate",
+        "fertilizingOftenLate",
+        "noFertilizerThisSeason",
+        "recentlyRepottedAvoidFertilizer",
+        "noRecentPhoto",
+    ])
+        .describe("Recommendation type, from list_care_recommendations."),
+    fingerprint: z.string().min(1).describe("Occurrence fingerprint, from list_care_recommendations."),
+}, async (args) => apiSend("POST", "/api/v1/care/recommendations/dismiss", { ...args }));
+// --- 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"));
+server.tool("list_soils", "List the user's soils.", async () => apiGet("/api/v1/soils"));
+server.tool("list_fertilizers", "List the user's fertilizers.", async () => apiGet("/api/v1/fertilizers"));
+// --- Boot -------------------------------------------------------------------
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error(`[plants-mcp] connected. API base: ${API_URL}`);
+}
+main().catch((err) => {
+    console.error("[plants-mcp] fatal:", err);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@sebamomann/plants-mcp",
+  "version": "0.1.0",
+  "description": "Read-only MCP server for the Sprig plant app, authenticated with a per-user API key.",
+  "type": "module",
+  "license": "MIT",
+  "author": "sebamomann <github@sebamomann.de>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sebamomann/plants-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/sebamomann/plants-mcp/issues"
+  },
+  "homepage": "https://github.com/sebamomann/plants-mcp#readme",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "plants",
+    "sprig"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "plants-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2"
+  }
+}