# MCP CalDAV STDIO Application

A Python-based MCP (Model Communication Protocol) application that provides CRUD operations for events, journals, and todos using the caldav Python library.

## Prerequisites

- Python 3.8 or higher
- `uv` (optional, for fast installation) or `pip`

## Dependencies

The required Python packages are listed in `pyproject.toml` and will be installed automatically:

- `caldav`
- `python-dateutil`
- `fastmcp`

## Installation Options

You can install the application using `uv` (recommended) or `pip`.

### Using uv (recommended)
```bash
uv pip install radicale-mcp
```

### Using pip
```bash
pip install radicale-mcp
```

### From source
```bash
git clone https://github.com/TheGreatGooo/radicale-mcp.git
cd radicale-mcp
uv pip install -e .
```

### Using uvx (run directly from GitHub)
```bash
uvx radicale_mcp@git+https://github.com/TheGreatGooo/radicale-mcp
```

## Features

- **MCP Protocol Support**: Communicates over STDIO using the Model Communication Protocol
- **CalDAV Integration**: Connects to any CalDAV server (like Radicale)
- **Full CRUD Operations**: Create, Read, Update, and Delete for events, journals, and todos
- **Standard Data Models**: Well-defined models for events, journals, and todos
- **Error Handling**: Comprehensive error handling and logging
- **Configuration Management**: Flexible configuration via files and environment variables

## Architecture

```
┌─────────────────┐    ┌──────────────────┐    ┌──────────────────┐
│   MCP Client    │    │  MCP CalDAV      │    │   CalDAV Server  │
│                 │    │  Application     │    │                  │
│  STDIO Input    │───▶│  (this app)      │───▶│  (e.g. Radicale) │
│  JSON Messages  │    │                  │    │                  │
│                 │◀───│                  │◀───│                  │
│  STDIO Output   │    │                  │    │                  │
└─────────────────┘    └──────────────────┘    └──────────────────┘
```

## Configuration

The application supports configuration through:
- Environment variables
- Configuration file (`config/settings.json`)

### Environment Variables
- `CALDAV_SERVER_URL`: CalDAV server URL (default: `http://localhost:5232`)
- `CALDAV_USERNAME`: Username for authentication (default: `user`)
- `CALDAV_PASSWORD`: Password for authentication (default: ``)
- `CALDAV_USE_SSL`: Whether to use SSL (default: `true`)
- `LOG_LEVEL`: Logging level (default: `INFO`)

### Configuration File
Create `config/settings.json`:
```json
{
  "server_url": "http://localhost:5232",
  "username": "user",
  "password": "",
  "use_ssl": true,
  "log_level": "INFO"
}
```

## Usage

The application runs as an MCP server by default. To start it:

```bash
python -m src.server
```

Or simply:

```bash
radicale_mcp
```

The application will listen on STDIO for MCP protocol messages. It supports the following methods:

### Event Operations
- `caldav.event.create`: Create a new event
- `caldav.event.read`: Read an existing event
- `caldav.event.update`: Update an existing event
- `caldav.event.delete`: Delete an event
- `caldav.event.list`: List all events

### Journal Operations
- `caldav.journal.create`: Create a new journal entry
- `caldav.journal.read`: Read an existing journal entry
- `caldav.journal.update`: Update an existing journal entry
- `caldav.journal.delete`: Delete a journal entry
- `caldav.journal.list`: List all journal entries

### Todo Operations
- `caldav.todo.create`: Create a new todo item
- `caldav.todo.read`: Read an existing todo item
- `caldav.todo.update`: Update an existing todo item
- `caldav.todo.delete`: Delete a todo item
- `caldav.todo.list`: List all todo items

## Example Request

```json
{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "caldav.event.create",
  "params": {
    "title": "Team Meeting",
    "description": "Weekly team sync",
    "start_time": "2023-10-15T10:00:00",
    "end_time": "2023-10-15T11:00:00",
    "location": "Conference Room A"
  }
}
```

## Example Response

```json
{
  "jsonrpc": "2.0",
  "id": "1",
  "result": {
    "id": "event-12345",
    "status": "created"
  }
}
```

## Development

### Project Structure
```
radicale-mcp/
├── src/main.py                 # Main application entry point
├── requirements.txt        # Python dependencies
├── config/                 # Configuration files
│   └── settings.json      # Application settings
├── src/                    # Source code
│   ├── __init__.py
│   ├── caldav_client.py    # CalDAV connection and operations
│   ├── models/             # Data models
│   │   ├── __init__.py
│   │   ├── event.py        # Event data model
│   │   ├── journal.py      # Journal data model
│   │   └── todo.py         # Todo data model
│   ├── operations/         # CRUD operations
│   │   ├── __init__.py
│   │   ├── event_ops.py    # Event CRUD operations
│   │   ├── journal_ops.py  # Journal CRUD operations
│   │   └── todo_ops.py     # Todo CRUD operations
│   ├── stdio_interface.py  # MCP STDIO protocol implementation
│   ├── config_manager.py   # Configuration management
│   └── error_handler.py    # Error handling and logging
└── docs/                   # Documentation
    ├── architecture.md
    ├── project_structure.md
    ├── data_models.md
    └── mcp_protocol.md
```

## FastMCP Integration

This application demonstrates how to integrate with the FastMCP library. The `src/server.py` file shows:

- How to create an MCP server instance
- How to define tools that can be called by MCP clients
- Integration with existing CalDAV functionality

To run the FastMCP server:
```bash
python -m server
```

## License

MIT