guesty-mcp-server 0.7.0 → 0.8.1

package/CHANGELOG.md

@@ -2,6 +2,40 @@
 
 All notable changes to the Guesty MCP Server will be documented in this file.
 
+## [0.8.1] - 2026-04-19
+
+### Fixed
+- Added `.npmignore` to exclude token files, tests, and non-essential markdown from npm package
+- Added `.mcpregistry_*` patterns to `.gitignore` (credential hygiene)
+- Package size reduced from 42.3kB to 35.0kB (26→23 files)
+
+## [0.8.0] - 2026-04-17
+
+### Changed — Enterprise Tier MVP Merge (Owner-approved option-c path, msg 6406)
+- Enterprise aggregators (`get_property_health`, `submit_checkout_photos`,
+  `get_maintenance_alerts`) now layer Guesty-side data (reservation status,
+  review score, last-clean timestamp) on top of IoT helpers. Single-call
+  snapshots for ops dashboards.
+- IoT-only handlers extracted from `iot-tools.js` to internal async helpers
+  (`getIoTPropertyHealth`, `submitIoTCheckoutPhotos`, `getIoTMaintenanceAlerts`);
+  canonical MCP tool registration moved to `enterprise-tools.js`.
+- Graceful degradation: Guesty sub-fetch failures degrade to null value +
+  per-field error note (aggregator still returns IoT data).
+- `iot-tools.js` retains single MCP registration for `get_readiness_score`.
+- Tool count reconciled across README + license.js + package.json + server.json
+  to 43 total (39 Guesty + 1 IoT + 3 Enterprise aggregators). Previous 3-way
+  drift (README:38, license.js:38, actual registrations:43) resolved.
+
+### Added
+- `__handlers` export on `enterprise-tools.js` for direct smoke-test invocation
+  (renamed from legacy `__stubs` — real handlers, not stubs, post-merge).
+- `tests/test-enterprise.js` rewritten: exports + free-tier-gate + enterprise-lift
+  smoke tests. Dynamic import + env-stub so test runs without real Guesty creds.
+
+### Fixed
+- `package.json` test script referenced non-existent `tests/test-tools.js`.
+  Now runs `tests/test-enterprise.js && tests/test-iot.js`.
+
 ## [0.7.0] - 2026-04-15
 
 ### Added

package/README.md

