magic-calendar

Magic Calendar

Create and manage interactive calendar projects. Each calendar project is a folder containing index.html (visualization), magic.project.js (metadata and categories), and events/ (monthly event files). All data operations go through tools — do not manually read or edit these files.

Workflow

1. Create project folder (shell_exec: mkdir)
2. setup_calendar_project  → initialize calendar
3. manage_calendar         → add categories (optional)
4. manage_calendar         → add events (batch or one-by-one)

Decision Tree

User request
├── Create new calendar       → setup_calendar_project
├── Add event/schedule/plan   → manage_calendar (add_event)
├── View/query events         → manage_calendar (list_events)
├── Modify existing event     → manage_calendar (update_event)
├── Delete/cancel event       → manage_calendar (delete_event)
├── Add event category        → manage_calendar (add_category)
└── View categories           → manage_calendar (list_categories)

---

Tool: setup_calendar_project

Initialize a calendar project in an existing folder. You must create the folder first via shell_exec.

Parameters

---

Tool: manage_calendar

Manage calendar events and categories.

Common Parameters (all actions)

add_event

Only title + start are required. All other fields are optional with sensible defaults.

list_events

All filters are optional. No filters = return all events.

update_event

Partial update — only pass fields you want to change.

delete_event

add_category

list_categories

No additional parameters.

Recurrence Rule Format

Pass as JSON string in the recurrence parameter:

{"type": "daily", "interval": 1, "end_date": "2026-06-30"}
{"type": "weekly", "interval": 1, "days_of_week": [1, 3, 5]}
{"type": "monthly", "interval": 1, "day_of_month": 15, "end_date": "2026-12-31"}

• type: daily / weekly / monthly
• interval: repeat every N days/weeks/months, default 1
• days_of_week: for weekly only, 1=Mon … 7=Sun
• day_of_month: for monthly, defaults to the day from start
• end_date: YYYY-MM-DD, omit for indefinite

---

Code Mode Examples

Create calendar and add events

from sdk.tool import tool

# 1. Create project folder
tool.call("shell_exec", {"command": "mkdir -p .workspace/content-calendar"})

# 2. Setup calendar with initial categories
tool.call("setup_calendar_project", {
    "project_path": "content-calendar",
    "calendar_name": "Content Publishing Calendar",
    "description": "30-day rolling content plan",
    "initial_categories": '[{"id":"publish","name":"Publish","color":"#4CAF50"},{"id":"review","name":"Review","color":"#2196F3"}]'
})

# 3. Minimal event (title + start only)
tool.call("manage_calendar", {
    "action": "add_event",
    "project_path": "content-calendar",
    "title": "Weekly standup",
    "start": "2026-04-21 10:00"
})

# 4. Full event
tool.call("manage_calendar", {
    "action": "add_event",
    "project_path": "content-calendar",
    "title": "Product review video",
    "start": "2026-04-22 14:00",
    "end": "2026-04-22 15:30",
    "category": "publish",
    "location": "Studio 3F",
    "description": "30s vertical tutorial"
})

# 5. Recurring event
tool.call("manage_calendar", {
    "action": "add_event",
    "project_path": "content-calendar",
    "title": "Content review meeting",
    "start": "2026-04-21 09:00",
    "recurrence": '{"type":"weekly","interval":1,"days_of_week":[1,3,5],"end_date":"2026-06-30"}'
})

# 6. All-day event (date-only start)
tool.call("manage_calendar", {
    "action": "add_event",
    "project_path": "content-calendar",
    "title": "Product launch day",
    "start": "2026-05-01",
    "category": "publish"
})

Query, update, and delete

from sdk.tool import tool

# Query by date range
result = tool.call("manage_calendar", {
    "action": "list_events",
    "project_path": "content-calendar",
    "date_from": "2026-04-21",
    "date_to": "2026-04-27"
})
print(result.content)

# Mark event as completed
tool.call("manage_calendar", {
    "action": "update_event",
    "project_path": "content-calendar",
    "event_id": "evt_a7f3b2",
    "status": "completed"
})

# Delete event
tool.call("manage_calendar", {
    "action": "delete_event",
    "project_path": "content-calendar",
    "event_id": "evt_c3d4e5"
})

---

Important Notes

1. Create folder first — setup_calendar_project does not create folders; use shell_exec beforehand
2. Event IDs are auto-generated — never pass id when creating; use the returned ID for update/delete
3. update_event is partial — omitted fields keep their current value
4. Time format — YYYY-MM-DD HH:MM for timed events, YYYY-MM-DD for all-day. No seconds or timezone suffixes
5. Do not manually edit project files — always use tools; manual edits waste context and may corrupt data format