Todocko MCP Server

English version below / Jump to English

MCP (Model Context Protocol) server pro práci s daty Todocko aplikace z AI asistentů.

Podpora

Claude Desktop - plná podpora
Claude Code (CLI) - plná podpora (stejná konfigurace)

Požadavky

Node.js 24.20+ — Evolu v8 to má v engines, a není to formalita: v8 stojí na navigator.locks, MessageChannel, BroadcastChannel a WebSocket, které má Node nativně teprve od 24
Todocko účet s daty synchronizovanými přes Evolu

Evolu v8 (TODO-88)

MCP běží na @evolu/common 8.9.0 a @evolu/nodejs 3.2.0.

v7 dodával createDbWorkerForPlatform, což bylo vše, co headless klient v Node potřeboval. v8 to zrušil: @evolu/nodejs v3 nabízí relay a pár primitiv, a jedinou kompletní klientskou platformu má upstream pro web. src/evoluPlatform.ts je protějšek pro Node, poskládaný ze stejných dílů.

Vyšel krátce, protože Node 24 má potřebná web API nativně. Oba workery běží in-process přes createWorker / createSharedWorker — to jsou vlastní fallbacky Evolu „pro platformy bez podpory workerů"; worker_threads by přinesly izolaci, kterou jednoprocesový CLI nepotřebuje.

Pět věcí, na kterých se to dá snadno rozbít:

installPolyfills() je povinné a musí proběhnout dřív než cokoli z @evolu/common. v8 volá Map.prototype.getOrInsert(Computed), které nemá žádný vydaný Node (ověřeno do 25.9.0). Bez toho to spadne na první zprávě.
Databáze patří jednomu mnemonicu. v7 při neshodě volal restoreAppOwner, který lokální databázi resetoval. v8 obnovu nemá, takže by v souboru zůstala data starého ownera zašifrovaná klíčem, který nový nemá. Server proto neshodu ohlásí a odmítne nastartovat — smaž ~/.todocko/todocko.db a nech ho stáhnout data znovu.
createNodeEvoluDeps() musí být singleton na proces. Shared worker drží jediný tabLeaderPortStore a initDbWorker každého tenanta předpokládá, že je už naplněný. Druhá sada deps znamená druhý shared worker, kterému nikdo leadera neohlásil, a vytvoření sdílené instance spadne na initDbWorker: Expected value to be non-nullable. Jeden worker obslouží obě instance jako dva tenanty podle appName, stejně jako @evolu/web na jedné stránce.
Mutace nevrací Result. v7 vracel z insert/update Result, takže se testovalo result.ok a čtlo result.value.id. v8 vrací přímo { id } a při neplatné změně vyhodí výjimku. Kontrola !result.ok proto uspěla vždy a nástroj ohlásil chybu u zápisu, který právě proběhl. U vkládání je to horší, protože uživatel to zkusí znovu a vznikne duplicita. Hlídá to src/tools/pure.test.ts.
Ownera filtrovat v SQL, ne až v JS. Sdílená instance drží data všech ownerů v jedné tabulce. limit provede SQLite dřív, než se v JS cokoli filtruje, takže nezúžený dotaz vrátí prvních N řádků přes všechny ownery a filtr je pak zahodí. Nástroj hlásil nula úkolů u projektu, který jich má 26. Stejná past číhá u orderBy position desc limit 1 při výpočtu další pozice.

Instalace

1. Stažení

Pomocí git:

git clone https://github.com/brnt-cz/todocko-mcp.git
cd todocko-mcp

Nebo stáhněte ZIP z Releases a rozbalte.

2. Spuštění instalátoru

Linux/macOS:

chmod +x install.sh
./install.sh

Windows (PowerShell):

.\install.ps1

Instalátor:

Nainstaluje závislosti a sestaví projekt
Zeptá se, zda chcete nakonfigurovat Claude Desktop, Claude Code nebo obojí
Vytvoří konfigurační soubor s placeholderem
Ručně doplňte svou 24slovnou zálohovací frázi do konfiguračního souboru
Restartujte Claude

Manuální instalace

Nainstalujte závislosti:
```
npm install
npm run build
```
Přidejte do konfigurace:

Claude Desktop (~/.config/Claude/claude_desktop_config.json na Linuxu nebo ~/Library/Application Support/Claude/claude_desktop_config.json na macOS):

{
  "mcpServers": {
    "todocko": {
      "command": "node",
      "args": ["/cesta/k/mcp-server/dist/index.js"],
      "env": {
        "TODOCKO_MNEMONIC": "vaše 24slovná zálohovací fráze"
      }
    }
  }
}

Claude Code (CLI) - přidejte do ~/.claude/settings.json:

{
  "mcpServers": {
    "todocko": {
      "command": "node",
      "args": ["/cesta/k/mcp-server/dist/index.js"],
      "env": {
        "TODOCKO_MNEMONIC": "vaše 24slovná zálohovací fráze"
      }
    }
  }
}

Restartujte Claude Desktop / Claude Code

Dostupné nástroje (152)

Projekty

Nástroj	Popis
`td_list_projects`	Seznam všech projektů
`td_get_project`	Detail projektu podle ID nebo kódu
`td_create_project`	Vytvoření nového projektu
`td_update_project`	Aktualizace projektu (name, code, color, isArchived, autoApproveMembers, isHiddenFromFilters)
`td_delete_project`	Smazání projektu (soft delete)

Úkoly

Nástroj	Popis
`td_list_tasks`	Seznam úkolů s filtry (projekt, status, priorita, assignee)
`td_get_task`	Detail úkolu podle ID nebo kódu (např. `PROJ-123`), včetně nastavení opakování
`td_create_task`	Vytvoření nového úkolu (včetně recurrence, sprintNumber, parentTaskId)
`td_update_task`	Aktualizace existujícího úkolu (včetně recurrence, sprintNumber, parentTaskId)
`td_search_tasks`	Vyhledávání úkolů podle textu
`td_bulk_update_tasks`	Hromadná aktualizace více úkolů (včetně sprintNumber)
`td_bulk_delete_tasks`	Hromadné smazání více úkolů
`td_delete_task`	Smazání jednoho úkolu (soft delete, kaskáda na worklogy a přílohy)
`td_list_git_events`	Git aktivita pro úkol (commits, PR) z relay serveru

