feat(calendar): add startAfter/startBefore/subject filters to list-events

[Taranasus (taranasus)]

Motivation

The list-events tool hardcodes a start/dateTime ge '<now>' filter, so any event that has already started (or that ended in the past) is invisible to the assistant. I hit this today trying to find a calendar event that started this morning — I had to bypass the MCP and call Graph API directly to locate it. Reasonable use cases like "find that meeting from last week" or "search my calendar for events titled 'X'" are currently impossible through the MCP.

What this PR adds

Three optional parameters on list-events. They are pure additions — the schema's required array is still empty and the default behaviour with no args is unchanged.

Param	Type	Description
startAfter	ISO 8601 string	Only return events whose start is on or after this time. Replaces the default "now" lower bound when supplied.
startBefore	ISO 8601 string	Only return events whose start is strictly before this time. Combine with startAfter to bound a window.
subject	string	Case-insensitive substring match against event subject (uses Graph's contains(subject, '...')).

Backward compatibility

When all three parameters are absent, list-events builds exactly the same start/dateTime ge '<now>' filter as before. The moment ANY of the three is supplied, the implicit "now" lower bound is removed and the provided predicates are AND-ed together — that's the whole point: a caller who explicitly asks for past events should not be silently filtered down to the future.

Security

User-supplied strings are passed through the existing escapeODataString helper (' → '') before interpolation into the $filter. A test verifies that an injection-style payload like x') or '1'='1 ends up fully contained inside a single quoted-string literal and the resulting filter "skeleton" (with quoted segments stripped) contains no or keyword or = operator outside quotes.

Test coverage (test/calendar/list.test.js)

1. No-arg call still filters to start ≥ now (captured timestamp falls between two test bookends, asserting it really is "now" at call time, not a constant).
2. startAfter='2026-01-01T00:00:00Z' overrides the default filter.
3. startBefore='2026-02-01T00:00:00Z' produces a strict upper bound.
4. subject='Miele' produces contains(subject, 'Miele').
5. All three combined are AND-ed together in declaration order.
6. Single quotes in subject are escaped (skeleton-stripping check guards against or 1=1 style injection).
7. Regression guard: subject-only filter does NOT silently re-introduce the default "now" lower bound.
8. Pure unit tests on the extracted buildListEventsFilter helper covering the default-now and quote-escape paths.

Quality gates

• npm test — 757 / 757 passing (30 suites)
• npm run lint — no new errors; warnings are all pre-existing in unrelated files
• npm run format:check — clean
• Husky pre-commit hook ran lint-staged successfully

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Calendar event search now supports optional filtering by start date range (startAfter, startBefore) and subject keyword matching. Default behavior preserved—upcoming events display automatically when no filters applied. Combine filters for targeted searches.

• Tests

  • Added unit tests validating calendar event filtering functionality.

[coderabbitai]

Warning

Review limit reached

@taranasus, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 46 minutes and 39 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: e8a86ba9-35d9-492d-b075-4fefc442ce97

📥 Commits

Reviewing files that changed from the base of the PR and between 5236cf1 and 077a3dc.

📒 Files selected for processing (3)

• calendar/index.js
• calendar/list.js
• test/calendar/list.test.js

📝 Walkthrough

Walkthrough

This PR adds optional filtering parameters to calendar event listing. The tool schema is extended with startAfter, startBefore, and subject filters; a new buildListEventsFilter() helper centralizes OData filter construction with safe string escaping; and comprehensive Jest tests validate default behavior, parameter overrides, and injection prevention.

Changes

Calendar Event Filtering

Layer / File(s)	Summary
Tool contract and API schema calendar/index.js	The list-events tool description documents default "upcoming" behavior and the new filters' semantics; the JSON schema adds startAfter, startBefore, and subject as optional properties with ISO-8601 and substring-matching descriptions.
Filter building and handler integration calendar/list.js	New buildListEventsFilter(args) constructs OData-safe $filter expressions, supporting backward-compatible defaults when no filters are supplied and combining startAfter, startBefore, and subject with AND logic; the handler now uses this helper instead of hardcoding the filter, and the function is exported for direct testing.
Test coverage for filtering logic test/calendar/list.test.js	Jest tests validate handleListEvents filter generation with default "now" bounds, parameter overrides, AND-joined conditions, and single-quote escaping to prevent injection; unit tests confirm buildListEventsFilter behavior; a helper strips quoted strings to analyze filter logic outside literals.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐰 A filter blooms in spring's soft light,
With parameters bound tight and right,
OData escapes keep injections away,
Tests guard the logic day by day! 🌸

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: adding three new optional filter parameters (startAfter, startBefore, subject) to the list-events tool in the calendar module.
Docstring Coverage	✅ Passed	Docstring coverage is 80.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@calendar/index.js`:
- Around line 29-38: The schema for the query parameters currently allows any
string for startAfter and startBefore; update the calendar query/schema
definition that declares startAfter and startBefore to validate ISO 8601
datetimes at the boundary (e.g., add a JSON Schema "format": "date-time" or a
strict ISO8601 regex "pattern" to both startAfter and startBefore in
calendar/index.js) so invalid values are rejected before reaching runtime;
ensure both properties use the same validation rule and keep their existing
descriptions.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 7d3cb371-2c0e-42d1-ab08-6f26cbd2bc5c

📥 Commits

Reviewing files that changed from the base of the PR and between 080f80e and 5236cf1.

📒 Files selected for processing (3)

• calendar/index.js
• calendar/list.js
• test/calendar/list.test.js