timezest-mcp 1.0.0

package/build/client.js

@@ -0,0 +1,68 @@
+import axios from 'axios';
+import { subDays, addDays, getUnixTime } from 'date-fns';
+export class TimeZestClient {
+    apiKey;
+    baseUrl = 'https://api.timezest.com/v1';
+    appointmentTypes = new Map();
+    constructor(apiKey) {
+        this.apiKey = apiKey;
+    }
+    async fetchAllPages(endpoint, params = {}) {
+        const results = [];
+        let page = 1;
+        let url = `${this.baseUrl}${endpoint}`;
+        while (true) {
+            const response = await axios.get(url, {
+                params: { ...params, page },
+                headers: { Authorization: `Bearer ${this.apiKey}` }
+            });
+            const data = response.data;
+            if (Array.isArray(data)) {
+                results.push(...data);
+                if (data.length < 50)
+                    break; // TimeZest pagination limit
+            }
+            else {
+                // Unexpected format
+                break;
+            }
+            page++;
+        }
+        return results;
+    }
+    async getAppointmentTypes() {
+        if (this.appointmentTypes.size > 0)
+            return this.appointmentTypes;
+        try {
+            const types = await this.fetchAllPages('/appointment_types');
+            types.forEach((t) => {
+                this.appointmentTypes.set(t.id, t.name);
+            });
+            return this.appointmentTypes;
+        }
+        catch (error) {
+            console.error('Error fetching appointment types:', error);
+            return new Map();
+        }
+    }
+    /**
+     * Fetches the standard 45-day window (14 days back, 30 forward) by created_at.
+     */
+    async getStandardWindowRequests() {
+        const now = new Date();
+        const start = subDays(now, 14);
+        const end = addDays(now, 30);
+        // API limits filters to created_at
+        const params = {
+            created_at_after: getUnixTime(start),
+            created_at_before: getUnixTime(end)
+        };
+        try {
+            return await this.fetchAllPages('/scheduling_requests', params);
+        }
+        catch (error) {
+            console.error('Error fetching scheduling requests:', error);
+            return [];
+        }
+    }
+}

package/build/index.js