Uživatelé

Nástroj	Popis
`td_list_users`	Seznam všech uživatelů
`td_get_user`	Detail uživatele
`td_create_user`	Vytvoření nového uživatele
`td_update_user`	Aktualizace uživatele
`td_delete_user`	Smazání uživatele (soft delete)

Worklogy

Nástroj	Popis
`td_list_worklogs`	Seznam worklogů pro úkol
`td_add_worklog`	Přidání worklogu k úkolu
`td_update_worklog`	Aktualizace worklogu
`td_delete_worklog`	Smazání worklogu (soft delete)

Přílohy

Nástroj	Popis
`td_upload_attachment`	Nahrání přílohy k úkolu (ze souboru nebo base64)
`td_list_attachments`	Seznam příloh úkolu
`td_download_attachment`	Stažení přílohy
`td_delete_attachment`	Smazání přílohy
`td_upload_note_attachment`	Nahrání přílohy k lokální poznámce projektu
`td_list_note_attachments`	Seznam příloh lokální poznámky
`td_download_note_attachment`	Stažení přílohy poznámky
`td_delete_note_attachment`	Smazání přílohy poznámky

Komentáře

Nástroj	Popis
`td_list_task_comments`	Seznam komentářů k úkolu
`td_create_task_comment`	Přidání komentáře k úkolu
`td_update_task_comment`	Úprava komentáře
`td_delete_task_comment`	Smazání komentáře (soft delete)

Checklist

Nástroj	Popis
`td_list_checklist_items`	Seznam položek checklistu úkolu
`td_create_checklist_item`	Přidání položky checklistu
`td_update_checklist_item`	Aktualizace položky (zaškrtnutí, pozice)
`td_delete_checklist_item`	Smazání položky (soft delete)

Zmínky (mentions)

Nástroj	Popis
`td_list_mentions`	Seznam zmínek uživatele
`td_create_mention`	Vytvoření zmínky
`td_mark_mention_read`	Označení zmínky jako přečtené
`td_mark_all_mentions_read`	Označení všech zmínek jako přečtených
`td_delete_mention`	Smazání zmínky (soft delete)

Linky mezi úkoly

Nástroj	Popis
`td_list_task_links`	Seznam linků úkolu
`td_create_task_link`	Vytvoření linku mezi úkoly
`td_delete_task_link`	Smazání linku (soft delete)

Tagy

Nástroj	Popis
`td_list_tags`	Seznam štítků; vrací `projectId`, umí filtrovat podle projektu i na nezařazené
`td_create_tag`	Vytvoření štítku — předej `projectId`, viz poznámku níž
`td_update_tag`	Přejmenování, změna barvy, přiřazení projektu, nebo příznak výchozího štítku
`td_delete_tag`	Smazání štítku (soft delete)
`td_list_task_tags`	Seznam štítků přiřazených k úkolu
`td_add_tag_to_task`	Přiřazení štítku k úkolu
`td_remove_tag_from_task`	Odebrání štítku z úkolu

Sdílené projekty (TODO-235):

Nástroj	Popis
`td_list_shared_tags`	Štítky ve sdíleném projektu
`td_create_shared_tag`	Vytvoření štítku ve sdíleném projektu
`td_update_shared_tag`	Přejmenování / změna barvy / příznak výchozího štítku
`td_delete_shared_tag`	Smazání (soft delete)
`td_add_shared_tag_to_task`	Přiřazení k úkolu ve sdíleném projektu
`td_remove_shared_tag_from_task`	Odebrání z úkolu

Štítek bez projektu appka nikde nenabídne. Od TODO-227 jsou štítky vázané na projekt; td_create_tag bez projectId vyrobí nezařazený štítek, který se v appce objeví jen v nastavení projektu v sekci „Nezařazené" s tlačítkem na přiřazení. Odpověď nástroje na to upozorní. Dodatečně to spraví td_update_tag s projectId.
Limity free tarifu (TODO-243). Tarifní limity patří do appky, ne sem. td_create_task a td_create_project proto do odpovědi přilepí varování s reálným počtem, když je owner na free tarifu a je nad limitem (1 projekt, 50 aktivních úkolů). Jde o to, aby se to člověk dozvěděl při zakládání, ne až zpětně v appce, a aby z textu bylo jasné, že o nic nepřišel. Nic to neblokuje a při neznámém tarifu (nedostupný relay) radši mlčí — falešný poplach je horší než žádný.

Výchozí štítky (TODO-239). isDefault u td_create_tag / td_update_tag (a sdílených variant) znamená, že štítek dostane každý nově zakládaný úkol projektu. td_create_task i td_create_shared_task je přidávají samy a vrátí je v appliedTags — appka je předzaškrtává v modalu, takže bez toho by výsledek závisel na tom, odkud úkol vznikne. Existujících úkolů se to nedotkne.
Ve sdílených projektech se zapisuje do jiné Evolu instance, proto samostatná sada nástrojů — td_add_tag_to_task na sdílený úkol nefunguje.

Šablony úkolů

Nástroj	Popis
`td_list_task_templates`	Seznam šablon úkolů
`td_create_task_template`	Vytvoření šablony
`td_update_task_template`	Aktualizace šablony
`td_delete_task_template`	Smazání šablony (soft delete)

Kanban sloupce

Nástroj	Popis
`td_list_kanban_columns`	Seznam kanban sloupců
`td_create_kanban_column`	Vytvoření sloupce
`td_update_kanban_column`	Aktualizace sloupce
`td_delete_kanban_column`	Smazání sloupce (soft delete)

Uložená zobrazení

Nástroj	Popis
`td_list_saved_views`	Seznam uložených zobrazení
`td_create_saved_view`	Vytvoření zobrazení
`td_update_saved_view`	Aktualizace zobrazení
`td_delete_saved_view`	Smazání zobrazení (soft delete)

Aktivita

Nástroj	Popis
`td_list_activity_log`	Seznam zápisů aktivity s filtry (úkol, aktor, akce, typ entity, datum od/do) — read-only

Poznámky k projektu

