@rowvyn/servicetitan-mcp 2.4.1 → 2.5.0

package/CHANGELOG.md

@@ -4,6 +4,35 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/), and this project adheres to [Semantic Versioning](https://semver.org/).
 
+## [2.5.0] - 2026-04-02
+
+### Performance
+- **HTTP keep-alive + connection pooling** — shared `https.Agent` with `keepAlive: true`, `maxSockets: 32` eliminates TLS handshake overhead on consecutive API calls.
+- **Auth pre-warming** — `client.prewarm()` called at server startup fetches and caches the OAuth token before the first tool execution, saving ~1-2s on cold starts.
+- **Parallel invoice tracking** — Reports 2281 and 2282 now fetched concurrently via `Promise.all()` instead of sequentially.
+- **Parallel estimate pipeline** — estimate pagination parallelized (6.49s → 1.50s).
+- **`fetchAllPagesBlind` helper** — fires all `maxPages` page requests simultaneously without a probe step to determine `totalCount` first. Applied to bookings, estimates, invoices, and payments pagination. Saves one sequential round-trip per paginated call.
+- **Sequential campaign calls** — `/v3/calls` endpoint uses sequential `fetchAllPages` instead of parallel. ServiceTitan's calls API exhibits extreme concurrency sensitivity (even 2 concurrent requests trigger rate-limiting and inflate results). Sequential is the only reliable approach.
+- **Report 165 removal** — `technician_scorecard` no longer fetches Report 165 (redundant with `ConvertedJobs` field from Report 168). Reduces parallel POST calls from 5 to 4 on the default path.
+
+### Added
+- **`includeServiceRevenue`** parameter on `intel_membership_health` — opt-in invoice pagination for service revenue breakdown. Default: `false` (saves ~2-4s).
+- **`includeProductivityMetrics`** parameter on `intel_revenue_summary` — opt-in Report 177 fetch for BU-level productivity metrics. Default: `false` (saves ~0.5-1s).
+- **`includeExtendedMetrics`** parameter on `intel_technician_scorecard` — opt-in Reports 171/173/174 for revenue-per-hour, billable efficiency, and recall data. Default: `false` (saves ~1-2s).
+- **`fetchAllPagesWithTotal`** helper — variant that returns both items and `totalCount` for callers that need the count.
+
+### Changed
+- **Score improvement** — baseline score improved from 0.91 to 0.92-0.94 (typical), up to 1.24 on fast ServiceTitan API days. All 25 ground truth questions still pass.
+- **Non-campaign tool latency** — `revenue_summary` 2.7-3.3s, `technician_scorecard` 2.1-2.7s, `membership_health` 2.0-2.8s, `estimate_pipeline` 1.5-1.8s, `invoice_tracking` 2.2-4.4s.
+
+### Fixed
+- **Test suite** — 12 test failures fixed for new opt-in parameter defaults and `fetchAllPagesBlind` mock compatibility. All 260 tests passing.
+
+## [2.4.2] - 2026-03-29
+
+### Fixed
+- **README cleanup** — removed misleading "0.001% revenue accuracy" stat (replaced with "Dashboard-matched revenue"), stripped internal "Report 175" jargon throughout. No code changes.
+
 ## [2.4.0] - 2026-03-28
 
 ### Added
@@ -210,6 +239,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/), and this
   - Generated TOOLS.md tool catalog
   - `.env.example` with all environment variables documented
 
+[2.5.0]: https://github.com/montrellcruse/servicetitan-mcp/compare/v2.4.2...v2.5.0
+[2.4.2]: https://github.com/montrellcruse/servicetitan-mcp/compare/v2.4.0...v2.4.2
 [2.3.1]: https://github.com/montrellcruse/servicetitan-mcp/compare/v2.3.0...v2.3.1
 [2.4.0]: https://github.com/montrellcruse/servicetitan-mcp/compare/v2.3.1...v2.4.0
 [2.3.0]: https://github.com/montrellcruse/servicetitan-mcp/compare/v2.2.0...v2.3.0

package/README.md

@@ -20,7 +20,7 @@ The only MCP server for the ServiceTitan API — 467 tools across 15 domains, pl
 - **ServiceTitan has no official MCP server** or developer tooling beyond REST docs
 - **Raw API access is friction-heavy** — OAuth token management, module-prefix routing, pagination, and response parsing all fall on you
 - **This server handles all of that** and adds 10 intelligence tools that aggregate multiple endpoints into operational insights
-- **Revenue accuracy within 0.001% of ServiceTitan's own dashboard** (verified on production data using Report 175 — the same source ST's internal engine uses)
+- **Dashboard-matched revenue** — verified on production data using the same Reporting API source that powers ST's own dashboard
 
 ---
 
@@ -28,7 +28,7 @@ The only MCP server for the ServiceTitan API — 467 tools across 15 domains, pl
 
 - **467 tools across 15 domains** — CRM, dispatch, accounting, payroll, inventory, marketing, and more
 - **10 intelligence tools** — composite analytics that aggregate multiple API calls into revenue summaries, ops snapshots, technician scorecards, and more
-- **Dashboard-accurate revenue** — `intel_revenue_summary` uses Report 175 to match ST's dashboard within 0.001%
+- **Dashboard-matched revenue** — `intel_revenue_summary` pulls from the same source as ST's own dashboard
 - **Read-only by default** — `ST_READONLY=true` out of the box; write tools only activate when you're ready
 - **Safety layer** — confirmation workflow for writes/deletes, audit logging with sensitive field redaction
 - **Domain filtering** — expose only the tool groups you need via `ST_DOMAINS`
