MCP

🚀 MCP Calendar Server

This is an MCP calendar management system based on ADT (Algebraic Data Type). It uses the Model Context Protocol (MCP) to manage calendar events. By applying the functional programming paradigm and ADT, it ensures type safety and predictability.

🚀 Quick Start

The MCP Calendar Server is designed to efficiently manage calendar events using the Model Context Protocol. With the application of functional programming paradigms and ADT, it offers robust type safety and predictability.

✨ Features

• ✅ CRUD operations for calendar events
• ✅ Categorize events by type (Study, Work, Rest, Activity)
• ✅ Manage event status (Planned, Completed, Canceled)
• ✅ Integrate a stamina system
• ✅ Prevent time conflicts
• ✅ Query events by date or category

📦 Installation

Requirements

• Python 3.10+
• uv package manager

Installation Steps

# Install dependencies
uv sync

# Install including development dependencies
uv sync --extra dev

Run the Server

# Start the MCP server
uv run python main.py

# Or run directly
uv run python src/main.py

💻 Usage Examples

Basic Usage

# Create a new calendar event
create_calendar_event(
    title="Team Meeting",
    start_time="2025-08-02T10:00:00",
    duration=60,
    category="WORK",
    description="Weekly team meeting",
    location="Meeting Room A",
    stamina_cost=20
)

# Query events by date
get_events_by_date("2025-08-02")

# Mark an event as completed
complete_event(event_id=1, stamina_after=80)

📚 Documentation

API Tools

1. get_all_events()

Retrieve all calendar events.

2. get_event_by_id(event_id: int)

Retrieve an event by its specific ID.

3. create_calendar_event(...)

Create a new calendar event.

Parameters:

• title: Event title
• start_time: Start time (ISO format: 2025-08-02T10:00:00)
• duration: Duration in minutes
• category: Event category (STUDY, WORK, REST, ACTIVITY)
• description: Event description (optional)
• location: Event location (optional)
• stamina_cost: Stamina cost (default: 0)

4. update_calendar_event(event_id: int, ...)

Update an existing event.

5. delete_calendar_event(event_id: int)

Delete an event.

6. complete_event(event_id: int, stamina_after: int)

Mark an event as completed.

7. get_events_by_category(category: str)

Retrieve events by category.

8. get_events_by_date(date: str)

Retrieve events for a specific date.

Data Models

EventCategory

• STUDY: Study
• WORK: Work
• REST: Rest
• ACTIVITY: Activity

EventStatus

• PLANNED: Planned
• COMPLETED: Completed
• CANCELED: Canceled

CalendarEvent

The core entity of a calendar event includes the following fields:

• ID, User ID, Title, Description, Location
• Start Time, Duration, Category
• Stamina Cost, Status, Stamina After Completion
• Creation Time

Project Structure

ittae-MCP/
├── src/
│   ├── __init__.py
│   ├── main.py                 # Main entry for the MCP server
│   ├── models/
│   │   └── __init__.py         # Define data models
│   ├── services/
│   │   ├── __init__.py
│   │   └── calendar_service.py # Business logic
│   └── exceptions/
│       └── __init__.py         # Exception handling
├── tests/                      # Test files
├── main.py                     # Entry point
├── pyproject.toml             # Project configuration
└── README.md

🔧 Technical Details

Testing

uv run pytest

Code Formatting

uv run black src/
uv run ruff check src/

📄 License

This project is distributed under the MIT License.