Nástroj	Popis
`td_list_project_notes`	Seznam lokálních poznámek projektu
`td_create_project_note`	Vytvoření lokální poznámky
`td_update_project_note`	Aktualizace lokální poznámky
`td_delete_project_note`	Smazání lokální poznámky (soft delete)

Dokumentace projektu

Dokumenty jsou poznámky s isDoc, takže mohou být zanořené pod jiný dokument (parentDocId).

Nástroj	Popis
`td_list_project_docs`	Seznam dokumentů projektu
`td_create_project_doc`	Vytvoření dokumentu
`td_update_project_doc`	Aktualizace dokumentu
`td_delete_project_doc`	Smazání dokumentu (soft delete)

Systémová oznámení (relay)

Broadcast oznámení pro všechny uživatele. Zápis a výpis včetně expirovaných vyžaduje TODOCKO_RELAY_ADMIN_KEY; obráceným směrem jdou zprávy od uživatelů, viz níž.

Nástroj	Popis
`td_list_system_notifications`	Seznam aktivních oznámení (s `admin: true` i expirovaná)
`td_create_system_notification`	Vytvoření oznámení pro všechny uživatele
`td_delete_system_notification`	Smazání oznámení

Deployment stages

Nástroj	Popis
`td_list_deployment_stages`	Seznam deployment stages pro projekt
`td_create_deployment_stage`	Vytvoření deployment stage
`td_update_deployment_stage`	Aktualizace deployment stage
`td_delete_deployment_stage`	Smazání deployment stage (soft delete)

Repository linky

Nástroj	Popis
`td_list_repository_links`	Seznam repozitářových linků
`td_create_repository_link`	Vytvoření repozitářového linku
`td_update_repository_link`	Aktualizace repozitářového linku
`td_delete_repository_link`	Smazání repozitářového linku

Sdílené projekty

Nástroj	Popis
`td_list_shared_projects`	Seznam sdílených projektů
`td_list_shared_tasks`	Seznam úkolů ze sdíleného projektu
`td_create_shared_task`	Vytvoření úkolu ve sdíleném projektu (auto-generovaný kód)
`td_update_shared_task`	Aktualizace úkolu ve sdíleném projektu (všechna pole včetně recurrence, estimate, blocking)
`td_delete_shared_task`	Smazání úkolu ve sdíleném projektu (soft delete, kaskáda na checklist)
`td_update_shared_project`	Aktualizace sdíleného projektu: název, kód, barva, archivace, skrytí z filtrů, automatické schvalování členů
`td_list_shared_worklogs`	Seznam worklogů úkolu ve sdíleném projektu
`td_add_shared_worklog`	Přidání worklogu k úkolu ve sdíleném projektu
`td_delete_shared_worklog`	Smazání worklogu ve sdíleném projektu
`td_list_shared_checklist_items`	Seznam položek checklistu úkolu ve sdíleném projektu
`td_create_shared_checklist_item`	Přidání položky checklistu ve sdíleném projektu
`td_update_shared_checklist_item`	Aktualizace položky checklistu ve sdíleném projektu
`td_delete_shared_checklist_item`	Smazání položky checklistu ve sdíleném projektu
`td_list_shared_task_comments`	Seznam komentářů úkolu ve sdíleném projektu
`td_create_shared_task_comment`	Přidání komentáře k úkolu ve sdíleném projektu
`td_update_shared_task_comment`	Aktualizace komentáře ve sdíleném projektu
`td_delete_shared_task_comment`	Smazání komentáře ve sdíleném projektu
`td_upload_shared_attachment`	Nahrání přílohy k úkolu ve sdíleném projektu
`td_list_shared_attachments`	Seznam příloh úkolu ve sdíleném projektu
`td_download_shared_attachment`	Stažení přílohy úkolu sdíleného projektu
`td_delete_shared_attachment`	Smazání přílohy úkolu sdíleného projektu
`td_list_shared_deployment_stages`	Seznam deployment stages pro sdílený projekt
`td_create_shared_deployment_stage`	Vytvoření deployment stage ve sdíleném projektu
`td_update_shared_deployment_stage`	Aktualizace deployment stage ve sdíleném projektu
`td_delete_shared_deployment_stage`	Smazání deployment stage ve sdíleném projektu
`td_list_shared_repository_links`	Seznam repozitářových linků sdíleného projektu
`td_create_shared_repository_link`	Vytvoření repozitářového linku ve sdíleném projektu
`td_update_shared_repository_link`	Aktualizace repozitářového linku ve sdíleném projektu
`td_delete_shared_repository_link`	Smazání repozitářového linku ve sdíleném projektu
`td_list_shared_project_notes`	Seznam poznámek sdíleného projektu
`td_create_shared_project_note`	Vytvoření poznámky ve sdíleném projektu
`td_update_shared_project_note`	Aktualizace poznámky ve sdíleném projektu
`td_delete_shared_project_note`	Smazání poznámky ve sdíleném projektu
`td_list_shared_members`	Seznam členů sdíleného projektu (jméno, oprávnění, kicked/blocked stav)
`td_update_shared_member`	Změna oprávnění / block / kick člena sdíleného projektu
`td_upload_shared_note_attachment`	Nahrání přílohy k poznámce sdíleného projektu
`td_list_shared_note_attachments`	Seznam příloh poznámky sdíleného projektu
`td_download_shared_note_attachment`	Stažení přílohy poznámky sdíleného projektu
`td_delete_shared_note_attachment`	Smazání přílohy poznámky sdíleného projektu
`td_list_shared_project_docs`	Seznam dokumentů sdíleného projektu
`td_create_shared_project_doc`	Vytvoření dokumentu ve sdíleném projektu
`td_update_shared_project_doc`	Aktualizace dokumentu ve sdíleném projektu
`td_delete_shared_project_doc`	Smazání dokumentu ve sdíleném projektu
`td_get_shared_task`	Detail jednoho úkolu ve sdíleném projektu (podle ID nebo kódu, s odpracovaným časem a počty checklistu a komentářů)
`td_list_shared_task_tags`	Tagy úkolu ve sdíleném projektu
`td_bulk_update_shared_tasks`	Hromadná úprava úkolů ve sdíleném projektu
`td_bulk_delete_shared_tasks`	Hromadné smazání úkolů ve sdíleném projektu (kaskáda na checklist a komentáře)
`td_update_shared_worklog`	Úprava worklogu ve sdíleném projektu
`td_list_shared_activity_log`	Aktivita ve sdíleném projektu (stejné filtry jako u osobní)

