meinKontextDocs
Navigation & search

Plugins

Calendar

Plan appointments and work blocks, optionally linked to tasks.

Calendar holds appointments, all-day events and planned work blocks in your meinKontext context. It works on its own. With Tasks enabled, it can connect planned time to a task without duplicating that task.

Workspaces in the browser

Use the page header to select one of your personal Workspaces. All content shows everything you may access, including content without a workspace assignment. An empty workspace stays empty. Manage assignments under Workspaces. The selection also applies when navigating, searching and exporting within the plugin. Save unfinished changes before switching workspaces; switching closes the previous editors.

A workspace says where content lives and where an agent works; a bucket says who else may use it. The workspace selection in the browser is not a grant: it widens neither access rights nor MCP credentials. More about workspaces.

Your first calendar

  1. Enable Kalender / Calendar in Account → Plugins (/account/plugins). Activation requires organization administration; it gives no access to other people's calendars.
  2. Open Calendar (/account/calendar) and create a named calendar. It starts private unless this workspace's calendars are shared; then it is shared with the same people.
  3. Create an appointment. Choose its date, time zone, start/end time and whether it is a draft or confirmed.
  4. Week is the default view. Click an empty slot or drag a time range, then enter the title and save in the side editor. Drag editable events to move them; drag their bottom edge to resize. Undo restores the previous time only if no newer edit has superseded it.
  5. Switch between week, month and agenda. Small screens use an agenda. The New event button and editor time fields provide alternatives to dragging. Expand the filters to select status, time zone or search text; which calendars you see is decided in the calendar list on the left.
  6. Reconnect an existing MCP client after activation, then ask it to load plugin_context for meinkontext.calendar.

Manage your calendars

