kbarbershop/square-mcp-server

Square MCP Server v2.3 - Field Name Compatibility Fix

🎯 Fixed Issue

Timeslots were displaying as undefined because Square API was returning fields in snake_case format (e.g., start_at, appointment_segments) instead of the expected camelCase format.

✅ What's Fixed in v2.3

• Field Name Compatibility: Now handles both snake_case and camelCase field names from Square API
• Enhanced Logging: Added detailed logging to track slot formatting
• Robust Parsing: Gracefully handles API response variations
• All Previous Fixes: Maintains timezone conversion and phone formatting from v2.2

🐛 The Bug

The code was checking for slot.startAt and slot.appointmentSegments, but Square API was returning slot.start_at and slot.appointment_segments. This caused:

• displayTime to be undefined
• Timeslots not showing correctly to customers

🔧 The Fix

Added fallback field access in getAvailability():

const startAtField = slot.startAt || slot.start_at;
const appointmentSegmentsField = slot.appointmentSegments || slot.appointment_segments;

Now supports both naming conventions for maximum compatibility.

📦 Deployment

Manual Deployment to Cloud Run

gcloud run deploy square-mcp-server \
  --source https://github.com/kbarbershop/square-mcp-server \
  --region us-east4 \
  --platform managed \
  --allow-unauthenticated \
  --project website-473417

Or deploy from your local directory:

cd "/Volumes/T7/Barber/website-code/kbarbershop_ai_receptionist/square-mcp-server"
gcloud run deploy square-mcp-server \
  --source . \
  --region us-east4 \
  --platform managed \
  --allow-unauthenticated

Check Deployment Status

curl https://square-mcp-server-265357944939.us-east4.run.app/health

Should return: "version": "2.3-field-fix"

🔧 Key Features

Enhanced getAvailability Response

Each slot now includes:

• startAt: Original UTC time (for Square API booking)
• displayTime: Human-readable Eastern Time (e.g., "Tue, Oct 8, 4:30 PM")
• easternTimeISO: ISO format in Eastern Time (e.g., "2025-10-08T16:30:00-04:00")
• Slot details (duration, service ID, team member, etc.)

Example Response

{
  "success": true,
  "availableSlots": [
    {
      "startAt": "2025-10-08T20:30:00Z",
      "displayTime": "Tue, Oct 8, 4:30 PM",
      "easternTimeISO": "2025-10-08T16:30:00-04:00",
      "durationMinutes": 30,
      "serviceVariationId": "7XPUHGDLY4N3H2OWTHMIABKF",
      "teamMemberId": "TMKzhB-WjsDff5rr"
    }
  ],
  "totalSlots": 32,
  "timezone": "America/New_York (Eastern Time)",
  "note": "All times shown in Eastern Time. Use the startAt field (UTC) when creating bookings."
}

📝 Changelog

v2.3 - Field Name Fix (2025-10-08)

• ✅ Fixed undefined timeslot display bug
• ✅ Added support for both snake_case and camelCase field names
• ✅ Enhanced logging with first/last slot details
• ✅ Added validation warnings for invalid slots
• ✅ Improved error handling and debugging

v2.2 - Timezone Fix (2025-10-08)

• ✅ Added formatTimeForDisplay() helper function
• ✅ Added convertToEasternTime() helper function
• ✅ Updated getAvailability() to return formatted times
• ✅ Enhanced logging and validation
• ✅ Fixed availability display bug

v2.1 - Availability Fix (2025-10-07)

• ✅ Added checkAvailability for specific time validation

v2.0 - Phone Fix (2025-10-07)

• ✅ Fixed phone number E.164 formatting
• ✅ Added webhook endpoints for ElevenLabs

🌐 Endpoints

• POST /tools/getAvailability - Get available time slots
• POST /tools/checkAvailability - Check specific time slot
• POST /tools/createBooking - Create appointment
• POST /tools/rescheduleBooking - Reschedule appointment
• POST /tools/cancelBooking - Cancel appointment
• POST /tools/lookupBooking - Find bookings by phone
• POST /tools/generalInquiry - Get business info
• GET /health - Health check
• GET /analytics/sources - Booking source analytics

🔗 Links

• GitHub: https://github.com/kbarbershop/square-mcp-server
• Service: https://square-mcp-server-265357944939.us-east4.run.app
• Health Check: https://square-mcp-server-265357944939.us-east4.run.app/health