Calendar Integrations

Relevant source files

The following files were used as context for generating this wiki page:

• src/lib/calendar.ts
• src/lib/calendar.test.ts
• src/types.ts
• src/mcp/tools.ts
• src/routes/settings.tsx
• src/routes/agents.tsx
• README.md

Calendar Integrations provide a read-only interface between Model Context Protocol (MCP) agents and external calendar providers, specifically Google Calendar and Microsoft Outlook/365. This system allows AI agents to list available calendars and retrieve event details within a specified timeframe while maintaining strict security boundaries.

The integration focuses on privacy by enforcing read-only access and sanitizing all retrieved content. It prevents agents from creating, editing, or deleting events, or responding to invitations.

Sources: README.md:144-148, src/lib/calendar.ts:7-14

Architecture and Data Flow

The system acts as a secure bridge, translating provider-specific API responses into a unified internal format used by MCP tools. It handles authentication via OAuth tokens and enforces permission checks at the agent level before fetching data from external APIs.

The following diagram illustrates the flow of a calendar request from an MCP agent through e-zer0 to the provider.

The diagram shows the request lifecycle, highlighting the authentication and sanitization stages.
Sources: src/mcp/tools.ts:167-208, src/lib/calendar.ts:7-14

Security and Permissions

Read-Only Enforcement

Calendar access is strictly read-only. The system does not expose tools for event creation, modification, or RSVP. OAuth scopes are requested specifically for read access:

• Google: calendar.calendarlist.readonly and calendar.events.readonly.
• Microsoft: Calendars.Read.

Sources: README.md:144-148, src/lib/calendar.test.ts:13-24

Agent-Level Grants

Calendar permissions are distinct from email permissions. An administrator must explicitly grant an agent access to "Calendar (read-only)" for specific accounts in the Agents > Edit interface.

Permission Type	Description	File Reference
Email Access	Allows reading and managing emails.	src/types.ts:63-66
Calendar Access	Allows reading calendar lists and events.	src/types.ts:172-175

Sources: README.md:149-156, src/routes/agents.tsx:18-68

Content Sanitization

All calendar metadata, including event titles, descriptions, and locations, pass through sanitizeEmailContent(). This process redacts PII and detects potential prompt injection attempts before the data reaches the agent.

Sources: src/mcp/tools.ts:182-185, src/mcp/tools.ts:200-205

Core Data Structures

The system uses unified interfaces to represent calendar data regardless of the backend provider.

export interface CalendarSummary {
    id: string;
    name: string;
    primary: boolean;
    time_zone?: string;
}

export interface CalendarEvent {
    id: string;
    title: string;
    description: string;
    location: string;
    start: string; // ISO 8601 or Date string
    end: string;   // ISO 8601 or Date string
    time_zone?: string;
    all_day: boolean;
    cancelled: boolean;
}

Sources: src/types.ts:140-156

Provider Implementation Details

Google Calendar

The integration interacts with the Google Calendar V3 API.

• Endpoint for Events: calendars/{calendarId}/events.
• Features: Expands recurring events into single occurrences using singleEvents=true.
• Time Handling: All-day events are identified by the presence of a date field without a time component.

Sources: src/lib/calendar.ts:80-97, src/lib/calendar.test.ts:32-52

Microsoft Outlook/365

The integration interacts with the Microsoft Graph API.

• Endpoint for Events: calendars/{calendarId}/calendarView.
• Features: Uses calendarView to retrieve occurrences of recurring meetings within the requested window.
• Time Handling: Requests times in UTC via headers (outlook.timezone="UTC") but retains the originalStartTimeZone in the returned event data.

Sources: src/lib/calendar.ts:100-116, src/lib/calendar.test.ts:54-79

MCP Tools

Three primary tools are exposed to agents for calendar interaction.

Tool Name	Purpose	Parameters
list_calendar_accounts	Lists accounts the agent is permitted to access.	None
list_calendars	Lists all calendars for a specific account.	accountId, pageToken
get_calendar_events	Retrieves events for a specific calendar.	accountId, calendarId, start, end, count, pageToken

Sources: src/mcp/tools.ts:161-208

Database Schema

The relationship between MCP clients (agents) and email accounts for calendar access is stored in a dedicated join table.

CREATE TABLE mcp_client_calendar_accounts (
    mcp_client_id INTEGER NOT NULL,
    email_account_id INTEGER NOT NULL,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    PRIMARY KEY (mcp_client_id, email_account_id),
    FOREIGN KEY (mcp_client_id) REFERENCES mcp_clients(id),
    FOREIGN KEY (email_account_id) REFERENCES email_accounts(id)
);

Sources: src/mcp/tools.ts:161-166, src/routes/agents.tsx:117-133

Summary

Calendar Integrations in e-zer0 provide a secure, read-only window into Google and Microsoft calendars for AI agents. By decoupling calendar permissions from email access and enforcing strict sanitization, the system ensures that agents can reason about schedules without compromising user credentials or sensitive data.