fix: correct MCP tool schemas against Cal.com API v2 spec

[sahitya-chandra]

Summary

Audited all MCP tool schemas against the Cal.com API v2 OpenAPI spec (calcom/cal) and fixed every confirmed mismatch:

schedules.ts

• availability slots: Changed day (singular string) → days (array of day-name strings) to match ScheduleAvailabilityInput_2024_06_11. This was causing 400 errors on every schedule create/update with availability.
• overrides: Made startTime and endTime required (spec: required: ["date", "startTime", "endTime"]). To mark a date unavailable, set both to "00:00".

event-types.ts

• bookingLimitsCount: Replaced z.record() with PER_DAY/PER_WEEK description → typed z.object({ day, week, month, year }) matching BookingLimitsCount_2024_06_14.
• bookingWindow: Replaced z.record() → typed z.object({ type: enum["businessDays"|"calendarDays"|"range"], value, rolling }) matching BookingWindow_2024_06_14.
• destinationCalendar: Replaced z.record() → typed z.object({ integration, externalId }) matching DestinationCalendar_2024_06_14.
• recurrence description: Corrected example field count → occurrences (matching Recurrence_2024_06_14).

bookings.ts

• allowConflicts / allowBookingOutOfBounds descriptions: Clarified these are host-only and ignored for non-hosts.

Verification

• All changes verified against calcom/cal source types (packages/platform/types/)
• Full test suite passes: 125 tests across 10 files

---

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR that start with 'DevinAI' or '@devin'.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
cal-companion-chat	Ignored		Apr 9, 2026 0:51am

[devin-ai-integration]

Devin Review found 1 potential issue.

View 4 additional findings in Devin Review.

[devin-ai-integration]

🔴 bookingWindow schema rejects { disabled: true }, breaking ability to remove booking window restrictions

The bookingWindow field in both createEventTypeSchema and updateEventTypeSchema was changed from z.record(z.unknown()) (which accepted any object, including { disabled: true }) to a z.object with type and value as required fields. According to the OpenAPI spec (docs/api-reference/v2/openapi.json), bookingWindow accepts a oneOf that includes Disabled_2024_06_14 (i.e. { disabled: true }) to reset/remove a previously configured booking window. With the new strict schema, passing { disabled: true } will fail zod validation because required fields type and value are missing. This is a regression — users can no longer disable booking windows through the MCP tool. The mobile app actively uses this pattern at apps/mobile/components/event-type-detail/utils/buildPartialUpdatePayload.ts:641.

Prompt for agents

The bookingWindow field in both createEventTypeSchema and updateEventTypeSchema now uses z.object with required type and value fields, which makes it impossible to pass { disabled: true } to reset/remove a booking window. The Cal.com API v2 spec uses a oneOf that includes the Disabled_2024_06_14 variant ({ disabled: true }) alongside the BusinessDays/CalendarDays/Range window variants.

To fix this, the zod schema should use z.union (or z.discriminatedUnion) to accept either the current window object OR a disabled object. For example:

bookingWindow: z.union([
  z.object({
    type: z.enum(["businessDays", "calendarDays", "range"]),
    value: z.union([z.number(), z.array(z.string())]),
    rolling: z.boolean().optional(),
  }),
  z.object({ disabled: z.literal(true) }),
]).optional()

This needs to be applied in both createEventTypeSchema (around line 105) and updateEventTypeSchema (around line 220) in apps/mcp-server/src/tools/event-types.ts. The corresponding TypeScript type annotations for the params of createEventType and updateEventType functions should also be updated to include the disabled variant.

---

Was this helpful? React with 👍 or 👎 to provide feedback.