Microsoft Graph Calendar Port

Purpose

This is the Harbor reference integration for Microsoft Graph Calendar.

Use it when:

• building Microsoft Graph Calendar actions in Harbor
• extending the Dock / Hub Microsoft Graph Calendar entry
• teaching Codex or OpenClaw how to map a scheduling API into Harbor Ports and Harbor Actions without turning Harbor into a generic calendar proxy

Harbor Port worksheet

Product

• Product: Microsoft Graph Calendar
• Publisher slug: microsoft
• Publisher name: Microsoft
• Category: Calendar
• Tags: microsoft, graph, calendar, events, productivity

Safe Harbor Port metadata

• Kind: http_api
• Label: Microsoft Graph Calendar API
• Description: Microsoft Graph Calendar connection managed locally through Harbor.
• Base URL: https://graph.microsoft.com/
• Auth mode: header_token
• Auth header name: Authorization
• Auth token prefix: Bearer

Hidden local config

• authToken

Harbor stores the token locally only. Dock / Hub manifests must never contain it.

Harbor action design notes

Microsoft Graph Calendar is a good Harbor fit today when we stay on signed-in-user /me routes.

Good Harbor Microsoft Graph Calendar actions:

• stable GET routes for signed-in user calendar discovery and event listing
• one explicit POST route for event creation
• typed query input for event page size
• requestBodyMode: "none" for reads
• requestBodyMode: "json" for create flows
• resultMode: "json_summary" for all starter actions

Avoid for now:

• freeform calendar IDs or calendar-group traversal
• arbitrary event patch, delete, or response-management surfaces
• extra request headers such as custom Prefer settings until Harbor models them directly
• automatic publish of create actions

Starter Microsoft Graph Calendar actions

Automatic read actions

• list-calendars -> GET /v1.0/me/calendars
• list-events -> GET /v1.0/me/events

Approval-friendly write actions

• create-event -> POST /v1.0/me/events

Why these actions

These routes fit Harbor's current safe model well because they:

• stay under one fixed Microsoft Graph API origin
• use fixed signed-in-user calendar paths relative to the Harbor Port
• keep query parameters typed and reviewable through Harbor's Action Model
• keep hidden auth entirely local to Harbor Node
• avoid arbitrary full URL editing and raw query-string injection
• can be reviewed as named capabilities before publish

Action Model notes

For Microsoft Graph Calendar actions, Harbor stores explicit path templates and typed parameter metadata such as:

• /v1.0/me/calendars
• /v1.0/me/events

At execution time, callers supply values by location:

• input.query for typed query parameters
• input.body for JSON write payloads

Example event listing request:

{
  "query": {
    "$top": 25
  }
}

Example create-event request:

{
  "body": {
    "subject": "Quarterly planning",
    "start": {
      "dateTime": "2026-04-02T10:00:00",
      "timeZone": "Pacific Standard Time"
    },
    "end": {
      "dateTime": "2026-04-02T11:00:00",
      "timeZone": "Pacific Standard Time"
    },
    "location": {
      "displayName": "Conf Room 3"
    },
    "attendees": [
      {
        "emailAddress": {
          "address": "alex@example.com",
          "name": "Alex"
        },
        "type": "required"
      }
    ]
  }
}

Harbor applies the fixed route, validates the typed inputs, and keeps the underlying access token hidden.

Suggested operator workflow

1. Import the Microsoft Graph Calendar Dock entry from Dock / Hub.
2. Configure the local Microsoft Graph bearer token in Harbor Node.
3. Use list-calendars first to verify the connection.
4. Use list-events with a small $top value to confirm mailbox calendar access.
5. Keep create-event on require_approval unless there is a very deliberate local policy reason not to.

Suggested agent workflow

1. Inspect the existing Microsoft Graph Calendar Harbor Port.
2. Inspect live actions and drafts.
3. Propose additional fixed-path actions only.
4. Validate and test drafts.
5. Request publish instead of self-publishing unless Harbor explicitly allows it.

Agents should never:

• ask Harbor for the stored token
• edit hidden Microsoft Graph auth
• widen Microsoft Graph Calendar into a generic arbitrary proxy

Current update strategy

For now, Microsoft Graph Calendar updates are manual:

• update the Dock / Hub Microsoft Graph Calendar integration document in apps/hub/catalog/integrations/microsoft/microsoft-graph-calendar.json
• bump the manifest version when the action set changes materially
• re-import into Harbor or create new drafts from the updated Dock entry

Official reference starting points

• Microsoft Graph overview: https://learn.microsoft.com/en-us/graph/api/overview?view=graph-rest-1.0
• List calendars: https://learn.microsoft.com/en-us/graph/api/user-list-calendars?view=graph-rest-1.0
• List events: https://learn.microsoft.com/en-us/graph/api/user-list-events?view=graph-rest-1.0
• Create event: https://learn.microsoft.com/en-us/graph/api/user-post-events?view=graph-rest-1.0