task-manager 📋

MCP-сервер керування задачами над доменом planner/ (на сервері — /srv/planner; markdown = джерело правди). Частина проєкту «Task Manager» (див. мозок: projects/task-manager/overview.md).

Що це

• Парсер/серіалізатор planner-формату (round-trip: чіпає лише рядки-задачі, решту зберігає).

• MCP-тули для Claude: list_tasks (без done за замовч., короткі рядки, query/limit), get_task, board, add_task, move_task (правила переходів + WIP-гард), set_priority, set_deadline, edit_task (будь-які поля + перенос між проєктами), delete_task, history (журнал змін).

• Три транспорти: stdio · http+bearer (tailnet) · OAuth (публічно за Caddy/Funnel) — Ф4 ✅.

• Веб-дашборд (канбан + календар) — Ф3 ✅, http://<host>:8792/task-manager (лише tailnet).

Related MCP server: blackboard

Веб-дашборд 🗂️

http://<host>:8792/task-manager — канбан (4 колонки, drag-and-drop) + календар за дедлайнами, форма додавання, редагування будь-яких полів і історія змін просто в картці. Один самодостатній HTML: без збірки, без npm, без зовнішніх CDN (працює і без інтернету). Стара адреса /ui віддає 302 на нову (щоб не ламати закладки).

Що вміє форма (Ф7, 2026-09-06):

• Заголовок (≤50, обовʼязковий) — саме він видно на картці й у календарі; повний текст на картці обрізаний двома рядками, у календарі не показується взагалі (він і ламав верстку). Єдине поле, яке НЕ можна очистити через none. Щоб не було тертя, форма пропонує чернетку заголовка з тексту — поки поле порожнє; написане руками не чіпає.

• Проєкт — селект із наявних. Нового проєкту з дашборда не завести: їх заводить AI через MCP (тултіп у формі про це каже).

• Домени — теги: обираєш наявний або дописуєш новий і тиснеш Enter.

• Кольори тегів — кнопка 🎨 у хедері: список тегів (з довідника) і кольорпікер для кожного, «✕» знімає колір; теги на картках фарбуються в обраний колір, без кольору — нейтральні. Колір можна задати й тегу, під яким зараз немає задач. Деталі — у «Кольори тегів» нижче.

• Звʼязки — тільки вибір із наявних (вони ведуть у нотатки мозку, якого сервіс не бачить).

• Шаблони — селект «⚡ Шаблон…» у хедері: типова задача створюється в один клік.

• Перенос у done = повноекранне конфеті-свято (дофамін як нагорода; при prefers-reduced-motion — тільки плашка, без анімації).

Шаблони задач

