guesty-mcp-server 0.7.0 → 0.8.1

package/src/iot-tools.js

@@ -1,20 +1,30 @@
 /**
- * Guesty MCP Server — IoT / Property Health Monitoring Tools
+ * Guesty MCP Server — IoT / Property Health (Internal Helpers + 1 MCP Tool)
  *
- * Enterprise-tier gated tools for IoT device monitoring,
- * checkout photo submission, maintenance alerts, and
- * physical readiness scoring.
- *
- * Phase 1: Core data collection and scoring.
+ * Phase 1: Core data collection + readiness scoring.
  * Phase 2: Vision-based photo comparison (planned).
+ *
+ * ── MERGE NOTE (2026-04-17, per Owner greenlight msg 6406) ─────────────
+ * The three tools `get_property_health`, `submit_checkout_photos`,
+ * `get_maintenance_alerts` that previously lived HERE as IoT-only MCP tools
+ * have been EXTRACTED into plain-async internal helpers. Their canonical
+ * MCP-tool registration has MOVED to `enterprise-tools.js`, where each one
+ * becomes an Enterprise aggregator that calls these helpers AND layers in
+ * Guesty-side data (reservation status, review score, last-clean timestamp).
+ *
+ * Only one tool — `get_readiness_score` — is registered directly from here.
+ * It is Physical-Readiness only (sensor + photo signal) and has no Guesty
+ * aggregation need.
+ *
+ * All three helpers RETURN raw data objects (not MCP content envelopes) and
+ * THROW on error. Enterprise aggregators handle envelope + error shaping.
  */
 
 import { z } from "zod";
-import { getTier, gatedHandler } from "./license.js";
+import { getTier } from "./license.js";
 import {
   getLatestReadings,
   getAlerts,
-  saveBaseline,
   getBaseline,
   savePhotos,
 } from "./iot-db.js";
