Accept "primary" as a default-calendar alias on input (#66)

get_calendar_events emits calendarId "primary" for default-calendar
events, but the input side rejected it: with accountId + calendarId both
set, the tool validated calendarId against ListCalendarsAsync (which
never lists "primary"), warned "not found", and skipped the fetch. Even
past that, the Outlook.com/M365 providers only routed an empty calendarId
to the default calendar, so "primary" hit Me.Calendars["primary"] and
returned nothing.

Close the symmetry gap:
- GetCalendarEventsTool skips calendarId validation for the "primary"
  alias and passes it through.
- Outlook.com and M365 GetCalendarEventsAsync treat "primary" as the
  default calendar (mirrors their existing GetCalendarEventDetailsAsync).
  Google already resolves "primary" natively; ICS/JSON ignore calendarId.

Also document "primary" in the calendarId parameter description and bump
version to 1.3.7.

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: rockfordlhotka

Directory.Build.props

@@ -1,5 +1,5 @@
 <Project>
   <PropertyGroup>
-    <VersionPrefix>1.3.6</VersionPrefix>
+    <VersionPrefix>1.3.7</VersionPrefix>
   </PropertyGroup>
 </Project>

src/CalendarMcp.Core/Providers/M365ProviderService.cs

@@ -607,8 +607,10 @@ public async Task<IEnumerable<CalendarEvent>> GetCalendarEventsAsync(
 
             // Use CalendarView for date range queries (it expands recurring events)
             Microsoft.Graph.Models.EventCollectionResponse? events;
-            
-            if (string.IsNullOrEmpty(calendarId))
+
+            // "primary" is our alias for the default calendar (Graph has no such id), so treat
+            // it like an omitted calendarId — mirrors GetCalendarEventDetailsAsync below.
+            if (string.IsNullOrEmpty(calendarId) || calendarId == "primary")
             {
                 // Query the default calendar
                 events = await graphClient.Me.Calendar.CalendarView.GetAsync(config =>

src/CalendarMcp.Core/Providers/OutlookComProviderService.cs

@@ -590,8 +590,10 @@ public async Task<IEnumerable<CalendarEvent>> GetCalendarEventsAsync(
             var end = endDate ?? DateTime.UtcNow.Date.AddDays(30);
 
             Microsoft.Graph.Models.EventCollectionResponse? events;
-            
-            if (string.IsNullOrEmpty(calendarId))
+
+            // "primary" is our alias for the default calendar (Graph has no such id), so treat
+            // it like an omitted calendarId — mirrors GetCalendarEventDetailsAsync below.
+            if (string.IsNullOrEmpty(calendarId) || calendarId == "primary")
             {
                 events = await graphClient.Me.Calendar.CalendarView.GetAsync(config =>
                 {

src/CalendarMcp.Core/Tools/GetCalendarEventsTool.cs

@@ -24,7 +24,7 @@ public async Task<string> GetCalendarEvents(
         [Description("Start of the date range (ISO 8601 format, e.g. `2026-02-20`). Defaults to today.")] DateTime? startDate = null,
         [Description("End of the date range, inclusive (ISO 8601 format, e.g. `2026-02-27`). Defaults to 7 days after startDate.")] DateTime? endDate = null,
         [Description("Account ID to query, or omit to query all enabled accounts. Obtain from list_accounts.")] string? accountId = null,
-        [Description("Calendar ID to query, or omit for all calendars. Obtain from list_calendars. If accountId is omitted, calendarId is used to identify the account automatically when it exists in exactly one account.")] string? calendarId = null,
+        [Description("Calendar ID to query, or omit for all calendars. Obtain from list_calendars, or pass 'primary' for the account's default calendar (also the value returned for default-calendar events). Requires accountId when using 'primary'. If accountId is omitted, calendarId is used to identify the account automatically when it exists in exactly one account.")] string? calendarId = null,
         [Description("Maximum number of events to return per account (default 50)")] int count = 50)
     {
         var tz = TimeZoneHelper.TryGetTimeZone(timeZone);
@@ -46,7 +46,12 @@ public async Task<string> GetCalendarEvents(
         if (!string.IsNullOrEmpty(accountId))
         {
             validAccounts = new List<AccountInfo> { await ToolGuard.RequireAccountAsync(accountRegistry, accountId) };
-            validateCalendarId = !string.IsNullOrEmpty(calendarId);
+            // "primary" is a universal alias for each account's default calendar. It never
+            // appears in ListCalendarsAsync output (providers return real calendar ids), and
+            // it's what the tool emits as the calendarId for default-calendar events — so skip
+            // validation and let the provider resolve it. Validating it would wrongly warn
+            // "not found" and skip the fetch.
+            validateCalendarId = !string.IsNullOrEmpty(calendarId) && !IsPrimaryAlias(calendarId);
         }
         else if (!string.IsNullOrEmpty(calendarId))
         {
@@ -224,4 +229,12 @@ public async Task<string> GetCalendarEvents(
             throw new McpException("Failed to get calendar events.", ex);
         }
     }
+
+    /// <summary>
+    /// "primary" is the alias every provider uses for an account's default calendar, and the
+    /// calendarId the tool emits for default-calendar events. It is accepted as input but is
+    /// never returned by ListCalendarsAsync, so it must bypass calendarId validation.
+    /// </summary>
+    private static bool IsPrimaryAlias(string? calendarId) =>
+        string.Equals(calendarId, "primary", StringComparison.Ordinal);
 }

src/CalendarMcp.Tests/Tools/GetCalendarEventsToolTests.cs

@@ -230,7 +230,9 @@ public async Task GetCalendarEvents_AccountIdWithMissingCalendarId_WarnsAndRetur
         var tool = new GetCalendarEventsTool(regExp.Instance(), factExp.Instance(),
             NullLogger<GetCalendarEventsTool>.Instance);
 
-        var result = await tool.GetCalendarEvents(TestTimeZone, Start, End, "acc-1", "primary");
+        // Use a genuinely non-existent id here ("primary" is a default-calendar alias that is
+        // intentionally accepted without validation — see the primary-alias test).
+        var result = await tool.GetCalendarEvents(TestTimeZone, Start, End, "acc-1", "cal-missing");
         var doc = JsonDocument.Parse(result);
 
         Assert.AreEqual(0, doc.RootElement.GetProperty("events").GetArrayLength());
@@ -239,7 +241,7 @@ public async Task GetCalendarEvents_AccountIdWithMissingCalendarId_WarnsAndRetur
         Assert.AreEqual(1, warnings.GetArrayLength());
         Assert.AreEqual("acc-1", warnings[0].GetProperty("accountId").GetString());
         var warningText = warnings[0].GetProperty("warning").GetString();
-        Assert.IsTrue(warningText!.Contains("primary"));
+        Assert.IsTrue(warningText!.Contains("cal-missing"));
         Assert.IsTrue(warningText.Contains("acc-1"));
         Assert.IsTrue(warningText.Contains("list_calendars"));
 
@@ -248,6 +250,51 @@ public async Task GetCalendarEvents_AccountIdWithMissingCalendarId_WarnsAndRetur
         provExp.Verify();
     }
 
+    [TestMethod]
+    public async Task GetCalendarEvents_AccountIdWithPrimaryAlias_SkipsValidationAndReturnsEvents()
+    {
+        // "primary" is the default-calendar alias and is never returned by ListCalendarsAsync,
+        // so it must bypass calendarId validation rather than warn "not found". The provider
+        // receives "primary" and resolves it to the default calendar.
+        var account = TestData.CreateAccount(id: "rockyl", provider: "outlook.com");
+        var events = new List<CalendarEvent>
+        {
+            TestData.CreateEvent(id: "ev1", accountId: "rockyl", calendarId: "primary", subject: "Meeting",
+                start: new DateTime(2025, 1, 10, 15, 0, 0, DateTimeKind.Utc),
+                end: new DateTime(2025, 1, 10, 16, 0, 0, DateTimeKind.Utc))
+        };
+
+        var regExp = new IAccountRegistryCreateExpectations();
+        regExp.Setups.GetAccountAsync("rockyl")
+            .ReturnValue(Task.FromResult<AccountInfo?>(account));
+
+        var provExp = new IProviderServiceCreateExpectations();
+        // ListCalendarsAsync must NOT be called for the "primary" alias — no validation needed.
+        provExp.Setups.GetCalendarEventsAsync(
+            "rockyl", "primary", Arg.Any<DateTime?>(), Arg.Any<DateTime?>(),
+            Arg.Any<int>(), Arg.Any<CancellationToken>())
+            .ReturnValue(Task.FromResult<IEnumerable<CalendarEvent>>(events));
+
+        var factExp = new IProviderServiceFactoryCreateExpectations();
+        factExp.Setups.GetProvider("outlook.com").ReturnValue(provExp.Instance());
+
+        var tool = new GetCalendarEventsTool(regExp.Instance(), factExp.Instance(),
+            NullLogger<GetCalendarEventsTool>.Instance);
+
+        var result = await tool.GetCalendarEvents(TestTimeZone, Start, End, "rockyl", "primary");
+        var doc = JsonDocument.Parse(result);
+
+        Assert.AreEqual(1, doc.RootElement.GetProperty("events").GetArrayLength());
+        Assert.AreEqual("ev1", doc.RootElement.GetProperty("events")[0].GetProperty("id").GetString());
+        Assert.AreEqual("primary", doc.RootElement.GetProperty("events")[0].GetProperty("calendarId").GetString());
+        // No "not found" warning for the primary alias.
+        Assert.AreEqual(JsonValueKind.Null, doc.RootElement.GetProperty("warnings").ValueKind);
+
+        regExp.Verify();
+        factExp.Verify();
+        provExp.Verify();
+    }
+
     [TestMethod]
     public async Task GetCalendarEvents_AccountIdWithValidCalendarId_ReturnsEventsNoWarning()
     {