Metadata-Version: 2.4
Name: vikunja-python
Version: 0.1.1
Summary: API wrapper, CLI tool, and MCP server for Vikunja
Author-email: Your Name <your.email@example.com>
License-Expression: WTFPL
Project-URL: Homepage, https://github.com/oedo808/vikunja-python
Project-URL: Repository, https://github.com/oedo808/vikunja-python
Project-URL: Documentation, https://github.com/oedo808/vikunja-python
Requires-Python: >=3.13.12
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: dateparser>=1.2.0
Requires-Dist: typer>=0.12.0
Requires-Dist: fastmcp>=0.1.0
Provides-Extra: test
Requires-Dist: pytest>=8.0.0; extra == "test"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "test"
Requires-Dist: testcontainers[mysql]>=4.0.0; extra == "test"

# Vikunja Python

Python API wrapper, CLI tool, MCP server, and Home Assistant integration for the [Vikunja](https://vikunja.io/) task management system.

Built for Python 3.13 with httpx, pydantic v2, fastmcp, and typer.

## Architecture

The project is structured into layers:

- **core/** -- Pydantic models, async HTTP client (httpx), error handling, API token and JWT authentication
- **cli/** -- Rich CLI built with typer and rich (task CRUD, project views, saved filter queries, dashboard summary)
- **mcp/** -- MCP server for agentic AI workflows (13 tools including list_tasks, get_task, create_task, list_saved_filter, task_summary)
- **custom_components/vikunja/** -- Home Assistant HACS integration (config flow, 3 sensors for saved filters)

## Getting Started

### Installation

From PyPI:

```bash
pip install vikunja-python
```

Or with uv:

```bash
uv sync --all-extras
```

### Environment Variables

Configure your Vikunja instance in a `.env` file or your shell:

```bash
VIKUNJA_URL="https://your-vikunja-instance.com/api/v1"
VIKUNJA_API_TOKEN="your_api_token_here"
VIKUNJA_DEBUG="true"   # Enable verbose stderr logging
```

## Features

### CLI (vikunja)

The CLI provides a human-friendly interface for managing tasks:

- list-tasks -- List tasks with rich table output (supports saved filters via negative project IDs)
- list-saved-filter -- Query saved filters (e.g., -2 for Due in 3 Days, -3 for Overdue, -4 for Due Today)
- summary -- Quick dashboard summary across all saved filters (parallel queries, optimized for ePaper dashboards)
- get-project -- Project details and views
- list-view-tasks -- List tasks from a specific project view
- get-task -- Full task details with description
- create-task -- Create a new task
- create-label -- Create a new label

```bash
uv run vikunja list-tasks
uv run vikunja list-saved-filter --filter-id -2
uv run vikunja summary --top 5
```

### MCP Server (vikunja-mcp)

MCP server for agentic workflows. 13 tools including:

- list_tasks, get_task, create_task, update_task, complete_task, delete_task
- list_saved_filter -- Query saved filters (e.g., -2 for Due in 3 Days)
- task_summary -- Dashboard summary across all filters in one parallel call
- list_projects, get_project, list_project_view_tasks
- list_labels, create_label
- add_subtask, add_task_link

```bash
uv run vikunja-mcp
```

### Home Assistant Integration

The package includes a HACS-ready custom component for Home Assistant:

- Config flow: URL + API token via the HA UI
- 3 sensors: Overdue, Due Today, Due in 3 Days (from Vikunja saved filters)
- Each sensor: state = task count, attributes = task list with IDs, titles, due dates
- Coordinator polls all filters in parallel every 5 minutes

Copy `custom_components/vikunja/` to your HA config's `custom_components/` directory, restart HA, and add via Settings -> Devices & Services.

## Saved Filter Support

Vikunja saved filters are accessed via negative project IDs:

| ID | Filter |
|----|--------|
| -2 | Due in 3 Days |
| -3 | Overdue |
| -4 | Due Today |

The API route is `GET /tasks?project_id=-2` (NOT `/projects/-2/tasks`).

## Testing

Unit tests run without Docker:

```bash
uv run pytest tests/test_task_models_unit.py tests/test_label_model_validation.py -v
```

Integration tests require Docker (spins up a real Vikunja instance via testcontainers):

```bash
uv run pytest
```

## Security & Auth

- API Key auth is the primary authentication method for both CLI and MCP server
- JWT tokens are used for UI-specific features (kanban buckets, reactions) in the CLI only
- The MCP server only supports API key authentication

## License

WTFPL - Do What the Fuck You Want to Public License.