The list left of the grid (a fold-out above it on narrow screens) holds every calendar you can read: My calendars, Shared with me, derived calendars such as birthdays, and an archive group.

  • The coloured dot before a name shows or hides that calendar; Alt-click shows only this one, "Show all" brings the rest back. Hidden calendars stay hidden on the next visit; cal= in the URL is a one-off view you can share.
  • The star marks the default calendar: new events land there unless you pick another. "Make default" sits in the ⋯ menu of any calendar you may write to. The default, the hidden list and your own colours for shared calendars are saved per workspace, so a work workspace and a private one keep separate selections (a private record that only you can read, next to the workspace's calendars).
  • Click a name to open its settings in the side panel: name (only the person who created the calendar can rename it), colour from the eight palette colours, description, default time zone and the duration a click into an empty slot reserves. Every event carries its calendar's colour; a work block is dashed and hatched, a draft outlined, a cancelled event struck through.
  • Filing (workspace assignment) and Sharing (members and bucket links, moved here from the event page) live in the same panel. A calendar is an ordinary record of the Calendar plugin: moving it to another workspace takes its events along. Sharing applies to the calendars that live together in the workspace; the panel names them and says when it also covers calendars created later. A calendar from before this update that was shared on its own never passes its share to a new calendar.
  • Archive replaces delete: an archived calendar leaves the list, its events stay readable and searchable, new events are refused, shares stay as they are. Restore it from the archive group. There is no delete.
  • + New calendar at the end of your own calendars creates one with the next free colour. It starts private unless this workspace's calendars are shared; then it is shared with the same people.
  • The arrow at the top of the list folds it to a slim strip and brings it back; the grid takes the width. The fold is remembered with your other calendar settings, per workspace.

A reader of someone else's calendar can only choose a personal colour and hide it; the owner sees no change.

Example client request: “Create a draft appointment in my Pilot calendar on 30 September 2026, 10:00–11:00 Europe/Berlin, title Proposal review.”

This creates a record in meinKontext. It does not send an invitation outside meinKontext, reserve another person's attendance or synchronize an external calendar. Overlapping appointments are permitted.

Time rules that matter

InputMeaning
Timed eventExact UTC start/end plus a named IANA zone, such as Europe/Berlin.
Local web/MCP inputConverted inside Calendar using the chosen zone, not a guessed model offset or the browser/server zone.
All-day formThe form asks for the first and inclusive last day.
All-day file/MCPendDateExclusive is the following day. A 2 October event ends at 2026-10-03.
Query[from, to) date boundaries in the requested zone; overlapping events are returned. The window is at most 366 days.

End must be after start. During daylight-saving changes, a skipped local time is invalid and a repeated local time needs a valid explicit offset. Ask for clarification; do not silently move a meeting. Changing the display time zone does not change its stored instant.

Edit, cancel, archive and restore

Open the event to edit its description, place, time or status. Draft and confirmed are different states; there is no automatic confirmation. Canceling retains the record. Canceled events are excluded from default query results; select canceled status to find them.

Cancel before archiving. Archive and restore require the current revision, as do edits. Restoring an archived event preserves its identity and status; it does not automatically confirm or reschedule it. Use the exact record ID via MCP if an archived record is not in the current calendar view.

Schedule work for a task

text
Tasks                                  Calendar
“Review offer” ←── live reference ──── “Focus block, 10:00–11:30”
due 2 October                          30 September, Europe/Berlin
  1. Enable both compatible plugins in the same owner organization.
  2. Open a task you can read and select Plan work time / Arbeitszeit einplanen.
  3. Choose a calendar you can write, start/end time and status, then save.
  4. The new event links to the task. The task detail shows linked events you can currently read.

The event owns the one taskRef connection. The task's deadline, assignment, source references, status and revision remain unchanged. A task can have several work blocks; each event has at most one linked task. You can unlink it without deleting either record. Task completion does not complete or cancel Calendar records.

SituationResult
Calendar onlyAppointments and work blocks work; no task linking.
Tasks onlyTasks and due dates work; no Calendar scheduling controls.
Both compatible and enabledLink/schedule if you can read the task and write the event.
Tasks disabled laterCalendar remains usable; independent edits and unlinking work. New links and link replays fail.
Calendar disabled laterTasks remains usable; Calendar writes stop, authorized Calendar reads/exports remain possible.
Task access revokedIts details cannot be resolved through the link; the calendar must not substitute a cached task title.
Different owner organizationsLinking is rejected, even if you can separately access both records.

The task detail currently previews up to ten authorized, non-canceled linked events. It links to Calendar for further inspection. These are optional contract-based features; neither plugin has a required dependency on the other.

Share a calendar safely

Open the calendar's settings panel (click its name in the calendar list) to grant reader/editor roles to members or to link the calendar to a shared bucket. New events follow that live container link, subject to protected parents and exclusions. A reader cannot edit events. An editor of a calendar cannot attach a private task they cannot read.

Calendar access does not grant task access, and task access does not grant Calendar access. To collaborate on both, grant each separately. Sharing a calendar is the precondition for inviting someone: only a person who can read the calendar can be invited. Participants and replies (0.0.6): an editor invites a person the calendar is shared with (event.invite, the people calendar_participants lists); only that person answers (event.respond: accepted, tentative, declined), never a managed agent. The answer writes into the event and files the meeting in the person's own calendar as an event linked to it, so both calendars show it; declining cancels that record. A pending invitation is an open item for the person until the event ends. Changing time or location asks every participant again. Nothing is sent outside meinKontext. Agent-to-agent negotiation is not implemented here.

Use an independent agent account

After authenticating that account with personal OAuth, call list_plugins, then plugin_configure({"plugin_id":"meinkontext.calendar","enabled":true}) as its organization owner/admin. Reconnect if the client caches tools. Create collections and use the workflow below entirely through MCP.

To share selected context with another existing account: create_bucket, add_bucket_member with the exact account email, plugin_access to discover the collection's domain roles, then plugin_link_bucket with a suitable role. This shares the whole collection, including future records. The recipient discovers both its own and shared collections, using each returned owner organization for subsequent calls. Receiving a collection grants neither custody nor the right to share it onward.

Use plugin_set_access for direct grants/exclusions to members of the same organization. Use remove_bucket_member to revoke a recipient's bucket access or plugin_link_bucket with role_id: null to unshare a collection. These changes leave the recipient's private context intact. Restricted import credentials cannot administer plugins or sharing.

MCP walkthrough

Load the Calendar guide with plugin_context, discover calendars with calendar_collections, and reuse the returned calendar IDs as collection_id (the tool names keep their historical spelling; a calendar is a record, and a new event files under the calendar you name). Each entry carries the calendar's colour, description, default zone and default duration, archived, and isDefault for your default calendar in the selected workspace. Use owner_organization_id from discovery for another owner's shared calendar. calendar_create_collection creates a calendar when requested, optionally with a colour. It starts private unless the workspace's calendars are shared; then it is shared with the same people, and the result says so (shared: true with a note to pass on). calendar_manage_collection renames (title), changes the profile (color, description, zone, default_duration_minutes), archives or restores a calendar, on explicit request only; it is not available to managed agents.

Call calendar_command, replacing the collection placeholder:

json
{
  "collection_id": "<returned-calendar-id>",
  "idempotency_key": "proposal-review-2026-09-30-1",
  "command": {
    "type": "event.save", "id": null,
    "title": "Proposal review", "description": "", "location": "",
    "kind": "meeting", "status": "draft",
    "time": {
      "kind": "local",
      "start": "2026-09-30T10:00:00",
      "end": "2026-09-30T11:00:00",
      "zone": "Europe/Berlin"
    }
  }
}

For user-specified local appointments, send time.kind: "local" and the original clock times with an IANA zone. Calendar resolves and stores exact UTC instants. On LOCAL_TIME_NEEDS_CLARIFICATION, ask the user about the clock gap or repeated time; never append Z or retry as UTC to bypass it. Only include an explicit offset when the user supplied it to disambiguate. time.kind: "timed" remains supported for sources that already provide exact UTC instants. Canonical event files and public record/summary contracts are unchanged.

Read the returned ID with plugin_get to get its current revision. Edit with event.save using that ID, all editable fields and expected_revisions; omit taskRef to preserve a link, or explicitly set it to null to remove it. Use event.status for confirmation/cancellation and event.task for attaching/unlinking a task. Obtain the task's reference from plugin_resolve using meinkontext.tasks.task-summary@1.0.0; do not guess IDs or installation ownership.

Retries use the same complete request and idempotency key. New intent uses a new key. After a revision conflict, reload and reconsider the edit. Access and enabled integration checks run again even when replaying an earlier success.

json
{
  "from": "2026-09-30", "to": "2026-10-01",
  "zone": "Europe/Berlin", "collection_id": "<returned-calendar-id>"
}

Pass that query to calendar_query. Optional query, status, task_id, offset and limit filter/page the result. nextOffset indicates another page. Use status: "canceled" to find canceled events. An empty result only means no currently accessible matching records; it does not prove another person's availability.

To answer "when is the person free" without reading any event, call calendar_free_busy with the same from, to, zone and optional collection_id. It returns only busy: the merged intervals of the confirmed appointments and work blocks you may read, timed ones as UTC instants (allDay: false), confirmed all-day events as date ranges with an exclusive end (allDay: true). Drafts and canceled events count as free; no title, calendar or other detail is returned. Managed agents may call it under their calendar grant. The same answer is the report dataset meinkontext.calendar.free-busy through plugin_dataset (input range and zone). It reserves nothing and covers only the calendars the connection can read.

Generic plugin_get, plugin_resolve, plugin_archive and plugin_export work on Calendar too. JSON export includes canonical plugin files under current access. The published summary and record contracts are listed in README.md.

Current limits

No recurrence, ICS/provider synchronization, external invitations, conflict prevention, reminders, scheduled jobs, cross-owner task links or unattended source-import profile. No LLM inference runs in meinKontext. Queries materialize one bounded range and are not a frozen snapshot across pages; large-scale load gates remain open.

If a client cannot find Calendar tools, reconnect after activation. If linking is absent, check both enabled plugins, compatible contracts, owner organization and access. If an event is missing, check the date range, display zone, canceled status and collection/owner filters. See Tasks guide, SDK integration design and acceptance evidence.

Conversations with Messages

When compatible Messages is enabled in the same organization, detail pages show linked conversations and a discuss action. It opens a question with this record as context. Each recipient needs independent source access; a message grants none. Replies do not change a Task or book an Event. The base plugin remains fully usable without Messages.

Managed agents (0.0.2)

The owner can grant a calendar collection to a named agent as reader or editor. The agent uses its own authenticated identity and work session. Existing credentials do not gain editor rights when a live role changes: issue a new credential. Calendar collection creation and access administration remain owner operations. Task references need an independent current Task grant; a Calendar grant never grants Tasks access. Agent edits do not send invitations or book external services.