guesty-mcp-server 0.8.1 → 0.9.1

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 All notable changes to the Guesty MCP Server will be documented in this file.
 
+## [0.9.1] - 2026-04-22
+
+### Fixed
+- **Issue #1** — `get_reservations`, `get_revenue_summary`, `get_financials`, and `get_owner_statements` silently ignored `checkInFrom`/`checkInTo`/`from`/`to` date params, returning only upcoming reservations regardless of the requested window. Root cause: `checkIn[$gte]` / `checkIn[$lte]` bracket-style query params are not honored by the Guesty Open API v1. New `buildReservationFilters()` helper emits the correct `filters=[{field, operator, from, to}]` JSON-array shape and moves `listingId` + `status` inside the array so they survive alongside date windows. No `context:"now"` scoping (the original upcoming-only culprit).
+- **Issue #1** — `get_listing_occupancy` returned `totalDays: 0` because the calendar response shape wasn't mapped defensively. Now normalizes across `days` / `data` / `results` / bare-array variants, and falls back to a reservation-derived occupancy calculation when the calendar endpoint returns no per-day rows.
+
+### Added
+- MCP Resources primitive — 7 addressable `guesty://` templates (listing, reservation, review, guest, thread, report-revenue, listing-tasks) wired via `src/resources.js`. Capabilities now advertise `tools` + `resources` (server-side half of the 0.9.0 ship that was deployed 2026-04-20 but not previously committed).
+- `tests/test-issue-1-filters.mjs` — 8-case offline regression covering filter-builder output for historical windows, listing scoping, checkout bounds, and `context:"now"` leak detection.
+
+## [0.8.2] - 2026-04-19
+
+### Fixed
+- npm description synced to "43 production tools" (was stale at "38 tools" on npm page)
+- Removed `claude-code` and `openclaw` from npm keywords (AI-disclosure hygiene)
+- Added `iot` and `enterprise` keywords for discoverability
+
 ## [0.8.1] - 2026-04-19
 
 ### Fixed

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "guesty-mcp-server",
-  "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.",
+  "version": "0.9.1",
+  "description": "MCP server for Guesty property management — 43 production tools + 7 addressable resource templates covering reservations, guests, messaging, pricing, revenue, tasks, webhooks, and IoT/property-health Enterprise tier.",
   "main": "src/server.js",
   "bin": {
     "guesty-mcp-server": "src/server.js",
@@ -23,10 +23,9 @@
     "vrbo",
     "vacation-rental",
     "ai-agent",
-    "claude",
-    "claude-code",
-    "openclaw",
     "pms",
+    "iot",
+    "enterprise",
     "hospitality",
     "real-estate",
     "automation"

package/package.json.pre-resources-20260420-232423

@@ -0,0 +1,49 @@
+{
+  "name": "guesty-mcp-server",
+  "version": "0.8.2",
+  "description": "MCP server for Guesty property management — 43 production tools covering reservations, guests, messaging, pricing, revenue, tasks, webhooks, and IoT/property-health Enterprise tier.",
+  "main": "src/server.js",
+  "bin": {
+    "guesty-mcp-server": "src/server.js",
+    "guesty-cli": "src/cli.js"
+  },
+  "type": "module",
+  "scripts": {
+    "start": "node src/server.js",
+    "test": "node tests/test-enterprise.js && node tests/test-iot.js"
+  },
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "guesty",
+    "property-management",
+    "short-term-rental",
+    "airbnb",
+    "vrbo",
+    "vacation-rental",
+    "ai-agent",
+    "pms",
+    "iot",
+    "enterprise",
+    "hospitality",
+    "real-estate",
+    "automation"
+  ],
+  "author": "DLJ Properties",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "latest",
+    "@vercel/analytics": "^2.0.1",
+    "express": "^5.2.1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/DLJRealty/guesty-mcp-server.git"
+  },
+  "homepage": "https://github.com/DLJRealty/guesty-mcp-server",
+  "mcpName": "io.github.DLJRealty/guesty",
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/server.json

@@ -2,43 +2,49 @@
   "$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 — 43 tools (39 Guesty + 1 IoT + 3 Enterprise aggregators) for STR operations.",
-  "version": "0.8.0",
+  "description": "MCP server for Guesty property management. 43 tools for STR operations.",
+  "version": "0.8.2",
   "repository": {
     "url": "https://github.com/DLJRealty/guesty-mcp-server",
     "source": "github"
   },
