vikunja-python 0.1.0__tar.gz → 0.1.2__tar.gz

vikunja_python-0.1.2/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.4
+Name: vikunja-python
+Version: 0.1.2
+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.11
+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.

vikunja_python-0.1.2/README.md

@@ -0,0 +1,123 @@
+# 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.

{vikunja_python-0.1.0 → vikunja_python-0.1.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "vikunja-python"
-version = "0.1.0"
+version = "0.1.2"
 description = "API wrapper, CLI tool, and MCP server for Vikunja"
 authors = [
     { name = "Your Name", email = "your.email@example.com" }
@@ -12,8 +12,14 @@ dependencies = [
     "typer>=0.12.0",
     "fastmcp>=0.1.0",
 ]
-requires-python = ">=3.13.12"
+requires-python = ">=3.11"
 license = "WTFPL"
+readme = "README.md"
+
+[project.urls]
+Homepage = "https://github.com/oedo808/vikunja-python"
+Repository = "https://github.com/oedo808/vikunja-python"
+Documentation = "https://github.com/oedo808/vikunja-python"
 
 [project.optional-dependencies]
 test = [

vikunja_python-0.1.2/vikunja_python.egg-info/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.4
+Name: vikunja-python
+Version: 0.1.2
+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.11
+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.

vikunja_python-0.1.0/PKG-INFO

@@ -1,16 +0,0 @@
-Metadata-Version: 2.4
-Name: vikunja-python
-Version: 0.1.0
-Summary: API wrapper, CLI tool, and MCP server for Vikunja
-Author-email: Your Name <your.email@example.com>
-License-Expression: WTFPL
-Requires-Python: >=3.13.12
-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-0.1.0/README.md

@@ -1,85 +0,0 @@
-# Vikunja Python
-
-An open-source (WTFPL) API wrapper, rich CLI tool, and Model Context Protocol (MCP) server for the [Vikunja](https://vikunja.io/) task management system.
-
-Built for **Python 3.13** using `httpx`, `pydantic v2`, and `fastmcp`.
-
-## 🏗 Architecture
-
-The project is structured into three distinct layers to ensure modularity and clean dependency management:
-
-- **`/core`**: The engine. Handles Pydantic models, HTTP client logic, and error handling. (Minimal dependencies).
-- **`/cli`**: A high-visual-impact command-line interface built with `typer` and `rich`.
-- **`/mcp`**: A Model Context Protocol server designed for agentic workflows, optimized for smaller LLMs (like Gemma).
-
-## 🚀 Getting Started
-
-### Installation
-This project uses `uv` for modern Python package management.
-
-```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"  # Recommended for MCP
-VIKUNJA_JWT_TOKEN="your_jwt_here"        # Required for Buckets/Reactions in CLI
-VIKUNJA_DEBUG="true"                     # Set to true or 1 to enable verbose stderr logging
-```
-
-## 🛠 Features & Tooling
-
-### CLI (`vikunja`)
-The CLI provides a rich, human-friendly interface for managing your workspace.
-- **Tasks & Projects**: Full CRUD support with formatted tables.
-- **Buckets (Kanban)**: List and manage columns (Requires JWT).
-- **Reactions**: Add emojis to tasks (Requires JWT).
-- **Labels**: List and categorize tasks.
-- **Auth**: Built-in `login` command to generate JWTs.
-
-```bash
-uv run vikunja list-tasks
-uv run vikunja login
-```
-
-### MCP Server (`vikunja-mcp`)
-A powerful server that gives LLMs "hands" to manage your Vikunja instance. Optimized for reliability and low turn-count.
-- **Global Search**: Find tasks across all projects in one turn.
-- **Bulk Scaffolding**: Create projects and multiple tasks in a single operation.
-- **Smart Dates**: Natural language date parsing (e.g., "remind me next Friday").
-- **Task Memory**: Full support for reading and writing task comments.
-- **Explicit Hierarchy**: Clear directional tools for subtasks and dependencies.
-
-```bash
-# Start via STDIO (for Claude Desktop)
-uv run vikunja-mcp
-
-# Start via SSE (HTTP)
-uv run vikunja-mcp dev --transport sse
-```
-
-## 🔒 Security & Auth Policy
-
-- **MCP Protocol**: The MCP server is strictly limited to **API Key Authentication**. We do not support user/password login via MCP to ensure secure, scoped agentic access.
-- **UI-Only Features**: Features like Buckets (Kanban columns) and Reactions currently require a JWT (UI Session). These are supported in the CLI but are excluded from the MCP server to maintain protocol security.
-
-## 🧪 Testing
-
-We use `testcontainers-python` to run integration tests against a live, ephemeral Vikunja instance. No mocks, just real API verification.
-
-```bash
-uv run pytest
-```
-
-## 🗺 Future Roadmap
-- [ ] **Backgrounds**: Support for Unsplash project backgrounds.
-- [ ] **Attachments**: File upload/download support.
-- [ ] **Webhooks**: Core models for receiving Vikunja events.
-- [ ] **Bulk Labels**: Tools for mass-tagging tasks.
-
-## 📜 License
-WTFPL - Do What the Fuck You Want to Public License.

vikunja_python-0.1.0/vikunja_python.egg-info/PKG-INFO

@@ -1,16 +0,0 @@
-Metadata-Version: 2.4
-Name: vikunja-python
-Version: 0.1.0
-Summary: API wrapper, CLI tool, and MCP server for Vikunja
-Author-email: Your Name <your.email@example.com>
-License-Expression: WTFPL
-Requires-Python: >=3.13.12
-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"