@@ -60,13 +60,16 @@ No install needed — runs directly:
         "ST_CLIENT_ID": "your-client-id",
         "ST_CLIENT_SECRET": "your-client-secret",
         "ST_APP_KEY": "your-app-key",
-        "ST_TENANT_ID": "your-tenant-id"
+        "ST_TENANT_ID": "your-tenant-id",
+        "ST_ENVIRONMENT": "production"
       }
     }
   }
 }
 ```
 
+> ⚠️ **`ST_ENVIRONMENT` defaults to `integration`.** If you're connecting to a live ServiceTitan account, you **must** set `ST_ENVIRONMENT` to `production` or you'll get silent auth failures and empty results.
+
 ### Install globally
 
 ```bash
@@ -183,7 +186,7 @@ The real differentiator. These 10 tools aggregate multiple API calls and report
 
 | Tool | What It Returns |
 |------|----------------|
-| `intel_revenue_summary` | Dashboard-accurate revenue by business unit using Report 175 — matches ServiceTitan within 0.001%. Includes completed revenue, non-job revenue, adjustments, collections, and BU productivity rollups. |
+| `intel_revenue_summary` | Dashboard-matched revenue by business unit. Includes completed revenue, non-job revenue, adjustments, collections, and BU productivity rollups. |
 | `intel_daily_snapshot` | 6-metric same-day ops briefing: revenue-to-date, jobs in progress, call outcomes, bookings, open estimates, and upcoming next-day jobs. |
 | `intel_technician_scorecard` | Per-tech jobs, revenue, avg ticket, productivity, lead gen, membership close rate, and sales from both tech and marketing leads — with team averages. |
 | `intel_membership_health` | Active memberships, signups, cancellations, renewals, retention rate, invoiced revenue, and conversion by business unit. |
@@ -198,7 +201,7 @@ These tools are why this server exists. Raw CRUD tools are table stakes. Intelli
 
 ### Revenue Accuracy
 
-`intel_revenue_summary` uses ServiceTitan's **Reporting API** (Report 175: "Revenue") to calculate totals. This is the same source ST's own dashboard uses — which means it includes:
+`intel_revenue_summary` uses ServiceTitan's **Reporting API** to calculate totals. This is the same source ST's own dashboard uses — which means it includes:
 
 - **Completed Revenue** — revenue from completed jobs
 - **Non-Job Revenue** — membership fees, add-ons, and other income not tied to a specific job
@@ -299,7 +302,7 @@ The CLI and this MCP server share the same design philosophy: push the business
 
 | Feature | This Server | Community MCP Servers |
 |---------|------------|----------------------|
-| Revenue accuracy | ✅ 0.001% of dashboard | ❌ $17–21K off per period |
+| Revenue accuracy | ✅ Dashboard-matched | ❌ $17–21K off per period |
 | Intelligence tools | ✅ 10 tools | ❌ None |
 | Domain coverage | ✅ 467 tools, 15 domains | ⚠️ 10–50 tools |
 | Safety layer | ✅ Read-only default, audit log | ❌ None |
@@ -330,6 +333,53 @@ npm run start      # run compiled server
 
 ---
 
+## Troubleshooting
+
+### npm permission errors (EACCES)
+
+If you see `EACCES: permission denied` errors when Claude Desktop tries to start the server, your npm cache directory is likely owned by root (common when Node was installed with `sudo`).
+
+**Fix:**
+
+```bash
+sudo chown -R $(whoami) ~/.npm
+```
+
+Then restart Claude Desktop.
+
+### Server won't start / "Could not connect to MCP server"
+
+1. **Test outside Claude Desktop first:**
+   ```bash
+   npx -y @rowvyn/servicetitan-mcp
+   ```
+   If this fails, the issue is with Node, npm, or your environment — not Claude Desktop.
+
+2. **Check Node version:** `node -v` — requires Node 22 or newer.
+
+3. **Check for conflicting MCP installs:** If you previously installed a different ServiceTitan MCP server, remove it:
+   ```bash
+   npm ls -g --depth=0 | grep -i servicetitan
+   npm uninstall -g <old-package-name>
+   npx clear-npx-cache
+   ```
+
+4. **Verify your `claude_desktop_config.json`** has no leftover entries from a previous MCP server. Only one `servicetitan` entry should exist under `mcpServers`.
+
+### Auth failures / $0 revenue / empty results
+
+- **Set `ST_ENVIRONMENT` to `production`.** This is the #1 cause. The default is `integration`, which authenticates against ServiceTitan's sandbox — not your live account. You'll get valid auth tokens that return zero data.
+- **Verify credentials match:** `ST_CLIENT_ID` and `ST_CLIENT_SECRET` must be from the same ServiceTitan app. You can't mix credentials from different apps.
+- **Check `ST_TENANT_ID`:** Must match the tenant associated with your app in the ServiceTitan developer portal.
+
+### Claude Desktop logs
+
+Claude Desktop writes MCP server logs to:
+- **macOS:** `~/Library/Logs/Claude/mcp*.log`
+- **Windows:** `%APPDATA%\Claude\logs\mcp*.log`
+
+---
+
 ## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md).