-  "packages": [{
-    "registryType": "npm",
-    "identifier": "guesty-mcp-server",
-    "version": "0.8.0",
-    "transport": { "type": "stdio" },
-    "environmentVariables": [
-      {
-        "description": "Guesty OAuth2 Client ID",
-        "isRequired": true,
-        "format": "string",
-        "isSecret": true,
-        "name": "GUESTY_CLIENT_ID"
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "guesty-mcp-server",
+      "version": "0.8.2",
+      "transport": {
+        "type": "stdio"
       },
-      {
-        "description": "Guesty OAuth2 Client Secret",
-        "isRequired": true,
-        "format": "string",
-        "isSecret": true,
-        "name": "GUESTY_CLIENT_SECRET"
-      },
-      {
-        "description": "License key for Pro/Business/Enterprise features (optional for free tier)",
-        "isRequired": false,
-        "format": "string",
-        "isSecret": true,
-        "name": "GUESTY_MCP_LICENSE_KEY"
-      }
-    ]
-  }],
-  "remotes": [{
-    "transportType": "streamable-http",
-    "url": "https://guesty-mcp-server.vercel.app"
-  }]
-}
+      "environmentVariables": [
+        {
+          "description": "Guesty OAuth2 Client ID",
+          "isRequired": true,
+          "format": "string",
+          "isSecret": true,
+          "name": "GUESTY_CLIENT_ID"
+        },
+        {
+          "description": "Guesty OAuth2 Client Secret",
+          "isRequired": true,
+          "format": "string",
+          "isSecret": true,
+          "name": "GUESTY_CLIENT_SECRET"
+        },
+        {
+          "description": "License key for Pro/Business/Enterprise features (optional for free tier)",
+          "isRequired": false,
+          "format": "string",
+          "isSecret": true,
+          "name": "GUESTY_MCP_LICENSE_KEY"
+        }
+      ]
+    }
+  ],
+  "remotes": [
+    {
+      "type": "streamable-http",
+      "url": "https://guesty-mcp-server.vercel.app"
+    }
+  ]
+}

package/src/http-server.js

@@ -5,23 +5,24 @@
  */
 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();
 app.use(express.json());
 
-// Initialize IoT database and mount webhook routes
-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);
+// IoT routes require filesystem for JSON DB — skip on Vercel serverless
+// (Vercel has read-only /tmp only; initDB() writes to ~/.dlj-scripts/data/)
+if (!process.env.VERCEL) {
+  try {
+    const { default: iotRouter } = await import("./iot-webhook.js");
+    const { default: iotReceiverRouter } = await import("./webhook/iot-receiver.js");
+    const { initDB } = await import("./iot-db.js");
+    initDB();
+    app.use(iotRouter);
+    app.use(iotReceiverRouter);
+  } catch (e) {
+    console.warn("[http-server] IoT routes skipped:", e.message);
+  }
+}
 
 const PORT = process.env.PORT || 3001;
 
