Content
# Tool List
## Overview
Desktop Calendar application for human users and AI Agents. Built with **Tauri 2 + React + SQLite**, featuring a local MCP Server for Agents to read and write the same calendar data.
Core concept: Humans manage schedules through the desktop GUI, while Agents manage schedules through the MCP protocol, sharing the same SQLite database, with changes synced in real-time.
## Features
### Desktop Calendar
- Floating Circular Widget: Defaults to docking in the bottom right area of the screen, draggable, displaying date and today's event overview
- Weekly View: Displays a 7-day time grid when expanded, supporting creation, editing, and deletion of events
- Event Types: Interview, Meeting, Reminder, Deadline, Default
- Tray Menu: Display calendar, hide to tray, exit application
- Single Instance Launch: Reopening the exe will wake up the existing window instead of launching multiple processes
- Dark Mode: Follows system theme
### MCP / Agent Capabilities
- Local HTTP MCP Server: Listens on `http://127.0.0.1:18765/mcp` by default
- MCP Apps Widget: Tool results can be rendered as interactive HTML Widgets
- Supports querying events, viewing details, creating events, updating events, deleting events, and querying free time slots
- MCP input strictly validated: Time range, color, URL, event type, status, and other invalid parameters will report clear errors
## MCP Tools
| Tool | Description |
| --- | --- |
| `list_events` | Queries events within a time range, returns an event list widget |
| `get_event` | Queries a single event detail, returns a detail widget |
| `create_event` | Creates a new event |
| `update_event` | Updates an existing event, supports clearing fields like notes, location, and link |
| `delete_event` | Soft deletes an event |
| `get_free_slots` | Queries free time slots within a specified date, returns a free time widget |
### MCP Connection Example
The application automatically starts the MCP HTTP service after launch:
```json
{
"mcpServers": {
"desktop-calendar": {
"type": "http",
"url": "http://127.0.0.1:18765/mcp"
}
}
}
```
Health check:
```text
http://127.0.0.1:18765/health
```
## Technology Stack
| Layer | Technology |
| --- | --- |
| Frontend | React 18, TypeScript, Vite 6 |
| UI | Phosphor Icons, Geist Sans/Mono, CSS variables |
| State Management | Zustand |
| Desktop Shell | Tauri 2 |
| Database | SQLite, rusqlite |
| MCP | rmcp Streamable HTTP Server, MCP Apps Widgets |
| Testing | Cargo test, Vitest |
## Quick Start
```bash
npm install
# Frontend development service
npm run dev
# Launch Tauri desktop application
npm run tauri dev
# Frontend build
npm run build
# Rust testing
cd src-tauri
cargo test
```
## Platform Compatibility
Currently mainly developed and verified on **Windows**.
| Platform | Status | Description |
| --- | --- | --- |
| Windows | Verified | Tray, transparent window, bottom right positioning, single instance, MCP Server all verified |
| macOS | Theoretically compatible, pending testing | Tauri/React/SQLite/MCP code is generally cross-platform, but tray menu icon, Dock behavior, transparent top window, avoiding Dock/Menu Bar still need verification on macOS |
| Linux | Not verified | Core dependencies are cross-platform, but tray and transparent window behavior depend on the desktop environment |
## Project Structure
```text
desktop-calendar-tauri/
├─ src/ # React frontend
│ ├─ components/
│ │ ├─ Calendar/ # EventCard, EventDialog, EventTooltip
│ │ ├─ Common/ # ErrorBoundary, StatusBar, DiagnosticPanel
│ │ ├─ WeekView/ # Weekly view component
│ │ └─ Widget/ # Floating ball widget
│ ├─ hooks/ # Window, drag, week navigation hooks
│ ├─ stores/ # Zustand store
│ ├─ utils/ # Date, layout, window tools
│ ├─ constants/ # Window size, event colors
│ └─ types/ # TypeScript types
├─ src-tauri/ # Tauri / Rust backend
│ ├─ src/
│ │ ├─ commands/ # Tauri IPC commands
│ │ ├─ db/ # SQLite schema, migrations, repository
│ │ ├─ mcp/ # MCP Server, tools, resources, widgets
│ │ └─ models/ # Rust data models
│ └─ tests/ # Rust integration tests
├─ docs/ # Documentation
├─ package.json
└─ README.md
```
## Data Model
Core event table:
```sql
CREATE TABLE events (
id TEXT PRIMARY KEY,
title TEXT NOT NULL,
description TEXT,
start_time INTEGER NOT NULL,
end_time INTEGER NOT NULL,
timezone TEXT DEFAULT 'Asia/Shanghai',
is_all_day INTEGER DEFAULT 0,
rrule TEXT,
rrule_until INTEGER,
exdates TEXT,
status TEXT DEFAULT 'confirmed',
color TEXT DEFAULT '#3B82F6',
event_type TEXT DEFAULT 'default',
location TEXT,
url TEXT,
created_by TEXT DEFAULT 'human',
created_at INTEGER NOT NULL,
updated_at INTEGER NOT NULL,
deleted_at INTEGER DEFAULT NULL
);
```
## Development Notes
- Project development guidelines see [docs/DEVELOPMENT-GUIDELINES.md](docs/DEVELOPMENT-GUIDELINES.md)
- MCP input uses fixed string time, interpreted as `Asia/Shanghai`: date and time are `YYYY-MM-DD HH:mm`, date is `YYYY-MM-DD`
- Database internally uses Unix milliseconds, frontend and MCP return values keep millisecond values
- `create_event` rejects duplicate events with the same time and title, and limits up to 2 events within any time segment
- MCP Server only binds to `127.0.0.1`
- Widget HTML exposed through MCP resource, MIME is `text/html;profile=mcp-app`
- After code changes, please run `cargo test` and `npm run build`
## License
MIT