planner/projects/<слаг>/template.md — по файлу на проєкт, рядки в тому ж форматі, що й задачі. Лежать у ПІДПАПЦІ проєкту, тому під керовані projects/*.md не підпадають і як задачі не читаються (перевірено тестом). Щоб додати шаблон — просто допиши рядок.

⚠️ Безпека — головне

Дашборд не має власної авторизації. Захист виключно мережевий: він реєструється тільки на bearer-інстансі (:8792), куди фаєрвол пускає лише з tailscale0. Перевірено з машини в тій самій домашній LAN: <lan-ip>:8792 → зʼєднання нема, <tailnet-ip>:8792 → відповідає.

НЕ реєструвати на OAuth-інстансі (:8793): він за Caddy/Funnel, і його маршрути публічні — дашборд без пароля виїхав би в інтернет. Два запобіжники: умова if not _OAUTH у task_manager.py і assert у web_ui.register() (на нього є тест).

Bearer-мідлварь вимагає токен лише на MCP-шляху /tasks; /task-manager і /api/* браузер відкриває без заголовків.

Журнал змін (аудит) 📜

Усі зміни задач пишуться в planner/.history/YYYY-MM.jsonl (append-only, по файлу на місяць, нічого не чистимо). Читається тулом history(id?, limit).

• add / edit / delete — з дифом «було → стало» по кожному полю; delete зберігає повний знімок задачі, бо операція незворотна.

• external — файл змінили повз сервіс (Obsidian, редактор). Стор звіряє sha256 керованих файлів із тим, що записував сам. Полів не знаємо, але журнал чесно каже, що тут була стороння правка й він неповний.

• client — ЗВІДКИ прийшла зміна: web (веб-дашборд) · mac (MCP через bearer/tailnet) · claude / chatgpt (MCP через OAuth — з client_name, яким клієнт зареєструвався по DCR) · phone (OAuth-фолбек, якщо назви клієнта нема) · local (stdio). Базова мітка — TASKS_CLIENT у systemd-юніті, але вона описує ІНСТАНС, а один інстанс обслуговує і дашборд, і MCP. Тому веб-хендлери перекривають її через ContextVar (as_client("web")), інакше клік у дашборді не відрізнявся б від виклику з Claude Code — обидва були б mac.

• user — ХТО її зробив: subject з OAuth-токена, інакше TASKS_DEFAULT_USER (vlad). Сервіс поки однокористувацький, але поле пишеться вже зараз — щоб при появі другого пароля старі записи лишились коректними, а нові самі почали розрізняти людей. У виводі history це подано як юзер@клієнт, напр. vlad@chatgpt.

• Живе всередині planner/, тож автоматично потрапляє в restic-бекап.

Ізоляція (важливо)

Сервіс має доступ лише до planner/ — нічого іншого на хості він не бачить. На сервері обидва інстанси працюють від юзера tasks у пісочниці systemd: бачать лише /srv/planner (запис, власник tasks) і код (лише читання); решти файлової системи не бачать.

Формат / схема

- [x] Текст  #домен ⏫ 📅 2026-08-31 ⚡M [[звʼязок]] 📌[Заголовок] ^id

• Статуси (порядок колонок): [ ] backlog · [>] to do · [b] blockers · [/] in progress · [r] in review · [t] testing · [x] done

• Переходи (стор, для move_task, edit_task і дашборда): у to do — лише з backlog, testing, in progress, in review або blockers; у blockers — лише з backlog, to do або testing; у in progress — лише з to do; у in review — лише з in progress; у testing — лише з in progress, in review або blockers; у backlog і done — звідки завгодно. Нові задачі завжди створюються в backlog. Виняток: backlog → to do — лише з дашборда (веб-API); через MCP (move_task і зміна статусу в edit_task, для будь-якого клієнта) це помилка. Решта переходів однакова в MCP і на дашборді. Колонка blockers стоїть на дашборді одразу після To Do; board рахує її.

• Пріоритети: 🔺 asap · ⏫ high · 🔽 low

• WIP-ліміт: ≤15 задач у in progress (по всьому planner); to do і in review без ліміту

• Порядок To Do — ручний, у planner/todo-order.json (список id; не файл задач): задачі To Do лежать у різних файлах проєктів, тож порядок рядків його не передає. Вхід у To Do без позиції — в кінець (з testing, blockers, backlog), а з in progress і in review — нагору (позиція 1); явна position перемагає це правило; на дашборді скидання картки на місце в колонці (і зі backlog, і з самої To Do) ставить її туди — POST /api/task/edit приймає position (1-based; більше за довжину — в кінець; <1 чи не ціле — помилка, нічого не пишеться; лише разом зі статусом todo або для задачі, що вже в To Do). Вихід із To Do і видалення прибирають id; задача To Do, якої нема у файлі (напр. поставлена в Obsidian), стає в кінець і не губиться. list_tasks(status=todo) (і колонка дашборда) віддає To Do в цьому порядку, а не за пріоритетом. move_task / edit_task у MCP position не мають — вхід у To Do за правилом вище (нагору з in progress/in review, інакше в кінець).

• 📌[…] — короткий заголовок (≤50 символів) для канбану/календаря, обовʼязковий при створенні задачі (рядки без нього, зроблені руками в Obsidian, читаються без помилки)

• ^id — стабільний адресний id (додається автоматично, Obsidian block-id)

• text — один рядок: перенос рядка в add_task / edit_task (MCP і дашборд) — помилка.

• План (plan) — багаторядковий markdown (кроки, секція «Фідбек» тощо) в окремому файлі planner/plans/<id>.md, а не в рядку задачі; формат рядка не змінюється. Стор читає лише tasks.md і projects/*.md, тож - [ ] усередині плану задачами не стають. Зберігається байт-у-байт. Задаєш: add_task(plan=…), edit_task(plan=…) (порожній параметр — не чіпати, none — прибрати; у сторі й порожній текст прибирає), дашборд (поле «План» у діалозі, береться з GET /api/task?id=… — у списку /api/tasks плану нема). Читаєш: get_task. delete_task видаляє й файл плану. Зміна плану пишеться в журнал як поле plan (було → стало).

Транспорти (патерн brain-access)

MCP-ендпоінт — шлях /tasks (як /brain і /media). Скоуп OAuth — tasks.

OAuth приймає лише дозволені redirect_uri (2026-09-30): https://claude.ai/api/mcp/auth_callback, конектор ChatGPT https://chatgpt.com/connector/oauth/L5rDATRQa6U6 і loopback (CLI-логін); перевизначення — TASKS_REDIRECT_ALLOWLIST (через кому; …/* — один сегмент-ID, loopback). Клієнти поза списком лишаються в стейті, але для сервера не існують. /login показує, хто просить доступ, куди піде код і коли клієнта зареєстровано.

Журнал аудиту OAuth: journalctl -u task-manager-oauth | grep OAUTH_AUDIT — події register, register_rejected, login, login_failed, login_locked, refresh: хто увійшов, який клієнт (назва + перші 8 символів client_id) і куди йде код (хост + шлях, тобто ID конектора ChatGPT). Без токенів, кодів і rid.

ChatGPT app і Claude-конектор 🤖

Один і той самий OAuth-ендпоінт https://<host>/tasks для обох — DCR + PKCE, вхід паролем (TASKS_OAUTH_PASSWORD_HASH).

• ChatGPT (web): Settings → Developer mode → Apps → + → Name Planner, URL https://<host>/tasks, Auth OAuth (DCR — реєструється сам) → форма пароля. Іконка: assets/task-manager-icon.png. Після зміни тулів — Refresh у налаштуваннях застосунку й новий чат.

• Claude (claude.ai / iOS): Settings → Connectors → Add custom connector → той самий URL.

OAuth (як у brain-access): токени привʼязані до TASKS_RESOURCE_URL (RFC 8707, за замовч. = issuer) і scope рівно tasks; ResourceGuard перевіряє resource на /token; refresh без розширення scope; прострочені й legacy-токени (без resource) вичищаються на старті — після оновлення з версії без resource-binding конектори треба перелогінити один раз. Анотації тулів: read-only — board, list_tasks, get_task, history; зміни — add_task, move_task, set_priority, set_deadline; деструктивні (ChatGPT питає підтвердження) — edit_task (очищення полів, перенос між файлами) і delete_task. Журнал: правки з OAuth підписуються клієнтом токена — vlad@chatgpt / vlad@claude.

Запуск

uv sync
uv run python -m unittest discover -s tests          # усі тести (88, офлайн, без секретів)
uv run coverage run -m unittest discover -s tests && uv run coverage report   # покриття, поріг 80%
uv run task_manager.py                    # MCP-сервер (stdio)

Конфіг (env / .env)

Повний перелік — у .env.example. Головне:

• TASKS_PLANNER_ROOT — корінь planner (за замовч. ~/AI/planner; на сервері — /srv/planner, задає конфіг інстансу).

• TASKS_WIP_LIMIT — ліміт in progress (за замовч. 15).

• TASKS_TOKEN — bearer-секрет (генеруєш САМ, §8).

• TASKS_OAUTH_PASSWORD_HASH — хеш пароля OAuth (згенеруй: python3 -c "from getpass import getpass; from tasks_oauth import hash_password; print(hash_password(getpass()))" у теці репо; пароль вводиш сам).

• TASKS_ISSUER_URL — публічний issuer, напр. https://<host>/tasks.

• TASKS_RESOURCE_URL — resource для привʼязки токенів (за замовч. = issuer, якщо той закінчується на /tasks).

Клієнти

Агенти (Claude Code, claude.ai, ChatGPT, Codex) підключаються через OAuth-конектор https://<host>/tasks — токенів на Mac немає й синкати нічого не треба. Bearer :8792 лишається для веб-дашборда й прямих викликів у tailnet; TASKS_TOKEN живе лише в /etc/task-manager/env на сервері.

Деплой (systemd, юзер tasks)

• Юніти task-manager (bearer + дашборд, :8792) і task-manager-oauth (:8793) — від юзера tasks; юніт-файли ставиш сам.

• Код — цей чекаут (~/AI/server/task-manager, лише читання для tasks); venv — на системному Python (юзер tasks не бачить ~/.local/share/uv):

cd ~/AI/server/task-manager && git pull --ff-only && uv sync --frozen --no-dev --python /usr/bin/python3
sudo systemctl restart task-manager task-manager-oauth

• Секрети — /etc/task-manager/env (root 0600, правити sudoedit); стан OAuth — /var/lib/task-manager/oauth_state.json (TASKS_STATE_DIR). .env у чекауті на сервері не лишається. Health-чек:

curl -s -o /dev/null -w "bearer=%{http_code}\n" http://127.0.0.1:8792/tasks           # 401 = живий
curl -s -o /dev/null -w "oauth=%{http_code}\n"  http://127.0.0.1:8793/.well-known/oauth-authorization-server
curl -s -o /dev/null -w "public=%{http_code}\n" https://your-host.example.ts.net/.well-known/oauth-authorization-server/tasks

Кольори тегів

planner/tag-colors.json — {"<тег без #>": "#RRGGBB"}. Це не файл задач: стор його не читає як задачі, не журналює і не «запікає» в нього id. Формат кольору — лише #RRGGBB.

• GET /api/tag-colors → {"tag_colors": {...}}; той самий обʼєкт приходить у GET /api/tasks.

• POST /api/tag-color {"tag": "дім", "color": "#12ab34"} — поставити; "color": null — зняти. Не-hex (red, #12345, …) → 400, нічого не записується. Відповідь — усі кольори.

• Перейменування/міграція тегів — поза цією функцією (див. нижче).

• Тести: tests/test_tag_colors.py.

Міграція тегів на англійську

scripts/migrate_tags.py перейменовує #теги у tasks.md, projects/*.md і шаблонах projects/<слаг>/template.md за мапою та сіє дефолтні кольори маркерів (to-agent зелений, to-admin помаранчевий, dev синій, infra фіолетовий, design рожевий, blocked червоний). Вже заданий колір не перезаписується. Зміни йдуть у .history (tool: migrate_tags). Запускати на проді вручну, спершу dry-run:

# mapping.json: {"розробка": "dev", "побут": "home"}   (теги без '#')
uv run python scripts/migrate_tags.py <planner root> --map mapping.json          # dry-run: теги, кількість задач, заміни
uv run python scripts/migrate_tags.py <planner root> --map mapping.json --apply  # запис

• Корінь planner — аргумент, інакше TASKS_PLANNER_ROOT, інакше ~/AI/planner.

• Не-ASCII тег без пари в мапі → помилка, нічого не записується (також у dry-run).

• #розробка #dev в одній задачі → один #dev. Повторний запуск нічого не міняє.

• Ключі вже наявного tag-colors.json не перейменовуються: колір старого тега задай новому через дашборд або POST /api/tag-color.

• Тести: tests/test_migrate_tags.py.

Файли

• planner_model.py — Task + парсер/рендер рядка, розбиття файлу на блоки (fence-safe).

• planner_store.py — читання/атомарний запис (flock), операції, правила переходів, WIP-гард.

• task_manager.py — MCP-сервер (MCPServer, SDK 2.x), тули + три транспорти.

• tasks_oauth.py — OAuth 2.1 AS (single-user, DCR + login-гейт, resource binding, ResourceGuard), клон brain_oauth.py.

• tests/ — офлайн-тести за ZOMBIES (Zero/One/Many/Boundary/Interface/Exceptions/Simple), покриття рядків+гілок ≥80% (fail_under у pyproject.toml; станом на 2026-09-25 — 95%):

  • test_store.py — модель і стор (парсер, WIP, edit/перенос, журнал, шаблони);

  • test_statuses.py — статуси to do [>] / blockers [b] / in review [r]: парсинг, без ліміту, фільтр;

  • test_todo_order.py / test_todo_order_api.py — ручний порядок To Do: стор, MCP-тули, веб-API;

  • test_transitions.py — матриця переходів 7×7 для store і веб-API, WIP при to do → in progress;

  • test_blockers_api.py — blockers і переходи крізь MCP (backlog → to do заборонено) та дашборд;

  • test_tools.py — MCP-тули через mcp.call_tool (формат, фільтри, межі, помилки ⚠️);

  • test_web_api.py — API дашборда + bearer-гейт /tasks на bearer-інстансі;

  • test_oauth_server.py — OAuth-інстанс: /login і лок, discovery, анотації, ResourceGuard, vlad@chatgpt;

  • test_oauth_flow.py — OAuth AS: resource/scope/PKCE/refresh, чистка токенів, паролі;

  • test_tag_colors.py — кольори тегів: стор, API, контракт розмітки дашборда;

  • test_migrate_tags.py — міграція тегів на англійську і сів кольорів маркерів;

  • _support.py — тимчасовий planner, імпорт сервера з env, ASGI-клієнт без мережі.

• assets/task-manager-icon.png — іконка для ChatGPT app / конектора.

⚠️ Потрібен MCP SDK 2.x: у 2.0 FastMCP перейменовано на MCPServer. Код мігровано 2026-09-06.