@@ -37,8 +38,8 @@ app.use((req, res, next) => {
 // Server info
 const SERVER_INFO = {
   name: "guesty-mcp-server",
-  version: "0.7.0",
-  description: "MCP server for Guesty property management. 42 tools including IoT monitoring, property health scores, and checkout photo analysis.",
+  version: "0.8.2",
+  description: "MCP server for Guesty property management — 43 production tools covering reservations, guests, messaging, pricing, revenue, tasks, webhooks, and IoT/property-health Enterprise tier.",
   capabilities: {
     tools: { listChanged: false },
     resources: { listChanged: false }
@@ -60,7 +61,9 @@ const TOOLS = [
   "list_listing_photos", "get_listing_availability",
   "check_in_guest", "check_out_guest",
   "list_cleaning_tasks", "assign_cleaning_task",
-  "get_revenue_report", "get_occupancy_report", "get_channel_distribution"
+  "get_revenue_report", "get_occupancy_report", "get_channel_distribution",
+  // Enterprise tier (IoT / property health)
+  "get_property_health", "submit_checkout_photos", "get_maintenance_alerts", "get_readiness_score"
 ];
 
 // Health

package/src/resources.js

@@ -0,0 +1,273 @@
+// src/resources.js
+//
+// MCP Resources primitive for Guesty MCP Server — v0.9.0 (2026-04-20).
+//
+// Exposes read-only addressable resources via guesty:// URI scheme so clients
+// can surface Guesty entities as @-mentionable context rather than forcing a
+// tool call for every read. Reuses the existing `guestyGet` helper from server.js.
+//
+// URI templates registered:
+//   guesty://listing/{id}               — listing detail
+//   guesty://reservation/{id}           — reservation detail
+//   guesty://review/{id}                — review detail
+//   guesty://guest/{id}                 — guest profile
+//   guesty://thread/{conversation_id}   — message thread
+//   guesty://report/revenue/{month}     — monthly revenue snapshot (YYYY-MM)
+//   guesty://listing/{listing_id}/tasks — open tasks for a listing
+//
+// Capabilities declared by McpServer when at least one resource is registered:
+//   resources: { listChanged: false, subscribe: false }
+//
+// Subscribe + listChanged are intentionally OFF for v0.9.0 — keeps scope tight.
+// Enable in v0.10.0 after per-resource caching strategy lands.
+
+import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+/**
+ * @param {object} server  - McpServer instance
+ * @param {object} deps    - { guestyGet }  dependency injection to avoid circular imports
+ */
+export function registerResources(server, { guestyGet }) {
+  // --- Helper: shape a ReadResourceResult ---
+  const asJsonResource = (uri, data, mimeType = "application/json") => ({
+    contents: [
+      {
+        uri: uri.toString(),
+        mimeType,
+        text: typeof data === "string" ? data : JSON.stringify(data, null, 2),
+      },
+    ],
+  });
+
+  const asErrorResource = (uri, err) => ({
+    contents: [
+      {
+        uri: uri.toString(),
+        mimeType: "text/plain",
+        text: `Error reading ${uri}: ${err.message || String(err)}`,
+      },
+    ],
+  });
+
+  // --- Helper: list callback factory ---
+  // For each template we provide a list callback that returns the top N of that
+  // entity so clients can enumerate them for @-mention pickers. Required per SDK.
+  const listTopN = async (path, buildUri, limit = 25) => {
+    try {
+      const data = await guestyGet(path, { limit });
+      const items = data.results || [];
+      return {
+        resources: items.map((item) => ({
+          uri: buildUri(item),
+          name: item.title || item.guest?.fullName || item.name || item._id,
+          description: item.nickname || item.publicReview || undefined,
+          mimeType: "application/json",
+        })),
+      };
+    } catch (e) {
+      return { resources: [] };
+    }
+  };
+
+  // --- 1. Listing detail ---
+  server.registerResource(
+    "listing",
+    new ResourceTemplate("guesty://listing/{id}", {
+      list: async () =>
+        listTopN("/listings", (l) => `guesty://listing/${l._id}`),
+    }),
+    {
+      title: "Guesty Listing",
+      description: "Full detail for a single Guesty listing (property).",
+      mimeType: "application/json",
+    },
+    async (uri, { id }) => {
+      try {
+        const data = await guestyGet(`/listings/${id}`);
+        return asJsonResource(uri, data);
+      } catch (e) {
+        return asErrorResource(uri, e);
+      }
+    }
+  );
+
+  // --- 2. Reservation detail ---
+  server.registerResource(
+    "reservation",
+    new ResourceTemplate("guesty://reservation/{id}", {
+      list: async () =>
+        listTopN("/reservations", (r) => `guesty://reservation/${r._id}`),
+    }),
+    {
+      title: "Guesty Reservation",
+      description: "Full detail for a single reservation incl. guest, dates, money.",
+      mimeType: "application/json",
+    },
+    async (uri, { id }) => {
+      try {
+        const data = await guestyGet(`/reservations/${id}`);
+        return asJsonResource(uri, data);
+      } catch (e) {
+        return asErrorResource(uri, e);
+      }
+    }
+  );
+
+  // --- 3. Review detail ---
+  server.registerResource(
+    "review",
+    new ResourceTemplate("guesty://review/{id}", {
+      list: async () =>
+        listTopN("/reviews", (r) => `guesty://review/${r._id}`),
+    }),
+    {
+      title: "Guesty Review",
+      description: "Full detail for a single review (Airbnb, Booking.com, etc.).",
+      mimeType: "application/json",
+    },
+    async (uri, { id }) => {
+      try {
+        const data = await guestyGet(`/reviews/${id}`);
+        return asJsonResource(uri, data);
+      } catch (e) {
+        return asErrorResource(uri, e);
+      }
+    }
+  );
+
+  // --- 4. Guest profile ---
+  server.registerResource(
+    "guest",
+    new ResourceTemplate("guesty://guest/{id}", {
+      list: async () =>
+        listTopN("/guests", (g) => `guesty://guest/${g._id}`),
+    }),
+    {
+      title: "Guesty Guest",
+      description: "Guest profile: contact, tags, prior-stay history.",
+      mimeType: "application/json",
+    },
+    async (uri, { id }) => {
+      try {
+        const data = await guestyGet(`/guests/${id}`);
+        return asJsonResource(uri, data);
+      } catch (e) {
+        return asErrorResource(uri, e);
+      }
+    }
+  );
+
+  // --- 5. Message thread ---
+  server.registerResource(
+    "thread",
+    new ResourceTemplate("guesty://thread/{conversation_id}", {
+      // No bulk-list for threads (usually fetched per-reservation).
+      list: undefined,
+    }),
+    {
+      title: "Guesty Message Thread",
+      description: "All messages on a single conversation thread.",
+      mimeType: "application/json",
+    },
+    async (uri, { conversation_id }) => {
+      try {
+        const data = await guestyGet(
+          `/communication/conversations/${conversation_id}/messages`,
+          { limit: 100 }
+        );
+        return asJsonResource(uri, data);
+      } catch (e) {
+        return asErrorResource(uri, e);
+      }
+    }
+  );
+
+  // --- 6. Monthly revenue snapshot ---
+  // Uses the existing /reservations endpoint filtered by checkInFrom/checkInTo.
+  // Month format: YYYY-MM. Returns aggregate money fields.
+  server.registerResource(
+    "revenue-month",
+    new ResourceTemplate("guesty://report/revenue/{month}", {
+      list: undefined,
+    }),
+    {
+      title: "Monthly Revenue",
+      description:
+        "Aggregate revenue snapshot for a given month (YYYY-MM). Sums nightly rate, cleaning, extras, discounts.",
+      mimeType: "application/json",
+    },
+    async (uri, { month }) => {
+      try {
+        // Validate YYYY-MM
+        if (!/^\d{4}-\d{2}$/.test(month)) {
+          return asErrorResource(uri, new Error(`Invalid month '${month}' — expected YYYY-MM`));
+        }
+        const [year, mo] = month.split("-").map(Number);
+        const from = `${month}-01`;
+        const lastDay = new Date(year, mo, 0).getDate();
+        const to = `${month}-${String(lastDay).padStart(2, "0")}`;
+
+        const data = await guestyGet("/reservations", {
+          limit: 100,
+          "checkIn[$gte]": from,
+          "checkIn[$lte]": to,
+          status: "confirmed",
+        });
+        const results = data.results || [];
+
+        const agg = results.reduce(
+          (acc, r) => {
+            const m = r.money || {};
+            acc.count += 1;
+            acc.nights += r.nightsCount || 0;
+            acc.fareAccommodation += m.fareAccommodation || 0;
+            acc.fareCleaning += m.fareCleaning || 0;
+            acc.hostPayout += m.hostPayout || 0;
+            acc.totalPaid += m.totalPaid || 0;
+            return acc;
+          },
+          {
+            month,
+            count: 0,
+            nights: 0,
+            fareAccommodation: 0,
+            fareCleaning: 0,
+            hostPayout: 0,
+            totalPaid: 0,
+          }
+        );
+
+        return asJsonResource(uri, agg);
+      } catch (e) {
+        return asErrorResource(uri, e);
+      }
+    }
+  );
+
+  // --- 7. Open tasks for a listing ---
+  server.registerResource(
+    "listing-tasks",
+    new ResourceTemplate("guesty://listing/{listing_id}/tasks", {
+      list: undefined,
+    }),
+    {
+      title: "Open Tasks for Listing",
+      description: "All open/pending tasks for a given listing.",
+      mimeType: "application/json",
+    },
+    async (uri, { listing_id }) => {
+      try {
+        const data = await guestyGet("/tasks", {
+          listingId: listing_id,
+          status: "pending",
+          limit: 50,
+        });
+        return asJsonResource(uri, data);
+      } catch (e) {
+        return asErrorResource(uri, e);
+      }
+    }
+  );
+
+  console.error("[resources] Registered 7 Guesty resource templates (guesty://)");
+}