Stavy úkolů a validace argumentů (TODO-296, TODO-297). Stav recurring je plnohodnotný, appka ho používá pro opakované úkoly a MCP ho teď nabízí ve všech devíti enumech. Zároveň se kontrolují hodnoty enumů a odmítají nedeklarované argumenty. Dřív byly enumy jen dokumentace a neznámý argument se tiše zahodil, což je přesně způsob, jak td_create_shared_checklist_item přijal isChecked, vrátil success a položku založil neodškrtnutou. Ten argument tam dnes je.
Při té příležitosti se srovnal i linkType: MCP nabízelo related, kterému appka nerozumí, a chyběly mu explicit a mention, které appka opravdu zapisuje. Platné hodnoty jsou blocks, explicit, mention.

Rodič se ověřuje, argumenty jsou dorovnané (TODO-300, TODO-302). td_create_task_comment a td_create_checklist_item šly dřív založit na neexistující úkol: řádek se zapsal proti ID, které nic nerozřeší, každý výpis jde přes taskId, takže ho nikdo nikdy nepřečte, a tool vrátil success. td_add_worklog to odmítal od TODO-90 M12, tyhle dva ne. Teď odmítají obě strany, osobní i sdílená, a sdílená scopuje i podle ownera.
Zároveň se dorovnalo devět argumentů, které sdílené tooly proti osobním neměly. Nejcitelnější byl td_update_shared_project: uměl jen archivaci, takže sdílený projekt nešlo přejmenovat.

Zprávy od uživatelů (relay)

Zprávy, které uživatelé posílají z aplikace (hlášení vad, návrhy, vzkazy). Výpis a mazání umí jen admin owner a relay od TODO-90 H2 nevěří samotnému ownerId — požadavek se podepisuje Ed25519 klíčem odvozeným z nastaveného mnemoniku. Odesílání relay nechává nepřihlášené, stejně jako formulář v appce.

Nástroj	Popis
`td_list_user_messages`	Výpis zpráv od uživatelů (jen admin owner)
`td_submit_user_message`	Odeslání zprávy adminům (hlášení vady, návrh, vzkaz)
`td_delete_user_message`	Smazání zprávy na relayi (jen admin owner, tvrdé smazání)

Analytika a přehledy

Nástroj	Popis
`td_get_dashboard_summary`	Přehled: úkoly dnes, po termínu, odpracováno tento týden, nadcházející deadline
`td_get_team_workload`	Vytížení týmu: odpracováno vs odhad vs kapacita per uživatel za období
`td_list_recurring_tasks`	Seznam opakujících se úkolů s konfigurací opakování
`td_list_overdue_tasks`	Úkoly po termínu (seřazené od nejstaršího)

Do v1.6.0 tyhle tři nástroje vracely vždy prázdno. td_list_recurring_tasks, td_list_overdue_tasks a td_list_tasks_by_date_range čtly result.rows, zatímco evolu.loadQuery vrací pole samo — takže count: 0 na jakýkoli vstup, bez chyby, které by šlo si všimnout. Opraveno v TODO-242 přes společný queryRows. Recurrence pole navíc vrací i td_get_task, takže nastavení opakování jde přečíst tou nejpřímější cestou. | td_list_tasks_by_date_range | Úkoly filtrované podle scheduledDate nebo deadline v daném rozmezí | | td_analyze_dependencies | Analýza závislostí: blokované úkoly, blokující řetězce, kritická cesta |

Sdílené projekty se do analytiky počítají (TODO-112). Do MCP IX čtlo všech pět přehledů jen osobní instanci, takže úkol ve sdíleném projektu neviděl dashboard, rozdělení vytížení, seznam opakujících se ani po termínu, ani dotaz na rozmezí dat. U vytížení to nebylo jen chybějící číslo: počítá se z odpracovaného času, takže vynechané sdílené minuty podhodnocovaly každého, kdo ve sdíleném projektu pracuje. Každý nástroj bere includeShared (výchozí true) a vrací sharedIncluded, ať je vidět, jestli se sdílená polovina opravdu načetla. td_analyze_dependencies zůstává záměrně jen osobní: appka sdílené taskLink řádky čte, ale žádné nezapisuje.
td_search_tasks hledá ve sdílených projektech taky, se stejným přepínačem.

Diagnostika

Nástroj	Popis
`td_sync_status`	Stav synchronizace
`td_force_sync`	Vynutí sync round-trip s relayem (užitečné, když chceš mít jistotu, že vidíš nejnovější data z jiného zařízení)

Příklady použití

Seznam projektů

Zobraz mi seznam všech projektů v Todocko

Seznam úkolů

Jaké mám úkoly ve stavu "todo"?
Zobraz úkoly projektu TODO

Detail úkolu

Jaké jsou detaily úkolu TODO-15?

Vytvoření úkolu

Vytvoř nový úkol v projektu PROJ s názvem "Opravit bug v přihlášení" a prioritou high
Vytvoř úkol s deadline na 2026-03-15 a scheduledDate na 2026-03-10

Aktualizace úkolu

Označ úkol PROJ-5 jako dokončený
Přiřaď úkol TODO-10 uživateli s ID xyz
Nastav scheduledDate úkolu TODO-10 na zítra

Logování času

Zaloguj 2 hodiny práce na úkol TODO-15 s popisem "Implementace feature"

Práce s přílohami

Nahraj soubor /home/user/report.pdf jako přílohu k úkolu TODO-15
Jaké přílohy má úkol TODO-15?
Smaž přílohu s ID xyz

Sdílené projekty

Zobraz sdílené projekty
Jaké úkoly jsou ve sdíleném projektu?
Označ úkol jako nasazený na produkci

Deployment stages

Jaké deployment stages má projekt?
Vytvoř novou deployment stage "Staging" pro sdílený projekt

Sub-úkoly