@@ -22,8 +32,11 @@ import {
 /**
  * Enterprise-tier gate. Returns an error response if the current
  * license is not enterprise. Wraps the inner handler otherwise.
+ *
+ * Exported so enterprise-tools.js can reuse the same gate without
+ * duplicating the string copy.
  */
-function enterpriseGated(toolName, handler) {
+export function enterpriseGated(toolName, handler) {
   return async (params) => {
     const tier = getTier();
     if (tier !== "enterprise") {
@@ -34,7 +47,7 @@ function enterpriseGated(toolName, handler) {
             text:
               `This tool (${toolName}) requires an Enterprise license. ` +
               `Your current tier is "${tier}". ` +
-              "IoT monitoring, property health, and readiness scoring are Enterprise-only features. " +
+              "IoT monitoring, property health aggregation, and readiness scoring are Enterprise-only features. " +
               "Upgrade at https://guestycopilot.com/pricing -- " +
               "Set GUESTY_MCP_LICENSE_KEY with an Enterprise key (gmcp_ent_*) to unlock.",
           },
@@ -52,7 +65,7 @@ function enterpriseGated(toolName, handler) {
  *   - "warning"  if ANY device has a warning alert
  *   - "healthy"  otherwise
  */
-function deriveOverallStatus(devices) {
+export function deriveOverallStatus(devices) {
   let status = "healthy";
   for (const d of devices) {
     if (d.alert_level === "critical") return "critical";
@@ -61,242 +74,96 @@ function deriveOverallStatus(devices) {
   return status;
 }
 
+// ─────────────────────────────────────────────────────────────────────────
+// INTERNAL HELPERS (exported for enterprise-tools.js aggregators)
+// Return raw data objects. Throw on error. No MCP envelope wrapping.
+// ─────────────────────────────────────────────────────────────────────────
+
 /**
- * Register all 4 IoT / Property Health tools on the given MCP server.
- *
- * @param {import("@modelcontextprotocol/sdk/server/mcp.js").McpServer} server
+ * Fetch IoT device health snapshot for a single property.
+ * @param {string} listingId Guesty listing ID
+ * @returns {Promise<{property_id: string, devices: Array, overall_status: string}>}
  */
-export function registerIoTTools(server) {
-  // ── Tool 1: get_property_health ─────────────────────────────────
-  server.tool(
-    "get_property_health",
-    "Get the current health status of all IoT devices at a property. Returns latest readings for every device (temperature, humidity, leak, lock, etc.) and an overall property status.",
-    {
-      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 readings = await getLatestReadings(params.listingId);
-        const devices = (readings || []).map((r) => ({
-          device_id: r.device_id,
-          type: r.type,
-          location: r.location,
-          last_reading: r.last_reading,
-          last_seen: r.last_seen,
-          alert_level: r.alert_level || null,
-        }));
-
-        const overallStatus = deriveOverallStatus(devices);
-
-        return {
-          content: [
-            {
-              type: "text",
-              text: JSON.stringify(
-                {
-                  property_id: params.listingId,
-                  devices,
-                  overall_status: overallStatus,
-                },
-                null,
-                2
-              ),
-            },
-          ],
-        };
-      } catch (e) {
-        return {
-          content: [
-            {
-              type: "text",
-              text: JSON.stringify(
-                {
-                  error: "Failed to retrieve property health data.",
-                  details: e.message,
-                },
-                null,
-                2
-              ),
-            },
-          ],
-          isError: true,
-        };
-      }
-    })
-  );
-
-  // ── Tool 2: submit_checkout_photos ──────────────────────────────
-  server.tool(
-    "submit_checkout_photos",
-    "Submit post-checkout photos for a property. Stores photo URLs/paths with reservation metadata for later comparison against baseline images. (Vision analysis is Phase 2.)",
-    {
-      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 {
-        if (!params.photos || params.photos.length === 0) {
-          return {
-            content: [
-              {
-                type: "text",
-                text: JSON.stringify(
-                  { error: "No photos provided. Include at least one photo URL or path." },
-                  null,
-                  2
-                ),
-              },
-            ],
-            isError: true,
-          };
-        }
-
-        const result = await savePhotos({
-          listingId: params.listingId,
-          reservationId: params.reservationId,
-          photos: params.photos,
-          timestamp: new Date().toISOString(),
-        });
-
-        return {
-          content: [
-            {
-              type: "text",
-              text: JSON.stringify(
-                {
-                  submission_id: result.submission_id,
-                  photo_count: params.photos.length,
-                  status: "received",
-                  message: "Photos queued for analysis",
-                },
-                null,
-                2
-              ),
-            },
-          ],
-        };
-      } catch (e) {
-        return {
-          content: [
-            {
-              type: "text",
-              text: JSON.stringify(
-                {
-                  error: "Failed to submit checkout photos.",
-                  details: e.message,
-                },
-                null,
-                2
-              ),
-            },
-          ],
-          isError: true,
-        };
-      }
-    })
-  );
+export async function getIoTPropertyHealth(listingId) {
+  const readings = await getLatestReadings(listingId);
+  const devices = (readings || []).map((r) => ({
+    device_id: r.device_id,
+    type: r.type,
+    location: r.location,
+    last_reading: r.last_reading,
+    last_seen: r.last_seen,
+    alert_level: r.alert_level || null,
+  }));
+  return {
+    property_id: listingId,
+    devices,
+    overall_status: deriveOverallStatus(devices),
+  };
+}
 
-  // ── Tool 3: get_maintenance_alerts ──────────────────────────────
-  server.tool(
-    "get_maintenance_alerts",
-    "Get active maintenance alerts from IoT devices. Filter by property, severity, or active-only status. Returns alerts with device info, severity, and timestamps.",
-    {
-      listingId: z
-        .string()
-        .optional()
-        .describe("Filter alerts to a specific listing ID. Omit for all properties."),
-      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 filters = {
-          listingId: params.listingId || null,
-          severity: params.severity === "all" ? null : params.severity,
-          activeOnly: params.active_only,
-        };
+/**
+ * Save submitted post-checkout photos for a property+reservation.
+ * @param {{listingId: string, reservationId: string, photos: string[]}} args
+ * @returns {Promise<{submission_id: string, photo_count: number, status: string, message: string}>}
+ */
+export async function submitIoTCheckoutPhotos({ listingId, reservationId, photos }) {
+  if (!photos || photos.length === 0) {
+    throw new Error("No photos provided. Include at least one photo URL or path.");
+  }
+  const result = await savePhotos({
+    listingId,
+    reservationId,
+    photos,
+    timestamp: new Date().toISOString(),
+  });
+  return {
+    submission_id: result.submission_id,
+    photo_count: photos.length,
+    status: "received",
+    message: "Photos queued for analysis",
+  };
+}
 
-        const alertData = await getAlerts(filters);
-        const alerts = (alertData || []).map((a) => ({
-          id: a.id,
-          device_id: a.device_id,
-          property_id: a.property_id,
-          alert_type: a.alert_type,
-          severity: a.severity,
-          message: a.message,
-          created_at: a.created_at,
-        }));
+/**
+ * Fetch IoT maintenance alerts, optionally filtered by listing / severity / active-only.
+ * @param {{listingId?: string, severity?: string, activeOnly?: boolean}} [filters]
+ * @returns {Promise<{alerts: Array, total_count: number}>}
+ */
+export async function getIoTMaintenanceAlerts(filters = {}) {
+  const dbFilters = {
+    listingId: filters.listingId || null,
+    severity:
+      !filters.severity || filters.severity === "all"
+        ? null
+        : filters.severity,
+    activeOnly: filters.activeOnly !== false, // default true
+  };
+  const alertData = await getAlerts(dbFilters);
+  const alerts = (alertData || []).map((a) => ({
+    id: a.id,
+    device_id: a.device_id,
+    property_id: a.property_id,
+    alert_type: a.alert_type,
+    severity: a.severity,
+    message: a.message,
+    created_at: a.created_at,
+  }));
+  return { alerts, total_count: alerts.length };
+}
 
-        return {
-          content: [
-            {
-              type: "text",
-              text: JSON.stringify(
-                {
-                  alerts,
-                  total_count: alerts.length,
-                },
-                null,
-                2
-              ),
-            },
-          ],
-        };
-      } catch (e) {
-        return {
-          content: [
-            {
-              type: "text",
-              text: JSON.stringify(
-                {
-                  error: "Failed to retrieve maintenance alerts.",
-                  details: e.message,
-                },
-                null,
-                2
-              ),
-            },
-          ],
-          isError: true,
-        };
-      }
-    })
-  );
+// ─────────────────────────────────────────────────────────────────────────
+// MCP TOOL REGISTRATION (only 1 tool — get_readiness_score)
+// The other 3 tools live in enterprise-tools.js post-merge.
+// ─────────────────────────────────────────────────────────────────────────
 
-  // ── Tool 4: get_readiness_score ─────────────────────────────────
+/**
+ * Register the Physical Readiness Score tool on the given MCP server.
+ * Enterprise-gated — requires Enterprise license key.
+ *
+ * @param {import("@modelcontextprotocol/sdk/server/mcp.js").McpServer} server
+ */
+export function registerIoTTools(server) {
+  // ── Tool: get_readiness_score ───────────────────────────────────
   server.tool(
     "get_readiness_score",
     "Calculate a 0-100 Physical Readiness Score for a property before guest check-in. Evaluates temperature, leak detection, door lock, humidity, critical alerts, and baseline photos.",

package/src/license.js

@@ -84,7 +84,10 @@ function isToolAllowed(toolName) {
 
 function getTierInfo() {
   const tier = getTier();
-  const totalTools = 38;
+  // 39 Guesty core tools + 1 IoT (get_readiness_score) + 3 Enterprise aggregators
+  // (get_property_health, submit_checkout_photos, get_maintenance_alerts) = 43.
+  // Updated 2026-04-17 for Enterprise Tier MVP merge (Owner msg 6406).
+  const totalTools = 43;
   return {
     tier,
     hasKey: !!process.env.GUESTY_MCP_LICENSE_KEY,
@@ -101,7 +104,7 @@ function gatedHandler(toolName, handler) {
                   "Free tier includes " + FREE_TOOLS.length + " operations and data tools. " +
                   "Guest messaging, review responses, and write operations require Pro+. " +
                   "Upgrade at https://guestycopilot.com/pricing -- " +
-                  "Set GUESTY_MCP_LICENSE_KEY env var to unlock all 38 tools.";
+                  "Set GUESTY_MCP_LICENSE_KEY env var to unlock all 43 tools.";
       return {
         content: [{ type: "text", text: msg }],
         isError: true,

package/src/server.js

@@ -4,6 +4,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { z } from "zod";
 import { getTier, getTierInfo, gatedHandler, FREE_TOOLS } from './license.js';
 import { registerIoTTools } from './iot-tools.js';
+import { registerEnterpriseTools } from './enterprise-tools.js';
 import { initDB } from './iot-db.js';
 
 // Guesty API Configuration
@@ -41,7 +42,7 @@ async function getToken() {
   return cachedToken;
 }
 
-async function guestyGet(path, params = {}, retries = 2) {
+export async function guestyGet(path, params = {}, retries = 2) {
   const token = await getToken();
   const url = new URL(`${GUESTY_API_BASE}${path}`);
   Object.entries(params).forEach(([k, v]) => {
@@ -1415,9 +1416,15 @@ server.tool(
   }
 );
 
-// Initialize IoT database and register IoT/Property Health tools (Enterprise tier)
+// Initialize IoT database and register Enterprise-tier tools.
+// After the 2026-04-17 MERGE:
+//   - iot-tools.js registers `get_readiness_score` only (1 tool).
+//   - enterprise-tools.js registers the 3 aggregator tools
+//     (get_property_health, submit_checkout_photos, get_maintenance_alerts)
+//     which wrap the extracted IoT helpers + Guesty-layer data.
 initDB();
 registerIoTTools(server);
+registerEnterpriseTools(server);
 
 // Start server
 const transport = new StdioServerTransport();

package/src/webhook/iot-receiver-server.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+/**
+ * Standalone boot for the IoT webhook receiver (Enterprise Tier stub).
+ *
+ * Runs the iot-receiver router on its own Express app, listening on
+ * IOT_WEBHOOK_PORT (default 3100). Use this for local dev / smoke tests
+ * when you do not want to start the full MCP HTTP server.
+ *
+ *   node src/webhook/iot-receiver-server.js
+ *   IOT_WEBHOOK_PORT=4100 node src/webhook/iot-receiver-server.js
+ *
+ * Production: run behind a reverse proxy that terminates TLS and enforces
+ * a real HMAC check against IOT_WEBHOOK_SECRET. Do NOT expose this port
+ * directly on the public internet.
+ */
+
+import express from "express";
+import iotReceiverRouter from "./iot-receiver.js";
+
+const PORT = parseInt(process.env.IOT_WEBHOOK_PORT || "3100", 10);
+
+const app = express();
+app.use(express.json({ limit: "256kb" }));
+app.use(iotReceiverRouter);
+
+app.listen(PORT, "127.0.0.1", () => {
+  console.log(`[iot-receiver] stub listening on http://127.0.0.1:${PORT}`);
+  console.log(`[iot-receiver] POST /webhook/iot/:property_id`);
+  console.log(`[iot-receiver] GET  /webhook/iot/health`);
+});

package/src/webhook/iot-receiver.js

@@ -0,0 +1,110 @@
+/**
+ * IoT Webhook Receiver — Enterprise Tier (STUB)
+ *
+ * Endpoints:
+ *   POST /webhook/iot/:property_id     — accept inbound IoT events
+ *   GET  /webhook/iot/health           — liveness probe
+ *
+ * Responsibilities (stub scope only):
+ *   - Require a non-empty `x-dlj-webhook-signature` header
+ *     (HMAC verification is stubbed — see TODO below).
+ *   - Parse JSON body: { device_id, event_type, severity, timestamp, metadata }
+ *   - Append one JSON line per event to ~/.dlj-scripts/logs/iot-webhook.log
+ *   - Return 202 Accepted with { received: true, event_id: <uuid> }
+ *
+ * NOT IN SCOPE (future phases):
+ *   - Real HMAC verification against IOT_WEBHOOK_SECRET
+ *   - Rate limiting
+ *   - Durable persistence / DB writes
+ *   - Fan-out to `get_maintenance_alerts` MCP tool
+ *
+ * Production deployment note:
+ *   This receiver is intended to run behind a reverse proxy (nginx / Caddy /
+ *   Cloudflare Tunnel) that terminates TLS and enforces real HMAC checks.
+ *   Do NOT expose port IOT_WEBHOOK_PORT (default 3100) on the public internet.
+ */
+
+import { Router } from "express";
+import { randomUUID } from "node:crypto";
+import { appendFile, mkdir } from "node:fs/promises";
+import { dirname } from "node:path";
+import { homedir } from "node:os";
+
+const router = Router();
+
+const LOG_PATH = `${homedir()}/.dlj-scripts/logs/iot-webhook.log`;
+
+// Best-effort: ensure logs dir exists at import time.
+mkdir(dirname(LOG_PATH), { recursive: true }).catch(() => {});
+
+/**
+ * Append a single JSON line to the rotating log file.
+ * Rotation itself is delegated to logrotate / launchd — this module is
+ * append-only.
+ */
+async function logEvent(entry) {
+  try {
+    await appendFile(LOG_PATH, JSON.stringify(entry) + "\n", "utf8");
+  } catch (err) {
+    // Surface a line to stderr but do not fail the request — observability
+    // is best-effort at this tier.
+    console.error("[iot-receiver] log write failed:", err.message);
+  }
+}
+
+// ── Health ────────────────────────────────────────────────────────────────
+
+router.get("/webhook/iot/health", (req, res) => {
+  res.status(200).json({
+    status: "ok",
+    receiver: "iot-webhook-stub",
+    log_path: LOG_PATH
+  });
+});
+
+// ── Inbound event ─────────────────────────────────────────────────────────
+
+router.post("/webhook/iot/:property_id", async (req, res) => {
+  const signature = req.get("x-dlj-webhook-signature");
+
+  // TODO: verify HMAC against IOT_WEBHOOK_SECRET
+  // Expected: HMAC-SHA256(body, IOT_WEBHOOK_SECRET) === signature
+  if (!signature || typeof signature !== "string" || signature.length === 0) {
+    return res.status(401).json({
+      received: false,
+      error: "missing x-dlj-webhook-signature header"
+    });
+  }
+
+  const body = req.body;
+  if (!body || typeof body !== "object" || Array.isArray(body)) {
+    return res.status(400).json({
+      received: false,
+      error: "body must be a JSON object"
+    });
+  }
+
+  const { device_id, event_type, severity, timestamp, metadata } = body;
+
+  const event_id = randomUUID();
+  const entry = {
+    event_id,
+    property_id: req.params.property_id,
+    device_id: device_id ?? null,
+    event_type: event_type ?? null,
+    severity: severity ?? null,
+    timestamp: timestamp ?? new Date().toISOString(),
+    metadata: metadata ?? null,
+    signature_present: true,
+    received_at: new Date().toISOString()
+  };
+
+  await logEvent(entry);
+
+  return res.status(202).json({
+    received: true,
+    event_id
+  });
+});
+
+export default router;

package/.env.example

@@ -1,2 +0,0 @@
-GUESTY_CLIENT_ID=your-client-id-here
-GUESTY_CLIENT_SECRET=your-client-secret-here

package/CONTRIBUTING.md

@@ -1,66 +0,0 @@
-# Contributing to Guesty MCP Server
-
-Thank you for your interest in contributing! This is the first MCP server for property management, and community contributions help make it better for everyone.
-
-## Getting Started
-
-1. Fork the repository
-2. Clone your fork: `git clone https://github.com/YOUR-USERNAME/guesty-mcp-server.git`
-3. Install dependencies: `npm install`
-4. Create a `.env` file with your Guesty API credentials (see `.env.example`)
-5. Run the server: `npm start`
-
-## Adding New Tools
-
-Each tool wraps a Guesty API endpoint. To add a new tool:
-
-1. Identify the Guesty API endpoint from [Guesty Open API docs](https://open-api.guesty.com/api-docs)
-2. Add the tool in `src/server.js` using the `server.tool()` pattern
-3. Follow the existing naming convention: `verb_noun` (e.g., `get_reservations`, `update_pricing`)
-4. Include proper Zod schema validation for all parameters
-5. Return structured JSON in the response
-
-### Tool Template
-
-```javascript
-server.tool(
-  "tool_name",
-  "Clear description of what this tool does",
-  {
-    param1: z.string().describe("What this parameter does"),
-    param2: z.number().optional().describe("Optional parameter"),
-  },
-  async (params) => {
-    const data = await guestyGet("/endpoint", { key: params.param1 });
-    return {
-      content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
-    };
-  }
-);
-```
-
-## Desired Contributions
-
-We'd love help with:
-- **New tools**: Reviews management, task/cleaning scheduling, owner statements, channel management
-- **Testing**: Integration tests, error handling edge cases
-- **Documentation**: Usage examples, video tutorials, blog posts
-- **PMS integrations**: Adapting this pattern for Hostaway, Lodgify, OwnerRez, etc.
-
-## Code Style
-
-- ES modules (import/export)
-- Async/await for all API calls
-- Descriptive error messages
-- Keep tools focused -- one API action per tool
-
-## Pull Requests
-
-1. Create a feature branch: `git checkout -b feature/new-tool`
-2. Make your changes
-3. Test against the Guesty API
-4. Submit a PR with a clear description of what the tool does and why
-
-## Questions?
-
-Open an issue on GitHub or reach out to [DLJ Properties](https://tinyhomeboutiques.com).

package/Dockerfile

@@ -1,13 +0,0 @@
-FROM node:18-alpine
-
-WORKDIR /app
-COPY package*.json ./
-RUN npm ci --production
-COPY . .
-
-ENV GUESTY_CLIENT_ID=""
-ENV GUESTY_CLIENT_SECRET=""
-
-EXPOSE 3001 3002
-
-CMD ["node", "src/server.js"]