altiplano 0.1.0__tar.gz

altiplano-0.1.0/.env.example

@@ -0,0 +1,2 @@
+VIKUNJA_URL=https://todo.example.com/api/v1
+VIKUNJA_API_TOKEN=tk_replace_me

altiplano-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+.env
+.uv/

altiplano-0.1.0/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: altiplano
+Version: 0.1.0
+Summary: Minimal MCP server for Vikunja (server-side filtering, no fluff)
+Project-URL: Homepage, https://github.com/aichholzer/altiplano
+Project-URL: Repository, https://github.com/aichholzer/altiplano
+Project-URL: Issues, https://github.com/aichholzer/altiplano/issues
+Author-email: Stefan Aichholzer <theaichholzer@gmail.com>
+License-Expression: MIT
+Keywords: mcp,model-context-protocol,tasks,todo,vikunja
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp>=1.2.0
+Description-Content-Type: text/markdown
+
+# altiplano
+
+A small, dependable MCP server for [Vikunja](https://vikunja.io). Named after the Andean altiplano, the high plateau that is the Vicuña's native habitat.
+
+Filtering and sorting are passed straight to the Vikunja API (server-side), so there is no client-side filtering engine and no paginate-then-filter pitfall.
+
+## Tools
+
+- `list_projects`
+- `list_tasks` (project_id, filter, sort_by, page, per_page)
+- `get_task` (task_id)
+- `create_task` (project_id, title, description?, priority?, due_date?)
+- `update_task` (task_id, title?, description?, done?, priority?)
+- `list_labels`
+- `add_label` (task_id, label_id)
+- `remove_label` (task_id, label_id)
+
+## Credentials (no secrets in mcp.json)
+
+The server resolves two values, in order:
+
+1. Environment variables `VIKUNJA_URL` and `VIKUNJA_API_TOKEN`.
+2. A per-device file of `KEY=VALUE` lines, default `~/.config/altiplano/env`
+   (override the path with `ALTIPLANO_CONFIG`).
+
+`VIKUNJA_URL` is the base API URL including `/api/v1` (e.g. `https://todo.example.com/api/v1`).
+
+Recommended so the shared `mcp.json` carries no secret:
+
+- Drop a per-device file and lock it down:
+  ```bash
+  mkdir -p ~/.config/altiplano
+  printf 'VIKUNJA_URL=https://todo.example.com/api/v1\nVIKUNJA_API_TOKEN=tk_xxx\n' > ~/.config/altiplano/env
+  chmod 600 ~/.config/altiplano/env
+  ```
+- Or inject via the launcher's environment (e.g. a systemd unit `EnvironmentFile=` pointing at a `chmod 600` file), which the server inherits.
+- For stronger setups, source the token from a secret manager/keychain at launch and export it into the environment.
+
+Then `mcp.json` only needs the command, no `env` block with secrets:
+
+```json
+{
+  "altiplano": {
+    "command": "uvx",
+    "args": ["altiplano"]
+  }
+}
+```
+
+## Run
+
+```bash
+uv run altiplano                                  # dev, from this directory
+uvx --from /mnt/settings/MCP/altiplano altiplano  # local path
+uvx altiplano                                     # from PyPI
+```
+
+## Notes
+
+- Vikunja priority scale: 0 Unset, 1 Low, 2 Medium, 3 High, 4 Urgent, 5 DO NOW.
+- The UI shows tasks by their project-local `identifier` (e.g. `#49`), which is not the global `id` the API uses.
+- Endpoint shapes (create via `PUT /projects/{id}/tasks`, update via `POST /tasks/{id}`) follow current Vikunja; adjust if your instance differs.

altiplano-0.1.0/README.md

@@ -0,0 +1,62 @@
+# altiplano
+
+A small, dependable MCP server for [Vikunja](https://vikunja.io). Named after the Andean altiplano, the high plateau that is the Vicuña's native habitat.
+
+Filtering and sorting are passed straight to the Vikunja API (server-side), so there is no client-side filtering engine and no paginate-then-filter pitfall.
+
+## Tools
+
+- `list_projects`
+- `list_tasks` (project_id, filter, sort_by, page, per_page)
+- `get_task` (task_id)
+- `create_task` (project_id, title, description?, priority?, due_date?)
+- `update_task` (task_id, title?, description?, done?, priority?)
+- `list_labels`
+- `add_label` (task_id, label_id)
+- `remove_label` (task_id, label_id)
+
+## Credentials (no secrets in mcp.json)
+
+The server resolves two values, in order:
+
+1. Environment variables `VIKUNJA_URL` and `VIKUNJA_API_TOKEN`.
+2. A per-device file of `KEY=VALUE` lines, default `~/.config/altiplano/env`
+   (override the path with `ALTIPLANO_CONFIG`).
+
+`VIKUNJA_URL` is the base API URL including `/api/v1` (e.g. `https://todo.example.com/api/v1`).
+
+Recommended so the shared `mcp.json` carries no secret:
+
+- Drop a per-device file and lock it down:
+  ```bash
+  mkdir -p ~/.config/altiplano
+  printf 'VIKUNJA_URL=https://todo.example.com/api/v1\nVIKUNJA_API_TOKEN=tk_xxx\n' > ~/.config/altiplano/env
+  chmod 600 ~/.config/altiplano/env
+  ```
+- Or inject via the launcher's environment (e.g. a systemd unit `EnvironmentFile=` pointing at a `chmod 600` file), which the server inherits.
+- For stronger setups, source the token from a secret manager/keychain at launch and export it into the environment.
+
+Then `mcp.json` only needs the command, no `env` block with secrets:
+
+```json
+{
+  "altiplano": {
+    "command": "uvx",
+    "args": ["altiplano"]
+  }
+}
+```
+
+## Run
+
+```bash
+uv run altiplano                                  # dev, from this directory
+uvx --from /mnt/settings/MCP/altiplano altiplano  # local path
+uvx altiplano                                     # from PyPI
+```
+
+## Notes
+
+- Vikunja priority scale: 0 Unset, 1 Low, 2 Medium, 3 High, 4 Urgent, 5 DO NOW.
+- The UI shows tasks by their project-local `identifier` (e.g. `#49`), which is not the global `id` the API uses.
+- Endpoint shapes (create via `PUT /projects/{id}/tasks`, update via `POST /tasks/{id}`) follow current Vikunja; adjust if your instance differs.

altiplano-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[project]
+name = "altiplano"
+version = "0.1.0"
+description = "Minimal MCP server for Vikunja (server-side filtering, no fluff)"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [
+  { name = "Stefan Aichholzer", email = "theaichholzer@gmail.com" },
+]
+keywords = ["mcp", "vikunja", "model-context-protocol", "todo", "tasks"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Topic :: Utilities",
+]
+dependencies = [
+  "mcp>=1.2.0",
+  "httpx>=0.27",
+]
+
+[project.urls]
+Homepage = "https://github.com/aichholzer/altiplano"
+Repository = "https://github.com/aichholzer/altiplano"
+Issues = "https://github.com/aichholzer/altiplano/issues"
+
+[project.scripts]
+altiplano = "altiplano.server:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/altiplano"]

altiplano-0.1.0/src/altiplano/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

altiplano-0.1.0/src/altiplano/server.py

@@ -0,0 +1,182 @@
+"""Minimal Vikunja MCP server.
+
+Filtering and sorting are passed straight to the Vikunja API (server-side),
+so there is no client-side filtering engine to get wrong.
+
+Credentials are resolved without storing secrets in a shared mcp.json:
+  1. Environment variables VIKUNJA_URL / VIKUNJA_API_TOKEN (preferred).
+  2. A per-device file of KEY=VALUE lines (default ~/.config/altiplano/env,
+     override with ALTIPLANO_CONFIG). Keep it chmod 600.
+"""
+
+import os
+from pathlib import Path
+from typing import Any
+
+import httpx
+from mcp.server.fastmcp import FastMCP
+
+mcp = FastMCP("altiplano")
+
+_CONFIG_FILE = Path(
+    os.environ.get("ALTIPLANO_CONFIG", Path.home() / ".config" / "altiplano" / "env")
+)
+
+
+def _from_file(key: str) -> str | None:
+    try:
+        for line in _CONFIG_FILE.read_text().splitlines():
+            line = line.strip()
+            if not line or line.startswith("#") or "=" not in line:
+                continue
+            k, v = line.split("=", 1)
+            if k.strip() == key:
+                return v.strip().strip('"').strip("'")
+    except FileNotFoundError:
+        return None
+    return None
+
+
+def _conf(key: str) -> str | None:
+    return os.environ.get(key) or _from_file(key)
+
+
+def _base() -> str:
+    url = _conf("VIKUNJA_URL")
+    if not url:
+        raise RuntimeError("VIKUNJA_URL is not set (env or ~/.config/altiplano/env)")
+    return url.rstrip("/")
+
+
+def _headers() -> dict[str, str]:
+    token = _conf("VIKUNJA_API_TOKEN")
+    if not token:
+        raise RuntimeError("VIKUNJA_API_TOKEN is not set (env or ~/.config/altiplano/env)")
+    return {"Authorization": f"Bearer {token}", "Content-Type": "application/json"}
+
+
+async def _request(method: str, path: str, **kwargs: Any) -> Any:
+    async with httpx.AsyncClient(base_url=_base(), headers=_headers(), timeout=30) as client:
+        r = await client.request(method, path, **kwargs)
+        r.raise_for_status()
+        if r.status_code == 204 or not r.content:
+            return {"ok": True}
+        return r.json()
+
+
+def _task_summary(t: dict) -> dict:
+    return {
+        "id": t.get("id"),
+        "identifier": t.get("identifier"),
+        "title": t.get("title"),
+        "done": t.get("done"),
+        "priority": t.get("priority"),
+    }
+
+
+@mcp.tool()
+async def list_projects() -> list[dict]:
+    """List all projects (boards)."""
+    data = await _request("GET", "/projects")
+    return [
+        {"id": p["id"], "title": p["title"], "is_archived": p.get("is_archived", False)}
+        for p in (data or [])
+    ]
+
+
+@mcp.tool()
+async def list_tasks(
+    project_id: int,
+    filter: str | None = None,
+    sort_by: str | None = None,
+    page: int = 1,
+    per_page: int = 50,
+) -> list[dict]:
+    """List tasks in a project.
+
+    `filter` and `sort_by` are passed to Vikunja and applied server-side, e.g.
+    filter="done = false && priority >= 4", sort_by="priority". Vikunja filters
+    then paginates, so results are complete regardless of page size.
+    """
+    params: dict[str, Any] = {"page": page, "per_page": per_page}
+    if filter:
+        params["filter"] = filter
+    if sort_by:
+        params["sort_by"] = sort_by
+    data = await _request("GET", f"/projects/{project_id}/tasks", params=params)
+    return [_task_summary(t) for t in (data or [])]
+
+
+@mcp.tool()
+async def get_task(task_id: int) -> dict:
+    """Get a single task with full detail."""
+    return await _request("GET", f"/tasks/{task_id}")
+
+
+@mcp.tool()
+async def create_task(
+    project_id: int,
+    title: str,
+    description: str | None = None,
+    priority: int | None = None,
+    due_date: str | None = None,
+) -> dict:
+    """Create a task in a project."""
+    payload: dict[str, Any] = {"title": title}
+    if description is not None:
+        payload["description"] = description
+    if priority is not None:
+        payload["priority"] = priority
+    if due_date is not None:
+        payload["due_date"] = due_date
+    return await _request("PUT", f"/projects/{project_id}/tasks", json=payload)
+
+
+@mcp.tool()
+async def update_task(
+    task_id: int,
+    title: str | None = None,
+    description: str | None = None,
+    done: bool | None = None,
+    priority: int | None = None,
+) -> dict:
+    """Update a task. Only the fields you pass are changed. Use `done` to open/close it."""
+    payload: dict[str, Any] = {}
+    if title is not None:
+        payload["title"] = title
+    if description is not None:
+        payload["description"] = description
+    if done is not None:
+        payload["done"] = done
+    if priority is not None:
+        payload["priority"] = priority
+    if not payload:
+        raise ValueError("No fields to update")
+    return await _request("POST", f"/tasks/{task_id}", json=payload)
+
+
+@mcp.tool()
+async def list_labels() -> list[dict]:
+    """List all labels."""
+    data = await _request("GET", "/labels")
+    return [{"id": x["id"], "title": x["title"]} for x in (data or [])]
+
+
+@mcp.tool()
+async def add_label(task_id: int, label_id: int) -> dict:
+    """Attach a label to a task."""
+    return await _request("PUT", f"/tasks/{task_id}/labels", json={"label_id": label_id})
+
+
+@mcp.tool()
+async def remove_label(task_id: int, label_id: int) -> dict:
+    """Remove a label from a task."""
+    return await _request("DELETE", f"/tasks/{task_id}/labels/{label_id}")
+
+
+def main() -> None:
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()