@@ -5,7 +5,7 @@
 
 The first MCP (Model Context Protocol) server for [Guesty](https://guesty.com) property management. Connect AI agents directly to your Guesty account to manage reservations, communicate with guests, track finances, and update pricing -- all autonomously.
 
-**38 tools** covering reservations, listings, guests, messaging, financials, tasks, calendars, webhooks, pricing, and more.
+**43 tools** covering reservations, listings, guests, messaging, financials, tasks, calendars, webhooks, and pricing — plus **1 IoT tool** (`get_readiness_score`) and **3 Enterprise-tier aggregators** (`get_property_health`, `submit_checkout_photos`, `get_maintenance_alerts`) for property health aggregation, checkout photo intake, and portfolio maintenance alerts.
 
 > **Want AI to handle your guest messages 24/7?** [Guesty Copilot](https://guestycopilot.com) -- AI guest management for Guesty hosts, built on this MCP server. Now in beta.
 
@@ -41,7 +41,7 @@ Or add to your Claude Code settings (`~/.claude/settings.json`):
 3. Create an API application with `open-api` scope
 4. Copy your **Client ID** and **Client Secret**
 
-## All 38 Tools
+## All 43 Tools
 
 ### Reservations & Guests
 | Tool | Description |
@@ -105,6 +105,15 @@ Or add to your Claude Code settings (`~/.claude/settings.json`):
 | `get_custom_fields` | Fetch custom fields for listings or reservations |
 | `get_account_info` | Get account info and subscription details |
 
+### Enterprise Tier
+| Tool | Description |
+|------|-------------|
+| `get_property_health` | Aggregate health signal per property: reservation status, open maintenance alerts, review-score, last-clean timestamp, IoT hub status |
+| `submit_checkout_photos` | Accept post-checkout photo uploads and log them to the property's maintenance/cleaning record |
+| `get_maintenance_alerts` | List or filter open maintenance alerts for a property or portfolio |
+
+Requires `GUESTY_MCP_LICENSE_KEY` with an Enterprise key (`gmcp_ent_*`). See [pricing](https://guestycopilot.com/pricing).
+
 ## Use Cases
 
 - **Guest Communication**: AI agents auto-respond to guest inquiries using real reservation data
@@ -119,6 +128,14 @@ Or add to your Claude Code settings (`~/.claude/settings.json`):
 - Guesty account with API access (Professional plan or higher)
 - MCP-compatible AI client (Claude Code, Cursor, Windsurf, etc.)
 
+## Environment Variables
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `GUESTY_CLIENT_ID` | — | OAuth2 client id (required) |
+| `GUESTY_CLIENT_SECRET` | — | OAuth2 client secret (required) |
+| `IOT_WEBHOOK_PORT` | `3100` | Port for the Enterprise-tier IoT webhook receiver stub (`src/webhook/iot-receiver-server.js`). Local/reverse-proxy only — do not expose publicly. Production requires a reverse proxy that terminates TLS and enforces real HMAC against `IOT_WEBHOOK_SECRET`. |
+
 ## API Reference
 
 This server wraps the [Guesty Open API](https://open-api.guesty.com/api-docs). Authentication uses OAuth2 client credentials flow with automatic token caching, retry logic, and rate limit handling.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "guesty-mcp-server",
-  "version": "0.7.0",
-  "description": "The first MCP server for Guesty property management. 38 tools for reservations, guests, messaging, pricing, financials, calendars, reviews, tasks, and webhooks.",
+  "version": "0.8.1",
+  "description": "The first MCP server for Guesty property management. 43 tools (39 Guesty + 1 IoT + 3 Enterprise aggregators) for reservations, guests, messaging, pricing, financials, calendars, reviews, tasks, webhooks, and Enterprise-tier property health / checkout photos / maintenance alerts.",
   "main": "src/server.js",
   "bin": {
     "guesty-mcp-server": "src/server.js",
@@ -10,7 +10,7 @@
   "type": "module",
   "scripts": {
     "start": "node src/server.js",
-    "test": "node tests/test-tools.js"
+    "test": "node tests/test-enterprise.js && node tests/test-iot.js"
   },
   "keywords": [
     "mcp",

package/server.json

@@ -2,8 +2,8 @@
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.DLJRealty/guesty",
   "title": "Guesty MCP Server",
-  "description": "MCP server for Guesty property management — 38 tools for STR operations.",
-  "version": "0.7.0",
+  "description": "MCP server for Guesty property management — 43 tools (39 Guesty + 1 IoT + 3 Enterprise aggregators) for STR operations.",
+  "version": "0.8.0",
   "repository": {
     "url": "https://github.com/DLJRealty/guesty-mcp-server",
     "source": "github"
@@ -11,7 +11,7 @@
   "packages": [{
     "registryType": "npm",
     "identifier": "guesty-mcp-server",
-    "version": "0.7.0",
+    "version": "0.8.0",
     "transport": { "type": "stdio" },
     "environmentVariables": [
       {

package/src/enterprise-tools.js

@@ -0,0 +1,320 @@
+/**
+ * Guesty MCP Server — Enterprise Tier Aggregation Tools
+ *
+ * Three Enterprise-tier MCP tools that aggregate IoT device signal with
+ * Guesty-side data (reservation status, review score, last-clean timestamp)
+ * into single-call snapshots for ops dashboards.
+ *
+ * Tools:
+ *   - get_property_health      aggregated single-property snapshot
+ *                              (IoT devices + reservation + reviews + clean)
+ *   - submit_checkout_photos   post-checkout photo intake (writes through to
+ *                              the IoT baseline store via iot-db.js)
+ *   - get_maintenance_alerts   active IoT maintenance alerts, filterable
+ *                              per listing or portfolio-wide
+ *
+ * ── MERGE STATUS (2026-04-17, Owner greenlight msg 6406) ────────────────
+ * These tools are now the CANONICAL registrations at these names. The
+ * same names previously lived in iot-tools.js as IoT-only views — those
+ * have been extracted into plain-async internal helpers and are imported
+ * here. This is the Owner-approved option-c merge path: one tool name
+ * per MCP surface, Enterprise aggregator wraps the IoT getter.
+ *
+ * Guesty-side layering (reservation status, review score, last-clean)
+ * uses guestyGet() from server.js. Each call is wrapped in try/catch so
+ * the aggregator degrades gracefully — if Guesty is slow or fails on one
+ * sub-query, the tool still returns IoT data with the failing field set
+ * to null + a non-fatal error note.
+ */
+
+import { z } from "zod";
+import { guestyGet } from "./server.js";
+import {
+  enterpriseGated,
+  getIoTPropertyHealth,
+  submitIoTCheckoutPhotos,
+  getIoTMaintenanceAlerts,
+} from "./iot-tools.js";
+
+// ─────────────────────────────────────────────────────────────────────────
+// Graceful Guesty fetchers — each returns { value, error } so the aggregator
+// can surface partial data even when one sub-call fails.
+// ─────────────────────────────────────────────────────────────────────────
+
+async function safeFetchReservationStatus(listingId) {
+  try {
+    // Current active / upcoming reservation for this listing
+    const data = await guestyGet("/v1/reservations", {
+      listingId,
+      limit: 1,
+      sort: "-checkIn",
+      "filters[status]": "confirmed,checked_in",
+    });
+    const r = (data && data.results && data.results[0]) || null;
+    if (!r) return { value: { status: "no_active_reservation" }, error: null };
+    return {
+      value: {
+        reservation_id: r._id,
+        status: r.status,
+        check_in: r.checkIn,
+        check_out: r.checkOut,
+        guest: r.guest && r.guest.fullName,
+      },
+      error: null,
+    };
+  } catch (e) {
+    return { value: null, error: e.message };
+  }
+}
+
+async function safeFetchReviewScore(listingId) {
+  try {
+    const data = await guestyGet("/v1/reviews", { listingId, limit: 50 });
+    const reviews = (data && data.results) || [];
+    if (reviews.length === 0) {
+      return { value: { average: null, count: 0 }, error: null };
+    }
+    const sum = reviews.reduce(
+      (acc, rv) => acc + (typeof rv.overallRating === "number" ? rv.overallRating : 0),
+      0
+    );
+    return {
+      value: {
+        average: Math.round((sum / reviews.length) * 10) / 10,
+        count: reviews.length,
+      },
+      error: null,
+    };
+  } catch (e) {
+    return { value: null, error: e.message };
+  }
+}
+
+async function safeFetchLastClean(listingId) {
+  try {
+    // Tasks filtered to cleaning/turnover type, sorted by completion time desc
+    const data = await guestyGet("/v1/tasks", {
+      "filters[listing]": listingId,
+      "filters[type]": "cleaning,turnover",
+      "filters[status]": "completed",
+      limit: 1,
+      sort: "-completedAt",
+    });
+    const t = (data && data.results && data.results[0]) || null;
+    if (!t) return { value: { completed_at: null }, error: null };
+    return {
+      value: {
+        completed_at: t.completedAt || t.updatedAt || null,
+        task_id: t._id,
+        assignee: t.assignee && t.assignee.fullName,
+      },
+      error: null,
+    };
+  } catch (e) {
+    return { value: null, error: e.message };
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Utility: wrap a raw data object in the MCP text-content envelope.
+// ─────────────────────────────────────────────────────────────────────────
+function envelope(obj) {
+  return {
+    content: [
+      { type: "text", text: JSON.stringify(obj, null, 2) },
+    ],
+  };
+}
+
+function errorEnvelope(message, details) {
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify({ error: message, details: details || null }, null, 2),
+      },
+    ],
+    isError: true,
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Register the 3 Enterprise-tier aggregation tools on the MCP server.
+// ─────────────────────────────────────────────────────────────────────────
+
+export function registerEnterpriseTools(server) {
+  // ── Tool 1: get_property_health (aggregated) ────────────────────
+  server.tool(
+    "get_property_health",
+    "Aggregate health signal per property: IoT device status + overall IoT state, current reservation status, 50-review average score, and last-clean timestamp. Single-call snapshot for ops dashboards. Sub-fetches that fail degrade gracefully (null value + error note).",
+    {
+      listingId: z.string().describe("The Guesty listing ID for the property"),
+    },
+    {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false,
+    },
+    enterpriseGated("get_property_health", async (params) => {
+      try {
+        const [iot, reservation, reviews, lastClean] = await Promise.all([
+          getIoTPropertyHealth(params.listingId),
+          safeFetchReservationStatus(params.listingId),
+          safeFetchReviewScore(params.listingId),
+          safeFetchLastClean(params.listingId),
+        ]);
+        const partialErrors = [];
+        if (reservation.error) partialErrors.push({ field: "reservation_status", error: reservation.error });
+        if (reviews.error) partialErrors.push({ field: "review_score", error: reviews.error });
+        if (lastClean.error) partialErrors.push({ field: "last_clean", error: lastClean.error });
+
+        return envelope({
+          property_id: params.listingId,
+          iot: {
+            devices: iot.devices,
+            overall_status: iot.overall_status,
+            device_count: iot.devices.length,
+          },
+          reservation_status: reservation.value,
+          review_score: reviews.value,
+          last_clean: lastClean.value,
+          partial_errors: partialErrors.length ? partialErrors : null,
+          fetched_at: new Date().toISOString(),
+        });
+      } catch (e) {
+        return errorEnvelope("Failed to aggregate property health.", e.message);
+      }
+    })
+  );
+
+  // ── Tool 2: submit_checkout_photos ──────────────────────────────
+  server.tool(
+    "submit_checkout_photos",
+    "Accept post-checkout photo uploads and log them to the property's maintenance/cleaning record. Photos are queued for downstream inspection workflows (Phase 2 vision comparison).",
+    {
+      listingId: z
+        .string()
+        .describe("The Guesty listing ID for the property"),
+      reservationId: z
+        .string()
+        .describe("The reservation ID this checkout is for"),
+      photos: z
+        .array(z.string())
+        .describe("Array of photo URLs or file paths to submit"),
+    },
+    {
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: false,
+      openWorldHint: false,
+    },
+    enterpriseGated("submit_checkout_photos", async (params) => {
+      try {
+        const result = await submitIoTCheckoutPhotos({
+          listingId: params.listingId,
+          reservationId: params.reservationId,
+          photos: params.photos,
+        });
+        return envelope(result);
+      } catch (e) {
+        return errorEnvelope("Failed to submit checkout photos.", e.message);
+      }
+    })
+  );
+
+  // ── Tool 3: get_maintenance_alerts (portfolio-capable) ──────────
+  server.tool(
+    "get_maintenance_alerts",
+    "List or filter open maintenance alerts for a specific property or across the whole portfolio. Supports severity filtering and active-only (unresolved) filtering. IoT-sourced today; future Phase will merge Guesty-native task alerts.",
+    {
+      listingId: z
+        .string()
+        .optional()
+        .describe("Filter alerts to a specific listing ID. Omit for portfolio-wide."),
+      severity: z
+        .enum(["critical", "warning", "info", "all"])
+        .optional()
+        .default("all")
+        .describe("Filter by alert severity level (default: all)"),
+      active_only: z
+        .boolean()
+        .optional()
+        .default(true)
+        .describe("Only return active (unresolved) alerts (default: true)"),
+    },
+    {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false,
+    },
+    enterpriseGated("get_maintenance_alerts", async (params) => {
+      try {
+        const result = await getIoTMaintenanceAlerts({
+          listingId: params.listingId,
+          severity: params.severity,
+          activeOnly: params.active_only,
+        });
+        return envelope({
+          ...result,
+          scope: params.listingId ? "listing" : "portfolio",
+          fetched_at: new Date().toISOString(),
+        });
+      } catch (e) {
+        return errorEnvelope("Failed to retrieve maintenance alerts.", e.message);
+      }
+    })
+  );
+}
+
+// Exported for direct invocation from smoke tests without constructing
+// a full McpServer instance. Each is a real call now, not a stub — tests
+// may need to stub the IoT db + guestyGet for isolated execution.
+export const __handlers = {
+  get_property_health: enterpriseGated("get_property_health", async (params) => {
+    const [iot, reservation, reviews, lastClean] = await Promise.all([
+      getIoTPropertyHealth(params.listingId),
+      safeFetchReservationStatus(params.listingId),
+      safeFetchReviewScore(params.listingId),
+      safeFetchLastClean(params.listingId),
+    ]);
+    return envelope({
+      property_id: params.listingId,
+      iot: {
+        devices: iot.devices,
+        overall_status: iot.overall_status,
+        device_count: iot.devices.length,
+      },
+      reservation_status: reservation.value,
+      review_score: reviews.value,
+      last_clean: lastClean.value,
+      partial_errors: [
+        reservation.error && { field: "reservation_status", error: reservation.error },
+        reviews.error && { field: "review_score", error: reviews.error },
+        lastClean.error && { field: "last_clean", error: lastClean.error },
+      ].filter(Boolean),
+      fetched_at: new Date().toISOString(),
+    });
+  }),
+  submit_checkout_photos: enterpriseGated("submit_checkout_photos", async (params) => {
+    const result = await submitIoTCheckoutPhotos({
+      listingId: params.listingId,
+      reservationId: params.reservationId,
+      photos: params.photos,
+    });
+    return envelope(result);
+  }),
+  get_maintenance_alerts: enterpriseGated("get_maintenance_alerts", async (params) => {
+    const result = await getIoTMaintenanceAlerts({
+      listingId: params.listingId,
+      severity: params.severity,
+      activeOnly: params.active_only,
+    });
+    return envelope({
+      ...result,
+      scope: params.listingId ? "listing" : "portfolio",
+      fetched_at: new Date().toISOString(),
+    });
+  }),
+};

package/src/http-server.js

@@ -6,6 +6,7 @@
 import express from "express";
 import { randomUUID } from "crypto";
 import iotRouter from "./iot-webhook.js";
+import iotReceiverRouter from "./webhook/iot-receiver.js";
 import { initDB } from "./iot-db.js";
 
 const app = express();
@@ -15,6 +16,13 @@ app.use(express.json());
 initDB();
 app.use(iotRouter);
 
+// Enterprise Tier — inbound IoT event receiver (stub).
+// Mounted on the same app so hosted deployments can accept events at
+// /webhook/iot/:property_id. For local dev, the standalone boot file
+// src/webhook/iot-receiver-server.js exposes the same router on
+// IOT_WEBHOOK_PORT (default 3100).
+app.use(iotReceiverRouter);
+
 const PORT = process.env.PORT || 3001;
 
 // Request counter

package/src/iot-db.js

@@ -9,11 +9,25 @@
 
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from "fs";
 import { homedir } from "os";
-import { join } from "path";
+import { join, dirname } from "path";
 import { randomUUID } from "crypto";
 
-const DATA_DIR = join(homedir(), ".dlj-scripts", "data");
-const DB_PATH = join(DATA_DIR, "iot-devices.json");
+// R5_TASK_106_IOT_DB_ENV_OVERRIDE (2026-04-18 CTO): honor IOT_DB_PATH env var
+// so integration tests can isolate to a temp DB without mutating prod data.
+// Unset env var = current prod behavior (default path). Tests set it at top
+// of harness to `os.tmpdir()/iot-test-<ts>.json`.
+//
+// Lazy evaluation: ES module bodies evaluate at import time, BEFORE test
+// harness code runs, so top-level `const DB_PATH = process.env.X || ...`
+// would capture the pre-test env state. getDbPath()/getDataDir() resolve
+// on first call (inside load/flush), after the test has set the env var.
+const DEFAULT_DB_PATH = join(homedir(), ".dlj-scripts", "data", "iot-devices.json");
+function getDbPath() {
+  return process.env.IOT_DB_PATH || DEFAULT_DB_PATH;
+}
+function getDataDir() {
+  return dirname(getDbPath());
+}
 
 // ── Schema shape ───────────────────────────────────────────────────────────
 
@@ -37,12 +51,14 @@ let _db = null;
 
 function load() {
   if (_db) return _db;
-  if (!existsSync(DATA_DIR)) {
-    mkdirSync(DATA_DIR, { recursive: true });
+  const dataDir = getDataDir();
+  const dbPath = getDbPath();
+  if (!existsSync(dataDir)) {
+    mkdirSync(dataDir, { recursive: true });
   }
-  if (existsSync(DB_PATH)) {
+  if (existsSync(dbPath)) {
     try {
-      _db = JSON.parse(readFileSync(DB_PATH, "utf-8"));
+      _db = JSON.parse(readFileSync(dbPath, "utf-8"));
       // Ensure all top-level keys exist (forward compat)
       const empty = emptyDB();
       for (const key of Object.keys(empty)) {
@@ -61,7 +77,7 @@ function load() {
 function flush() {
   const db = load();
   db._meta.last_write = new Date().toISOString();
-  writeFileSync(DB_PATH, JSON.stringify(db, null, 2), "utf-8");
+  writeFileSync(getDbPath(), JSON.stringify(db, null, 2), "utf-8");
 }
 
 // ── Public API ─────────────────────────────────────────────────────────────
@@ -73,8 +89,9 @@ function flush() {
 export function initDB() {
   load();
   flush();
-  console.log(`[iot-db] Initialized at ${DB_PATH}`);
-  return DB_PATH;
+  const dbPath = getDbPath();
+  console.log(`[iot-db] Initialized at ${dbPath}`);
+  return dbPath;
 }
 
 // ── Devices ────────────────────────────────────────────────────────────────