Vytvoř sub-úkol k úkolu TODO-15 v projektu TODO
Odpoj úkol TODO-20 od rodičovského úkolu (parentTaskId: null)

Přehledy a analytika

Jaký mám dnes přehled? (dashboard summary)
Jak je vytížený tým tento týden?
Jaké úkoly jsou po termínu?
Zobraz úkoly naplánované na příští týden
Analyzuj závislosti v projektu TODO
Jaké mám opakující se úkoly?

Linux CLI (`todo`) (TODO-160)

Vedle MCP serveru je v balíčku i CLI todo pro rychlé osobní ovládání z terminálu — sdílí stejnou databázi i TODOCKO_MNEMONIC jako MCP. Po npm link (nebo globální instalaci) je dostupné jako todo.

📖 Podrobný návod: CLI.md

# Přidání úkolu (bez -p použije první projekt)
todo add "Opravit login"
todo add "Opravit login" -p TODO --priority high --scheduled today

# Změna stavu (identifikace kódem úkolu)
todo done TODO-160          # status=done
todo start TODO-160         # status=in_progress
todo mv TODO-160 review     # backlog|todo|in_progress|review|done|recurring

# Worklog
todo log TODO-160 1h30m "ladění OAuth"
todo worklogs TODO-160      # tabulka worklogů

# Strojový výstup na všech příkazech
todo add "X" --json

Architektura: src/cli.ts (commander) → mapuje argumenty na existující tool handlery (handleToolCall), žádná duplicitní business logika. Kód úkolu se překládá na ID přes td_get_task.
Sync: po mutaci čeká ~3 s na relay; když je offline, vypíše ⚠ uloženo lokálně a skončí s kódem 0 (data jsou lokálně bezpečně).
Exit kódy: 0 úspěch, 1 user/business chyba (neznámý kód, špatný stav/čas), 2 config (chybí mnemonic).
Barvy jen v TTY a při nenastaveném NO_COLOR.
Pozn.: běží jako samostatný proces nad stejnou SQLite DB jako MCP; při souběžném zápisu s MCP může (vzácně) nastat SQLITE_BUSY — v takovém případě příkaz zopakuj. Mimo rozsah v1: list/today, editace popisu, projekty/tagy/checklist, sdílené projekty.

Bezpečnost

Důležité: Vaše zálohovací fráze (mnemonic) je citlivý údaj!

Nikdy ji nesdílejte v přímé konverzaci s AI
V konfiguraci MCP serveru je fráze bezpečná (AI k ní nemá přístup)
Kdokoli s vaší frází má plný přístup k vašim datům

WebSocket Origin (TODO-169)

MCP server při WebSocket připojení k relay posílá hlavičku Origin: https://todocko-mcp. Sdílený relay (relay.todocko.cz) má tuto hodnotu povolenou ve whitelistu Access Control. Pokud používáš vlastní relay, musíš ji přidat do tiers.json.allowedDomains, jinak relay odmítne připojení s 403 Forbidden na WS upgrade.

Umístění dat

Databáze jsou uloženy v adresáři ~/.todocko/:

