timezest-mcp 1.0.5 → 1.0.7

package/README.md

@@ -1,35 +1,37 @@
 # 📅 TimeZest MCP Server
 
-An MCP (Model Context Protocol) server that brings **TimeZest** scheduling data (confirmed appointments, pending invitations, and ticket-linked schedules) directly into your Claude conversations.
+Bring your **TimeZest** scheduling data directly into Claude through the Model Context Protocol (MCP). Perform real-time scheduling lookups, engineer briefings, and ticket-linked appointment management without leaving your chat.
 
 ---
 
-## 📋 Prerequisites (One-Time Setup)
+## 🌟 Features
 
-Before you begin, ensure you have **Node.js** installed on your machine. This is what allows Claude to run the server.
-
-1.  **Download Node.js**: [Download here (v18 or higher recommended)](https://nodejs.org/)
-2.  **Verify**: Open a terminal and type `node -v` to confirm it's installed.
+- **Morning Briefings**: Instantly get confirmed vs. pending invitations for today, grouped by engineer.
+- **Ticket Lookups**: Look up appointments by their original ConnectWise ticket number (e.g. #964400).
+- **Engineer Schedules**: View upcoming timelines for specific staff members.
+- **Pending Follow-ups**: Identify aging, unbooked invitations to prevent ticket stall.
+- **Cancellation Insights**: Quickly triage cancelled requests for rebooking.
+- **Enterprise Ready**: Full support for timezone transformations (TZ) and automated Vitest testing suite.
 
 ---
 
-## 🚀 How to Install (For Colleagues)
+## 🚀 Quick Start (via npm/npx)
 
-You don't need to download or build any code. You can run this directly using `npx`.
+The fastest way to use this server is via `npx`. No manual cloning or building is required to get started.
 
-### Option A — Claude Desktop (Standard)
+### 1. Configure Claude Desktop
 Open your Claude Desktop configuration file:
 - **Windows:** `%AppData%\Roaming\Claude\claude_desktop_config.json`
-- **Mac:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
 
-Add this entry to the `mcpServers` section:
+Add the following entry to the `mcpServers` object:
 
 ```json
 {
   "mcpServers": {
     "timezest": {
-      "command": "cmd",
-      "args": ["/c", "npx", "-y", "timezest-mcp@latest"],
+      "command": "npx",
+      "args": ["-y", "timezest-mcp@latest"],
       "env": {
         "TIMEZEST_API_KEY": "YOUR_API_KEY_HERE",
         "TIMEZEST_DEFAULT_TZ": "America/Chicago"
@@ -39,50 +41,81 @@ Add this entry to the `mcpServers` section:
 }
 ```
 
-### Option B — Claude Code (CLI)
-If you use the terminal-based **Claude Code**, run this single command to add the server globally:
+### 2. Configure via Claude Code (CLI)
+Run the following command in your terminal to add the server globally:
 
 ```bash
-claude mcp add-json timezest "{\"type\": \"stdio\", \"command\": \"cmd\", \"args\": [\"/c\", \"npx\", \"-y\", \"timezest-mcp@latest\"], \"env\": {\"TIMEZEST_API_KEY\": \"YOUR_API_KEY_HERE\", \"TIMEZEST_DEFAULT_TZ\": \"America/Chicago\"}}"
+# Windows
+claude mcp add-json timezest "{\"type\": \"stdio\", \"command\": \"cmd\", \"args\": [\"/c\", \"npx\", \"-y\", \"timezest-mcp@latest\"], \"env\": {\"TIMEZEST_API_KEY\": \"YOUR_API_KEY\", \"TIMEZEST_DEFAULT_TZ\": \"America/Chicago\"}}"
+
+# macOS / Linux
+claude mcp add-json timezest '{"type": "stdio", "command": "npx", "args": ["-y", "timezest-mcp@latest"], "env": {"TIMEZEST_API_KEY": "YOUR_API_KEY", "TIMEZEST_DEFAULT_TZ": "America/Chicago"}}'
 ```
 
 ---
 
 ## 💡 Example Prompts
+
 Once connected, try asking Claude:
 - *"What's the briefing for today?"*
-- *"Show me Aaron's schedule for next week"*
+- *"Show me Scout's schedule for next week"*
 - *"Find any TimeZest requests for ticket #964400"*
-- *"Who has the oldest pending invitations?"*
-- *"Give me the appointment stats for the last 14 days"*
-- *"Show me recently cancelled appointments for Isam"*
+- *"Provide appointment stats for the last 14 days"*
+- *"Show me recently cancelled appointments for rebooking"*
 
 ---
 
 ## 🛠️ Available Tools
 
-| Tool | What It Does |
-|------|-------------|
+| Tool | Purpose |
+|------|---------|
 | `get_todays_appointments` | Morning briefing: Confirmed today vs. pending unbooked |
 | `list_appointments` | Flexible range search with engineer and status filters |
 | `get_engineer_schedule` | Sorted timeline for a specific engineer |
 | `list_pending_requests` | Follow up on `sent` and `new` (unbooked) invitations |
-| `find_appointment_by_ticket` | Instant lookup using ConnectWise ticket numbers |
-| `get_appointment_types` | List all available scheduling types (ID vs Name) |
-| `get_appointment_stats` | Management summary: Counts, minutes, and oldest pending |
-| `list_cancelled_appointments` | Triage cancelled requests for rebooking |
+| `find_appointment_by_ticket` | Instant lookup using source ticket numbers |
+| `get_appointment_stats` | Management summary: Counts, minutes, and aging requests |
+| `list_cancelled_appointments` | Triage cancelled requests with rebooking URLs |
+
+---
+
+## 🔧 Development & Contributing
+
+If you wish to contribute to the project or build the server from source, follow these steps:
+
+### Manual Installation
+1. **Clone the repository**:
+   ```bash
+   git clone https://github.com/sagarkalra-tech/TimeZest-MCP.git
+   ```
+2. **Install dependencies**:
+   ```bash
+   npm install
+   ```
+3. **Build the project**:
+   ```bash
+   npm run build
+   ```
+4. **Run the server locally**:
+   ```bash
+   npm start
+   ```
+
+### Running Tests
+We use **Vitest** for all our transformations and API logic. To run the suite:
+```bash
+npm run test
+```
 
 ---
 
-## 📦 Technical Info
-- **Package Name:** `timezest-mcp`
-- **Platform:** Node.js (v18+)
-- **Environment Variables**:
-    - `TIMEZEST_API_KEY` (Required): Your TimeZest Bearer token.
-    - `TIMEZEST_DEFAULT_TZ` (Optional): Default IANA timezone (e.g. `America/Chicago`).
-- **Developer:** Sagar Kalra
+## ⚙️ Configuration Variables
+
+- `TIMEZEST_API_KEY` (Required): Your TimeZest Bearer token.
+- `TIMEZEST_DEFAULT_TZ` (Optional): Default IANA timezone (e.g. `America/Chicago`).
 
 ---
 
 ## 📄 License
+
 MIT © 2026 Sagar Kalra.

package/build/__tests__/client.test.js

@@ -0,0 +1,88 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { TimeZestClient } from '../client.js';
+import axios from 'axios';
+vi.mock('axios');
+const mockedAxios = vi.mocked(axios);
+describe('TimeZestClient', () => {
+    let client;
+    beforeEach(() => {
+        vi.clearAllMocks();
+        client = new TimeZestClient('test-api-key', { maxRetries: 1, retryDelayMs: 10 });
+    });
+    describe('getAppointmentTypes', () => {
+        it('fetches and caches appointment types', async () => {
+            mockedAxios.get.mockResolvedValueOnce({
+                data: [
+                    { id: 'apty_1', internal_name: 'Remote Access' },
+                    { id: 'apty_2', name: 'Phone Call' },
+                ],
+            });
+            const types = await client.getAppointmentTypes();
+            expect(types.get('apty_1')).toBe('Remote Access');
+            expect(types.get('apty_2')).toBe('Phone Call');
+            // Second call should use cache — no additional HTTP request
+            const types2 = await client.getAppointmentTypes();
+            expect(types2.size).toBe(2);
+            expect(mockedAxios.get).toHaveBeenCalledTimes(1);
+        });
+        it('prefers internal_name over name', async () => {
+            mockedAxios.get.mockResolvedValueOnce({
+                data: [{ id: 'apty_1', internal_name: 'Internal', name: 'External' }],
+            });
+            const types = await client.getAppointmentTypes();
+            expect(types.get('apty_1')).toBe('Internal');
+        });
+        it('throws a descriptive error on API failure', async () => {
+            mockedAxios.get.mockRejectedValueOnce({
+                response: { status: 401, data: { message: 'Unauthorized' } },
+            });
+            await expect(client.getAppointmentTypes()).rejects.toThrow(/401/);
+        });
+    });
+    describe('getSchedulingRequests', () => {
+        it('fetches scheduling requests with date window params', async () => {
+            mockedAxios.get.mockResolvedValueOnce({
+                data: { scheduling_requests: [{ id: 'sreq_1' }] },
+            });
+            const results = await client.getSchedulingRequests(7, 14);
+            expect(results).toHaveLength(1);
+            expect(results[0].id).toBe('sreq_1');
+            const callParams = mockedAxios.get.mock.calls[0][1]?.params;
+            expect(callParams).toHaveProperty('created_at_after');
+            expect(callParams).toHaveProperty('created_at_before');
+            expect(callParams.page).toBe(1);
+        });
+    });
+    describe('retry logic', () => {
+        it('retries on 429 rate limit', async () => {
+            mockedAxios.get
+                .mockRejectedValueOnce({ response: { status: 429, headers: {} } })
+                .mockResolvedValueOnce({ data: [{ id: 'apty_1', name: 'Test' }] });
+            const types = await client.getAppointmentTypes();
+            expect(types.size).toBe(1);
+            expect(mockedAxios.get).toHaveBeenCalledTimes(2);
+        });
+        it('retries on 500 server error', async () => {
+            mockedAxios.get
+                .mockRejectedValueOnce({ response: { status: 500 } })
+                .mockResolvedValueOnce({ data: [{ id: 'apty_1', name: 'Test' }] });
+            const types = await client.getAppointmentTypes();
+            expect(types.size).toBe(1);
+            expect(mockedAxios.get).toHaveBeenCalledTimes(2);
+        });
+        it('does not retry on 400 client error', async () => {
+            mockedAxios.get.mockRejectedValueOnce({
+                response: { status: 400, data: { message: 'Bad Request' } },
+            });
+            await expect(client.getAppointmentTypes()).rejects.toBeTruthy();
+            expect(mockedAxios.get).toHaveBeenCalledTimes(1);
+        });
+        it('exhausts retries and throws', async () => {
+            mockedAxios.get
+                .mockRejectedValueOnce({ response: { status: 500 } })
+                .mockRejectedValueOnce({ response: { status: 500, data: { message: 'Down' } } });
+            await expect(client.getAppointmentTypes()).rejects.toThrow(/500/);
+            expect(mockedAxios.get).toHaveBeenCalledTimes(2); // 1 initial + 1 retry
+        });
+    });
+});

package/build/__tests__/filter.test.js

@@ -0,0 +1,66 @@
+import { describe, it, expect } from 'vitest';
+import { matchEngineer, filterByDateRange } from '../utils/filter.js';
+function makeAppointment(overrides = {}) {
+    return {
+        id: 'sreq_1',
+        status: 'scheduled',
+        appointment_type: 'Remote Access to PC',
+        appointment_type_id: 'apty_1',
+        engineer: 'Scout Kalra',
+        engineer_id: 'agnt_1',
+        dispatched_from_team: false,
+        start_time: '2026-03-25T15:00:00.000Z',
+        start_time_local: '2026-03-25 10:00 AM GMT-5',
+        duration_mins: 30,
+        end_user_name: 'John Doe',
+        end_user_email: 'john@example.com',
+        ticket_number: '#12345',
+        ticket_type: 'service_ticket',
+        company_id: 100,
+        contact_id: 200,
+        scheduling_url: 'https://test.timezest.com/schedule/abc',
+        created_at: '2026-03-24T12:00:00.000Z',
+        updated_at: '2026-03-24T12:00:00.000Z',
+        age_hours: 24,
+        ...overrides,
+    };
+}
+describe('matchEngineer', () => {
+    it('matches by partial engineer name (case-insensitive)', () => {
+        expect(matchEngineer(makeAppointment(), 'scout')).toBe(true);
+        expect(matchEngineer(makeAppointment(), 'Scout')).toBe(true);
+        expect(matchEngineer(makeAppointment(), 'KALRA')).toBe(true);
+    });
+    it('matches by team name', () => {
+        const appt = makeAppointment({ dispatched_from_team: true, team_name: 'MSP Red Team' });
+        expect(matchEngineer(appt, 'red team')).toBe(true);
+        expect(matchEngineer(appt, 'MSP')).toBe(true);
+    });
+    it('returns false for non-matching query', () => {
+        expect(matchEngineer(makeAppointment(), 'Aaron')).toBe(false);
+    });
+});
+describe('filterByDateRange', () => {
+    const appointments = [
+        makeAppointment({ id: '1', start_time: '2026-03-24T10:00:00.000Z' }),
+        makeAppointment({ id: '2', start_time: '2026-03-25T10:00:00.000Z' }),
+        makeAppointment({ id: '3', start_time: '2026-03-26T10:00:00.000Z' }),
+        makeAppointment({ id: '4', start_time: '2026-03-27T10:00:00.000Z' }),
+    ];
+    it('filters appointments within date range', () => {
+        // end date parses as midnight, so only 3/25 10:00 AM fits within 3/25–3/26T00:00
+        const result = filterByDateRange(appointments, '2026-03-24', '2026-03-27');
+        expect(result.map(a => a.id)).toEqual(['1', '2', '3']);
+    });
+    it('returns empty array when no appointments match', () => {
+        const result = filterByDateRange(appointments, '2026-04-01', '2026-04-05');
+        expect(result).toEqual([]);
+    });
+    it('uses created_at for pending appointments with no start_time', () => {
+        const pending = [
+            makeAppointment({ id: 'p1', status: 'sent', start_time: null, created_at: '2026-03-25T10:00:00.000Z' }),
+        ];
+        const result = filterByDateRange(pending, '2026-03-25', '2026-03-26');
+        expect(result.map(a => a.id)).toEqual(['p1']);
+    });
+});

package/build/__tests__/transform.test.js

@@ -0,0 +1,105 @@
+import { describe, it, expect } from 'vitest';
+import { transformAppointment } from '../utils/transform.js';
+const appointmentTypes = new Map([
+    ['apty_123', 'Remote Access to PC'],
+    ['apty_456', 'Phone Call'],
+]);
+function makeRawRequest(overrides = {}) {
+    return {
+        id: 'sreq_abc',
+        status: 'scheduled',
+        appointment_type_id: 'apty_123',
+        created_at: 1711382400, // 2024-03-25T16:00:00Z
+        updated_at: 1711382400,
+        selected_start_time: 1711468800, // 2024-03-26T16:00:00Z
+        duration_mins: 30,
+        end_user_name: 'John Doe',
+        end_user_email: 'john@example.com',
+        scheduling_url: 'https://test.timezest.com/schedule/abc',
+        scheduled_agents: [{ id: 'agnt_1', name: 'Scout Kalra' }],
+        resources: [{ id: 'agnt_1', name: 'Scout Kalra', object: 'agent' }],
+        associated_entities: [
+            { type: 'connectwise_psa/service_ticket', number: '#12345' },
+            { type: 'connectwise_psa/company', id: 100 },
+            { type: 'connectwise_psa/contact', id: 200 },
+        ],
+        ...overrides,
+    };
+}
+describe('transformAppointment', () => {
+    it('transforms a scheduled appointment with all fields', () => {
+        const result = transformAppointment(makeRawRequest(), appointmentTypes, 'America/Chicago');
+        expect(result.id).toBe('sreq_abc');
+        expect(result.status).toBe('scheduled');
+        expect(result.appointment_type).toBe('Remote Access to PC');
+        expect(result.engineer).toBe('Scout Kalra');
+        expect(result.engineer_id).toBe('agnt_1');
+        expect(result.duration_mins).toBe(30);
+        expect(result.end_user_name).toBe('John Doe');
+        expect(result.end_user_email).toBe('john@example.com');
+        expect(result.ticket_number).toBe('#12345');
+        expect(result.ticket_type).toBe('service_ticket');
+        expect(result.company_id).toBe(100);
+        expect(result.contact_id).toBe(200);
+        expect(result.start_time).toBeTruthy();
+        expect(result.start_time_local).toBeTruthy();
+        expect(result.created_at).toMatch(/^\d{4}-\d{2}-\d{2}T/);
+        expect(result.age_hours).toBeGreaterThan(0);
+    });
+    it('resolves engineer from scheduled_agents first', () => {
+        const result = transformAppointment(makeRawRequest({
+            scheduled_agents: [{ id: 'agnt_A', name: 'Agent A' }],
+            resources: [{ id: 'agnt_B', name: 'Agent B', object: 'agent' }],
+        }), appointmentTypes);
+        expect(result.engineer).toBe('Agent A');
+        expect(result.engineer_id).toBe('agnt_A');
+    });
+    it('falls back to resources when no scheduled_agents', () => {
+        const result = transformAppointment(makeRawRequest({
+            scheduled_agents: [],
+            resources: [{ id: 'agnt_B', name: 'Agent B', object: 'agent' }],
+        }), appointmentTypes);
+        expect(result.engineer).toBe('Agent B');
+    });
+    it('returns Unassigned when no agent available', () => {
+        const result = transformAppointment(makeRawRequest({
+            scheduled_agents: [],
+            resources: [{ id: 'team_1', name: 'MSP Team', object: 'team' }],
+        }), appointmentTypes);
+        expect(result.engineer).toBe('Unassigned');
+        expect(result.dispatched_from_team).toBe(true);
+        expect(result.team_name).toBe('MSP Team');
+    });
+    it('handles null start_time for pending requests', () => {
+        const result = transformAppointment(makeRawRequest({
+            status: 'sent',
+            selected_start_time: null,
+        }), appointmentTypes);
+        expect(result.start_time).toBeNull();
+        expect(result.start_time_local).toBeNull();
+    });
+    it('resolves project_ticket type', () => {
+        const result = transformAppointment(makeRawRequest({
+            associated_entities: [
+                { type: 'connectwise_psa/project_ticket', number: '#999' },
+            ],
+        }), appointmentTypes);
+        expect(result.ticket_type).toBe('project_ticket');
+        expect(result.ticket_number).toBe('#999');
+    });
+    it('handles unknown appointment type gracefully', () => {
+        const result = transformAppointment(makeRawRequest({
+            appointment_type_id: 'apty_unknown',
+        }), appointmentTypes);
+        expect(result.appointment_type).toBe('Unknown');
+    });
+    it('handles missing associated_entities', () => {
+        const result = transformAppointment(makeRawRequest({
+            associated_entities: [],
+        }), appointmentTypes);
+        expect(result.ticket_number).toBeNull();
+        expect(result.ticket_type).toBeNull();
+        expect(result.company_id).toBeNull();
+        expect(result.contact_id).toBeNull();
+    });
+});

package/build/client.js

@@ -4,17 +4,44 @@ export class TimeZestClient {
     apiKey;
     baseUrl = 'https://api.timezest.com/v1';
     appointmentTypes = new Map();
-    constructor(apiKey) {
+    maxRetries;
+    retryDelayMs;
+    constructor(apiKey, { maxRetries = 3, retryDelayMs = 1000 } = {}) {
         this.apiKey = apiKey;
+        this.maxRetries = maxRetries;
+        this.retryDelayMs = retryDelayMs;
+    }
+    async fetchWithRetry(url, config) {
+        let lastError;
+        for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+            try {
+                return await axios.get(url, config);
+            }
+            catch (error) {
+                lastError = error;
+                const status = error?.response?.status;
+                // Only retry on network errors, 429, or 5xx
+                if (status && status !== 429 && status < 500)
+                    throw error;
+                if (attempt < this.maxRetries) {
+                    const delay = status === 429
+                        ? (parseInt(error.response?.headers?.['retry-after'] || '0', 10) * 1000 || this.retryDelayMs * (attempt + 1))
+                        : this.retryDelayMs * (attempt + 1);
+                    await new Promise(r => setTimeout(r, delay));
+                }
+            }
+        }
+        throw lastError;
     }
     async fetchAllPages(endpoint, params = {}) {
         const results = [];
         let page = 1;
         let url = `${this.baseUrl}${endpoint}`;
         while (true) {
-            const response = await axios.get(url, {
+            const response = await this.fetchWithRetry(url, {
                 params: { ...params, page },
-                headers: { Authorization: `Bearer ${this.apiKey}` }
+                headers: { Authorization: `Bearer ${this.apiKey}` },
+                timeout: 30000
             });
             const data = response.data;
             // Handle both flat arrays and wrapped responses (e.g., { scheduling_requests: [...] })
@@ -48,7 +75,7 @@ export class TimeZestClient {
         try {
             const types = await this.fetchAllPages('/appointment_types');
             types.forEach((t) => {
-                this.appointmentTypes.set(t.id, t.name ?? `(unnamed – ${t.id})`);
+                this.appointmentTypes.set(t.id, t.internal_name ?? t.name ?? `(unnamed – ${t.id})`);
             });
             return this.appointmentTypes;
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "timezest-mcp",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "description": "MCP Server for TimeZest scheduling API — brings appointments, pending requests, and ticket-linked schedules to Claude.",
   "main": "build/index.js",
   "author": "Sagar Kalra",
@@ -25,17 +25,20 @@
   "scripts": {
     "build": "tsc",
     "watch": "tsc -w",
+    "test": "vitest run",
+    "test:watch": "vitest",
     "prepublishOnly": "npm run build",
     "start": "node build/index.js"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^0.6.0",
+    "@modelcontextprotocol/sdk": "^1.28.0",
     "axios": "^1.6.0",
     "date-fns": "^3.0.0",
     "date-fns-tz": "^3.0.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
-    "typescript": "^5.0.0"
+    "typescript": "^5.0.0",
+    "vitest": "^4.1.2"
   }
 }