@@ -0,0 +1,254 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { TimeZestClient } from "./client.js";
+import { transformAppointment } from "./utils/transform.js";
+import { matchEngineer, filterByDateRange } from "./utils/filter.js";
+import { format, parseISO, isSameDay, formatDistanceToNow } from 'date-fns';
+import { formatInTimeZone } from 'date-fns-tz';
+const API_KEY = process.env.TIMEZEST_API_KEY || '';
+if (!API_KEY) {
+    process.stderr.write("Error: TIMEZEST_API_KEY is required.\n");
+    process.exit(1);
+}
+const client = new TimeZestClient(API_KEY);
+const server = new Server({
+    name: "timezest-mcp",
+    version: "1.0.0",
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+const TOOLS = [
+    {
+        name: "get_todays_appointments",
+        description: "The morning briefing tool. Returns confirmed appointments for today grouped by engineer, with pending unbooked requests listed separately.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                timezone: { type: "string", description: "Default: America/Chicago" }
+            }
+        }
+    },
+    {
+        name: "list_appointments",
+        description: "Flexible query across any date range with optional engineer and status filters.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                start_date: { type: "string", description: "YYYY-MM-DD" },
+                end_date: { type: "string", description: "YYYY-MM-DD" },
+                engineer_name: { type: "string", description: "Partial match, case-insensitive" },
+                status: { type: "string", enum: ["scheduled", "sent", "new", "cancelled"] },
+                timezone: { type: "string", description: "Default: America/Chicago" }
+            },
+            required: ["start_date", "end_date"]
+        }
+    },
+    {
+        name: "get_engineer_schedule",
+        description: "All upcoming appointments for a named engineer, sorted by time.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                engineer_name: { type: "string" },
+                days_ahead: { type: "number", default: 7 },
+                include_pending: { type: "boolean", default: true }
+            },
+            required: ["engineer_name"]
+        }
+    },
+    {
+        name: "list_pending_requests",
+        description: "All unbooked invitations (sent and new). Returns age in hours/days.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                days_back: { type: "number", default: 14 },
+                engineer_name: { type: "string" },
+                older_than_hours: { type: "number" }
+            }
+        }
+    },
+    {
+        name: "find_appointment_by_ticket",
+        description: "Find appointments linked to a ConnectWise ticket number.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                ticket_number: { type: "string", description: "e.g. 964400 or #964400" }
+            },
+            required: ["ticket_number"]
+        }
+    },
+    {
+        name: "get_appointment_types",
+        description: "List all appointment type definitions.",
+        inputSchema: { type: "object", properties: {} }
+    },
+    {
+        name: "get_appointment_stats",
+        description: "Aggregate summary of appointment data.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                days_back: { type: "number", default: 14 },
+                days_forward: { type: "number", default: 30 }
+            }
+        }
+    },
+    {
+        name: "list_cancelled_appointments",
+        description: "Cancelled requests with scheduling URLs for rebooking.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                days_back: { type: "number", default: 7 },
+                engineer_name: { type: "string" }
+            }
+        }
+    }
+];
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: TOOLS,
+}));
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    const appointmentTypes = await client.getAppointmentTypes();
+    const rawRequests = await client.getStandardWindowRequests();
+    const tz = args?.timezone || process.env.TIMEZEST_DEFAULT_TZ || 'America/Chicago';
+    const all = rawRequests.map(r => transformAppointment(r, appointmentTypes, tz));
+    switch (name) {
+        case "get_todays_appointments": {
+            const today = new Date();
+            const scheduled = all.filter(a => a.status === 'scheduled' && a.start_time && isSameDay(parseISO(a.start_time), today));
+            const pending = all.filter(a => (a.status === 'sent' || a.status === 'new'));
+            const grouped = {};
+            scheduled.forEach(s => {
+                if (!grouped[s.engineer])
+                    grouped[s.engineer] = [];
+                grouped[s.engineer].push(`${s.start_time_local} ${s.appointment_type} - ${s.end_user_name}, ${s.ticket_number}`);
+            });
+            let response = `Today's Briefing (${formatInTimeZone(today, tz, 'yyyy-MM-dd')})\n\nConfirmed:\n`;
+            if (Object.keys(grouped).length === 0)
+                response += "  None\n";
+            for (const [eng, apps] of Object.entries(grouped)) {
+                response += `  ${eng}:\n`;
+                apps.forEach(a => response += `    ${a}\n`);
+            }
+            response += `\nPending (Not yet booked):\n`;
+            if (pending.length === 0)
+                response += "  None\n";
+            pending.forEach(p => {
+                response += `  ${p.engineer} — ${p.end_user_name} (${p.status}) — sent ${format(parseISO(p.created_at), 'MMM dd')} [${formatDistanceToNow(parseISO(p.created_at))} old]\n`;
+            });
+            return { content: [{ type: "text", text: response }] };
+        }
+        case "list_appointments": {
+            const start = args?.start_date;
+            const end = args?.end_date;
+            const engName = args?.engineer_name;
+            const status = args?.status;
+            let filtered = all;
+            if (start && end)
+                filtered = filterByDateRange(filtered, start, end);
+            if (engName)
+                filtered = filtered.filter(a => matchEngineer(a, engName));
+            if (status)
+                filtered = filtered.filter(a => a.status === status);
+            return { content: [{ type: "text", text: JSON.stringify(filtered, null, 2) }] };
+        }
+        case "get_engineer_schedule": {
+            const engName = args?.engineer_name;
+            const includePending = args?.include_pending !== false;
+            let filtered = all.filter(a => matchEngineer(a, engName));
+            if (!includePending)
+                filtered = filtered.filter(a => a.status === 'scheduled');
+            filtered.sort((a, b) => {
+                const timeA = a.start_time || a.created_at;
+                const timeB = b.start_time || b.created_at;
+                return timeA.localeCompare(timeB);
+            });
+            return { content: [{ type: "text", text: JSON.stringify(filtered, null, 2) }] };
+        }
+        case "list_pending_requests": {
+            const engName = args?.engineer_name;
+            const hours = args?.older_than_hours;
+            let pending = all.filter(a => a.status === 'sent' || a.status === 'new');
+            if (engName)
+                pending = pending.filter(a => matchEngineer(a, engName));
+            if (hours)
+                pending = pending.filter(a => a.age_hours >= hours);
+            return { content: [{ type: "text", text: JSON.stringify(pending, null, 2) }] };
+        }
+        case "find_appointment_by_ticket": {
+            const tNum = (args?.ticket_number).replace('#', '');
+            const filtered = all.filter(a => a.ticket_number?.replace('#', '') === tNum);
+            return { content: [{ type: "text", text: JSON.stringify(filtered, null, 2) }] };
+        }
+        case "get_appointment_types": {
+            const sorted = Array.from(appointmentTypes.entries()).sort((a, b) => a[1].localeCompare(b[1]));
+            let text = "ID | Name\n---|---\n";
+            sorted.forEach(([id, name]) => {
+                text += `${id} | ${name}\n`;
+            });
+            return { content: [{ type: "text", text }] };
+        }
+        case "get_appointment_stats": {
+            const stats = {
+                total: all.length,
+                by_status: { scheduled: 0, sent: 0, new: 0, cancelled: 0 },
+                by_engineer: {},
+                today: { confirmed: 0, pending: 0, total_minutes: 0 },
+                oldest_pending_days: 0,
+                type_breakdown: {}
+            };
+            const today = new Date();
+            all.forEach(a => {
+                // @ts-ignore
+                if (stats.by_status[a.status] !== undefined)
+                    stats.by_status[a.status]++;
+                if (!stats.by_engineer[a.engineer])
+                    stats.by_engineer[a.engineer] = { scheduled: 0, pending: 0 };
+                if (a.status === 'scheduled')
+                    stats.by_engineer[a.engineer].scheduled++;
+                else if (a.status === 'sent' || a.status === 'new')
+                    stats.by_engineer[a.engineer].pending++;
+                if (a.status === 'scheduled' && a.start_time && isSameDay(parseISO(a.start_time), today)) {
+                    stats.today.confirmed++;
+                    stats.today.total_minutes += a.duration_mins;
+                }
+                else if ((a.status === 'sent' || a.status === 'new') && isSameDay(parseISO(a.created_at), today)) {
+                    stats.today.pending++;
+                }
+                if (a.status === 'sent' || a.status === 'new') {
+                    const days = Math.floor(a.age_hours / 24);
+                    if (days > stats.oldest_pending_days)
+                        stats.oldest_pending_days = days;
+                }
+                stats.type_breakdown[a.appointment_type] = (stats.type_breakdown[a.appointment_type] || 0) + 1;
+            });
+            return { content: [{ type: "text", text: JSON.stringify(stats, null, 2) }] };
+        }
+        case "list_cancelled_appointments": {
+            const engName = args?.engineer_name;
+            let cancelled = all.filter(a => a.status === 'cancelled');
+            if (engName)
+                cancelled = cancelled.filter(a => matchEngineer(a, engName));
+            return { content: [{ type: "text", text: JSON.stringify(cancelled, null, 2) }] };
+        }
+        default:
+            throw new Error(`Unknown tool: ${name}`);
+    }
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    process.stderr.write("TimeZest MCP Server started.\n");
+}
+main().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+});