Platforma	Cesta
Linux	`~/.todocko/`
macOS	`~/.todocko/`
Windows	`C:\Users\<user>\.todocko\`

Soubory:

todocko.db - vaše osobní data (úkoly, projekty)
todocko-shared.db - sdílené projekty

Změna konfigurace

Claude Code (CLI)

Po změně konfigurace v ~/.claude/settings.json (např. změna mnemonicu) spusťte příkaz:

/mcp

Tím se MCP server restartuje s novou konfigurací.

Přepnutí na jiný účet

Při změně mnemonicu na jiný Todocko účet je potřeba smazat lokální databázi:

# Linux/macOS
rm ~/.todocko/todocko.db

# Windows
del %USERPROFILE%\.todocko\todocko.db

Databáze obsahuje ID vlastníka z předchozího mnemonicu. Po smazání se při dalším spuštění vytvoří nová databáze a stáhnou se data nového účtu.

Troubleshooting

Server se nespustí

Zkontrolujte, že máte Node.js 24.20+
Zkontrolujte, že jste spustili npm run build
Zkontrolujte logy v Claude Desktop

Data se nesynchronizují

Ověřte, že je zálohovací fráze správná (24 slov)
Zkontrolujte internetové připojení
Počkejte pár sekund na synchronizaci
Zkuste smazat ~/.todocko/todocko.db a restartovat

Nástroje nejsou viditelné

Restartujte Claude Desktop
V Claude Code použijte /mcp pro reload
Zkontrolujte konfigurační soubor
Zkontrolujte cestu k dist/index.js

Každý `loadQuery` skončí timeoutem (`loadQuery timed out after 15000ms`)

Příčina: better-sqlite3 native binding byl zkompilován proti jiné Node.js ABI verzi, než pod kterou MCP server běží. new Database() selže s ERR_DLOPEN_FAILED, Evolu dbWorker init nikdy nedoběhne a všechny loadQuery volání visí navždy. Mutace (insert/update) reportují success, ale ve skutečnosti se nezapíšou.

Symptom v praxi: td_sync_status hlásí ok, errorCount: 0, ale td_get_task, td_list_* apod. timeoutují.

Fix — přebuildit native binding proti aktuálnímu Node:

cd ~/.todocko-mcp # případně cesta, kde máš nainstalované todocko-mcp
cd node_modules/better-sqlite3
npx node-gyp rebuild --release

Pak /mcp reconnect v Claude Code.

Mismatch je typický, pokud upgradneš Node.js (např. z v22 na v25) nebo přepneš mezi nvm a linuxbrew/brew Node. Při instalaci installer použije node z PATH — pokud claude později spouští MCP přes jiný node binary, binding nesedí.

Vývoj

# Instalace závislostí
npm install

# Build
npm run build

# Watch mode pro vývoj
npm run dev

# Ruční spuštění
TODOCKO_MNEMONIC="vaše fráze" npm start

English

MCP (Model Context Protocol) server for working with Todocko app data from AI assistants.

Support

Claude Desktop - full support
Claude Code (CLI) - full support (same configuration)

Requirements

Node.js 24.20+ — required by Evolu v8's engines, and not merely formally: v8 relies on navigator.locks, MessageChannel, BroadcastChannel and WebSocket, which Node only has natively from 24 on
Todocko account with data synchronized via Evolu

Installation

1. Download

Using git:

git clone https://github.com/brnt-cz/todocko-mcp.git
cd todocko-mcp

Or download ZIP from Releases and extract.

2. Run the installer

Linux/macOS:

chmod +x install.sh
./install.sh

Windows (PowerShell):

.\install.ps1

The installer will:

Install dependencies and build the project
Ask whether to configure Claude Desktop, Claude Code, or both
Create a configuration file with a placeholder
Manually add your 24-word backup phrase to the configuration file
Restart Claude

Manual installation

Install dependencies:
```
npm install
npm run build
```
Add to configuration:

Claude Desktop (~/.config/Claude/claude_desktop_config.json on Linux or ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "todocko": {
      "command": "node",
      "args": ["/path/to/mcp-server/dist/index.js"],
      "env": {
        "TODOCKO_MNEMONIC": "your 24 word backup phrase"
      }
    }
  }
}

Claude Code (CLI) - add to ~/.claude/settings.json:

{
  "mcpServers": {
    "todocko": {
      "command": "node",
      "args": ["/path/to/mcp-server/dist/index.js"],
      "env": {
        "TODOCKO_MNEMONIC": "your 24 word backup phrase"
      }
    }
  }
}

Restart Claude Desktop / Claude Code

Available Tools (152)

Projects

Tool	Description
`td_list_projects`	List all projects
`td_get_project`	Get project details by ID or code
`td_create_project`	Create a new project
`td_update_project`	Update a project (name, code, color, isArchived, autoApproveMembers, isHiddenFromFilters)
`td_delete_project`	Delete a project (soft delete)

Tasks

Tool	Description
`td_list_tasks`	List tasks with filters (project, status, priority, assignee)
`td_get_task`	Get task details by ID or code (e.g., `PROJ-123`), recurrence settings included
`td_create_task`	Create a new task (with recurrence, sprint, parentTaskId support)
`td_update_task`	Update an existing task (with recurrence, sprint, parentTaskId support)
`td_search_tasks`	Search tasks by text
`td_bulk_update_tasks`	Bulk update multiple tasks
`td_bulk_delete_tasks`	Bulk delete multiple tasks
`td_delete_task`	Soft-delete a single personal task (cascades to its worklogs and attachments).
`td_list_git_events`	List git events (push, PR opened/merged/closed) for a task by its code.

Users

Tool	Description
`td_list_users`	List all users
`td_get_user`	Get user details
`td_create_user`	Create a new user
`td_update_user`	Update a user
`td_delete_user`	Delete a user (soft delete)

Worklogs

Tool	Description
`td_list_worklogs`	List worklogs for a task
`td_add_worklog`	Add a worklog to a task
`td_update_worklog`	Update a worklog
`td_delete_worklog`	Delete a worklog (soft delete)

Attachments

Tool	Description
`td_upload_attachment`	Upload an attachment to a task (from file or base64)
`td_list_attachments`	List attachments for a task
`td_download_attachment`	Download an attachment
`td_delete_attachment`	Delete an attachment
`td_upload_note_attachment`	Upload an attachment to a local project note
`td_list_note_attachments`	List attachments of a local note
`td_download_note_attachment`	Download a note attachment
`td_delete_note_attachment`	Delete a note attachment

Comments

Tool	Description
`td_list_task_comments`	List comments for a task
`td_create_task_comment`	Add a comment to a task
`td_update_task_comment`	Update a comment
`td_delete_task_comment`	Delete a comment (soft delete)

Checklist

Tool	Description
`td_list_checklist_items`	List checklist items for a task
`td_create_checklist_item`	Add a checklist item
`td_update_checklist_item`	Update a checklist item (check, reposition)
`td_delete_checklist_item`	Delete a checklist item (soft delete)

Mentions

Tool	Description
`td_list_mentions`	List mentions for a user
`td_create_mention`	Create a mention
`td_mark_mention_read`	Mark a mention as read
`td_mark_all_mentions_read`	Mark all mentions as read
`td_delete_mention`	Delete a mention (soft delete)

Task Links

Tool	Description
`td_list_task_links`	List links for a task
`td_create_task_link`	Create a link between tasks
`td_delete_task_link`	Delete a task link (soft delete)

Task Templates

Tool	Description
`td_list_task_templates`	List task templates
`td_create_task_template`	Create a task template
`td_update_task_template`	Update a task template
`td_delete_task_template`	Delete a task template (soft delete)

Kanban Columns

Tool	Description
`td_list_kanban_columns`	List kanban columns
`td_create_kanban_column`	Create a kanban column
`td_update_kanban_column`	Update a kanban column
`td_delete_kanban_column`	Delete a kanban column (soft delete)

Saved Views

Tool	Description
`td_list_saved_views`	List saved views
`td_create_saved_view`	Create a saved view
`td_update_saved_view`	Update a saved view
`td_delete_saved_view`	Delete a saved view (soft delete)

Activity Log

Tool	Description
`td_list_activity_log`	List activity log entries with filters (task, actor, action, entityType, date from/to) — read-only

Project Notes

Tool	Description
`td_list_project_notes`	List local project notes
`td_create_project_note`	Create a local project note
`td_update_project_note`	Update a local project note
`td_delete_project_note`	Delete a local project note (soft delete)

Deployment Stages

Tool	Description
`td_list_deployment_stages`	List deployment stages for a project
`td_create_deployment_stage`	Create a deployment stage for a personal project.
`td_update_deployment_stage`	Update a deployment stage in a personal project.
`td_delete_deployment_stage`	Soft-delete a deployment stage in a personal project.

Repository Links

Tool	Description
`td_list_repository_links`	List repository links
`td_create_repository_link`	Create a repository link
`td_delete_repository_link`	Delete a repository link
`td_update_repository_link`	Update a repository link for a project.

Shared Projects

Tool	Description
`td_list_shared_projects`	List shared projects
`td_list_shared_tasks`	List tasks from a shared project
`td_update_shared_task`	Update a task in a shared project
`td_list_shared_deployment_stages`	List deployment stages for a shared project
`td_create_shared_deployment_stage`	Create a deployment stage in a shared project
`td_list_shared_repository_links`	List repository links for a shared project
`td_create_shared_repository_link`	Create a repository link in a shared project
`td_list_shared_project_notes`	List notes for a shared project
`td_create_shared_project_note`	Create a note in a shared project
`td_update_shared_project_note`	Update a note in a shared project
`td_delete_shared_project_note`	Delete a note in a shared project
`td_list_shared_members`	List members of a shared project (name, permission, kicked/blocked state)
`td_update_shared_member`	Change permission / block / kick a shared project member
`td_upload_shared_note_attachment`	Upload an attachment to a shared project note
`td_list_shared_note_attachments`	List attachments of a shared project note
`td_download_shared_note_attachment`	Download a shared note attachment
`td_delete_shared_note_attachment`	Delete a shared note attachment
`td_list_shared_project_docs`	List document pages from a shared project
`td_create_shared_project_doc`	Create a document page in a shared project
`td_update_shared_project_doc`	Update a document page in a shared project
`td_delete_shared_project_doc`	Delete a document page in a shared project (soft delete)
`td_create_shared_task`	Create a task in a shared project.
`td_delete_shared_task`	Soft-delete a task in a shared project (cascades to its checklist items and comments).
`td_list_shared_worklogs`	List worklogs for a task in a shared project.
`td_add_shared_worklog`	Add a worklog to a task in a shared project.
`td_delete_shared_worklog`	Soft-delete a worklog in a shared project.
`td_list_shared_checklist_items`	List checklist items for a task in a shared project.
`td_create_shared_checklist_item`	Create a checklist item on a task in a shared project.
`td_update_shared_checklist_item`	Update a checklist item in a shared project (toggle done, rename, reorder).
`td_delete_shared_checklist_item`	Soft-delete a checklist item in a shared project.
`td_list_shared_task_comments`	List comments for a task in a shared project.
`td_create_shared_task_comment`	Add a comment to a task in a shared project.
`td_update_shared_task_comment`	Update a comment in a shared project.
`td_delete_shared_task_comment`	Soft-delete a comment in a shared project.
`td_update_shared_repository_link`	Update a repository link in a shared project.
`td_delete_shared_repository_link`	Soft-delete a repository link in a shared project.
`td_update_shared_deployment_stage`	Update a deployment stage in a shared project.
`td_delete_shared_deployment_stage`	Soft-delete a deployment stage in a shared project.
`td_update_shared_project`	Update shared-project metadata (archive / hide from filters).
`td_upload_shared_attachment`	Upload a file attachment to a task in a shared project.
`td_list_shared_attachments`	List file attachments of a task in a shared project (metadata only, no data).
`td_download_shared_attachment`	Download a task attachment from a shared project.
`td_delete_shared_attachment`	Soft-delete a task attachment in a shared project.
`td_get_shared_task`	Get one task in a shared project by ID or code, with its worklog total, checklist and comment counts.
`td_list_shared_task_tags`	List the tags on a task in a shared project.
`td_bulk_update_shared_tasks`	Update several tasks in a shared project at once.
`td_bulk_delete_shared_tasks`	Soft-delete several tasks in a shared project at once, cascading their checklist items and comments.
`td_update_shared_worklog`	Update a worklog in a shared project.
`td_list_shared_activity_log`	List activity log entries for a shared project.

Project Documentation

Documents are notes with isDoc, so they can nest under another document via parentDocId.

Tool	Description
`td_list_project_docs`	List local project document pages (not synced to shared projects)
`td_create_project_doc`	Create a local project document page
`td_update_project_doc`	Update a local project document page
`td_delete_project_doc`	Delete a local project document page (soft delete)

System Notifications (relay)

Broadcast notices for every user. Writing, and listing expired ones, needs TODOCKO_RELAY_ADMIN_KEY.

Tool	Description
`td_list_system_notifications`	List active system/broadcast notifications from the relay server.
`td_create_system_notification`	Create a broadcast notification visible to all Todocko users.
`td_delete_system_notification`	Delete a system notification by ID.

User Messages (relay)

What users send from the app: bug reports, feature requests, notes. Listing and deleting are admin-owner only and the request is signed with the configured mnemonic; submitting needs no admin rights.

Tool	Description
`td_list_user_messages`	List messages users have sent from the app (bug reports, feature requests, notes).
`td_submit_user_message`	Send a message to the Todocko admins (bug report, feature request or note), the same way the app's feedback form does.
`td_delete_user_message`	Delete one user message from the relay.

Analytics & Reports

Tool	Description
`td_get_dashboard_summary`	Overview: tasks today, overdue, this week's worklog, upcoming deadlines
`td_get_team_workload`	Team workload: logged vs estimate vs capacity per user for a period
`td_list_recurring_tasks`	List recurring tasks with recurrence configuration
`td_list_overdue_tasks`	Overdue tasks (sorted oldest first)

Before v1.6.0 these three tools always returned nothing. td_list_recurring_tasks, td_list_overdue_tasks and td_list_tasks_by_date_range read result.rows, while evolu.loadQuery resolves to the array itself — so count: 0 for every input, with no error to notice. Fixed in TODO-242 behind a shared queryRows. td_get_task now returns the recurrence settings too, so a schedule can be read the obvious way. | td_list_tasks_by_date_range | Tasks filtered by scheduledDate or deadline within a date range | | td_analyze_dependencies | Dependency analysis: blocked tasks, blocking chains, critical path |

Diagnostics

Tool	Description
`td_sync_status`	Sync status
`td_force_sync`	Force a sync round-trip with the relay (useful when you want to make sure you're reading the latest data from another device)

Usage Examples

List projects

Show me all projects in Todocko

List tasks

What tasks do I have with status "todo"?
Show tasks for project TODO

Task details

What are the details of task TODO-15?

Create task

Create a new task in project PROJ with title "Fix login bug" and priority high
Create a task with deadline 2026-03-15 and scheduledDate 2026-03-10

Update task

Mark task PROJ-5 as completed
Assign task TODO-10 to user with ID xyz
Set scheduledDate of task TODO-10 to tomorrow

Log time

Log 2 hours of work on task TODO-15 with description "Feature implementation"

Working with attachments

Upload file /home/user/report.pdf as attachment to task TODO-15
What attachments does task TODO-15 have?
Delete attachment with ID xyz

Shared projects

Show shared projects
What tasks are in the shared project?
Mark task as deployed to production

Deployment stages

What deployment stages does the project have?
Create a new deployment stage "Staging" for the shared project

Sub-tasks

Create a sub-task for task TODO-15 in project TODO
Detach task TODO-20 from its parent (parentTaskId: null)

Analytics & Reports

What's my dashboard summary for today?
How is the team's workload this week?
What tasks are overdue?
Show tasks scheduled for next week
Analyze dependencies in project TODO
What recurring tasks do I have?

Security

Important: Your backup phrase (mnemonic) is sensitive data!

Never share it directly in conversation with AI
In the MCP server configuration, the phrase is safe (AI has no access to it)
Anyone with your phrase has full access to your data

Data Location

Databases are stored in the ~/.todocko/ directory:

Platform	Path
Linux	`~/.todocko/`
macOS	`~/.todocko/`
Windows	`C:\Users\<user>\.todocko\`

Files:

todocko.db - your personal data (tasks, projects)
todocko-shared.db - shared projects

Configuration Changes

Claude Code (CLI)

After changing configuration in ~/.claude/settings.json (e.g., changing mnemonic), run the command:

/mcp

This will restart the MCP server with the new configuration.

Switching to a Different Account

When changing the mnemonic to a different Todocko account, you need to delete the local database:

# Linux/macOS
rm ~/.todocko/todocko.db

# Windows
del %USERPROFILE%\.todocko\todocko.db

The database contains the owner ID from the previous mnemonic. After deletion, a new database will be created on the next startup and data from the new account will be downloaded.

Troubleshooting

Server won't start

Check that you have Node.js 24.20 or newer (Evolu v8 requires it)
Check that you ran npm run build
Check logs in Claude Desktop

Data not syncing

Verify the backup phrase is correct (24 words)
Check internet connection
Wait a few seconds for synchronization
Try deleting ~/.todocko/todocko.db and restart

Tools not visible

Restart Claude Desktop
In Claude Code, use /mcp for reload
Check the configuration file
Check the path to dist/index.js

Every `loadQuery` ends with a timeout (`loadQuery timed out after 15000ms`)

Cause: the better-sqlite3 native binding was compiled against a different Node.js ABI than the one running the MCP server. new Database() fails with ERR_DLOPEN_FAILED, the Evolu dbWorker init never completes, and every loadQuery hangs forever. Mutations (insert/update) report success but are silently lost.

Typical symptoms: td_sync_status reports ok with errorCount: 0, but td_get_task, td_list_*, etc. all time out.

Fix — rebuild the native binding against the current Node:

cd ~/.todocko-mcp # or wherever todocko-mcp is installed
cd node_modules/better-sqlite3
npx node-gyp rebuild --release

Then /mcp reconnect in Claude Code.

This mismatch typically appears after upgrading Node.js (e.g. v22 → v25) or switching between nvm and linuxbrew/brew Node, because the installer builds the binding against the node from PATH, but claude may later spawn the MCP with a different node binary.

Development

# Install dependencies
npm install

# Build
npm run build

# Watch mode for development
npm run dev

# Tests
npm test

# Manual run
TODOCKO_MNEMONIC="your phrase" npm start

Testy

Vitest, 24 testů ve dvou souborech. Běží v CI (ci.yml, push i PR na main) od TODO-229 — do té doby CI spouštěla jen build, takže se nikdo nedozvěděl, že helpers.test.ts na Node 18/20 ani neprojde importem: přes helpers.ts tahal ../evolu.js, jehož inicializace při načtení modulu spadne na crypto.getRandomValues must be defined.

Proto jsou funkce bez závislosti na Evolu v src/tools/pure.ts a testují se odtud. helpers.ts je re-exportuje, takže volající se nemění. Když píšeš helper, který Evolu nepotřebuje, patří do pure.ts — jinak ho nejde testovat bez nastartované databáze.

Závazná verze je Node 24.20 nebo novější — je v engines a Evolu v8 na starším neběží. Na té jede ci.yml i release.yml.

Todocko MCP Server

Podpora

Požadavky

Evolu v8 (TODO-88)

Instalace

1. Stažení

2. Spuštění instalátoru

Manuální instalace

Dostupné nástroje (152)

Projekty

Úkoly

Uživatelé

Worklogy

Přílohy

Komentáře

Checklist

Zmínky (mentions)

Linky mezi úkoly

Tagy

Šablony úkolů

Kanban sloupce

Uložená zobrazení

Aktivita

Poznámky k projektu

Dokumentace projektu

Systémová oznámení (relay)

Deployment stages

Repository linky

Sdílené projekty

Zprávy od uživatelů (relay)

Analytika a přehledy

Diagnostika

Příklady použití

Seznam projektů

Seznam úkolů

Detail úkolu

Vytvoření úkolu

Aktualizace úkolu

Logování času

Práce s přílohami

Sdílené projekty

Deployment stages

Sub-úkoly

Přehledy a analytika

Linux CLI (todo) (TODO-160)

Bezpečnost

WebSocket Origin (TODO-169)

Umístění dat

Změna konfigurace

Claude Code (CLI)

Přepnutí na jiný účet

Troubleshooting

Server se nespustí

Data se nesynchronizují

Nástroje nejsou viditelné

Každý loadQuery skončí timeoutem (loadQuery timed out after 15000ms)

Vývoj

English

Support

Requirements

Installation

1. Download

2. Run the installer

Manual installation

Available Tools (152)

Projects

Tasks

Users

Worklogs

Attachments

Comments

Checklist

Mentions

Task Links

Tags

Task Templates

Kanban Columns

Saved Views

Activity Log

Project Notes

Linux CLI (`todo`) (TODO-160)

Každý `loadQuery` skončí timeoutem (`loadQuery timed out after 15000ms`)

Every `loadQuery` ends with a timeout (`loadQuery timed out after 15000ms`)