package/build/utils/filter.js

@@ -0,0 +1,20 @@
+import { isWithinInterval, parseISO } from 'date-fns';
+export function matchEngineer(appointment, query) {
+    const normQuery = query.toLowerCase();
+    const engineerName = appointment.engineer.toLowerCase();
+    if (engineerName.includes(normQuery))
+        return true;
+    if (appointment.team_name?.toLowerCase().includes(normQuery))
+        return true;
+    return false;
+}
+export function filterByDateRange(appointments, startDate, endDate) {
+    const start = parseISO(startDate);
+    const end = parseISO(endDate);
+    return appointments.filter(a => {
+        if (!a.start_time)
+            return false;
+        const date = parseISO(a.start_time);
+        return isWithinInterval(date, { start, end });
+    });
+}

package/build/utils/transform.js

@@ -0,0 +1,49 @@
+import { formatInTimeZone } from 'date-fns-tz';
+import { differenceInHours, fromUnixTime } from 'date-fns';
+export function transformAppointment(raw, appointmentTypes, timezone = 'America/Chicago') {
+    const createdAt = fromUnixTime(raw.created_at);
+    const updatedAt = fromUnixTime(raw.updated_at);
+    const startTime = raw.selected_start_time ? fromUnixTime(raw.selected_start_time) : null;
+    // Engineer logic as per implementation plan
+    let engineer = 'Unassigned';
+    let engineerId = 'unassigned';
+    if (raw.scheduled_agents && raw.scheduled_agents.length > 0) {
+        engineer = raw.scheduled_agents[0].name;
+        engineerId = raw.scheduled_agents[0].id;
+    }
+    else if (raw.resources && raw.resources.length > 0) {
+        // Only use resources for assignment name if it is an agent
+        const firstResource = raw.resources[0];
+        if (firstResource.object === 'agent') {
+            engineer = firstResource.name;
+            engineerId = firstResource.id;
+        }
+    }
+    const dispatchedFromTeam = raw.resources?.some((r) => r.object === 'team') ?? false;
+    const teamName = raw.resources?.find((r) => r.object === 'team')?.name;
+    // Ticket logic
+    const ticket = raw.associated_entities?.find((e) => e.type === 'connectwise_psa/service_ticket' || e.type === 'connectwise_psa/project_ticket');
+    return {
+        id: raw.id,
+        status: raw.status,
+        appointment_type: appointmentTypes.get(raw.appointment_type_id) ?? 'Unknown',
+        appointment_type_id: raw.appointment_type_id,
+        engineer,
+        engineer_id: engineerId,
+        dispatched_from_team: dispatchedFromTeam,
+        team_name: teamName,
+        start_time: startTime ? startTime.toISOString() : null,
+        start_time_local: startTime ? formatInTimeZone(startTime, timezone, 'yyyy-MM-dd h:mm a zzz') : null,
+        duration_mins: raw.duration_mins,
+        end_user_name: raw.end_user_name,
+        end_user_email: raw.end_user_email,
+        ticket_number: ticket?.number ?? null,
+        ticket_type: ticket?.type === 'connectwise_psa/service_ticket' ? 'service_ticket' : (ticket?.type === 'connectwise_psa/project_ticket' ? 'project_ticket' : null),
+        company_id: raw.associated_entities?.find((e) => e.type === 'connectwise_psa/company')?.id ?? null,
+        contact_id: raw.associated_entities?.find((e) => e.type === 'connectwise_psa/contact')?.id ?? null,
+        scheduling_url: raw.scheduling_url,
+        created_at: createdAt.toISOString(),
+        updated_at: updatedAt.toISOString(),
+        age_hours: differenceInHours(new Date(), createdAt)
+    };
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "timezest-mcp",
+  "version": "1.0.0",
+  "description": "MCP Server for TimeZest scheduling API",
+  "main": "build/index.js",
+  "type": "module",
+  "bin": {
+    "timezest-mcp": "build/index.js"
+  },
+  "files": [
+    "build"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "watch": "tsc -w",
+    "prepublishOnly": "npm run build",
+    "start": "node build/index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^0.6.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"
+  }
+}