todocko-mcp 3.10.2 → 3.10.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +1336 -1169
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,132 +1,72 @@
|
|
|
1
1
|
# Todocko MCP Server
|
|
2
2
|
|
|
3
|
-
>
|
|
3
|
+
> [Česká verze níže](#česky) / Czech version below
|
|
4
4
|
|
|
5
|
-
MCP (Model Context Protocol) server
|
|
6
|
-
|
|
7
|
-
## Podpora
|
|
8
|
-
|
|
9
|
-
- **Claude Desktop** - plná podpora
|
|
10
|
-
- **Claude Code (CLI)** - plná podpora (stejná konfigurace)
|
|
5
|
+
MCP (Model Context Protocol) server for working with [Todocko](https://app.todocko.cz) app data from AI assistants.
|
|
11
6
|
|
|
12
|
-
##
|
|
7
|
+
## Support
|
|
13
8
|
|
|
14
|
-
- **
|
|
15
|
-
|
|
16
|
-
má Node nativně teprve od 24
|
|
17
|
-
- Todocko účet s daty synchronizovanými přes Evolu
|
|
9
|
+
- **Claude Desktop** - full support
|
|
10
|
+
- **Claude Code (CLI)** - full support (same configuration)
|
|
18
11
|
|
|
19
|
-
##
|
|
12
|
+
## Requirements
|
|
20
13
|
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
14
|
+
- **Node.js 24.20+** – required by Evolu v8's `engines`, and not merely formally:
|
|
15
|
+
v8 relies on `navigator.locks`, `MessageChannel`, `BroadcastChannel` and
|
|
16
|
+
`WebSocket`, which Node only has natively from 24 on
|
|
17
|
+
- Todocko account with data synchronized via Evolu
|
|
24
18
|
|
|
25
|
-
|
|
26
|
-
databáze na disku**:
|
|
19
|
+
## Installation
|
|
27
20
|
|
|
28
|
-
|
|
29
|
-
od better-sqlite3 respektuje šifrovací klíč, který Evolu pro klientskou
|
|
30
|
-
databázi předává, takže soubor v `~/.todocko` je nově **šifrovaný**. Starou
|
|
31
|
-
databázi psanou better-sqlite3 nový driver neotevře, skončí na
|
|
32
|
-
`file is not a database` (SQLITE_NOTADB, ověřeno na kopii reálné databáze).
|
|
33
|
-
**Při upgradu je proto nutné lokální databáze smazat**; jsou jen keší dat
|
|
34
|
-
z relaye, takže se stáhnou znovu (ověřeno: čerstvá databáze se dosynchronizovala
|
|
35
|
-
na 17 MB). Co nebylo odsynchronizované, je pryč, takže před smazáním
|
|
36
|
-
zkontrolovat `td_sync_status`.
|
|
37
|
-
- Dopad na bezpečnost je naopak příjemný: lokální kopie všech úkolů už neleží na
|
|
38
|
-
disku v plaintextu. Druhá strana téže mince je, že do souboru nenahlédne ani
|
|
39
|
-
žádný vlastní nástroj, což odneslo `ensureMissingColumns`.
|
|
40
|
-
- Transportní URL je od 8.27 brandovaný `RelayUrl`, takže `TODOCKO_RELAY_URL` se
|
|
41
|
-
parsuje přes `RelayUrlFromString` a URL s query se odmítne; `createOwnerWebSocketTransport`
|
|
42
|
-
si `?ownerId=` připojuje sám.
|
|
43
|
-
- Platforma musí nově dodat `deleteDatabaseFiles` (maže soubor databáze i žurnál)
|
|
44
|
-
a `getDevicePersistence` i na hlavním vlákně, ne jen v shared workeru.
|
|
21
|
+
### From npm
|
|
45
22
|
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
a řádek zapíše pod jiného ownera, odkud se nenasynchronizuje. Hlídá to
|
|
49
|
-
`src/tools/sharedWrites.test.ts`. Databázi, jejíž worker spadl, Evolu nově
|
|
50
|
-
odmítne přes `evoluError`; `td_sync_status` ji ukáže v poli `evoluError`
|
|
51
|
-
a nástroje na ni nečekají do timeoutu, hned řeknou, že je potřeba reconnect.
|
|
52
|
-
(TODO-427)
|
|
23
|
+
Nothing to clone and nothing to build. Point Claude at the published package
|
|
24
|
+
and it fetches it on first run:
|
|
53
25
|
|
|
54
|
-
|
|
55
|
-
potřeboval. v8 to zrušil: `@evolu/nodejs` v3 nabízí relay a pár primitiv, a
|
|
56
|
-
jedinou kompletní klientskou platformu má upstream pro web. `src/evoluPlatform.ts`
|
|
57
|
-
je protějšek pro Node, poskládaný ze stejných dílů.
|
|
26
|
+
**Claude Desktop** (`~/.config/Claude/claude_desktop_config.json` on Linux or `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
|
|
58
27
|
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
28
|
+
```json
|
|
29
|
+
{
|
|
30
|
+
"mcpServers": {
|
|
31
|
+
"todocko": {
|
|
32
|
+
"command": "npx",
|
|
33
|
+
"args": ["-y", "todocko-mcp"],
|
|
34
|
+
"env": {
|
|
35
|
+
"TODOCKO_MNEMONIC": "your 24 word backup phrase"
|
|
36
|
+
}
|
|
37
|
+
}
|
|
38
|
+
}
|
|
39
|
+
}
|
|
40
|
+
```
|
|
63
41
|
|
|
64
|
-
|
|
42
|
+
**Claude Code (CLI)** - add the same block to `~/.claude/settings.json`, then
|
|
43
|
+
restart Claude.
|
|
65
44
|
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
v aplikaci; velikost kusu musí sedět s ní, jinak se příloha nahraná tady
|
|
70
|
-
otevře jinde useknutá. Čtení umí i starý tvar, base64 v `attachment.data`,
|
|
71
|
-
protože schéma je append-only.
|
|
72
|
-
- **Obsah nové přílohy leží ve vlastním shardu** (`src/attachmentShards.ts`,
|
|
73
|
-
TODO-450), ne pod AppOwnerem. Jednotlivou změnu v CRDT smazat nejde, jen
|
|
74
|
-
označit jako smazanou, takže owner je jediná jednotka skutečného smazání.
|
|
75
|
-
Cesta `attachment/<id>` se odvozuje z id přílohy, a tedy se nikam neukládá;
|
|
76
|
-
v řádku je jen značka `contentShard`. Odvození i pořadí při mazání, nejdřív
|
|
77
|
-
relay a pak lokálně, musí sedět s aplikací, jinak se obě poloviny rozejdou
|
|
78
|
-
tiše: příloha nahraná tady by se tam otevřela prázdná. Shard se registruje
|
|
79
|
-
jen na dobu nahrání nebo čtení, protože adresa transportu nese owner id
|
|
80
|
-
a trvale registrovaný shard by znamenal jeden WebSocket na každou přílohu.
|
|
81
|
-
- **Hlášení stavů dohledává jména k identifikátorům** (`src/statusReporting.ts`,
|
|
82
|
-
TODO-458). Pilulka v aplikaci ukazovala u volání, která dostanou jen id,
|
|
83
|
-
zkrácený identifikátor, což člověku neříká nic. Tabulky i sloupce, ze kterých
|
|
84
|
-
se jméno bere, jsou vyjmenované vedle seznamu povolených polí, ne odvozené
|
|
85
|
-
z názvu nástroje. Dohledání běží uvnitř téhož pošli a nečekej jako celé
|
|
86
|
-
hlášení a má vlastní strop, takže zaseknutý dotaz nedrží frontu; když se nic
|
|
87
|
-
nenajde, zůstane zkrácené id.
|
|
45
|
+
Pin a version with `todocko-mcp@<version>` instead of `todocko-mcp` if you would
|
|
46
|
+
rather decide yourself when to move. To get the `todo` command line tool on your
|
|
47
|
+
`PATH` as well, install the package globally:
|
|
88
48
|
|
|
49
|
+
```bash
|
|
50
|
+
npm install -g todocko-mcp
|
|
51
|
+
```
|
|
89
52
|
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
- **Databáze patří jednomu mnemonicu.** v7 při neshodě volal `restoreAppOwner`,
|
|
94
|
-
který lokální databázi resetoval. v8 obnovu nemá, takže by v souboru zůstala
|
|
95
|
-
data starého ownera zašifrovaná klíčem, který nový nemá. Server proto neshodu
|
|
96
|
-
**ohlásí a odmítne nastartovat** — smaž `~/.todocko/todocko.db` a nech ho
|
|
97
|
-
stáhnout data znovu.
|
|
98
|
-
- **`createNodeEvoluDeps()` musí být singleton na proces.** Shared worker drží
|
|
99
|
-
jediný `tabLeaderPortStore` a `initDbWorker` každého tenanta předpokládá, že
|
|
100
|
-
je už naplněný. Druhá sada deps znamená druhý shared worker, kterému nikdo
|
|
101
|
-
leadera neohlásil, a vytvoření sdílené instance spadne na
|
|
102
|
-
`initDbWorker: Expected value to be non-nullable`. Jeden worker obslouží obě
|
|
103
|
-
instance jako dva tenanty podle `appName`, stejně jako `@evolu/web` na jedné
|
|
104
|
-
stránce.
|
|
105
|
-
- **Mutace nevrací `Result`.** v7 vracel z `insert`/`update` `Result`, takže se
|
|
106
|
-
testovalo `result.ok` a čtlo `result.value.id`. v8 vrací přímo `{ id }` a při
|
|
107
|
-
neplatné změně vyhodí výjimku. Kontrola `!result.ok` proto uspěla vždy a
|
|
108
|
-
nástroj ohlásil chybu u zápisu, který právě proběhl. U vkládání je to horší,
|
|
109
|
-
protože uživatel to zkusí znovu a vznikne duplicita. Hlídá to
|
|
110
|
-
`src/tools/pure.test.ts`.
|
|
111
|
-
- **Ownera filtrovat v SQL, ne až v JS.** Sdílená instance drží data všech
|
|
112
|
-
ownerů v jedné tabulce. `limit` provede SQLite dřív, než se v JS cokoli
|
|
113
|
-
filtruje, takže nezúžený dotaz vrátí prvních N řádků přes všechny ownery a
|
|
114
|
-
filtr je pak zahodí. Nástroj hlásil nula úkolů u projektu, který jich má 26.
|
|
115
|
-
Stejná past číhá u `orderBy position desc limit 1` při výpočtu další pozice.
|
|
53
|
+
Note that `TODOCKO_MNEMONIC` is the private key to all of your data. Keep it in
|
|
54
|
+
the configuration file and nowhere else: never on a command line, never in a
|
|
55
|
+
shell history, never in a repository. See [Security](#security).
|
|
116
56
|
|
|
117
|
-
|
|
57
|
+
### From source
|
|
118
58
|
|
|
119
|
-
|
|
59
|
+
#### 1. Download
|
|
120
60
|
|
|
121
|
-
**
|
|
61
|
+
**Using git:**
|
|
122
62
|
```bash
|
|
123
63
|
git clone https://github.com/brnt-cz/todocko-mcp.git
|
|
124
64
|
cd todocko-mcp
|
|
125
65
|
```
|
|
126
66
|
|
|
127
|
-
**
|
|
67
|
+
**Or download ZIP** from [Releases](https://github.com/brnt-cz/todocko-mcp/releases) and extract.
|
|
128
68
|
|
|
129
|
-
|
|
69
|
+
#### 2. Run the installer
|
|
130
70
|
|
|
131
71
|
**Linux/macOS:**
|
|
132
72
|
```bash
|
|
@@ -139,641 +79,584 @@ chmod +x install.sh
|
|
|
139
79
|
.\install.ps1
|
|
140
80
|
```
|
|
141
81
|
|
|
142
|
-
|
|
143
|
-
1.
|
|
144
|
-
2.
|
|
145
|
-
3.
|
|
146
|
-
4. **
|
|
147
|
-
5.
|
|
82
|
+
The installer will:
|
|
83
|
+
1. Install dependencies and build the project
|
|
84
|
+
2. Ask whether to configure Claude Desktop, Claude Code, or both
|
|
85
|
+
3. Create a configuration file with a placeholder
|
|
86
|
+
4. **Manually add** your 24-word backup phrase to the configuration file
|
|
87
|
+
5. Restart Claude
|
|
148
88
|
|
|
149
|
-
|
|
89
|
+
#### Manual installation
|
|
150
90
|
|
|
151
|
-
1.
|
|
91
|
+
1. Install dependencies:
|
|
152
92
|
```bash
|
|
153
93
|
npm install
|
|
154
94
|
npm run build
|
|
155
95
|
```
|
|
156
96
|
|
|
157
|
-
2.
|
|
97
|
+
2. Add to configuration:
|
|
158
98
|
|
|
159
|
-
**Claude Desktop** (`~/.config/Claude/claude_desktop_config.json`
|
|
99
|
+
**Claude Desktop** (`~/.config/Claude/claude_desktop_config.json` on Linux or `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
|
|
160
100
|
|
|
161
101
|
```json
|
|
162
102
|
{
|
|
163
103
|
"mcpServers": {
|
|
164
104
|
"todocko": {
|
|
165
105
|
"command": "node",
|
|
166
|
-
"args": ["/
|
|
106
|
+
"args": ["/path/to/mcp-server/dist/index.js"],
|
|
167
107
|
"env": {
|
|
168
|
-
"TODOCKO_MNEMONIC": "
|
|
108
|
+
"TODOCKO_MNEMONIC": "your 24 word backup phrase"
|
|
169
109
|
}
|
|
170
110
|
}
|
|
171
111
|
}
|
|
172
112
|
}
|
|
173
113
|
```
|
|
174
114
|
|
|
175
|
-
**Claude Code (CLI)** -
|
|
115
|
+
**Claude Code (CLI)** - add to `~/.claude/settings.json`:
|
|
176
116
|
|
|
177
117
|
```json
|
|
178
118
|
{
|
|
179
119
|
"mcpServers": {
|
|
180
120
|
"todocko": {
|
|
181
121
|
"command": "node",
|
|
182
|
-
"args": ["/
|
|
122
|
+
"args": ["/path/to/mcp-server/dist/index.js"],
|
|
183
123
|
"env": {
|
|
184
|
-
"TODOCKO_MNEMONIC": "
|
|
124
|
+
"TODOCKO_MNEMONIC": "your 24 word backup phrase"
|
|
185
125
|
}
|
|
186
126
|
}
|
|
187
127
|
}
|
|
188
128
|
}
|
|
189
129
|
```
|
|
190
130
|
|
|
191
|
-
3.
|
|
192
|
-
|
|
193
|
-
## Dostupné nástroje (161)
|
|
131
|
+
3. Restart Claude Desktop / Claude Code
|
|
194
132
|
|
|
195
|
-
|
|
133
|
+
## Available Tools (161)
|
|
196
134
|
|
|
197
|
-
|
|
198
|
-
|---------|-------|
|
|
199
|
-
| `td_list_projects` | Seznam všech projektů |
|
|
200
|
-
| `td_get_project` | Detail projektu podle ID nebo kódu |
|
|
201
|
-
| `td_create_project` | Vytvoření nového projektu (kód jen `A-Z` a `0-9`, jako v appce) |
|
|
202
|
-
| `td_update_project` | Aktualizace projektu (name, code, color, isArchived, isHiddenFromFilters; kód jen `A-Z` a `0-9`). `autoApproveMembers` patří sdílenému projektu, tady se odmítne, viz `td_update_shared_project` |
|
|
203
|
-
| `td_delete_project` | Smazání projektu (soft delete) |
|
|
135
|
+
### Projects
|
|
204
136
|
|
|
205
|
-
|
|
137
|
+
| Tool | Description |
|
|
138
|
+
|------|-------------|
|
|
139
|
+
| `td_list_projects` | List all projects |
|
|
140
|
+
| `td_get_project` | Get project details by ID or code |
|
|
141
|
+
| `td_create_project` | Create a new project (code: `A-Z` and `0-9` only, as in the app) |
|
|
142
|
+
| `td_update_project` | Update a project (name, code, color, isArchived, isHiddenFromFilters; code `A-Z` and `0-9` only). `autoApproveMembers` belongs to the shared project and is refused here, see `td_update_shared_project` |
|
|
143
|
+
| `td_delete_project` | Delete a project (soft delete) |
|
|
206
144
|
|
|
207
|
-
|
|
208
|
-
|---------|-------|
|
|
209
|
-
| `td_list_tasks` | Seznam úkolů s filtry (projekt, status, priorita, assignee) |
|
|
210
|
-
| `td_get_task` | Detail úkolu podle ID nebo kódu (např. `PROJ-123`), včetně nastavení opakování |
|
|
211
|
-
| `td_create_task` | Vytvoření nového úkolu (včetně recurrence, sprintNumber, parentTaskId) |
|
|
212
|
-
| `td_update_task` | Aktualizace existujícího úkolu (včetně recurrence, sprintNumber, parentTaskId) |
|
|
213
|
-
| `td_search_tasks` | Vyhledávání úkolů podle textu |
|
|
214
|
-
| `td_bulk_update_tasks` | Hromadná aktualizace více úkolů (včetně sprintNumber) |
|
|
215
|
-
| `td_bulk_delete_tasks` | Hromadné smazání více úkolů |
|
|
216
|
-
| `td_delete_task` | Smazání jednoho úkolu (soft delete, kaskáda na worklogy a přílohy) |
|
|
217
|
-
| `td_list_git_events` | Git aktivita pro úkol (commits, PR) z relay serveru |
|
|
145
|
+
### Tasks
|
|
218
146
|
|
|
219
|
-
|
|
147
|
+
| Tool | Description |
|
|
148
|
+
|------|-------------|
|
|
149
|
+
| `td_list_tasks` | List tasks with filters (project, status, priority, assignee) |
|
|
150
|
+
| `td_get_task` | Get task details by ID or code (e.g., `PROJ-123`), recurrence settings included |
|
|
151
|
+
| `td_create_task` | Create a new task (with recurrence, sprint, parentTaskId support) |
|
|
152
|
+
| `td_update_task` | Update an existing task (with recurrence, sprint, parentTaskId support) |
|
|
153
|
+
| `td_search_tasks` | Search tasks by text |
|
|
154
|
+
| `td_bulk_update_tasks` | Bulk update multiple tasks |
|
|
155
|
+
| `td_bulk_delete_tasks` | Bulk delete multiple tasks |
|
|
156
|
+
| `td_delete_task` | Soft-delete a single personal task (cascades to its worklogs and attachments). |
|
|
157
|
+
| `td_list_git_events` | List git events (push, PR opened/merged/closed) for a task by its code. |
|
|
220
158
|
|
|
221
|
-
|
|
222
|
-
|---------|-------|
|
|
223
|
-
| `td_list_users` | Seznam všech uživatelů |
|
|
224
|
-
| `td_get_user` | Detail uživatele |
|
|
225
|
-
| `td_create_user` | Vytvoření nového uživatele |
|
|
226
|
-
| `td_update_user` | Aktualizace uživatele |
|
|
227
|
-
| `td_delete_user` | Smazání uživatele (soft delete) |
|
|
159
|
+
### Users
|
|
228
160
|
|
|
229
|
-
|
|
161
|
+
| Tool | Description |
|
|
162
|
+
|------|-------------|
|
|
163
|
+
| `td_list_users` | List all users |
|
|
164
|
+
| `td_get_user` | Get user details |
|
|
165
|
+
| `td_create_user` | Create a new user |
|
|
166
|
+
| `td_update_user` | Update a user |
|
|
167
|
+
| `td_delete_user` | Delete a user (soft delete) |
|
|
230
168
|
|
|
231
|
-
|
|
232
|
-
|---------|-------|
|
|
233
|
-
| `td_list_worklogs` | Seznam worklogů pro úkol |
|
|
234
|
-
| `td_add_worklog` | Přidání worklogu k úkolu |
|
|
235
|
-
| `td_update_worklog` | Aktualizace worklogu |
|
|
236
|
-
| `td_delete_worklog` | Smazání worklogu (soft delete) |
|
|
169
|
+
### Worklogs
|
|
237
170
|
|
|
238
|
-
|
|
171
|
+
| Tool | Description |
|
|
172
|
+
|------|-------------|
|
|
173
|
+
| `td_list_worklogs` | List worklogs for a task |
|
|
174
|
+
| `td_add_worklog` | Add a worklog to a task |
|
|
175
|
+
| `td_update_worklog` | Update a worklog |
|
|
176
|
+
| `td_delete_worklog` | Delete a worklog (soft delete) |
|
|
239
177
|
|
|
240
|
-
|
|
241
|
-
|---------|-------|
|
|
242
|
-
| `td_upload_attachment` | Nahrání přílohy k úkolu (ze souboru nebo base64) |
|
|
243
|
-
| `td_list_attachments` | Seznam příloh úkolu |
|
|
244
|
-
| `td_download_attachment` | Stažení přílohy |
|
|
245
|
-
| `td_delete_attachment` | Smazání přílohy |
|
|
246
|
-
| `td_upload_note_attachment` | Nahrání přílohy k lokální poznámce projektu |
|
|
247
|
-
| `td_list_note_attachments` | Seznam příloh lokální poznámky |
|
|
248
|
-
| `td_download_note_attachment` | Stažení přílohy poznámky |
|
|
249
|
-
| `td_delete_note_attachment` | Smazání přílohy poznámky |
|
|
178
|
+
### Attachments
|
|
250
179
|
|
|
251
|
-
|
|
180
|
+
| Tool | Description |
|
|
181
|
+
|------|-------------|
|
|
182
|
+
| `td_upload_attachment` | Upload an attachment to a task (from file or base64) |
|
|
183
|
+
| `td_list_attachments` | List attachments for a task |
|
|
184
|
+
| `td_download_attachment` | Download an attachment |
|
|
185
|
+
| `td_delete_attachment` | Delete an attachment |
|
|
186
|
+
| `td_upload_note_attachment` | Upload an attachment to a local project note |
|
|
187
|
+
| `td_list_note_attachments` | List attachments of a local note |
|
|
188
|
+
| `td_download_note_attachment` | Download a note attachment |
|
|
189
|
+
| `td_delete_note_attachment` | Delete a note attachment |
|
|
252
190
|
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
|
256
|
-
|
|
257
|
-
| `
|
|
258
|
-
| `
|
|
191
|
+
### Comments
|
|
192
|
+
|
|
193
|
+
| Tool | Description |
|
|
194
|
+
|------|-------------|
|
|
195
|
+
| `td_list_task_comments` | List comments for a task |
|
|
196
|
+
| `td_create_task_comment` | Add a comment to a task |
|
|
197
|
+
| `td_update_task_comment` | Update a comment |
|
|
198
|
+
| `td_delete_task_comment` | Delete a comment (soft delete) |
|
|
259
199
|
|
|
260
200
|
### Checklist
|
|
261
201
|
|
|
262
|
-
|
|
|
263
|
-
|
|
264
|
-
| `td_list_checklist_items` |
|
|
265
|
-
| `td_create_checklist_item` |
|
|
266
|
-
| `td_update_checklist_item` |
|
|
267
|
-
| `td_delete_checklist_item` |
|
|
202
|
+
| Tool | Description |
|
|
203
|
+
|------|-------------|
|
|
204
|
+
| `td_list_checklist_items` | List checklist items for a task |
|
|
205
|
+
| `td_create_checklist_item` | Add a checklist item |
|
|
206
|
+
| `td_update_checklist_item` | Update a checklist item (check, reposition) |
|
|
207
|
+
| `td_delete_checklist_item` | Delete a checklist item (soft delete) |
|
|
268
208
|
|
|
269
|
-
###
|
|
209
|
+
### Mentions
|
|
270
210
|
|
|
271
|
-
|
|
|
272
|
-
|
|
273
|
-
| `td_list_mentions` |
|
|
274
|
-
| `td_create_mention` |
|
|
275
|
-
| `td_mark_mention_read` |
|
|
276
|
-
| `td_mark_all_mentions_read` |
|
|
277
|
-
| `td_delete_mention` |
|
|
211
|
+
| Tool | Description |
|
|
212
|
+
|------|-------------|
|
|
213
|
+
| `td_list_mentions` | List mentions for a user |
|
|
214
|
+
| `td_create_mention` | Create a mention |
|
|
215
|
+
| `td_mark_mention_read` | Mark a mention as read |
|
|
216
|
+
| `td_mark_all_mentions_read` | Mark all mentions as read |
|
|
217
|
+
| `td_delete_mention` | Delete a mention (soft delete) |
|
|
278
218
|
|
|
279
|
-
###
|
|
219
|
+
### Task Links
|
|
280
220
|
|
|
281
|
-
|
|
|
282
|
-
|
|
283
|
-
| `td_list_app_settings` |
|
|
284
|
-
| `td_set_app_setting` |
|
|
285
|
-
| `td_list_task_links` |
|
|
286
|
-
| `td_create_task_link` |
|
|
287
|
-
| `td_delete_task_link` |
|
|
221
|
+
| Tool | Description |
|
|
222
|
+
|------|-------------|
|
|
223
|
+
| `td_list_app_settings` | Account settings that follow the user across devices |
|
|
224
|
+
| `td_set_app_setting` | Set one account setting |
|
|
225
|
+
| `td_list_task_links` | List links for a task |
|
|
226
|
+
| `td_create_task_link` | Create a link between tasks (`blocks`, `explicit`, `mention`, `relates`, `duplicate`) |
|
|
227
|
+
| `td_delete_task_link` | Delete a task link (soft delete) |
|
|
288
228
|
|
|
289
|
-
###
|
|
229
|
+
### Tags
|
|
290
230
|
|
|
291
|
-
|
|
|
292
|
-
|
|
293
|
-
| `td_list_tags` |
|
|
294
|
-
| `td_create_tag` |
|
|
295
|
-
| `td_update_tag` |
|
|
296
|
-
| `td_delete_tag` |
|
|
297
|
-
| `td_list_task_tags` |
|
|
298
|
-
| `td_add_tag_to_task` |
|
|
299
|
-
| `td_remove_tag_from_task` |
|
|
231
|
+
| Tool | Description |
|
|
232
|
+
|------|-------------|
|
|
233
|
+
| `td_list_tags` | List tags; returns `projectId`, filters by project or unassigned |
|
|
234
|
+
| `td_create_tag` | Create a tag – **pass `projectId`**, see the note below |
|
|
235
|
+
| `td_update_tag` | Rename, recolour, assign to a project, or mark default |
|
|
236
|
+
| `td_delete_tag` | Delete a tag (soft delete) |
|
|
237
|
+
| `td_list_task_tags` | List tags assigned to a task |
|
|
238
|
+
| `td_add_tag_to_task` | Assign a tag to a task |
|
|
239
|
+
| `td_remove_tag_from_task` | Remove a tag from a task |
|
|
300
240
|
|
|
301
|
-
|
|
241
|
+
Shared projects (TODO-235):
|
|
302
242
|
|
|
303
|
-
|
|
|
304
|
-
|
|
305
|
-
| `td_list_shared_tags` |
|
|
306
|
-
| `td_create_shared_tag` |
|
|
307
|
-
| `td_update_shared_tag` |
|
|
308
|
-
| `td_delete_shared_tag` |
|
|
309
|
-
| `td_add_shared_tag_to_task` |
|
|
310
|
-
| `td_remove_shared_tag_from_task` |
|
|
243
|
+
| Tool | Description |
|
|
244
|
+
|------|-------------|
|
|
245
|
+
| `td_list_shared_tags` | Tags in a shared project |
|
|
246
|
+
| `td_create_shared_tag` | Create a tag in a shared project |
|
|
247
|
+
| `td_update_shared_tag` | Rename / recolour |
|
|
248
|
+
| `td_delete_shared_tag` | Delete (soft delete) |
|
|
249
|
+
| `td_add_shared_tag_to_task` | Assign to a task in a shared project |
|
|
250
|
+
| `td_remove_shared_tag_from_task` | Remove from a task |
|
|
311
251
|
|
|
312
|
-
>
|
|
313
|
-
>
|
|
314
|
-
>
|
|
315
|
-
>
|
|
316
|
-
>
|
|
252
|
+
> **A tag without a project is never offered by the app.** Since TODO-227 tags
|
|
253
|
+
> belong to a project; `td_create_tag` without `projectId` makes an **unassigned**
|
|
254
|
+
> tag, which shows up only under "Nezařazené" in project settings with a button to
|
|
255
|
+
> adopt it. The tool response says so. Fix it afterwards with `td_update_tag` and
|
|
256
|
+
> a `projectId`.
|
|
317
257
|
>
|
|
318
|
-
> **
|
|
319
|
-
> `td_create_task`
|
|
320
|
-
>
|
|
321
|
-
>
|
|
322
|
-
>
|
|
323
|
-
>
|
|
324
|
-
>
|
|
258
|
+
> **Free-tier limits (TODO-243).** Tier caps belong to the app, not here.
|
|
259
|
+
> `td_create_task` and `td_create_project` append a warning with the real count
|
|
260
|
+
> when the owner is on the free tier and above its cap (1 project, 50 **active**
|
|
261
|
+
> tasks), so that it is learned at creation time rather than later in the app, and
|
|
262
|
+
> so that the text makes clear nothing was lost. **Nothing is blocked**, and with
|
|
263
|
+
> an unknown tier (unreachable relay) it stays silent – a false alarm is worse
|
|
264
|
+
> than none.
|
|
325
265
|
|
|
326
|
-
> **
|
|
327
|
-
> (
|
|
328
|
-
>
|
|
329
|
-
>
|
|
330
|
-
>
|
|
266
|
+
> **Default tags (TODO-239).** `isDefault` on `td_create_tag` / `td_update_tag`
|
|
267
|
+
> (and the shared variants) means every task newly created in the project gets the
|
|
268
|
+
> tag. Both `td_create_task` and `td_create_shared_task` apply them and report them
|
|
269
|
+
> back in `appliedTags` – the app pre-ticks them in its form, so without this the
|
|
270
|
+
> result would depend on where the task was created. Existing tasks are untouched.
|
|
331
271
|
>
|
|
332
|
-
>
|
|
333
|
-
>
|
|
334
|
-
|
|
335
|
-
### Šablony úkolů
|
|
336
|
-
|
|
337
|
-
| Nástroj | Popis |
|
|
338
|
-
|---------|-------|
|
|
339
|
-
| `td_list_task_templates` | Seznam šablon úkolů |
|
|
340
|
-
| `td_create_task_template` | Vytvoření šablony (volitelně `checklistItems` a `tagIds`) |
|
|
341
|
-
| `td_update_task_template` | Aktualizace šablony (`checklistItems`, `tagIds`; prázdné pole maže) |
|
|
342
|
-
| `td_delete_task_template` | Smazání šablony (soft delete) |
|
|
343
|
-
|
|
344
|
-
### Kanban sloupce
|
|
345
|
-
|
|
346
|
-
| Nástroj | Popis |
|
|
347
|
-
|---------|-------|
|
|
348
|
-
| `td_list_kanban_columns` | Seznam kanban sloupců |
|
|
349
|
-
| `td_create_kanban_column` | Vytvoření sloupce (volitelně `wipLimit`, max. úkolů na uživatele v In progress před varováním v hlavičce) |
|
|
350
|
-
| `td_update_kanban_column` | Aktualizace sloupce (`wipLimit: null` limit zruší) |
|
|
351
|
-
| `td_delete_kanban_column` | Smazání sloupce (soft delete) |
|
|
352
|
-
|
|
353
|
-
### Uložená zobrazení
|
|
354
|
-
|
|
355
|
-
| Nástroj | Popis |
|
|
356
|
-
|---------|-------|
|
|
357
|
-
| `td_list_saved_views` | Seznam uložených zobrazení |
|
|
358
|
-
| `td_create_saved_view` | Vytvoření zobrazení |
|
|
359
|
-
| `td_update_saved_view` | Aktualizace zobrazení |
|
|
360
|
-
| `td_delete_saved_view` | Smazání zobrazení (soft delete) |
|
|
361
|
-
|
|
362
|
-
### Aktivita
|
|
272
|
+
> Shared projects write to a **different Evolu instance**, hence the separate set
|
|
273
|
+
> – `td_add_tag_to_task` does not work on a shared task.
|
|
363
274
|
|
|
364
|
-
|
|
365
|
-
|---------|-------|
|
|
366
|
-
| `td_list_activity_log` | Seznam zápisů aktivity s filtry (úkol, aktor, akce, typ entity, datum od/do) — read-only |
|
|
275
|
+
### Task Templates
|
|
367
276
|
|
|
368
|
-
|
|
277
|
+
| Tool | Description |
|
|
278
|
+
|------|-------------|
|
|
279
|
+
| `td_list_task_templates` | List task templates |
|
|
280
|
+
| `td_create_task_template` | Create a task template (optional `checklistItems` and `tagIds`) |
|
|
281
|
+
| `td_update_task_template` | Update a task template (`checklistItems`, `tagIds`; empty array clears) |
|
|
282
|
+
| `td_delete_task_template` | Delete a task template (soft delete) |
|
|
369
283
|
|
|
370
|
-
|
|
371
|
-
|---------|-------|
|
|
372
|
-
| `td_list_project_notes` | Seznam lokálních poznámek projektu (rejstřík: titulek a `contentLength`, obsah až na `includeContent`) |
|
|
373
|
-
| `td_get_project_note` | Jedna lokální poznámka včetně obsahu |
|
|
374
|
-
| `td_create_project_note` | Vytvoření lokální poznámky |
|
|
375
|
-
| `td_update_project_note` | Aktualizace lokální poznámky |
|
|
376
|
-
| `td_delete_project_note` | Smazání lokální poznámky (soft delete) |
|
|
284
|
+
### Kanban Columns
|
|
377
285
|
|
|
378
|
-
|
|
286
|
+
| Tool | Description |
|
|
287
|
+
|------|-------------|
|
|
288
|
+
| `td_list_kanban_columns` | List kanban columns |
|
|
289
|
+
| `td_create_kanban_column` | Create a kanban column (optional `wipLimit`, max tasks per user in In progress before the header warns) |
|
|
290
|
+
| `td_update_kanban_column` | Update a kanban column (`wipLimit: null` clears the limit) |
|
|
291
|
+
| `td_delete_kanban_column` | Delete a kanban column (soft delete) |
|
|
379
292
|
|
|
380
|
-
|
|
381
|
-
(`parentDocId`).
|
|
293
|
+
### Saved Views
|
|
382
294
|
|
|
383
|
-
|
|
|
384
|
-
|
|
385
|
-
| `
|
|
386
|
-
| `
|
|
387
|
-
| `
|
|
388
|
-
| `
|
|
389
|
-
| `td_delete_project_doc` | Smazání dokumentu (soft delete) |
|
|
295
|
+
| Tool | Description |
|
|
296
|
+
|------|-------------|
|
|
297
|
+
| `td_list_saved_views` | List saved views |
|
|
298
|
+
| `td_create_saved_view` | Create a saved view |
|
|
299
|
+
| `td_update_saved_view` | Update a saved view |
|
|
300
|
+
| `td_delete_saved_view` | Delete a saved view (soft delete) |
|
|
390
301
|
|
|
391
|
-
###
|
|
302
|
+
### Activity Log
|
|
392
303
|
|
|
393
|
-
|
|
394
|
-
|
|
395
|
-
|
|
304
|
+
| Tool | Description |
|
|
305
|
+
|------|-------------|
|
|
306
|
+
| `td_list_activity_log` | List activity log entries with filters (task, actor, action, entityType, date from/to) – read-only |
|
|
396
307
|
|
|
397
|
-
|
|
398
|
-
a `td_delete_system_notification` klientovi vůbec nenabízejí (nemohly by nic
|
|
399
|
-
jiného než vrátit 401) a u výpisu zmizí přepínač `admin`. Klíč se navíc nikdy
|
|
400
|
-
neposílá přes nešifrované `http://` jinam než na localhost. (TODO-441)
|
|
308
|
+
### Project Notes
|
|
401
309
|
|
|
402
|
-
|
|
|
403
|
-
|
|
404
|
-
| `
|
|
405
|
-
| `
|
|
406
|
-
| `
|
|
310
|
+
| Tool | Description |
|
|
311
|
+
|------|-------------|
|
|
312
|
+
| `td_list_project_notes` | List local project notes (index: title and `contentLength`; content via `includeContent`) |
|
|
313
|
+
| `td_get_project_note` | Read one local project note, with its content |
|
|
314
|
+
| `td_create_project_note` | Create a local project note |
|
|
315
|
+
| `td_update_project_note` | Update a local project note |
|
|
316
|
+
| `td_delete_project_note` | Delete a local project note (soft delete) |
|
|
407
317
|
|
|
408
|
-
### Deployment
|
|
318
|
+
### Deployment Stages
|
|
409
319
|
|
|
410
|
-
|
|
|
411
|
-
|
|
412
|
-
| `td_list_deployment_stages` |
|
|
413
|
-
| `td_create_deployment_stage` |
|
|
414
|
-
| `td_update_deployment_stage` |
|
|
415
|
-
| `td_delete_deployment_stage` |
|
|
320
|
+
| Tool | Description |
|
|
321
|
+
|------|-------------|
|
|
322
|
+
| `td_list_deployment_stages` | List deployment stages for a project |
|
|
323
|
+
| `td_create_deployment_stage` | Create a deployment stage for a personal project. |
|
|
324
|
+
| `td_update_deployment_stage` | Update a deployment stage in a personal project. |
|
|
325
|
+
| `td_delete_deployment_stage` | Soft-delete a deployment stage in a personal project. |
|
|
416
326
|
|
|
417
|
-
### Repository
|
|
327
|
+
### Repository Links
|
|
418
328
|
|
|
419
|
-
|
|
|
420
|
-
|
|
421
|
-
| `td_list_repository_links` |
|
|
422
|
-
| `td_create_repository_link` |
|
|
423
|
-
| `
|
|
424
|
-
| `
|
|
329
|
+
| Tool | Description |
|
|
330
|
+
|------|-------------|
|
|
331
|
+
| `td_list_repository_links` | List repository links |
|
|
332
|
+
| `td_create_repository_link` | Create a repository link |
|
|
333
|
+
| `td_delete_repository_link` | Delete a repository link |
|
|
334
|
+
| `td_update_repository_link` | Update a repository link for a project. |
|
|
425
335
|
|
|
426
|
-
###
|
|
336
|
+
### Shared Projects
|
|
427
337
|
|
|
428
|
-
|
|
|
429
|
-
|
|
430
|
-
| `td_list_shared_projects` |
|
|
431
|
-
| `td_list_shared_tasks` |
|
|
432
|
-
| `
|
|
433
|
-
| `
|
|
434
|
-
| `
|
|
435
|
-
| `
|
|
436
|
-
| `
|
|
437
|
-
| `
|
|
438
|
-
| `
|
|
439
|
-
| `
|
|
440
|
-
| `
|
|
441
|
-
| `
|
|
442
|
-
| `
|
|
443
|
-
| `
|
|
444
|
-
| `
|
|
445
|
-
| `
|
|
446
|
-
| `
|
|
447
|
-
| `
|
|
448
|
-
| `
|
|
449
|
-
| `
|
|
450
|
-
| `
|
|
451
|
-
| `
|
|
452
|
-
| `
|
|
453
|
-
| `
|
|
454
|
-
| `
|
|
455
|
-
| `
|
|
456
|
-
| `
|
|
457
|
-
| `
|
|
458
|
-
| `
|
|
459
|
-
| `
|
|
460
|
-
| `
|
|
461
|
-
| `
|
|
462
|
-
| `
|
|
463
|
-
| `
|
|
464
|
-
| `
|
|
465
|
-
| `
|
|
466
|
-
| `
|
|
467
|
-
| `
|
|
468
|
-
| `
|
|
469
|
-
| `
|
|
470
|
-
| `
|
|
471
|
-
| `
|
|
472
|
-
| `
|
|
473
|
-
| `
|
|
474
|
-
| `
|
|
475
|
-
| `
|
|
476
|
-
| `
|
|
477
|
-
| `
|
|
478
|
-
| `td_get_shared_task` |
|
|
479
|
-
| `td_list_shared_task_tags` |
|
|
480
|
-
| `td_bulk_update_shared_tasks` |
|
|
481
|
-
| `td_bulk_delete_shared_tasks` |
|
|
482
|
-
| `td_update_shared_worklog` |
|
|
483
|
-
| `td_list_shared_activity_log` |
|
|
338
|
+
| Tool | Description |
|
|
339
|
+
|------|-------------|
|
|
340
|
+
| `td_list_shared_projects` | List shared projects with your permission (no longer returns `ownerSecret`) |
|
|
341
|
+
| `td_list_shared_tasks` | List tasks from a shared project |
|
|
342
|
+
| `td_update_shared_task` | Update a task in a shared project |
|
|
343
|
+
| `td_list_shared_deployment_stages` | List deployment stages for a shared project |
|
|
344
|
+
| `td_create_shared_deployment_stage` | Create a deployment stage in a shared project |
|
|
345
|
+
| `td_list_shared_repository_links` | List repository links for a shared project |
|
|
346
|
+
| `td_create_shared_repository_link` | Create a repository link in a shared project |
|
|
347
|
+
| `td_list_shared_project_notes` | List notes for a shared project (index; content via `includeContent`) |
|
|
348
|
+
| `td_get_shared_project_note` | Read one note from a shared project, with its content |
|
|
349
|
+
| `td_create_shared_project_note` | Create a note in a shared project |
|
|
350
|
+
| `td_update_shared_project_note` | Update a note in a shared project |
|
|
351
|
+
| `td_delete_shared_project_note` | Delete a note in a shared project |
|
|
352
|
+
| `td_list_shared_members` | List members of a shared project (name, permission, kicked/blocked state, `isPending` = waiting for approval). The owner also gets `verifiedPermission` (what they granted) and `effectivePermission` (the lower of the two, which decides the write key) |
|
|
353
|
+
| `td_update_shared_member` | Admin only. Change permission between `write` and `admin`, approve a pending join or unblock (only while the project has no rotated write key); refuses block, kick, reject and downgrade to `read`, which belong in the app. A permission set by the owner is also recorded as their `memberGrant`, which is what hands out the write key; an admin who does not own the project changes only the member's claim |
|
|
354
|
+
| `td_upload_shared_note_attachment` | Upload an attachment to a shared project note |
|
|
355
|
+
| `td_list_shared_note_attachments` | List attachments of a shared project note |
|
|
356
|
+
| `td_download_shared_note_attachment` | Download a shared note attachment |
|
|
357
|
+
| `td_delete_shared_note_attachment` | Delete a shared note attachment |
|
|
358
|
+
| `td_list_shared_project_docs` | List document pages from a shared project (index; content via `includeContent`) |
|
|
359
|
+
| `td_get_shared_project_doc` | Read one document page from a shared project, with its content |
|
|
360
|
+
| `td_create_shared_project_doc` | Create a document page in a shared project |
|
|
361
|
+
| `td_update_shared_project_doc` | Update a document page in a shared project |
|
|
362
|
+
| `td_delete_shared_project_doc` | Delete a document page in a shared project (soft delete) |
|
|
363
|
+
| `td_create_shared_task` | Create a task in a shared project. |
|
|
364
|
+
| `td_delete_shared_task` | Soft-delete a task in a shared project (cascades to its checklist items and comments). |
|
|
365
|
+
| `td_list_shared_worklogs` | List worklogs for a task in a shared project. |
|
|
366
|
+
| `td_add_shared_worklog` | Add a worklog to a task in a shared project. |
|
|
367
|
+
| `td_delete_shared_worklog` | Soft-delete a worklog in a shared project. |
|
|
368
|
+
| `td_list_shared_checklist_items` | List checklist items for a task in a shared project. |
|
|
369
|
+
| `td_create_shared_checklist_item` | Create a checklist item on a task in a shared project. |
|
|
370
|
+
| `td_update_shared_checklist_item` | Update a checklist item in a shared project (toggle done, rename, reorder). |
|
|
371
|
+
| `td_delete_shared_checklist_item` | Soft-delete a checklist item in a shared project. |
|
|
372
|
+
| `td_list_shared_task_links` | List dependency links for a task in a shared project. |
|
|
373
|
+
| `td_create_shared_task_link` | Create a dependency link between tasks in a shared project. |
|
|
374
|
+
| `td_delete_shared_task_link` | Delete a dependency link in a shared project (soft delete). |
|
|
375
|
+
| `td_list_shared_task_comments` | List comments for a task in a shared project. |
|
|
376
|
+
| `td_create_shared_task_comment` | Add a comment to a task in a shared project. |
|
|
377
|
+
| `td_update_shared_task_comment` | Update a comment in a shared project. |
|
|
378
|
+
| `td_delete_shared_task_comment` | Soft-delete a comment in a shared project. |
|
|
379
|
+
| `td_update_shared_repository_link` | Update a repository link in a shared project. |
|
|
380
|
+
| `td_delete_shared_repository_link` | Soft-delete a repository link in a shared project. |
|
|
381
|
+
| `td_update_shared_deployment_stage` | Update a deployment stage in a shared project. |
|
|
382
|
+
| `td_delete_shared_deployment_stage` | Soft-delete a deployment stage in a shared project. |
|
|
383
|
+
| `td_update_shared_project` | Update shared-project metadata (archive / hide from filters). |
|
|
384
|
+
| `td_upload_shared_attachment` | Upload a file attachment to a task in a shared project. |
|
|
385
|
+
| `td_list_shared_attachments` | List file attachments of a task in a shared project (metadata only, no data). |
|
|
386
|
+
| `td_download_shared_attachment` | Download a task attachment from a shared project. |
|
|
387
|
+
| `td_delete_shared_attachment` | Soft-delete a task attachment in a shared project. |
|
|
388
|
+
| `td_get_shared_task` | Get one task in a shared project by ID or code, with its worklog total, checklist and comment counts. |
|
|
389
|
+
| `td_list_shared_task_tags` | List the tags on a task in a shared project. |
|
|
390
|
+
| `td_bulk_update_shared_tasks` | Update several tasks in a shared project at once. |
|
|
391
|
+
| `td_bulk_delete_shared_tasks` | Soft-delete several tasks in a shared project at once, cascading their checklist items and comments. |
|
|
392
|
+
| `td_update_shared_worklog` | Update a worklog in a shared project. |
|
|
393
|
+
| `td_list_shared_activity_log` | List activity log entries for a shared project. |
|
|
484
394
|
|
|
485
|
-
> **
|
|
395
|
+
> **Permissions, `ownerSecret` and history in shared projects (TODO-434).**
|
|
486
396
|
>
|
|
487
|
-
> - **`ownerSecret`
|
|
488
|
-
>
|
|
489
|
-
>
|
|
490
|
-
>
|
|
491
|
-
>
|
|
492
|
-
> - **
|
|
493
|
-
>
|
|
494
|
-
>
|
|
495
|
-
>
|
|
496
|
-
> deployment stages,
|
|
497
|
-
>
|
|
498
|
-
>
|
|
499
|
-
> -
|
|
500
|
-
>
|
|
501
|
-
>
|
|
502
|
-
> kick,
|
|
503
|
-
>
|
|
504
|
-
>
|
|
505
|
-
>
|
|
506
|
-
>
|
|
507
|
-
>
|
|
508
|
-
>
|
|
509
|
-
>
|
|
510
|
-
>
|
|
511
|
-
>
|
|
512
|
-
>
|
|
513
|
-
>
|
|
397
|
+
> - **`ownerSecret` is optional; leave it out.** Every shared tool looks it up
|
|
398
|
+
> from your `projectRef` by `sharedOwnerId`, and `td_list_shared_projects` no
|
|
399
|
+
> longer returns it. The secret is the key to the whole project, so it used
|
|
400
|
+
> to sit in the model's context and every transcript. Passing it still works
|
|
401
|
+
> and is checked against `sharedOwnerId`.
|
|
402
|
+
> - **Writes are gated by permission, as in the app** (`src/permissions.ts`, a
|
|
403
|
+
> port of the app's `permissions.ts`). Tasks, worklogs, checklist items,
|
|
404
|
+
> comments, attachments, links, tag assignment, notes and documents need
|
|
405
|
+
> `write` or `admin`. Project settings (`td_update_shared_project`, delete and
|
|
406
|
+
> restore included), deployment stages, repository links, tag management and
|
|
407
|
+
> members need the owner or `admin`. Without a `projectRef` writes are
|
|
408
|
+
> refused, reads still work. A refusal is an error and nothing is written.
|
|
409
|
+
> - **Member management is partial.** After every member change the app rotates
|
|
410
|
+
> the write key or hands the current one over, otherwise a blocked member keeps
|
|
411
|
+
> writing. The MCP cannot rotate, so changes that leave the member unable to
|
|
412
|
+
> write (block, kick, reject, downgrade to `read`) are refused with a pointer
|
|
413
|
+
> to the app. Approving, unblocking and upgrading pass only while the project
|
|
414
|
+
> has no rotated write key.
|
|
415
|
+
> - **Shared writes record history** in the shared instance, the same entries
|
|
416
|
+
> the app writes (task created / updated per field / deleted, worklog,
|
|
417
|
+
> checklist, comment, attachment, tag, stage, repository link, project,
|
|
418
|
+
> member), with your account as `actorId` and `source: "mcp"` in metadata.
|
|
419
|
+
> - **Deleting an unknown id** is an error instead of `success`, and bulk delete
|
|
420
|
+
> counts it as skipped. `td_update_shared_project` picks the project row the
|
|
421
|
+
> way the app does (oldest live row) and can restore it from the Trash.
|
|
422
|
+
> - **Project codes** may contain only `A-Z` and `0-9`, and concurrent
|
|
423
|
+
> `td_create_task` / `td_create_shared_task` calls for one project no longer
|
|
424
|
+
> get the same code.
|
|
514
425
|
|
|
515
|
-
|
|
516
|
-
> `recurring` je plnohodnotný, appka ho používá pro opakované úkoly a MCP ho
|
|
517
|
-
> teď nabízí ve všech devíti enumech. Zároveň se **kontrolují hodnoty enumů a
|
|
518
|
-
> odmítají nedeklarované argumenty**. Dřív byly enumy jen dokumentace a
|
|
519
|
-
> neznámý argument se tiše zahodil, což je přesně způsob, jak
|
|
520
|
-
> `td_create_shared_checklist_item` přijal `isChecked`, vrátil `success`
|
|
521
|
-
> a položku založil neodškrtnutou. Ten argument tam dnes je.
|
|
522
|
-
>
|
|
523
|
-
> Při té příležitosti se srovnal i `linkType`: MCP nabízelo `related`, kterému
|
|
524
|
-
> appka nerozumí, a chyběly mu `explicit` a `mention`, které appka opravdu
|
|
525
|
-
> zapisuje. Platné hodnoty jsou `blocks`, `explicit`, `mention`.
|
|
426
|
+
### Project Documentation
|
|
526
427
|
|
|
527
|
-
|
|
528
|
-
> `td_create_task_comment` a `td_create_checklist_item` šly dřív založit na
|
|
529
|
-
> **neexistující úkol**: řádek se zapsal proti ID, které nic nerozřeší, každý
|
|
530
|
-
> výpis jde přes `taskId`, takže ho nikdo nikdy nepřečte, a tool vrátil
|
|
531
|
-
> `success`. `td_add_worklog` to odmítal od TODO-90 M12, tyhle dva ne. Teď
|
|
532
|
-
> odmítají obě strany, osobní i sdílená, a sdílená scopuje i podle ownera.
|
|
533
|
-
>
|
|
534
|
-
> Zároveň se dorovnalo devět argumentů, které sdílené tooly proti osobním
|
|
535
|
-
> neměly. Nejcitelnější byl `td_update_shared_project`: uměl jen archivaci,
|
|
536
|
-
> takže **sdílený projekt nešlo přejmenovat**.
|
|
428
|
+
Documents are notes with `isDoc`, so they can nest under another document via `parentDocId`.
|
|
537
429
|
|
|
538
|
-
|
|
430
|
+
| Tool | Description |
|
|
431
|
+
|------|-------------|
|
|
432
|
+
| `td_list_project_docs` | List local project document pages (index: title, hierarchy and `contentLength`; content via `includeContent`) |
|
|
433
|
+
| `td_get_project_doc` | Read one local project document page, with its content |
|
|
434
|
+
| `td_create_project_doc` | Create a local project document page |
|
|
435
|
+
| `td_update_project_doc` | Update a local project document page |
|
|
436
|
+
| `td_delete_project_doc` | Delete a local project document page (soft delete) |
|
|
539
437
|
|
|
540
|
-
|
|
541
|
-
Výpis a mazání umí jen **admin owner** a relay od TODO-90 H2 nevěří samotnému
|
|
542
|
-
`ownerId` — požadavek se podepisuje Ed25519 klíčem odvozeným z nastaveného
|
|
543
|
-
mnemoniku. Odesílání relay nechává nepřihlášené, stejně jako formulář v appce.
|
|
438
|
+
### System Notifications (relay)
|
|
544
439
|
|
|
545
|
-
|
|
546
|
-
|---------|-------|
|
|
547
|
-
| `td_list_user_messages` | Výpis zpráv od uživatelů (jen admin owner) |
|
|
548
|
-
| `td_submit_user_message` | Odeslání zprávy adminům (hlášení vady, návrh, vzkaz) |
|
|
549
|
-
| `td_delete_user_message` | Smazání zprávy na relayi (jen admin owner, tvrdé smazání) |
|
|
440
|
+
Broadcast notices for every user. Writing, and listing expired ones, needs `TODOCKO_RELAY_ADMIN_KEY`.
|
|
550
441
|
|
|
551
|
-
|
|
442
|
+
Without `TODOCKO_RELAY_ADMIN_KEY`, `td_create_system_notification` and
|
|
443
|
+
`td_delete_system_notification` are not offered to the client at all (a 401 is
|
|
444
|
+
the only answer they could give) and the listing drops its `admin` flag. The key
|
|
445
|
+
is never sent over plain `http://` to anything but localhost. (TODO-441)
|
|
552
446
|
|
|
553
|
-
|
|
|
554
|
-
|
|
555
|
-
| `
|
|
556
|
-
| `
|
|
557
|
-
| `
|
|
558
|
-
| `td_list_overdue_tasks` | Úkoly po termínu (seřazené od nejstaršího) |
|
|
447
|
+
| Tool | Description |
|
|
448
|
+
|------|-------------|
|
|
449
|
+
| `td_list_system_notifications` | List active system/broadcast notifications from the relay server. |
|
|
450
|
+
| `td_create_system_notification` | Create a broadcast notification visible to all Todocko users. |
|
|
451
|
+
| `td_delete_system_notification` | Delete a system notification by ID. |
|
|
559
452
|
|
|
560
|
-
|
|
561
|
-
> `td_list_overdue_tasks` a `td_list_tasks_by_date_range` čtly `result.rows`,
|
|
562
|
-
> zatímco `evolu.loadQuery` vrací pole samo — takže `count: 0` na jakýkoli vstup,
|
|
563
|
-
> bez chyby, které by šlo si všimnout. Opraveno v TODO-242 přes společný
|
|
564
|
-
> `queryRows`. Recurrence pole navíc vrací i `td_get_task`, takže nastavení
|
|
565
|
-
> opakování jde přečíst tou nejpřímější cestou.
|
|
566
|
-
| `td_list_tasks_by_date_range` | Úkoly filtrované podle scheduledDate nebo deadline v daném rozmezí |
|
|
567
|
-
| `td_analyze_dependencies` | Analýza závislostí: blokované úkoly, blokující řetězce, kritická cesta |
|
|
453
|
+
### User Messages (relay)
|
|
568
454
|
|
|
569
|
-
|
|
570
|
-
> pět přehledů jen osobní instanci, takže úkol ve sdíleném projektu neviděl
|
|
571
|
-
> dashboard, rozdělení vytížení, seznam opakujících se ani po termínu, ani dotaz
|
|
572
|
-
> na rozmezí dat. U vytížení to nebylo jen chybějící číslo: počítá se
|
|
573
|
-
> z odpracovaného času, takže vynechané sdílené minuty podhodnocovaly každého,
|
|
574
|
-
> kdo ve sdíleném projektu pracuje. Každý nástroj bere `includeShared`
|
|
575
|
-
> (výchozí `true`) a vrací `sharedIncluded`, ať je vidět, jestli se sdílená
|
|
576
|
-
> polovina opravdu načetla. `td_analyze_dependencies` zůstává záměrně jen
|
|
577
|
-
> osobní: appka sdílené `taskLink` řádky čte, ale žádné nezapisuje.
|
|
578
|
-
>
|
|
579
|
-
> `td_search_tasks` hledá ve sdílených projektech taky, se stejným přepínačem.
|
|
455
|
+
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.
|
|
580
456
|
|
|
581
|
-
|
|
457
|
+
| Tool | Description |
|
|
458
|
+
|------|-------------|
|
|
459
|
+
| `td_list_user_messages` | List messages users have sent from the app (bug reports, feature requests, notes). |
|
|
460
|
+
| `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. |
|
|
461
|
+
| `td_delete_user_message` | Delete one user message from the relay. |
|
|
582
462
|
|
|
583
|
-
|
|
584
|
-
|---------|-------|
|
|
585
|
-
| `td_sync_status` | Stav synchronizace |
|
|
586
|
-
| `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í) |
|
|
463
|
+
### Analytics & Reports
|
|
587
464
|
|
|
588
|
-
|
|
465
|
+
| Tool | Description |
|
|
466
|
+
|------|-------------|
|
|
467
|
+
| `td_get_dashboard_summary` | Overview: tasks today, overdue, this week's worklog, upcoming deadlines |
|
|
468
|
+
| `td_get_team_workload` | Team workload: logged vs estimate vs capacity per user for a period |
|
|
469
|
+
| `td_list_recurring_tasks` | List recurring tasks with recurrence configuration |
|
|
470
|
+
| `td_list_overdue_tasks` | Overdue tasks (sorted oldest first) |
|
|
589
471
|
|
|
590
|
-
|
|
472
|
+
> **Before v1.6.0 these three tools always returned nothing.**
|
|
473
|
+
> `td_list_recurring_tasks`, `td_list_overdue_tasks` and
|
|
474
|
+
> `td_list_tasks_by_date_range` read `result.rows`, while `evolu.loadQuery`
|
|
475
|
+
> resolves to the array itself – so `count: 0` for every input, with no error to
|
|
476
|
+
> notice. Fixed in TODO-242 behind a shared `queryRows`. `td_get_task` now returns
|
|
477
|
+
> the recurrence settings too, so a schedule can be read the obvious way.
|
|
478
|
+
| `td_list_tasks_by_date_range` | Tasks filtered by scheduledDate or deadline within a date range |
|
|
479
|
+
| `td_analyze_dependencies` | Dependency analysis: blocked tasks, blocking chains, critical path |
|
|
480
|
+
|
|
481
|
+
### Diagnostics
|
|
482
|
+
|
|
483
|
+
| Tool | Description |
|
|
484
|
+
|------|-------------|
|
|
485
|
+
| `td_sync_status` | Sync status |
|
|
486
|
+
| `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) |
|
|
487
|
+
|
|
488
|
+
## Usage Examples
|
|
489
|
+
|
|
490
|
+
### List projects
|
|
591
491
|
```
|
|
592
|
-
|
|
492
|
+
Show me all projects in Todocko
|
|
593
493
|
```
|
|
594
494
|
|
|
595
|
-
###
|
|
495
|
+
### List tasks
|
|
596
496
|
```
|
|
597
|
-
|
|
598
|
-
|
|
497
|
+
What tasks do I have with status "todo"?
|
|
498
|
+
Show tasks for project TODO
|
|
599
499
|
```
|
|
600
500
|
|
|
601
|
-
###
|
|
501
|
+
### Task details
|
|
602
502
|
```
|
|
603
|
-
|
|
503
|
+
What are the details of task TODO-15?
|
|
604
504
|
```
|
|
605
505
|
|
|
606
|
-
###
|
|
506
|
+
### Create task
|
|
607
507
|
```
|
|
608
|
-
|
|
609
|
-
|
|
508
|
+
Create a new task in project PROJ with title "Fix login bug" and priority high
|
|
509
|
+
Create a task with deadline 2026-03-15 and scheduledDate 2026-03-10
|
|
610
510
|
```
|
|
611
511
|
|
|
612
|
-
###
|
|
512
|
+
### Update task
|
|
613
513
|
```
|
|
614
|
-
|
|
615
|
-
|
|
616
|
-
|
|
514
|
+
Mark task PROJ-5 as completed
|
|
515
|
+
Assign task TODO-10 to user with ID xyz
|
|
516
|
+
Set scheduledDate of task TODO-10 to tomorrow
|
|
617
517
|
```
|
|
618
518
|
|
|
619
|
-
###
|
|
519
|
+
### Log time
|
|
620
520
|
```
|
|
621
|
-
|
|
521
|
+
Log 2 hours of work on task TODO-15 with description "Feature implementation"
|
|
622
522
|
```
|
|
623
523
|
|
|
624
|
-
###
|
|
524
|
+
### Working with attachments
|
|
625
525
|
```
|
|
626
|
-
|
|
627
|
-
|
|
628
|
-
|
|
526
|
+
Upload file /home/user/report.pdf as attachment to task TODO-15
|
|
527
|
+
What attachments does task TODO-15 have?
|
|
528
|
+
Delete attachment with ID xyz
|
|
629
529
|
```
|
|
630
530
|
|
|
631
|
-
###
|
|
531
|
+
### Shared projects
|
|
632
532
|
```
|
|
633
|
-
|
|
634
|
-
|
|
635
|
-
|
|
533
|
+
Show shared projects
|
|
534
|
+
What tasks are in the shared project?
|
|
535
|
+
Mark task as deployed to production
|
|
636
536
|
```
|
|
637
537
|
|
|
638
538
|
### Deployment stages
|
|
639
539
|
```
|
|
640
|
-
|
|
641
|
-
|
|
540
|
+
What deployment stages does the project have?
|
|
541
|
+
Create a new deployment stage "Staging" for the shared project
|
|
642
542
|
```
|
|
643
543
|
|
|
644
|
-
### Sub
|
|
544
|
+
### Sub-tasks
|
|
645
545
|
```
|
|
646
|
-
|
|
647
|
-
|
|
546
|
+
Create a sub-task for task TODO-15 in project TODO
|
|
547
|
+
Detach task TODO-20 from its parent (parentTaskId: null)
|
|
648
548
|
```
|
|
649
549
|
|
|
650
|
-
###
|
|
550
|
+
### Analytics & Reports
|
|
651
551
|
```
|
|
652
|
-
|
|
653
|
-
|
|
654
|
-
|
|
655
|
-
|
|
656
|
-
|
|
657
|
-
|
|
552
|
+
What's my dashboard summary for today?
|
|
553
|
+
How is the team's workload this week?
|
|
554
|
+
What tasks are overdue?
|
|
555
|
+
Show tasks scheduled for next week
|
|
556
|
+
Analyze dependencies in project TODO
|
|
557
|
+
What recurring tasks do I have?
|
|
658
558
|
```
|
|
659
559
|
|
|
660
|
-
##
|
|
560
|
+
## Command line (`todo`)
|
|
661
561
|
|
|
662
|
-
|
|
562
|
+
The package also ships a `todo` command line tool for quick personal use from a
|
|
563
|
+
terminal. It shares the same database and the same `TODOCKO_MNEMONIC` as the MCP
|
|
564
|
+
server, and a global install (`npm install -g todocko-mcp`) puts it on your
|
|
565
|
+
`PATH`.
|
|
663
566
|
|
|
664
|
-
📖 **
|
|
567
|
+
📖 **Full guide: [CLI.md](CLI.md)**
|
|
665
568
|
|
|
666
569
|
```bash
|
|
667
|
-
#
|
|
668
|
-
todo add "
|
|
669
|
-
todo add "
|
|
570
|
+
# Add a task (without -p it uses the first project)
|
|
571
|
+
todo add "Fix the login"
|
|
572
|
+
todo add "Fix the login" -p TODO --priority high --scheduled today
|
|
670
573
|
|
|
671
|
-
#
|
|
574
|
+
# Change status (tasks are addressed by their code)
|
|
672
575
|
todo done TODO-160 # status=done
|
|
673
576
|
todo start TODO-160 # status=in_progress
|
|
674
577
|
todo mv TODO-160 review # backlog|todo|in_progress|review|done|recurring
|
|
675
578
|
|
|
676
579
|
# Worklog
|
|
677
|
-
todo log TODO-160 1h30m "
|
|
678
|
-
todo worklogs TODO-160 #
|
|
580
|
+
todo log TODO-160 1h30m "debugging OAuth"
|
|
581
|
+
todo worklogs TODO-160 # worklog table
|
|
679
582
|
|
|
680
|
-
#
|
|
583
|
+
# Machine readable output on every command
|
|
681
584
|
todo add "X" --json
|
|
682
585
|
```
|
|
683
586
|
|
|
684
|
-
- **
|
|
685
|
-
|
|
686
|
-
- **Exit
|
|
687
|
-
|
|
688
|
-
- **
|
|
689
|
-
|
|
690
|
-
|
|
691
|
-
|
|
692
|
-
|
|
693
|
-
|
|
694
|
-
- Nikdy ji nesdílejte v přímé konverzaci s AI
|
|
695
|
-
- MCP server frázi nevystavuje přes žádný nástroj: nejde ji z Todočka přečíst ani vypsat
|
|
696
|
-
- To ale neznamená, že k ní AI nemá přístup. Agent, který umí spouštět příkazy nebo číst
|
|
697
|
-
soubory (Claude Code a podobní), si `~/.claude.json` nebo `~/.claude/settings.json`
|
|
698
|
-
přečte stejně jako kterýkoli jiný soubor. Konfigurace chrání frázi před nástroji MCP,
|
|
699
|
-
ne před shellem. (TODO-441)
|
|
700
|
-
- Kdokoli s vaší frází má plný přístup k vašim datům
|
|
701
|
-
|
|
702
|
-
### Kontrola argumentů a cest (TODO-441)
|
|
703
|
-
|
|
704
|
-
- Hodnoty argumentů se kontrolují proti typu, který nástroj deklaruje. `isBlocked: "false"`
|
|
705
|
-
se dřív ukládalo jako `true` (neprázdný řetězec je pravdivý), teď je to chyba.
|
|
706
|
-
- Datová pole (`deadline`, `scheduledDate`, `loggedAt`, `recurrenceEndDate`, `startDate`,
|
|
707
|
-
`endDate`, …) musí být `YYYY-MM-DD`; kde schéma mluví o datetime (`completedAt`,
|
|
708
|
-
`expiresAt`, `from`/`to` v activity logu), projde i ISO datetime. `deadline: "zítra"`
|
|
709
|
-
se dřív uložilo doslova a nikdo se to nedozvěděl.
|
|
710
|
-
- Přílohy: cesty se vyhodnocují až po rozpadnutí symlinků, takže odkaz uvnitř povoleného
|
|
711
|
-
adresáře už nevede ven. Stahování nově odmítá tečkové soubory (stejně jako nahrávání)
|
|
712
|
-
a nepřepíše existující soubor, dokud nepošleš `overwrite: true`.
|
|
713
|
-
|
|
714
|
-
### WebSocket Origin (TODO-169)
|
|
715
|
-
|
|
716
|
-
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.
|
|
587
|
+
- **Sync:** after a mutation it waits about 3 s for the relay. Offline it prints
|
|
588
|
+
`⚠ uloženo lokálně` and exits 0, because the data is safe locally either way.
|
|
589
|
+
- **Exit codes:** `0` success, `1` user or business error (unknown code, bad
|
|
590
|
+
status or duration), `2` configuration (missing mnemonic).
|
|
591
|
+
- **Colors** only on a TTY and only when `NO_COLOR` is unset.
|
|
592
|
+
- **Note:** it runs as its own process against the same SQLite database as the
|
|
593
|
+
MCP server. A write that collides with the MCP server can rarely raise
|
|
594
|
+
`SQLITE_BUSY`; repeat the command when it does. Out of scope for v1:
|
|
595
|
+
`list`/`today`, editing descriptions, projects, tags, checklists and shared
|
|
596
|
+
projects.
|
|
717
597
|
|
|
718
|
-
|
|
598
|
+
## Security
|
|
719
599
|
|
|
720
|
-
|
|
721
|
-
projektu na relayi. Klíč odvozený z `ownerSecret` tím přestane platit a relay
|
|
722
|
-
s ním odmítne každý zápis.
|
|
600
|
+
**Important:** Your backup phrase (mnemonic) is sensitive data!
|
|
723
601
|
|
|
724
|
-
|
|
725
|
-
|
|
726
|
-
|
|
727
|
-
|
|
602
|
+
- Never share it directly in conversation with AI
|
|
603
|
+
- The MCP server never exposes the phrase through a tool: nothing in Todocko can read or print it
|
|
604
|
+
- That is not the same as the AI having no access to it. An agent that can run commands or
|
|
605
|
+
read files (Claude Code and the like) reads `~/.claude.json` or `~/.claude/settings.json`
|
|
606
|
+
like any other file. The configuration keeps the phrase away from MCP tools, not from a
|
|
607
|
+
shell. (TODO-441)
|
|
608
|
+
- Anyone with your phrase has full access to your data
|
|
728
609
|
|
|
729
|
-
###
|
|
610
|
+
### Argument and path checks (TODO-441)
|
|
730
611
|
|
|
731
|
-
|
|
732
|
-
|
|
733
|
-
|
|
612
|
+
- Argument values are checked against the type the tool declares. `isBlocked: "false"`
|
|
613
|
+
used to be stored as `true` (a non-empty string is truthy); it is an error now.
|
|
614
|
+
- Date arguments (`deadline`, `scheduledDate`, `loggedAt`, `recurrenceEndDate`,
|
|
615
|
+
`startDate`, `endDate`, ...) must be `YYYY-MM-DD`; where the schema says datetime
|
|
616
|
+
(`completedAt`, `expiresAt`, activity-log `from`/`to`) an ISO datetime is accepted too.
|
|
617
|
+
`deadline: "zitra"` used to be stored verbatim with nothing reporting it.
|
|
618
|
+
- Attachments: paths are judged after symlinks are resolved, so a link inside the allowed
|
|
619
|
+
directory no longer leads out of it. Downloads now refuse dotfiles (as uploads already
|
|
620
|
+
did) and never replace an existing file unless `overwrite: true` is passed.
|
|
734
621
|
|
|
735
|
-
|
|
736
|
-
- `memberGrant` na každého člena, jehož oprávnění vlastník nastavil ručně,
|
|
737
|
-
a ten pozvánku přebíjí.
|
|
622
|
+
### Shared project write key rotation (TODO-268)
|
|
738
623
|
|
|
739
|
-
|
|
740
|
-
|
|
741
|
-
|
|
742
|
-
Skutečné oprávnění je to nižší z nároku a záznamu.
|
|
624
|
+
When the owner of a shared project removes a member, the app swaps the
|
|
625
|
+
project's write key on the relay. The key derived from `ownerSecret` stops
|
|
626
|
+
being valid and the relay refuses every write made with it.
|
|
743
627
|
|
|
744
|
-
|
|
745
|
-
|
|
746
|
-
|
|
747
|
-
|
|
748
|
-
nárokuje víc, než má potvrzeno.
|
|
628
|
+
This server picks the new key up from the `projectRef.writeKey` column, which
|
|
629
|
+
reaches its database through the ordinary AppOwner sync. It checks at start and
|
|
630
|
+
then once a minute, so a rotation can leave about a minute in which writes to
|
|
631
|
+
that one project are refused and the rows wait locally. Reading is unaffected.
|
|
749
632
|
|
|
750
|
-
##
|
|
633
|
+
## Data Location
|
|
751
634
|
|
|
752
|
-
|
|
635
|
+
Databases are stored in the `~/.todocko/` directory:
|
|
753
636
|
|
|
754
|
-
|
|
|
755
|
-
|
|
637
|
+
| Platform | Path |
|
|
638
|
+
|----------|------|
|
|
756
639
|
| Linux | `~/.todocko/` |
|
|
757
640
|
| macOS | `~/.todocko/` |
|
|
758
641
|
| Windows | `C:\Users\<user>\.todocko\` |
|
|
759
642
|
|
|
760
|
-
|
|
761
|
-
- `todocko.db` -
|
|
762
|
-
- `todocko-shared.db` -
|
|
643
|
+
Files:
|
|
644
|
+
- `todocko.db` - your personal data (tasks, projects)
|
|
645
|
+
- `todocko-shared.db` - shared projects
|
|
763
646
|
|
|
764
|
-
##
|
|
647
|
+
## Configuration Changes
|
|
765
648
|
|
|
766
649
|
### Claude Code (CLI)
|
|
767
650
|
|
|
768
|
-
|
|
651
|
+
After changing configuration in `~/.claude/settings.json` (e.g., changing mnemonic), run the command:
|
|
769
652
|
```
|
|
770
653
|
/mcp
|
|
771
654
|
```
|
|
772
|
-
|
|
655
|
+
This will restart the MCP server with the new configuration.
|
|
773
656
|
|
|
774
|
-
###
|
|
657
|
+
### Switching to a Different Account
|
|
775
658
|
|
|
776
|
-
|
|
659
|
+
When changing the mnemonic to a **different Todocko account**, you need to delete the local database:
|
|
777
660
|
|
|
778
661
|
```bash
|
|
779
662
|
# Linux/macOS
|
|
@@ -783,181 +666,314 @@ rm ~/.todocko/todocko.db
|
|
|
783
666
|
del %USERPROFILE%\.todocko\todocko.db
|
|
784
667
|
```
|
|
785
668
|
|
|
786
|
-
|
|
669
|
+
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.
|
|
670
|
+
|
|
671
|
+
## Troubleshooting
|
|
672
|
+
|
|
673
|
+
### Server won't start
|
|
674
|
+
- Check that you have Node.js 24.20 or newer (Evolu v8 requires it)
|
|
675
|
+
- Check that you ran `npm run build`
|
|
676
|
+
- Check logs in Claude Desktop
|
|
677
|
+
|
|
678
|
+
### Data not syncing
|
|
679
|
+
- Verify the backup phrase is correct (24 words)
|
|
680
|
+
- Check internet connection
|
|
681
|
+
- Wait a few seconds for synchronization
|
|
682
|
+
- Try deleting `~/.todocko/todocko.db` and restart
|
|
683
|
+
|
|
684
|
+
### Tools not visible
|
|
685
|
+
- Restart Claude Desktop
|
|
686
|
+
- In Claude Code, use `/mcp` for reload
|
|
687
|
+
- Check the configuration file
|
|
688
|
+
- Check the path to dist/index.js
|
|
689
|
+
|
|
690
|
+
### `project ... is a shared project` on a write
|
|
691
|
+
A shared project keeps its data in the **shared instance**, so the personal
|
|
692
|
+
tools (`td_create_task`, `td_update_task`, `td_bulk_update_tasks`) refuse a
|
|
693
|
+
write aimed at one and point at the `td_*_shared_*` counterpart.
|
|
694
|
+
|
|
695
|
+
Such a write used to be stored quietly in the personal instance beside the real
|
|
696
|
+
row, leaving the same task in two instances, free to drift: the app reads the
|
|
697
|
+
shared side and `td_list_tasks` reads the personal one, so the two disagreed
|
|
698
|
+
with nothing reporting it. (TODO-318)
|
|
699
|
+
|
|
700
|
+
**Deletes are still allowed** on a shared project, because otherwise old
|
|
701
|
+
personal copies could never be cleaned up. `td_search_tasks` with
|
|
702
|
+
`includeShared` shows both copies side by side and is the quickest way to spot
|
|
703
|
+
a split task.
|
|
704
|
+
|
|
705
|
+
### `Todocko MCP už nad touto databází běží` (TODO-341)
|
|
706
|
+
A second instance over the same backup phrase refuses to start. The client
|
|
707
|
+
database runs with `journal_mode=delete` and a zero `busy_timeout`, so the
|
|
708
|
+
second process gets SQLITE_BUSY immediately, Evolu turns it into
|
|
709
|
+
`PanicAbortReason: database is locked`, and the **first** process loses its
|
|
710
|
+
dbWorker. Until TODO-341 a new window silently killed the one you were working
|
|
711
|
+
in.
|
|
712
|
+
|
|
713
|
+
The lock is `~/.todocko/todocko-<owner>.lock` next to the database. It holds the
|
|
714
|
+
owning pid; after a crash the next start detects it as stale
|
|
715
|
+
(`process.kill(pid, 0)`) and takes it over.
|
|
716
|
+
|
|
717
|
+
If you really need a second instance (the `todo` CLI next to the MCP, say), give
|
|
718
|
+
it its own database name:
|
|
719
|
+
```bash
|
|
720
|
+
TODOCKO_INSTANCE=cli todo ...
|
|
721
|
+
```
|
|
722
|
+
It gets `~/.todocko/todocko-cli-<owner>.db`, a separate local copy that
|
|
723
|
+
reconciles with the first one through the relay. Allowed characters are
|
|
724
|
+
`a-z0-9-`; anything else is dropped and an empty value means the default
|
|
725
|
+
database.
|
|
726
|
+
|
|
727
|
+
### Every `loadQuery` ends with a timeout (`loadQuery timed out after 15000ms`)
|
|
728
|
+
|
|
729
|
+
There are two causes, told apart by what the server says.
|
|
730
|
+
|
|
731
|
+
**1. A dead dbWorker after two processes raced (TODO-316).** Two MCP processes
|
|
732
|
+
creating the schema of the same database at the same time race each other. The
|
|
733
|
+
loser gets `SqliteError: table evolu_version already exists` and its dbWorker
|
|
734
|
+
stays dead for the life of the process. Typically on the first starts after an
|
|
735
|
+
MCP upgrade that adds a table.
|
|
736
|
+
|
|
737
|
+
Since TODO-316 the server detects this at startup and **refuses to start**:
|
|
738
|
+
every tool call returns `Evolu dbWorker never answered` immediately. Since
|
|
739
|
+
TODO-317 the reason the worker died is recorded too, in `workerDefects` from
|
|
740
|
+
`td_sync_status` and on stderr as `FATAL: Evolu dbWorker defect: ...`. It used to
|
|
741
|
+
look healthy while every query hung until the client gave up 1800s later. The
|
|
742
|
+
fix is a `/mcp` reconnect in Claude Code.
|
|
743
|
+
|
|
744
|
+
**2. A mismatched native binding.** 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.
|
|
745
|
+
|
|
746
|
+
Typical symptoms: `td_sync_status` reports `ok` with `errorCount: 0`, but `td_get_task`, `td_list_*`, etc. all time out.
|
|
747
|
+
|
|
748
|
+
Fix – rebuild the native binding against the current Node:
|
|
749
|
+
```bash
|
|
750
|
+
cd ~/.todocko-mcp # or wherever todocko-mcp is installed
|
|
751
|
+
cd node_modules/better-sqlite3
|
|
752
|
+
npx node-gyp rebuild --release
|
|
753
|
+
```
|
|
754
|
+
Then `/mcp` reconnect in Claude Code.
|
|
755
|
+
|
|
756
|
+
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.
|
|
757
|
+
|
|
758
|
+
## Development
|
|
759
|
+
|
|
760
|
+
```bash
|
|
761
|
+
# Install dependencies
|
|
762
|
+
npm install
|
|
763
|
+
|
|
764
|
+
# Build
|
|
765
|
+
npm run build
|
|
766
|
+
|
|
767
|
+
# Watch mode for development
|
|
768
|
+
npm run dev
|
|
769
|
+
|
|
770
|
+
# Tests
|
|
771
|
+
npm test
|
|
772
|
+
|
|
773
|
+
# Manual run
|
|
774
|
+
TODOCKO_MNEMONIC="your phrase" npm start
|
|
775
|
+
```
|
|
776
|
+
|
|
777
|
+
### Tests
|
|
787
778
|
|
|
788
|
-
|
|
779
|
+
Vitest. **The suite runs in CI** (`ci.yml`, on pushes and
|
|
780
|
+
pull requests to `main`) since TODO-229. Before that CI only built, so nobody
|
|
781
|
+
learned that `helpers.test.ts` **does not even survive the import** on Node
|
|
782
|
+
18/20: through `helpers.ts` it pulled in `../evolu.js`, whose module-level
|
|
783
|
+
initialization dies on `crypto.getRandomValues must be defined`.
|
|
789
784
|
|
|
790
|
-
|
|
791
|
-
|
|
792
|
-
|
|
793
|
-
|
|
785
|
+
That is why the functions with no Evolu dependency live in
|
|
786
|
+
**`src/tools/pure.ts`** and are tested from there. `helpers.ts` re-exports them,
|
|
787
|
+
so callers do not change. A helper that does not need Evolu belongs in
|
|
788
|
+
`pure.ts`, otherwise it cannot be tested without a running database.
|
|
794
789
|
|
|
795
|
-
|
|
796
|
-
|
|
797
|
-
- Zkontrolujte internetové připojení
|
|
798
|
-
- Počkejte pár sekund na synchronizaci
|
|
799
|
-
- Zkuste smazat `~/.todocko/todocko.db` a restartovat
|
|
790
|
+
The required version is **Node 24.20 or newer**: it is in `engines` and Evolu v8
|
|
791
|
+
does not run on anything older. `ci.yml` and `release.yml` both use it.
|
|
800
792
|
|
|
793
|
+
### Releasing
|
|
801
794
|
|
|
802
|
-
|
|
795
|
+
```bash
|
|
796
|
+
npm version patch # or minor / major
|
|
797
|
+
git push --follow-tags
|
|
798
|
+
```
|
|
803
799
|
|
|
804
|
-
|
|
805
|
-
|
|
806
|
-
|
|
807
|
-
|
|
800
|
+
The tag starts `release.yml`, which builds, runs the tests, checks that the tag
|
|
801
|
+
matches `package.json` and then **stages** the release on npm with a signed
|
|
802
|
+
provenance statement. It carries no npm credentials: the runner asks for a
|
|
803
|
+
short-lived one through trusted publishing (OIDC).
|
|
808
804
|
|
|
809
|
-
|
|
810
|
-
|
|
811
|
-
-
|
|
812
|
-
|
|
813
|
-
- Zkontrolujte cestu k dist/index.js
|
|
805
|
+
Staging is deliberate. A release does not reach anyone until it is approved on
|
|
806
|
+
npmjs.com under **Staged Packages**, or with `npm stage list todocko-mcp` and
|
|
807
|
+
`npm stage approve <stage-id>`. Approval needs 2FA, so a workflow run that
|
|
808
|
+
someone else managed to steer cannot put a version in front of users on its own.
|
|
814
809
|
|
|
815
|
-
|
|
816
|
-
Sdílený projekt má svá data ve **sdílené instanci**. Osobní nástroje
|
|
817
|
-
(`td_create_task`, `td_update_task`, `td_bulk_update_tasks`) proto zápis do
|
|
818
|
-
takového projektu odmítnou a pošlou tě na `td_*_shared_*` protějšek.
|
|
810
|
+
---
|
|
819
811
|
|
|
820
|
-
|
|
821
|
-
tím dvě kopie téhož úkolu v různých instancích, které se rozcházely: aplikace
|
|
822
|
-
čte sdílenou stranu, MCP `td_list_tasks` osobní, takže každý ukazoval něco
|
|
823
|
-
jiného a nic to nehlásilo. (TODO-318)
|
|
812
|
+
# Česky
|
|
824
813
|
|
|
825
|
-
|
|
826
|
-
nešlo uklidit. `td_search_tasks` s `includeShared` ukáže obě kopie vedle sebe a
|
|
827
|
-
je proto nejrychlejší způsob, jak zjistit, že je úkol rozdvojený.
|
|
814
|
+
MCP (Model Context Protocol) server pro práci s daty [Todocko](https://app.todocko.cz) aplikace z AI asistentů.
|
|
828
815
|
|
|
829
|
-
|
|
830
|
-
`td_create_task` odvozuje kód z nejvyššího, který v téhle kopii vidí. Když část
|
|
831
|
-
účtu ještě nedorazila, je maximum nižší než skutečné a vznikne kód, který na
|
|
832
|
-
relayi už existuje. Stalo se to 2026-09-23: v 07:01 kopie neměla TODO-360 až
|
|
833
|
-
367 a server vyrobil TODO-353 a dál, v 09:33 už je nad stejným souborem měla
|
|
834
|
-
a navázal správně na 368. Nic se nerozbilo jen proto, že 353 až 359 byla shodou
|
|
835
|
-
okolností volná.
|
|
816
|
+
## Podpora
|
|
836
817
|
|
|
837
|
-
|
|
838
|
-
|
|
839
|
-
obou stranách. Když je kopie pozadu, zápis se odmítne a řekne, kolik zpráv
|
|
840
|
-
chybí; až se sync dotáhne, projde. Když se relay zeptat nedá, zápis projde:
|
|
841
|
-
odmítat i tam by z lokálně prvního nástroje udělalo nástroj závislý na síti.
|
|
818
|
+
- **Claude Desktop** - plná podpora
|
|
819
|
+
- **Claude Code (CLI)** - plná podpora (stejná konfigurace)
|
|
842
820
|
|
|
843
|
-
|
|
821
|
+
## Požadavky
|
|
844
822
|
|
|
845
|
-
**
|
|
846
|
-
|
|
847
|
-
|
|
823
|
+
- **Node.js 24.20+** – Evolu v8 to má v `engines`, a není to formalita: v8 stojí
|
|
824
|
+
na `navigator.locks`, `MessageChannel`, `BroadcastChannel` a `WebSocket`, které
|
|
825
|
+
má Node nativně teprve od 24
|
|
826
|
+
- Todocko účet s daty synchronizovanými přes Evolu
|
|
848
827
|
|
|
849
|
-
|
|
850
|
-
Druhá instance nad stejnou zálohovací frází se odmítne nastartovat. Není to
|
|
851
|
-
opatrnost navíc: klientská databáze jede v režimu `journal_mode=delete`
|
|
852
|
-
s nulovým `busy_timeout`, takže druhý proces dostane SQLITE_BUSY okamžitě,
|
|
853
|
-
Evolu z toho udělá `PanicAbortReason: database is locked` a **prvnímu** procesu
|
|
854
|
-
umře dbWorker. Do TODO-341 tak nové okno tiše shodilo to, ve kterém jsi pracoval
|
|
855
|
-
(projevilo se jako `status: worker-dead`, viz níž).
|
|
828
|
+
## Evolu v8 (TODO-88)
|
|
856
829
|
|
|
857
|
-
|
|
858
|
-
|
|
859
|
-
|
|
830
|
+
MCP běží na `@evolu/common` 8.27.0 a `@evolu/nodejs` 4.6.0. Upgrade z 8.22
|
|
831
|
+
(TODO-431) nevyžadoval změnu kódu; sync přes relay ověřen v obou směrech
|
|
832
|
+
proti verzi 8.22.
|
|
860
833
|
|
|
861
|
-
|
|
862
|
-
|
|
863
|
-
v tabulce procesů a signál 0 na něm uspěje. Zámek pak vypadá jako věčně držený
|
|
864
|
-
a žádná nová instance se nespustí. Stalo se to 2026-09-22, kdy byl držitel ve
|
|
865
|
-
stavu `Z` a jeho rodič zastavený `claude` ve stavu `Tl`, takže neměl kdo
|
|
866
|
-
sklízet. Na Linuxu se proto čte stav z `/proc/<pid>/stat` a `Z` se bere jako
|
|
867
|
-
mrtvý. Kde `/proc` není, zůstává původní chování.
|
|
834
|
+
Upgrade na 8.27 (TODO-448) změnu kódu vyžadoval, a hlavně **mění formát
|
|
835
|
+
databáze na disku**:
|
|
868
836
|
|
|
869
|
-
|
|
870
|
-
|
|
871
|
-
|
|
872
|
-
|
|
873
|
-
|
|
874
|
-
|
|
875
|
-
|
|
876
|
-
|
|
837
|
+
- `@evolu/nodejs` 4.4 vyměnilo better-sqlite3 za vlastní SQLite. Ten na rozdíl
|
|
838
|
+
od better-sqlite3 respektuje šifrovací klíč, který Evolu pro klientskou
|
|
839
|
+
databázi předává, takže soubor v `~/.todocko` je nově **šifrovaný**. Starou
|
|
840
|
+
databázi psanou better-sqlite3 nový driver neotevře, skončí na
|
|
841
|
+
`file is not a database` (SQLITE_NOTADB, ověřeno na kopii reálné databáze).
|
|
842
|
+
**Při upgradu je proto nutné lokální databáze smazat**; jsou jen keší dat
|
|
843
|
+
z relaye, takže se stáhnou znovu (ověřeno: čerstvá databáze se dosynchronizovala
|
|
844
|
+
na 17 MB). Co nebylo odsynchronizované, je pryč, takže před smazáním
|
|
845
|
+
zkontrolovat `td_sync_status`.
|
|
846
|
+
- Dopad na bezpečnost je naopak příjemný: lokální kopie všech úkolů už neleží na
|
|
847
|
+
disku v plaintextu. Druhá strana téže mince je, že do souboru nenahlédne ani
|
|
848
|
+
žádný vlastní nástroj, což odneslo `ensureMissingColumns`.
|
|
849
|
+
- Transportní URL je od 8.27 brandovaný `RelayUrl`, takže `TODOCKO_RELAY_URL` se
|
|
850
|
+
parsuje přes `RelayUrlFromString` a URL s query se odmítne; `createOwnerWebSocketTransport`
|
|
851
|
+
si `?ownerId=` připojuje sám.
|
|
852
|
+
- Platforma musí nově dodat `deleteDatabaseFiles` (maže soubor databáze i žurnál)
|
|
853
|
+
a `getDevicePersistence` i na hlavním vlákně, ne jen v shared workeru.
|
|
877
854
|
|
|
878
|
-
|
|
879
|
-
|
|
880
|
-
|
|
881
|
-
|
|
882
|
-
|
|
883
|
-
|
|
884
|
-
|
|
855
|
+
Od Evolu 8.20.3 nese zápis do sdílené instance celého ownera,
|
|
856
|
+
`{ owner: sharedOwner }`, ne `{ ownerId }`. Zapomenuté `ownerId` Evolu ignoruje
|
|
857
|
+
a řádek zapíše pod jiného ownera, odkud se nenasynchronizuje. Hlídá to
|
|
858
|
+
`src/tools/sharedWrites.test.ts`. Databázi, jejíž worker spadl, Evolu nově
|
|
859
|
+
odmítne přes `evoluError`; `td_sync_status` ji ukáže v poli `evoluError`
|
|
860
|
+
a nástroje na ni nečekají do timeoutu, hned řeknou, že je potřeba reconnect.
|
|
861
|
+
(TODO-427)
|
|
885
862
|
|
|
886
|
-
|
|
863
|
+
v7 dodával `createDbWorkerForPlatform`, což bylo vše, co headless klient v Node
|
|
864
|
+
potřeboval. v8 to zrušil: `@evolu/nodejs` v3 nabízí relay a pár primitiv, a
|
|
865
|
+
jedinou kompletní klientskou platformu má upstream pro web. `src/evoluPlatform.ts`
|
|
866
|
+
je protějšek pro Node, poskládaný ze stejných dílů.
|
|
887
867
|
|
|
888
|
-
|
|
868
|
+
Vyšel krátce, protože Node 24 má potřebná web API nativně. Oba workery běží
|
|
869
|
+
**in-process** přes `createWorker` / `createSharedWorker` – to jsou vlastní
|
|
870
|
+
fallbacky Evolu „pro platformy bez podpory workerů"; `worker_threads` by přinesly
|
|
871
|
+
izolaci, kterou jednoprocesový CLI nepotřebuje.
|
|
889
872
|
|
|
890
|
-
|
|
891
|
-
současně zakládají schéma téže databáze, se porvou. Poražený dostane
|
|
892
|
-
`SqliteError: table evolu_version already exists` a jeho dbWorker zůstane
|
|
893
|
-
mrtvý do konce života procesu. Typicky při prvních startech po upgradu MCP,
|
|
894
|
-
který přidá tabulku.
|
|
873
|
+
Sedm věcí, na kterých se to dá snadno rozbít:
|
|
895
874
|
|
|
896
|
-
|
|
897
|
-
|
|
898
|
-
|
|
899
|
-
|
|
900
|
-
|
|
901
|
-
|
|
875
|
+
- **Mutace má strop 640 000 bajtů** (od 8.12). Větší zápis vyhodí výjimku ještě
|
|
876
|
+
před uložením, takže se ani nenasynchronizuje. Přílohy se proto ukládají
|
|
877
|
+
binárně a po kusech po 480 KiB (`src/tools/attachmentChunks.ts`), stejně jako
|
|
878
|
+
v aplikaci; velikost kusu musí sedět s ní, jinak se příloha nahraná tady
|
|
879
|
+
otevře jinde useknutá. Čtení umí i starý tvar, base64 v `attachment.data`,
|
|
880
|
+
protože schéma je append-only.
|
|
881
|
+
- **Obsah nové přílohy leží ve vlastním shardu** (`src/attachmentShards.ts`,
|
|
882
|
+
TODO-450), ne pod AppOwnerem. Jednotlivou změnu v CRDT smazat nejde, jen
|
|
883
|
+
označit jako smazanou, takže owner je jediná jednotka skutečného smazání.
|
|
884
|
+
Cesta `attachment/<id>` se odvozuje z id přílohy, a tedy se nikam neukládá;
|
|
885
|
+
v řádku je jen značka `contentShard`. Odvození i pořadí při mazání, nejdřív
|
|
886
|
+
relay a pak lokálně, musí sedět s aplikací, jinak se obě poloviny rozejdou
|
|
887
|
+
tiše: příloha nahraná tady by se tam otevřela prázdná. Shard se registruje
|
|
888
|
+
jen na dobu nahrání nebo čtení, protože adresa transportu nese owner id
|
|
889
|
+
a trvale registrovaný shard by znamenal jeden WebSocket na každou přílohu.
|
|
890
|
+
- **Hlášení stavů dohledává jména k identifikátorům** (`src/statusReporting.ts`,
|
|
891
|
+
TODO-458). Pilulka v aplikaci ukazovala u volání, která dostanou jen id,
|
|
892
|
+
zkrácený identifikátor, což člověku neříká nic. Tabulky i sloupce, ze kterých
|
|
893
|
+
se jméno bere, jsou vyjmenované vedle seznamu povolených polí, ne odvozené
|
|
894
|
+
z názvu nástroje. Dohledání běží uvnitř téhož pošli a nečekej jako celé
|
|
895
|
+
hlášení a má vlastní strop, takže zaseknutý dotaz nedrží frontu; když se nic
|
|
896
|
+
nenajde, zůstane zkrácené id.
|
|
902
897
|
|
|
903
|
-
**2. Databáze, kterou nový driver neotevře.** Od TODO-448 je klientská databáze
|
|
904
|
-
šifrovaná a starou, plaintextovou, nový driver odmítne: `file is not a database`.
|
|
905
|
-
Symptom je stejný jako u všech vad dbWorkeru, tedy `Evolu dbWorker never answered`
|
|
906
|
-
u každého volání. Řešení je smazat `~/.todocko/todocko*-<ownerId>.db` a nechat
|
|
907
|
-
data stáhnout z relaye; předtím se ujistit přes `td_sync_status`, že nic nečeká
|
|
908
|
-
na odeslání.
|
|
909
898
|
|
|
910
|
-
|
|
911
|
-
|
|
912
|
-
|
|
899
|
+
- **`installPolyfills()` je povinné** a musí proběhnout dřív než cokoli
|
|
900
|
+
z `@evolu/common`. v8 volá `Map.prototype.getOrInsert(Computed)`, které nemá
|
|
901
|
+
žádný vydaný Node (ověřeno do 25.9.0). Bez toho to spadne na první zprávě.
|
|
902
|
+
- **Databáze patří jednomu mnemonicu.** v7 při neshodě volal `restoreAppOwner`,
|
|
903
|
+
který lokální databázi resetoval. v8 obnovu nemá, takže by v souboru zůstala
|
|
904
|
+
data starého ownera zašifrovaná klíčem, který nový nemá. Server proto neshodu
|
|
905
|
+
**ohlásí a odmítne nastartovat** – smaž `~/.todocko/todocko.db` a nech ho
|
|
906
|
+
stáhnout data znovu.
|
|
907
|
+
- **`createNodeEvoluDeps()` musí být singleton na proces.** Shared worker drží
|
|
908
|
+
jediný `tabLeaderPortStore` a `initDbWorker` každého tenanta předpokládá, že
|
|
909
|
+
je už naplněný. Druhá sada deps znamená druhý shared worker, kterému nikdo
|
|
910
|
+
leadera neohlásil, a vytvoření sdílené instance spadne na
|
|
911
|
+
`initDbWorker: Expected value to be non-nullable`. Jeden worker obslouží obě
|
|
912
|
+
instance jako dva tenanty podle `appName`, stejně jako `@evolu/web` na jedné
|
|
913
|
+
stránce.
|
|
914
|
+
- **Mutace nevrací `Result`.** v7 vracel z `insert`/`update` `Result`, takže se
|
|
915
|
+
testovalo `result.ok` a čtlo `result.value.id`. v8 vrací přímo `{ id }` a při
|
|
916
|
+
neplatné změně vyhodí výjimku. Kontrola `!result.ok` proto uspěla vždy a
|
|
917
|
+
nástroj ohlásil chybu u zápisu, který právě proběhl. U vkládání je to horší,
|
|
918
|
+
protože uživatel to zkusí znovu a vznikne duplicita. Hlídá to
|
|
919
|
+
`src/tools/pure.test.ts`.
|
|
920
|
+
- **Ownera filtrovat v SQL, ne až v JS.** Sdílená instance drží data všech
|
|
921
|
+
ownerů v jedné tabulce. `limit` provede SQLite dřív, než se v JS cokoli
|
|
922
|
+
filtruje, takže nezúžený dotaz vrátí prvních N řádků přes všechny ownery a
|
|
923
|
+
filtr je pak zahodí. Nástroj hlásil nula úkolů u projektu, který jich má 26.
|
|
924
|
+
Stejná past číhá u `orderBy position desc limit 1` při výpočtu další pozice.
|
|
913
925
|
|
|
914
|
-
##
|
|
926
|
+
## Instalace
|
|
915
927
|
|
|
916
|
-
|
|
917
|
-
# Instalace závislostí
|
|
918
|
-
npm install
|
|
928
|
+
### Z npm
|
|
919
929
|
|
|
920
|
-
|
|
921
|
-
|
|
930
|
+
Není co klonovat ani sestavovat. Stačí Clauda nasměrovat na vydaný balíček,
|
|
931
|
+
který si při prvním spuštění sám stáhne:
|
|
922
932
|
|
|
923
|
-
|
|
924
|
-
npm run dev
|
|
933
|
+
**Claude Desktop** (`~/.config/Claude/claude_desktop_config.json` na Linuxu nebo `~/Library/Application Support/Claude/claude_desktop_config.json` na macOS):
|
|
925
934
|
|
|
926
|
-
|
|
927
|
-
|
|
935
|
+
```json
|
|
936
|
+
{
|
|
937
|
+
"mcpServers": {
|
|
938
|
+
"todocko": {
|
|
939
|
+
"command": "npx",
|
|
940
|
+
"args": ["-y", "todocko-mcp"],
|
|
941
|
+
"env": {
|
|
942
|
+
"TODOCKO_MNEMONIC": "vaše 24slovná zálohovací fráze"
|
|
943
|
+
}
|
|
944
|
+
}
|
|
945
|
+
}
|
|
946
|
+
}
|
|
928
947
|
```
|
|
929
948
|
|
|
930
|
-
|
|
931
|
-
|
|
932
|
-
# English
|
|
949
|
+
**Claude Code (CLI)** - tentýž blok přidejte do `~/.claude/settings.json`
|
|
950
|
+
a restartujte Clauda.
|
|
933
951
|
|
|
934
|
-
|
|
935
|
-
|
|
936
|
-
|
|
937
|
-
|
|
938
|
-
- **Claude Desktop** - full support
|
|
939
|
-
- **Claude Code (CLI)** - full support (same configuration)
|
|
952
|
+
Místo `todocko-mcp` můžete napsat `todocko-mcp@<verze>` a držet si tak verzi pod
|
|
953
|
+
kontrolou. Pokud chcete mít v `PATH` i nástroj `todo` pro příkazovou řádku,
|
|
954
|
+
nainstalujte balíček globálně:
|
|
940
955
|
|
|
941
|
-
|
|
956
|
+
```bash
|
|
957
|
+
npm install -g todocko-mcp
|
|
958
|
+
```
|
|
942
959
|
|
|
943
|
-
|
|
944
|
-
|
|
945
|
-
|
|
946
|
-
- Todocko account with data synchronized via Evolu
|
|
960
|
+
Pozor, `TODOCKO_MNEMONIC` je privátní klíč ke všem vašim datům. Patří do
|
|
961
|
+
konfiguračního souboru a nikam jinam: nikdy na příkazovou řádku, nikdy do
|
|
962
|
+
historie shellu, nikdy do repozitáře. Viz [Bezpečnost](#bezpečnost).
|
|
947
963
|
|
|
948
|
-
|
|
964
|
+
### Ze zdrojových kódů
|
|
949
965
|
|
|
950
|
-
|
|
966
|
+
#### 1. Stažení
|
|
951
967
|
|
|
952
|
-
**
|
|
968
|
+
**Pomocí git:**
|
|
953
969
|
```bash
|
|
954
970
|
git clone https://github.com/brnt-cz/todocko-mcp.git
|
|
955
971
|
cd todocko-mcp
|
|
956
972
|
```
|
|
957
973
|
|
|
958
|
-
**
|
|
974
|
+
**Nebo stáhněte ZIP** z [Releases](https://github.com/brnt-cz/todocko-mcp/releases) a rozbalte.
|
|
959
975
|
|
|
960
|
-
|
|
976
|
+
#### 2. Spuštění instalátoru
|
|
961
977
|
|
|
962
978
|
**Linux/macOS:**
|
|
963
979
|
```bash
|
|
@@ -970,546 +986,641 @@ chmod +x install.sh
|
|
|
970
986
|
.\install.ps1
|
|
971
987
|
```
|
|
972
988
|
|
|
973
|
-
|
|
974
|
-
1.
|
|
975
|
-
2.
|
|
976
|
-
3.
|
|
977
|
-
4. **
|
|
978
|
-
5.
|
|
989
|
+
Instalátor:
|
|
990
|
+
1. Nainstaluje závislosti a sestaví projekt
|
|
991
|
+
2. Zeptá se, zda chcete nakonfigurovat Claude Desktop, Claude Code nebo obojí
|
|
992
|
+
3. Vytvoří konfigurační soubor s placeholderem
|
|
993
|
+
4. **Ručně doplňte** svou 24slovnou zálohovací frázi do konfiguračního souboru
|
|
994
|
+
5. Restartujte Claude
|
|
979
995
|
|
|
980
|
-
|
|
996
|
+
#### Manuální instalace
|
|
981
997
|
|
|
982
|
-
1.
|
|
998
|
+
1. Nainstalujte závislosti:
|
|
983
999
|
```bash
|
|
984
1000
|
npm install
|
|
985
1001
|
npm run build
|
|
986
1002
|
```
|
|
987
1003
|
|
|
988
|
-
2.
|
|
1004
|
+
2. Přidejte do konfigurace:
|
|
989
1005
|
|
|
990
|
-
**Claude Desktop** (`~/.config/Claude/claude_desktop_config.json`
|
|
1006
|
+
**Claude Desktop** (`~/.config/Claude/claude_desktop_config.json` na Linuxu nebo `~/Library/Application Support/Claude/claude_desktop_config.json` na macOS):
|
|
991
1007
|
|
|
992
1008
|
```json
|
|
993
1009
|
{
|
|
994
1010
|
"mcpServers": {
|
|
995
1011
|
"todocko": {
|
|
996
1012
|
"command": "node",
|
|
997
|
-
"args": ["/
|
|
1013
|
+
"args": ["/cesta/k/mcp-server/dist/index.js"],
|
|
998
1014
|
"env": {
|
|
999
|
-
"TODOCKO_MNEMONIC": "
|
|
1015
|
+
"TODOCKO_MNEMONIC": "vaše 24slovná zálohovací fráze"
|
|
1000
1016
|
}
|
|
1001
1017
|
}
|
|
1002
1018
|
}
|
|
1003
1019
|
}
|
|
1004
1020
|
```
|
|
1005
1021
|
|
|
1006
|
-
**Claude Code (CLI)** -
|
|
1022
|
+
**Claude Code (CLI)** - přidejte do `~/.claude/settings.json`:
|
|
1007
1023
|
|
|
1008
1024
|
```json
|
|
1009
1025
|
{
|
|
1010
1026
|
"mcpServers": {
|
|
1011
1027
|
"todocko": {
|
|
1012
1028
|
"command": "node",
|
|
1013
|
-
"args": ["/
|
|
1029
|
+
"args": ["/cesta/k/mcp-server/dist/index.js"],
|
|
1014
1030
|
"env": {
|
|
1015
|
-
"TODOCKO_MNEMONIC": "
|
|
1031
|
+
"TODOCKO_MNEMONIC": "vaše 24slovná zálohovací fráze"
|
|
1016
1032
|
}
|
|
1017
1033
|
}
|
|
1018
1034
|
}
|
|
1019
1035
|
}
|
|
1020
1036
|
```
|
|
1021
1037
|
|
|
1022
|
-
3.
|
|
1038
|
+
3. Restartujte Claude Desktop / Claude Code
|
|
1023
1039
|
|
|
1024
|
-
##
|
|
1040
|
+
## Dostupné nástroje (161)
|
|
1025
1041
|
|
|
1026
|
-
###
|
|
1042
|
+
### Projekty
|
|
1027
1043
|
|
|
1028
|
-
|
|
|
1029
|
-
|
|
1030
|
-
| `td_list_projects` |
|
|
1031
|
-
| `td_get_project` |
|
|
1032
|
-
| `td_create_project` |
|
|
1033
|
-
| `td_update_project` |
|
|
1034
|
-
| `td_delete_project` |
|
|
1044
|
+
| Nástroj | Popis |
|
|
1045
|
+
|---------|-------|
|
|
1046
|
+
| `td_list_projects` | Seznam všech projektů |
|
|
1047
|
+
| `td_get_project` | Detail projektu podle ID nebo kódu |
|
|
1048
|
+
| `td_create_project` | Vytvoření nového projektu (kód jen `A-Z` a `0-9`, jako v appce) |
|
|
1049
|
+
| `td_update_project` | Aktualizace projektu (name, code, color, isArchived, isHiddenFromFilters; kód jen `A-Z` a `0-9`). `autoApproveMembers` patří sdílenému projektu, tady se odmítne, viz `td_update_shared_project` |
|
|
1050
|
+
| `td_delete_project` | Smazání projektu (soft delete) |
|
|
1035
1051
|
|
|
1036
|
-
###
|
|
1052
|
+
### Úkoly
|
|
1037
1053
|
|
|
1038
|
-
|
|
|
1039
|
-
|
|
1040
|
-
| `td_list_tasks` |
|
|
1041
|
-
| `td_get_task` |
|
|
1042
|
-
| `td_create_task` |
|
|
1043
|
-
| `td_update_task` |
|
|
1044
|
-
| `td_search_tasks` |
|
|
1045
|
-
| `td_bulk_update_tasks` |
|
|
1046
|
-
| `td_bulk_delete_tasks` |
|
|
1047
|
-
| `td_delete_task` |
|
|
1048
|
-
| `td_list_git_events` |
|
|
1054
|
+
| Nástroj | Popis |
|
|
1055
|
+
|---------|-------|
|
|
1056
|
+
| `td_list_tasks` | Seznam úkolů s filtry (projekt, status, priorita, assignee) |
|
|
1057
|
+
| `td_get_task` | Detail úkolu podle ID nebo kódu (např. `PROJ-123`), včetně nastavení opakování |
|
|
1058
|
+
| `td_create_task` | Vytvoření nového úkolu (včetně recurrence, sprintNumber, parentTaskId) |
|
|
1059
|
+
| `td_update_task` | Aktualizace existujícího úkolu (včetně recurrence, sprintNumber, parentTaskId) |
|
|
1060
|
+
| `td_search_tasks` | Vyhledávání úkolů podle textu |
|
|
1061
|
+
| `td_bulk_update_tasks` | Hromadná aktualizace více úkolů (včetně sprintNumber) |
|
|
1062
|
+
| `td_bulk_delete_tasks` | Hromadné smazání více úkolů |
|
|
1063
|
+
| `td_delete_task` | Smazání jednoho úkolu (soft delete, kaskáda na worklogy a přílohy) |
|
|
1064
|
+
| `td_list_git_events` | Git aktivita pro úkol (commits, PR) z relay serveru |
|
|
1049
1065
|
|
|
1050
|
-
###
|
|
1066
|
+
### Uživatelé
|
|
1051
1067
|
|
|
1052
|
-
|
|
|
1053
|
-
|
|
1054
|
-
| `td_list_users` |
|
|
1055
|
-
| `td_get_user` |
|
|
1056
|
-
| `td_create_user` |
|
|
1057
|
-
| `td_update_user` |
|
|
1058
|
-
| `td_delete_user` |
|
|
1068
|
+
| Nástroj | Popis |
|
|
1069
|
+
|---------|-------|
|
|
1070
|
+
| `td_list_users` | Seznam všech uživatelů |
|
|
1071
|
+
| `td_get_user` | Detail uživatele |
|
|
1072
|
+
| `td_create_user` | Vytvoření nového uživatele |
|
|
1073
|
+
| `td_update_user` | Aktualizace uživatele |
|
|
1074
|
+
| `td_delete_user` | Smazání uživatele (soft delete) |
|
|
1059
1075
|
|
|
1060
|
-
###
|
|
1076
|
+
### Worklogy
|
|
1061
1077
|
|
|
1062
|
-
|
|
|
1063
|
-
|
|
1064
|
-
| `td_list_worklogs` |
|
|
1065
|
-
| `td_add_worklog` |
|
|
1066
|
-
| `td_update_worklog` |
|
|
1067
|
-
| `td_delete_worklog` |
|
|
1078
|
+
| Nástroj | Popis |
|
|
1079
|
+
|---------|-------|
|
|
1080
|
+
| `td_list_worklogs` | Seznam worklogů pro úkol |
|
|
1081
|
+
| `td_add_worklog` | Přidání worklogu k úkolu |
|
|
1082
|
+
| `td_update_worklog` | Aktualizace worklogu |
|
|
1083
|
+
| `td_delete_worklog` | Smazání worklogu (soft delete) |
|
|
1068
1084
|
|
|
1069
|
-
###
|
|
1085
|
+
### Přílohy
|
|
1070
1086
|
|
|
1071
|
-
|
|
|
1072
|
-
|
|
1073
|
-
| `td_upload_attachment` |
|
|
1074
|
-
| `td_list_attachments` |
|
|
1075
|
-
| `td_download_attachment` |
|
|
1076
|
-
| `td_delete_attachment` |
|
|
1077
|
-
| `td_upload_note_attachment` |
|
|
1078
|
-
| `td_list_note_attachments` |
|
|
1079
|
-
| `td_download_note_attachment` |
|
|
1080
|
-
| `td_delete_note_attachment` |
|
|
1087
|
+
| Nástroj | Popis |
|
|
1088
|
+
|---------|-------|
|
|
1089
|
+
| `td_upload_attachment` | Nahrání přílohy k úkolu (ze souboru nebo base64) |
|
|
1090
|
+
| `td_list_attachments` | Seznam příloh úkolu |
|
|
1091
|
+
| `td_download_attachment` | Stažení přílohy |
|
|
1092
|
+
| `td_delete_attachment` | Smazání přílohy |
|
|
1093
|
+
| `td_upload_note_attachment` | Nahrání přílohy k lokální poznámce projektu |
|
|
1094
|
+
| `td_list_note_attachments` | Seznam příloh lokální poznámky |
|
|
1095
|
+
| `td_download_note_attachment` | Stažení přílohy poznámky |
|
|
1096
|
+
| `td_delete_note_attachment` | Smazání přílohy poznámky |
|
|
1081
1097
|
|
|
1082
|
-
###
|
|
1098
|
+
### Komentáře
|
|
1083
1099
|
|
|
1084
|
-
|
|
|
1085
|
-
|
|
1086
|
-
| `td_list_task_comments` |
|
|
1087
|
-
| `td_create_task_comment` |
|
|
1088
|
-
| `td_update_task_comment` |
|
|
1089
|
-
| `td_delete_task_comment` |
|
|
1100
|
+
| Nástroj | Popis |
|
|
1101
|
+
|---------|-------|
|
|
1102
|
+
| `td_list_task_comments` | Seznam komentářů k úkolu |
|
|
1103
|
+
| `td_create_task_comment` | Přidání komentáře k úkolu |
|
|
1104
|
+
| `td_update_task_comment` | Úprava komentáře |
|
|
1105
|
+
| `td_delete_task_comment` | Smazání komentáře (soft delete) |
|
|
1090
1106
|
|
|
1091
1107
|
### Checklist
|
|
1092
1108
|
|
|
1093
|
-
|
|
|
1094
|
-
|
|
1095
|
-
| `td_list_checklist_items` |
|
|
1096
|
-
| `td_create_checklist_item` |
|
|
1097
|
-
| `td_update_checklist_item` |
|
|
1098
|
-
| `td_delete_checklist_item` |
|
|
1109
|
+
| Nástroj | Popis |
|
|
1110
|
+
|---------|-------|
|
|
1111
|
+
| `td_list_checklist_items` | Seznam položek checklistu úkolu |
|
|
1112
|
+
| `td_create_checklist_item` | Přidání položky checklistu |
|
|
1113
|
+
| `td_update_checklist_item` | Aktualizace položky (zaškrtnutí, pozice) |
|
|
1114
|
+
| `td_delete_checklist_item` | Smazání položky (soft delete) |
|
|
1099
1115
|
|
|
1100
|
-
###
|
|
1116
|
+
### Zmínky (mentions)
|
|
1101
1117
|
|
|
1102
|
-
|
|
|
1103
|
-
|
|
1104
|
-
| `td_list_mentions` |
|
|
1105
|
-
| `td_create_mention` |
|
|
1106
|
-
| `td_mark_mention_read` |
|
|
1107
|
-
| `td_mark_all_mentions_read` |
|
|
1108
|
-
| `td_delete_mention` |
|
|
1118
|
+
| Nástroj | Popis |
|
|
1119
|
+
|---------|-------|
|
|
1120
|
+
| `td_list_mentions` | Seznam zmínek uživatele |
|
|
1121
|
+
| `td_create_mention` | Vytvoření zmínky |
|
|
1122
|
+
| `td_mark_mention_read` | Označení zmínky jako přečtené |
|
|
1123
|
+
| `td_mark_all_mentions_read` | Označení všech zmínek jako přečtených |
|
|
1124
|
+
| `td_delete_mention` | Smazání zmínky (soft delete) |
|
|
1109
1125
|
|
|
1110
|
-
###
|
|
1126
|
+
### Linky mezi úkoly
|
|
1111
1127
|
|
|
1112
|
-
|
|
|
1113
|
-
|
|
1114
|
-
| `td_list_app_settings` |
|
|
1115
|
-
| `td_set_app_setting` |
|
|
1116
|
-
| `td_list_task_links` |
|
|
1117
|
-
| `td_create_task_link` |
|
|
1118
|
-
| `td_delete_task_link` |
|
|
1128
|
+
| Nástroj | Popis |
|
|
1129
|
+
|---------|-------|
|
|
1130
|
+
| `td_list_app_settings` | Nastavení účtu, která se přenášejí mezi zařízeními |
|
|
1131
|
+
| `td_set_app_setting` | Nastavení jedné hodnoty na účtu |
|
|
1132
|
+
| `td_list_task_links` | Seznam linků úkolu |
|
|
1133
|
+
| `td_create_task_link` | Vytvoření linku mezi úkoly (`blocks`, `explicit`, `mention`, `relates`, `duplicate`) |
|
|
1134
|
+
| `td_delete_task_link` | Smazání linku (soft delete) |
|
|
1119
1135
|
|
|
1120
|
-
###
|
|
1136
|
+
### Tagy
|
|
1121
1137
|
|
|
1122
|
-
|
|
|
1123
|
-
|
|
1124
|
-
| `td_list_tags` |
|
|
1125
|
-
| `td_create_tag` |
|
|
1126
|
-
| `td_update_tag` |
|
|
1127
|
-
| `td_delete_tag` |
|
|
1128
|
-
| `td_list_task_tags` |
|
|
1129
|
-
| `td_add_tag_to_task` |
|
|
1130
|
-
| `td_remove_tag_from_task` |
|
|
1138
|
+
| Nástroj | Popis |
|
|
1139
|
+
|---------|-------|
|
|
1140
|
+
| `td_list_tags` | Seznam štítků; vrací `projectId`, umí filtrovat podle projektu i na nezařazené |
|
|
1141
|
+
| `td_create_tag` | Vytvoření štítku – **předej `projectId`**, viz poznámku níž |
|
|
1142
|
+
| `td_update_tag` | Přejmenování, změna barvy, přiřazení projektu, nebo příznak výchozího štítku |
|
|
1143
|
+
| `td_delete_tag` | Smazání štítku (soft delete) |
|
|
1144
|
+
| `td_list_task_tags` | Seznam štítků přiřazených k úkolu |
|
|
1145
|
+
| `td_add_tag_to_task` | Přiřazení štítku k úkolu |
|
|
1146
|
+
| `td_remove_tag_from_task` | Odebrání štítku z úkolu |
|
|
1131
1147
|
|
|
1132
|
-
|
|
1148
|
+
Sdílené projekty (TODO-235):
|
|
1133
1149
|
|
|
1134
|
-
|
|
|
1135
|
-
|
|
1136
|
-
| `td_list_shared_tags` |
|
|
1137
|
-
| `td_create_shared_tag` |
|
|
1138
|
-
| `td_update_shared_tag` |
|
|
1139
|
-
| `td_delete_shared_tag` |
|
|
1140
|
-
| `td_add_shared_tag_to_task` |
|
|
1141
|
-
| `td_remove_shared_tag_from_task` |
|
|
1150
|
+
| Nástroj | Popis |
|
|
1151
|
+
|---------|-------|
|
|
1152
|
+
| `td_list_shared_tags` | Štítky ve sdíleném projektu |
|
|
1153
|
+
| `td_create_shared_tag` | Vytvoření štítku ve sdíleném projektu |
|
|
1154
|
+
| `td_update_shared_tag` | Přejmenování / změna barvy / příznak výchozího štítku |
|
|
1155
|
+
| `td_delete_shared_tag` | Smazání (soft delete) |
|
|
1156
|
+
| `td_add_shared_tag_to_task` | Přiřazení k úkolu ve sdíleném projektu |
|
|
1157
|
+
| `td_remove_shared_tag_from_task` | Odebrání z úkolu |
|
|
1142
1158
|
|
|
1143
|
-
>
|
|
1144
|
-
>
|
|
1145
|
-
>
|
|
1146
|
-
>
|
|
1147
|
-
>
|
|
1159
|
+
> **Štítek bez projektu appka nikde nenabídne.** Od TODO-227 jsou štítky vázané
|
|
1160
|
+
> na projekt; `td_create_tag` bez `projectId` vyrobí **nezařazený** štítek, který
|
|
1161
|
+
> se v appce objeví jen v nastavení projektu v sekci „Nezařazené" s tlačítkem na
|
|
1162
|
+
> přiřazení. Odpověď nástroje na to upozorní. Dodatečně to spraví
|
|
1163
|
+
> `td_update_tag` s `projectId`.
|
|
1148
1164
|
>
|
|
1149
|
-
> **
|
|
1150
|
-
> `td_create_task`
|
|
1151
|
-
>
|
|
1152
|
-
>
|
|
1153
|
-
>
|
|
1154
|
-
>
|
|
1155
|
-
>
|
|
1165
|
+
> **Limity free tarifu (TODO-243).** Tarifní limity patří do appky, ne sem.
|
|
1166
|
+
> `td_create_task` a `td_create_project` proto do odpovědi přilepí varování
|
|
1167
|
+
> s reálným počtem, když je owner na free tarifu a je nad limitem (1 projekt,
|
|
1168
|
+
> 50 **aktivních** úkolů). Jde o to, aby se to člověk dozvěděl při zakládání, ne až
|
|
1169
|
+
> zpětně v appce, a aby z textu bylo jasné, že o nic nepřišel. **Nic to neblokuje**
|
|
1170
|
+
> a při neznámém tarifu (nedostupný relay) radši mlčí – falešný poplach je horší
|
|
1171
|
+
> než žádný.
|
|
1156
1172
|
|
|
1157
|
-
> **
|
|
1158
|
-
> (
|
|
1159
|
-
>
|
|
1160
|
-
>
|
|
1161
|
-
>
|
|
1173
|
+
> **Výchozí štítky (TODO-239).** `isDefault` u `td_create_tag` / `td_update_tag`
|
|
1174
|
+
> (a sdílených variant) znamená, že štítek dostane **každý nově zakládaný úkol**
|
|
1175
|
+
> projektu. `td_create_task` i `td_create_shared_task` je přidávají samy a vrátí
|
|
1176
|
+
> je v `appliedTags` – appka je předzaškrtává v modalu, takže bez toho by výsledek
|
|
1177
|
+
> závisel na tom, odkud úkol vznikne. Existujících úkolů se to nedotkne.
|
|
1162
1178
|
>
|
|
1163
|
-
>
|
|
1164
|
-
>
|
|
1179
|
+
> Ve sdílených projektech se zapisuje do **jiné Evolu instance**, proto samostatná
|
|
1180
|
+
> sada nástrojů – `td_add_tag_to_task` na sdílený úkol nefunguje.
|
|
1165
1181
|
|
|
1166
|
-
###
|
|
1182
|
+
### Šablony úkolů
|
|
1167
1183
|
|
|
1168
|
-
|
|
|
1169
|
-
|
|
1170
|
-
| `td_list_task_templates` |
|
|
1171
|
-
| `td_create_task_template` |
|
|
1172
|
-
| `td_update_task_template` |
|
|
1173
|
-
| `td_delete_task_template` |
|
|
1184
|
+
| Nástroj | Popis |
|
|
1185
|
+
|---------|-------|
|
|
1186
|
+
| `td_list_task_templates` | Seznam šablon úkolů |
|
|
1187
|
+
| `td_create_task_template` | Vytvoření šablony (volitelně `checklistItems` a `tagIds`) |
|
|
1188
|
+
| `td_update_task_template` | Aktualizace šablony (`checklistItems`, `tagIds`; prázdné pole maže) |
|
|
1189
|
+
| `td_delete_task_template` | Smazání šablony (soft delete) |
|
|
1190
|
+
|
|
1191
|
+
### Kanban sloupce
|
|
1192
|
+
|
|
1193
|
+
| Nástroj | Popis |
|
|
1194
|
+
|---------|-------|
|
|
1195
|
+
| `td_list_kanban_columns` | Seznam kanban sloupců |
|
|
1196
|
+
| `td_create_kanban_column` | Vytvoření sloupce (volitelně `wipLimit`, max. úkolů na uživatele v In progress před varováním v hlavičce) |
|
|
1197
|
+
| `td_update_kanban_column` | Aktualizace sloupce (`wipLimit: null` limit zruší) |
|
|
1198
|
+
| `td_delete_kanban_column` | Smazání sloupce (soft delete) |
|
|
1174
1199
|
|
|
1175
|
-
###
|
|
1200
|
+
### Uložená zobrazení
|
|
1176
1201
|
|
|
1177
|
-
|
|
|
1178
|
-
|
|
1179
|
-
| `
|
|
1180
|
-
| `
|
|
1181
|
-
| `
|
|
1182
|
-
| `
|
|
1202
|
+
| Nástroj | Popis |
|
|
1203
|
+
|---------|-------|
|
|
1204
|
+
| `td_list_saved_views` | Seznam uložených zobrazení |
|
|
1205
|
+
| `td_create_saved_view` | Vytvoření zobrazení |
|
|
1206
|
+
| `td_update_saved_view` | Aktualizace zobrazení |
|
|
1207
|
+
| `td_delete_saved_view` | Smazání zobrazení (soft delete) |
|
|
1183
1208
|
|
|
1184
|
-
###
|
|
1209
|
+
### Aktivita
|
|
1185
1210
|
|
|
1186
|
-
|
|
|
1187
|
-
|
|
1188
|
-
| `
|
|
1189
|
-
| `td_create_saved_view` | Create a saved view |
|
|
1190
|
-
| `td_update_saved_view` | Update a saved view |
|
|
1191
|
-
| `td_delete_saved_view` | Delete a saved view (soft delete) |
|
|
1211
|
+
| Nástroj | Popis |
|
|
1212
|
+
|---------|-------|
|
|
1213
|
+
| `td_list_activity_log` | Seznam zápisů aktivity s filtry (úkol, aktor, akce, typ entity, datum od/do) – read-only |
|
|
1192
1214
|
|
|
1193
|
-
###
|
|
1215
|
+
### Poznámky k projektu
|
|
1194
1216
|
|
|
1195
|
-
|
|
|
1196
|
-
|
|
1197
|
-
| `
|
|
1217
|
+
| Nástroj | Popis |
|
|
1218
|
+
|---------|-------|
|
|
1219
|
+
| `td_list_project_notes` | Seznam lokálních poznámek projektu (rejstřík: titulek a `contentLength`, obsah až na `includeContent`) |
|
|
1220
|
+
| `td_get_project_note` | Jedna lokální poznámka včetně obsahu |
|
|
1221
|
+
| `td_create_project_note` | Vytvoření lokální poznámky |
|
|
1222
|
+
| `td_update_project_note` | Aktualizace lokální poznámky |
|
|
1223
|
+
| `td_delete_project_note` | Smazání lokální poznámky (soft delete) |
|
|
1198
1224
|
|
|
1199
|
-
###
|
|
1225
|
+
### Dokumentace projektu
|
|
1200
1226
|
|
|
1201
|
-
|
|
1202
|
-
|
|
1203
|
-
| `td_list_project_notes` | List local project notes (index: title and `contentLength`; content via `includeContent`) |
|
|
1204
|
-
| `td_get_project_note` | Read one local project note, with its content |
|
|
1205
|
-
| `td_create_project_note` | Create a local project note |
|
|
1206
|
-
| `td_update_project_note` | Update a local project note |
|
|
1207
|
-
| `td_delete_project_note` | Delete a local project note (soft delete) |
|
|
1227
|
+
Dokumenty jsou poznámky s `isDoc`, takže mohou být zanořené pod jiný dokument
|
|
1228
|
+
(`parentDocId`).
|
|
1208
1229
|
|
|
1209
|
-
|
|
1230
|
+
| Nástroj | Popis |
|
|
1231
|
+
|---------|-------|
|
|
1232
|
+
| `td_list_project_docs` | Seznam dokumentů projektu (rejstřík: titulek, hierarchie a `contentLength`, obsah až na `includeContent`) |
|
|
1233
|
+
| `td_get_project_doc` | Jedna stránka dokumentace včetně obsahu |
|
|
1234
|
+
| `td_create_project_doc` | Vytvoření dokumentu |
|
|
1235
|
+
| `td_update_project_doc` | Aktualizace dokumentu |
|
|
1236
|
+
| `td_delete_project_doc` | Smazání dokumentu (soft delete) |
|
|
1210
1237
|
|
|
1211
|
-
|
|
1212
|
-
|------|-------------|
|
|
1213
|
-
| `td_list_deployment_stages` | List deployment stages for a project |
|
|
1214
|
-
| `td_create_deployment_stage` | Create a deployment stage for a personal project. |
|
|
1215
|
-
| `td_update_deployment_stage` | Update a deployment stage in a personal project. |
|
|
1216
|
-
| `td_delete_deployment_stage` | Soft-delete a deployment stage in a personal project. |
|
|
1238
|
+
### Systémová oznámení (relay)
|
|
1217
1239
|
|
|
1218
|
-
|
|
1240
|
+
Broadcast oznámení pro všechny uživatele. Zápis a výpis včetně expirovaných
|
|
1241
|
+
vyžaduje `TODOCKO_RELAY_ADMIN_KEY`; obráceným směrem jdou zprávy od uživatelů,
|
|
1242
|
+
viz níž.
|
|
1219
1243
|
|
|
1220
|
-
|
|
1221
|
-
|
|
1222
|
-
|
|
1223
|
-
|
|
1224
|
-
| `td_delete_repository_link` | Delete a repository link |
|
|
1225
|
-
| `td_update_repository_link` | Update a repository link for a project. |
|
|
1244
|
+
Bez `TODOCKO_RELAY_ADMIN_KEY` se `td_create_system_notification`
|
|
1245
|
+
a `td_delete_system_notification` klientovi vůbec nenabízejí (nemohly by nic
|
|
1246
|
+
jiného než vrátit 401) a u výpisu zmizí přepínač `admin`. Klíč se navíc nikdy
|
|
1247
|
+
neposílá přes nešifrované `http://` jinam než na localhost. (TODO-441)
|
|
1226
1248
|
|
|
1227
|
-
|
|
1249
|
+
| Nástroj | Popis |
|
|
1250
|
+
|---------|-------|
|
|
1251
|
+
| `td_list_system_notifications` | Seznam aktivních oznámení (s `admin: true` i expirovaná) |
|
|
1252
|
+
| `td_create_system_notification` | Vytvoření oznámení pro všechny uživatele |
|
|
1253
|
+
| `td_delete_system_notification` | Smazání oznámení |
|
|
1228
1254
|
|
|
1229
|
-
|
|
1230
|
-
|------|-------------|
|
|
1231
|
-
| `td_list_shared_projects` | List shared projects with your permission (no longer returns `ownerSecret`) |
|
|
1232
|
-
| `td_list_shared_tasks` | List tasks from a shared project |
|
|
1233
|
-
| `td_update_shared_task` | Update a task in a shared project |
|
|
1234
|
-
| `td_list_shared_deployment_stages` | List deployment stages for a shared project |
|
|
1235
|
-
| `td_create_shared_deployment_stage` | Create a deployment stage in a shared project |
|
|
1236
|
-
| `td_list_shared_repository_links` | List repository links for a shared project |
|
|
1237
|
-
| `td_create_shared_repository_link` | Create a repository link in a shared project |
|
|
1238
|
-
| `td_list_shared_project_notes` | List notes for a shared project (index; content via `includeContent`) |
|
|
1239
|
-
| `td_get_shared_project_note` | Read one note from a shared project, with its content |
|
|
1240
|
-
| `td_create_shared_project_note` | Create a note in a shared project |
|
|
1241
|
-
| `td_update_shared_project_note` | Update a note in a shared project |
|
|
1242
|
-
| `td_delete_shared_project_note` | Delete a note in a shared project |
|
|
1243
|
-
| `td_list_shared_members` | List members of a shared project (name, permission, kicked/blocked state, `isPending` = waiting for approval). The owner also gets `verifiedPermission` (what they granted) and `effectivePermission` (the lower of the two, which decides the write key) |
|
|
1244
|
-
| `td_update_shared_member` | Admin only. Change permission between `write` and `admin`, approve a pending join or unblock (only while the project has no rotated write key); refuses block, kick, reject and downgrade to `read`, which belong in the app. A permission set by the owner is also recorded as their `memberGrant`, which is what hands out the write key; an admin who does not own the project changes only the member's claim |
|
|
1245
|
-
| `td_upload_shared_note_attachment` | Upload an attachment to a shared project note |
|
|
1246
|
-
| `td_list_shared_note_attachments` | List attachments of a shared project note |
|
|
1247
|
-
| `td_download_shared_note_attachment` | Download a shared note attachment |
|
|
1248
|
-
| `td_delete_shared_note_attachment` | Delete a shared note attachment |
|
|
1249
|
-
| `td_list_shared_project_docs` | List document pages from a shared project (index; content via `includeContent`) |
|
|
1250
|
-
| `td_get_shared_project_doc` | Read one document page from a shared project, with its content |
|
|
1251
|
-
| `td_create_shared_project_doc` | Create a document page in a shared project |
|
|
1252
|
-
| `td_update_shared_project_doc` | Update a document page in a shared project |
|
|
1253
|
-
| `td_delete_shared_project_doc` | Delete a document page in a shared project (soft delete) |
|
|
1254
|
-
| `td_create_shared_task` | Create a task in a shared project. |
|
|
1255
|
-
| `td_delete_shared_task` | Soft-delete a task in a shared project (cascades to its checklist items and comments). |
|
|
1256
|
-
| `td_list_shared_worklogs` | List worklogs for a task in a shared project. |
|
|
1257
|
-
| `td_add_shared_worklog` | Add a worklog to a task in a shared project. |
|
|
1258
|
-
| `td_delete_shared_worklog` | Soft-delete a worklog in a shared project. |
|
|
1259
|
-
| `td_list_shared_checklist_items` | List checklist items for a task in a shared project. |
|
|
1260
|
-
| `td_create_shared_checklist_item` | Create a checklist item on a task in a shared project. |
|
|
1261
|
-
| `td_update_shared_checklist_item` | Update a checklist item in a shared project (toggle done, rename, reorder). |
|
|
1262
|
-
| `td_delete_shared_checklist_item` | Soft-delete a checklist item in a shared project. |
|
|
1263
|
-
| `td_list_shared_task_links` | List dependency links for a task in a shared project. |
|
|
1264
|
-
| `td_create_shared_task_link` | Create a dependency link between tasks in a shared project. |
|
|
1265
|
-
| `td_delete_shared_task_link` | Delete a dependency link in a shared project (soft delete). |
|
|
1266
|
-
| `td_list_shared_task_comments` | List comments for a task in a shared project. |
|
|
1267
|
-
| `td_create_shared_task_comment` | Add a comment to a task in a shared project. |
|
|
1268
|
-
| `td_update_shared_task_comment` | Update a comment in a shared project. |
|
|
1269
|
-
| `td_delete_shared_task_comment` | Soft-delete a comment in a shared project. |
|
|
1270
|
-
| `td_update_shared_repository_link` | Update a repository link in a shared project. |
|
|
1271
|
-
| `td_delete_shared_repository_link` | Soft-delete a repository link in a shared project. |
|
|
1272
|
-
| `td_update_shared_deployment_stage` | Update a deployment stage in a shared project. |
|
|
1273
|
-
| `td_delete_shared_deployment_stage` | Soft-delete a deployment stage in a shared project. |
|
|
1274
|
-
| `td_update_shared_project` | Update shared-project metadata (archive / hide from filters). |
|
|
1275
|
-
| `td_upload_shared_attachment` | Upload a file attachment to a task in a shared project. |
|
|
1276
|
-
| `td_list_shared_attachments` | List file attachments of a task in a shared project (metadata only, no data). |
|
|
1277
|
-
| `td_download_shared_attachment` | Download a task attachment from a shared project. |
|
|
1278
|
-
| `td_delete_shared_attachment` | Soft-delete a task attachment in a shared project. |
|
|
1279
|
-
| `td_get_shared_task` | Get one task in a shared project by ID or code, with its worklog total, checklist and comment counts. |
|
|
1280
|
-
| `td_list_shared_task_tags` | List the tags on a task in a shared project. |
|
|
1281
|
-
| `td_bulk_update_shared_tasks` | Update several tasks in a shared project at once. |
|
|
1282
|
-
| `td_bulk_delete_shared_tasks` | Soft-delete several tasks in a shared project at once, cascading their checklist items and comments. |
|
|
1283
|
-
| `td_update_shared_worklog` | Update a worklog in a shared project. |
|
|
1284
|
-
| `td_list_shared_activity_log` | List activity log entries for a shared project. |
|
|
1255
|
+
### Deployment stages
|
|
1285
1256
|
|
|
1286
|
-
|
|
1287
|
-
|
|
1288
|
-
|
|
1289
|
-
|
|
1290
|
-
|
|
1291
|
-
|
|
1292
|
-
> and is checked against `sharedOwnerId`.
|
|
1293
|
-
> - **Writes are gated by permission, as in the app** (`src/permissions.ts`, a
|
|
1294
|
-
> port of the app's `permissions.ts`). Tasks, worklogs, checklist items,
|
|
1295
|
-
> comments, attachments, links, tag assignment, notes and documents need
|
|
1296
|
-
> `write` or `admin`. Project settings (`td_update_shared_project`, delete and
|
|
1297
|
-
> restore included), deployment stages, repository links, tag management and
|
|
1298
|
-
> members need the owner or `admin`. Without a `projectRef` writes are
|
|
1299
|
-
> refused, reads still work. A refusal is an error and nothing is written.
|
|
1300
|
-
> - **Member management is partial.** After every member change the app rotates
|
|
1301
|
-
> the write key or hands the current one over, otherwise a blocked member keeps
|
|
1302
|
-
> writing. The MCP cannot rotate, so changes that leave the member unable to
|
|
1303
|
-
> write (block, kick, reject, downgrade to `read`) are refused with a pointer
|
|
1304
|
-
> to the app. Approving, unblocking and upgrading pass only while the project
|
|
1305
|
-
> has no rotated write key.
|
|
1306
|
-
> - **Shared writes record history** in the shared instance, the same entries
|
|
1307
|
-
> the app writes (task created / updated per field / deleted, worklog,
|
|
1308
|
-
> checklist, comment, attachment, tag, stage, repository link, project,
|
|
1309
|
-
> member), with your account as `actorId` and `source: "mcp"` in metadata.
|
|
1310
|
-
> - **Deleting an unknown id** is an error instead of `success`, and bulk delete
|
|
1311
|
-
> counts it as skipped. `td_update_shared_project` picks the project row the
|
|
1312
|
-
> way the app does (oldest live row) and can restore it from the Trash.
|
|
1313
|
-
> - **Project codes** may contain only `A-Z` and `0-9`, and concurrent
|
|
1314
|
-
> `td_create_task` / `td_create_shared_task` calls for one project no longer
|
|
1315
|
-
> get the same code.
|
|
1257
|
+
| Nástroj | Popis |
|
|
1258
|
+
|---------|-------|
|
|
1259
|
+
| `td_list_deployment_stages` | Seznam deployment stages pro projekt |
|
|
1260
|
+
| `td_create_deployment_stage` | Vytvoření deployment stage |
|
|
1261
|
+
| `td_update_deployment_stage` | Aktualizace deployment stage |
|
|
1262
|
+
| `td_delete_deployment_stage` | Smazání deployment stage (soft delete) |
|
|
1316
1263
|
|
|
1317
|
-
###
|
|
1264
|
+
### Repository linky
|
|
1318
1265
|
|
|
1319
|
-
|
|
1266
|
+
| Nástroj | Popis |
|
|
1267
|
+
|---------|-------|
|
|
1268
|
+
| `td_list_repository_links` | Seznam repozitářových linků |
|
|
1269
|
+
| `td_create_repository_link` | Vytvoření repozitářového linku |
|
|
1270
|
+
| `td_update_repository_link` | Aktualizace repozitářového linku |
|
|
1271
|
+
| `td_delete_repository_link` | Smazání repozitářového linku |
|
|
1320
1272
|
|
|
1321
|
-
|
|
1322
|
-
|------|-------------|
|
|
1323
|
-
| `td_list_project_docs` | List local project document pages (index: title, hierarchy and `contentLength`; content via `includeContent`) |
|
|
1324
|
-
| `td_get_project_doc` | Read one local project document page, with its content |
|
|
1325
|
-
| `td_create_project_doc` | Create a local project document page |
|
|
1326
|
-
| `td_update_project_doc` | Update a local project document page |
|
|
1327
|
-
| `td_delete_project_doc` | Delete a local project document page (soft delete) |
|
|
1273
|
+
### Sdílené projekty
|
|
1328
1274
|
|
|
1329
|
-
|
|
1275
|
+
| Nástroj | Popis |
|
|
1276
|
+
|---------|-------|
|
|
1277
|
+
| `td_list_shared_projects` | Seznam sdílených projektů s vaším oprávněním (`ownerSecret` už nevrací) |
|
|
1278
|
+
| `td_list_shared_tasks` | Seznam úkolů ze sdíleného projektu |
|
|
1279
|
+
| `td_create_shared_task` | Vytvoření úkolu ve sdíleném projektu (auto-generovaný kód) |
|
|
1280
|
+
| `td_update_shared_task` | Aktualizace úkolu ve sdíleném projektu (všechna pole včetně recurrence, estimate, blocking) |
|
|
1281
|
+
| `td_delete_shared_task` | Smazání úkolu ve sdíleném projektu (soft delete, kaskáda na checklist) |
|
|
1282
|
+
| `td_update_shared_project` | Aktualizace sdíleného projektu: název, kód, barva, archivace, skrytí z filtrů, automatické schvalování členů |
|
|
1283
|
+
| `td_list_shared_worklogs` | Seznam worklogů úkolu ve sdíleném projektu |
|
|
1284
|
+
| `td_add_shared_worklog` | Přidání worklogu k úkolu ve sdíleném projektu |
|
|
1285
|
+
| `td_delete_shared_worklog` | Smazání worklogu ve sdíleném projektu |
|
|
1286
|
+
| `td_list_shared_checklist_items` | Seznam položek checklistu úkolu ve sdíleném projektu |
|
|
1287
|
+
| `td_create_shared_checklist_item` | Přidání položky checklistu ve sdíleném projektu |
|
|
1288
|
+
| `td_update_shared_checklist_item` | Aktualizace položky checklistu ve sdíleném projektu |
|
|
1289
|
+
| `td_delete_shared_checklist_item` | Smazání položky checklistu ve sdíleném projektu |
|
|
1290
|
+
| `td_list_shared_task_links` | Seznam vazeb úkolu ve sdíleném projektu |
|
|
1291
|
+
| `td_create_shared_task_link` | Vytvoření vazby mezi úkoly ve sdíleném projektu |
|
|
1292
|
+
| `td_delete_shared_task_link` | Smazání vazby ve sdíleném projektu (soft delete) |
|
|
1293
|
+
| `td_list_shared_task_comments` | Seznam komentářů úkolu ve sdíleném projektu |
|
|
1294
|
+
| `td_create_shared_task_comment` | Přidání komentáře k úkolu ve sdíleném projektu |
|
|
1295
|
+
| `td_update_shared_task_comment` | Aktualizace komentáře ve sdíleném projektu |
|
|
1296
|
+
| `td_delete_shared_task_comment` | Smazání komentáře ve sdíleném projektu |
|
|
1297
|
+
| `td_upload_shared_attachment` | Nahrání přílohy k úkolu ve sdíleném projektu |
|
|
1298
|
+
| `td_list_shared_attachments` | Seznam příloh úkolu ve sdíleném projektu |
|
|
1299
|
+
| `td_download_shared_attachment` | Stažení přílohy úkolu sdíleného projektu |
|
|
1300
|
+
| `td_delete_shared_attachment` | Smazání přílohy úkolu sdíleného projektu |
|
|
1301
|
+
| `td_list_shared_deployment_stages` | Seznam deployment stages pro sdílený projekt |
|
|
1302
|
+
| `td_create_shared_deployment_stage` | Vytvoření deployment stage ve sdíleném projektu |
|
|
1303
|
+
| `td_update_shared_deployment_stage` | Aktualizace deployment stage ve sdíleném projektu |
|
|
1304
|
+
| `td_delete_shared_deployment_stage` | Smazání deployment stage ve sdíleném projektu |
|
|
1305
|
+
| `td_list_shared_repository_links` | Seznam repozitářových linků sdíleného projektu |
|
|
1306
|
+
| `td_create_shared_repository_link` | Vytvoření repozitářového linku ve sdíleném projektu |
|
|
1307
|
+
| `td_update_shared_repository_link` | Aktualizace repozitářového linku ve sdíleném projektu |
|
|
1308
|
+
| `td_delete_shared_repository_link` | Smazání repozitářového linku ve sdíleném projektu |
|
|
1309
|
+
| `td_list_shared_project_notes` | Seznam poznámek sdíleného projektu (rejstřík, obsah až na `includeContent`) |
|
|
1310
|
+
| `td_get_shared_project_note` | Jedna poznámka sdíleného projektu včetně obsahu |
|
|
1311
|
+
| `td_create_shared_project_note` | Vytvoření poznámky ve sdíleném projektu |
|
|
1312
|
+
| `td_update_shared_project_note` | Aktualizace poznámky ve sdíleném projektu |
|
|
1313
|
+
| `td_delete_shared_project_note` | Smazání poznámky ve sdíleném projektu |
|
|
1314
|
+
| `td_list_shared_members` | Seznam členů sdíleného projektu (jméno, oprávnění, kicked/blocked stav, `isPending` = čeká na schválení). Vlastníkovi navíc `verifiedPermission` (co udělil) a `effectivePermission` (to nižší z obojího, rozhoduje o write key) |
|
|
1315
|
+
| `td_update_shared_member` | Jen admin. Změna oprávnění mezi `write` a `admin`, schválení čekajícího nebo odblokování (jen dokud projekt nemá rotovaný klíč); block, kick, zamítnutí a snížení na `read` odmítne, ty patří do appky. Oprávnění nastavené vlastníkem se zapíše i jako jeho `memberGrant`, což teprve rozdává write key; admin bez vlastnictví změní jen členův nárok |
|
|
1316
|
+
| `td_upload_shared_note_attachment` | Nahrání přílohy k poznámce sdíleného projektu |
|
|
1317
|
+
| `td_list_shared_note_attachments` | Seznam příloh poznámky sdíleného projektu |
|
|
1318
|
+
| `td_download_shared_note_attachment` | Stažení přílohy poznámky sdíleného projektu |
|
|
1319
|
+
| `td_delete_shared_note_attachment` | Smazání přílohy poznámky sdíleného projektu |
|
|
1320
|
+
| `td_list_shared_project_docs` | Seznam dokumentů sdíleného projektu (rejstřík, obsah až na `includeContent`) |
|
|
1321
|
+
| `td_get_shared_project_doc` | Jedna stránka dokumentace sdíleného projektu včetně obsahu |
|
|
1322
|
+
| `td_create_shared_project_doc` | Vytvoření dokumentu ve sdíleném projektu |
|
|
1323
|
+
| `td_update_shared_project_doc` | Aktualizace dokumentu ve sdíleném projektu |
|
|
1324
|
+
| `td_delete_shared_project_doc` | Smazání dokumentu ve sdíleném projektu |
|
|
1325
|
+
| `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ářů) |
|
|
1326
|
+
| `td_list_shared_task_tags` | Tagy úkolu ve sdíleném projektu |
|
|
1327
|
+
| `td_bulk_update_shared_tasks` | Hromadná úprava úkolů ve sdíleném projektu |
|
|
1328
|
+
| `td_bulk_delete_shared_tasks` | Hromadné smazání úkolů ve sdíleném projektu (kaskáda na checklist a komentáře) |
|
|
1329
|
+
| `td_update_shared_worklog` | Úprava worklogu ve sdíleném projektu |
|
|
1330
|
+
| `td_list_shared_activity_log` | Aktivita ve sdíleném projektu (stejné filtry jako u osobní) |
|
|
1331
|
+
|
|
1332
|
+
> **Oprávnění, `ownerSecret` a historie ve sdílených projektech (TODO-434).**
|
|
1333
|
+
>
|
|
1334
|
+
> - **`ownerSecret` je nepovinný a nemá se posílat.** Každý sdílený nástroj si ho
|
|
1335
|
+
> najde ve vašem `projectRef` podle `sharedOwnerId` a `td_list_shared_projects`
|
|
1336
|
+
> ho už nevrací. Secret je klíč k celému projektu, takže dřív ležel v kontextu
|
|
1337
|
+
> modelu i v každém přepisu konverzace. Kdo ho pošle, tomu to dál funguje
|
|
1338
|
+
> (a kontroluje se proti `sharedOwnerId`).
|
|
1339
|
+
> - **Zápisy hlídají oprávnění stejně jako appka** (`src/permissions.ts`, port
|
|
1340
|
+
> appkového `permissions.ts`). Úkoly, worklogy, checklist, komentáře, přílohy,
|
|
1341
|
+
> vazby, přiřazení štítků, poznámky a dokumenty chtějí `write` nebo `admin`.
|
|
1342
|
+
> Nastavení projektu (`td_update_shared_project` včetně mazání a obnovy),
|
|
1343
|
+
> deployment stages, repozitářové linky, správa štítků a členové chtějí
|
|
1344
|
+
> vlastníka nebo `admin`. Bez `projectRef` se zápis odmítne, čtení jde dál.
|
|
1345
|
+
> Odmítnutí přijde jako chyba a nic se nezapíše.
|
|
1346
|
+
> - **Členy MCP spravuje jen napůl.** Appka po každé změně člena rotuje
|
|
1347
|
+
> zapisovací klíč nebo předá ten současný, jinak zablokovaný člen zapisuje dál.
|
|
1348
|
+
> MCP rotovat neumí, takže změny, po kterých člen nesmí zapisovat (block,
|
|
1349
|
+
> kick, zamítnutí, snížení na `read`), odmítne s odkazem na appku. Schválení,
|
|
1350
|
+
> odblokování a povýšení projdou, jen dokud projekt nemá rotovaný klíč.
|
|
1351
|
+
> - **Sdílené zápisy píšou historii** do sdílené instance, stejné záznamy jako
|
|
1352
|
+
> appka (úkol vytvořen/upraven po polích/smazán, worklog, checklist, komentář,
|
|
1353
|
+
> příloha, štítek, stage, repozitář, projekt, člen), s `actorId` vašeho účtu
|
|
1354
|
+
> a `source: "mcp"` v metadatech.
|
|
1355
|
+
> - **Mazání neexistujícího id** vrací chybu místo `success` a hromadné mazání ho
|
|
1356
|
+
> počítá mezi přeskočené. `td_update_shared_project` vybírá řádek projektu
|
|
1357
|
+
> stejně jako appka (nejstarší živý) a umí ho obnovit z koše.
|
|
1358
|
+
> - **Kód projektu** smí obsahovat jen `A-Z` a `0-9` a souběžná volání
|
|
1359
|
+
> `td_create_task` / `td_create_shared_task` do jednoho projektu už nedostanou
|
|
1360
|
+
> stejný kód.
|
|
1330
1361
|
|
|
1331
|
-
|
|
1362
|
+
> **Stavy úkolů a validace argumentů (TODO-296, TODO-297).** Stav
|
|
1363
|
+
> `recurring` je plnohodnotný, appka ho používá pro opakované úkoly a MCP ho
|
|
1364
|
+
> teď nabízí ve všech devíti enumech. Zároveň se **kontrolují hodnoty enumů a
|
|
1365
|
+
> odmítají nedeklarované argumenty**. Dřív byly enumy jen dokumentace a
|
|
1366
|
+
> neznámý argument se tiše zahodil, což je přesně způsob, jak
|
|
1367
|
+
> `td_create_shared_checklist_item` přijal `isChecked`, vrátil `success`
|
|
1368
|
+
> a položku založil neodškrtnutou. Ten argument tam dnes je.
|
|
1369
|
+
>
|
|
1370
|
+
> Při té příležitosti se srovnal i `linkType`: MCP nabízelo `related`, kterému
|
|
1371
|
+
> appka nerozumí, a chyběly mu `explicit` a `mention`, které appka opravdu
|
|
1372
|
+
> zapisuje. Platné hodnoty jsou `blocks`, `explicit`, `mention`.
|
|
1332
1373
|
|
|
1333
|
-
|
|
1334
|
-
`
|
|
1335
|
-
|
|
1336
|
-
|
|
1374
|
+
> **Rodič se ověřuje, argumenty jsou dorovnané (TODO-300, TODO-302).**
|
|
1375
|
+
> `td_create_task_comment` a `td_create_checklist_item` šly dřív založit na
|
|
1376
|
+
> **neexistující úkol**: řádek se zapsal proti ID, které nic nerozřeší, každý
|
|
1377
|
+
> výpis jde přes `taskId`, takže ho nikdo nikdy nepřečte, a tool vrátil
|
|
1378
|
+
> `success`. `td_add_worklog` to odmítal od TODO-90 M12, tyhle dva ne. Teď
|
|
1379
|
+
> odmítají obě strany, osobní i sdílená, a sdílená scopuje i podle ownera.
|
|
1380
|
+
>
|
|
1381
|
+
> Zároveň se dorovnalo devět argumentů, které sdílené tooly proti osobním
|
|
1382
|
+
> neměly. Nejcitelnější byl `td_update_shared_project`: uměl jen archivaci,
|
|
1383
|
+
> takže **sdílený projekt nešlo přejmenovat**.
|
|
1337
1384
|
|
|
1338
|
-
|
|
1339
|
-
|------|-------------|
|
|
1340
|
-
| `td_list_system_notifications` | List active system/broadcast notifications from the relay server. |
|
|
1341
|
-
| `td_create_system_notification` | Create a broadcast notification visible to all Todocko users. |
|
|
1342
|
-
| `td_delete_system_notification` | Delete a system notification by ID. |
|
|
1385
|
+
### Zprávy od uživatelů (relay)
|
|
1343
1386
|
|
|
1344
|
-
|
|
1387
|
+
Zprávy, které uživatelé posílají z aplikace (hlášení vad, návrhy, vzkazy).
|
|
1388
|
+
Výpis a mazání umí jen **admin owner** a relay od TODO-90 H2 nevěří samotnému
|
|
1389
|
+
`ownerId` – požadavek se podepisuje Ed25519 klíčem odvozeným z nastaveného
|
|
1390
|
+
mnemoniku. Odesílání relay nechává nepřihlášené, stejně jako formulář v appce.
|
|
1345
1391
|
|
|
1346
|
-
|
|
1392
|
+
| Nástroj | Popis |
|
|
1393
|
+
|---------|-------|
|
|
1394
|
+
| `td_list_user_messages` | Výpis zpráv od uživatelů (jen admin owner) |
|
|
1395
|
+
| `td_submit_user_message` | Odeslání zprávy adminům (hlášení vady, návrh, vzkaz) |
|
|
1396
|
+
| `td_delete_user_message` | Smazání zprávy na relayi (jen admin owner, tvrdé smazání) |
|
|
1347
1397
|
|
|
1348
|
-
|
|
1349
|
-
|------|-------------|
|
|
1350
|
-
| `td_list_user_messages` | List messages users have sent from the app (bug reports, feature requests, notes). |
|
|
1351
|
-
| `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. |
|
|
1352
|
-
| `td_delete_user_message` | Delete one user message from the relay. |
|
|
1398
|
+
### Analytika a přehledy
|
|
1353
1399
|
|
|
1354
|
-
|
|
1400
|
+
| Nástroj | Popis |
|
|
1401
|
+
|---------|-------|
|
|
1402
|
+
| `td_get_dashboard_summary` | Přehled: úkoly dnes, po termínu, odpracováno tento týden, nadcházející deadline |
|
|
1403
|
+
| `td_get_team_workload` | Vytížení týmu: odpracováno vs odhad vs kapacita per uživatel za období |
|
|
1404
|
+
| `td_list_recurring_tasks` | Seznam opakujících se úkolů s konfigurací opakování |
|
|
1405
|
+
| `td_list_overdue_tasks` | Úkoly po termínu (seřazené od nejstaršího) |
|
|
1355
1406
|
|
|
1356
|
-
|
|
1357
|
-
|
|
1358
|
-
|
|
1359
|
-
|
|
1360
|
-
|
|
1361
|
-
|
|
1407
|
+
> **Do v1.6.0 tyhle tři nástroje vracely vždy prázdno.** `td_list_recurring_tasks`,
|
|
1408
|
+
> `td_list_overdue_tasks` a `td_list_tasks_by_date_range` čtly `result.rows`,
|
|
1409
|
+
> zatímco `evolu.loadQuery` vrací pole samo – takže `count: 0` na jakýkoli vstup,
|
|
1410
|
+
> bez chyby, které by šlo si všimnout. Opraveno v TODO-242 přes společný
|
|
1411
|
+
> `queryRows`. Recurrence pole navíc vrací i `td_get_task`, takže nastavení
|
|
1412
|
+
> opakování jde přečíst tou nejpřímější cestou.
|
|
1413
|
+
| `td_list_tasks_by_date_range` | Úkoly filtrované podle scheduledDate nebo deadline v daném rozmezí |
|
|
1414
|
+
| `td_analyze_dependencies` | Analýza závislostí: blokované úkoly, blokující řetězce, kritická cesta |
|
|
1362
1415
|
|
|
1363
|
-
> **
|
|
1364
|
-
>
|
|
1365
|
-
>
|
|
1366
|
-
>
|
|
1367
|
-
>
|
|
1368
|
-
>
|
|
1369
|
-
|
|
1370
|
-
|
|
1416
|
+
> **Sdílené projekty se do analytiky počítají (TODO-112).** Do MCP IX čtlo všech
|
|
1417
|
+
> pět přehledů jen osobní instanci, takže úkol ve sdíleném projektu neviděl
|
|
1418
|
+
> dashboard, rozdělení vytížení, seznam opakujících se ani po termínu, ani dotaz
|
|
1419
|
+
> na rozmezí dat. U vytížení to nebylo jen chybějící číslo: počítá se
|
|
1420
|
+
> z odpracovaného času, takže vynechané sdílené minuty podhodnocovaly každého,
|
|
1421
|
+
> kdo ve sdíleném projektu pracuje. Každý nástroj bere `includeShared`
|
|
1422
|
+
> (výchozí `true`) a vrací `sharedIncluded`, ať je vidět, jestli se sdílená
|
|
1423
|
+
> polovina opravdu načetla. `td_analyze_dependencies` zůstává záměrně jen
|
|
1424
|
+
> osobní: appka sdílené `taskLink` řádky čte, ale žádné nezapisuje.
|
|
1425
|
+
>
|
|
1426
|
+
> `td_search_tasks` hledá ve sdílených projektech taky, se stejným přepínačem.
|
|
1371
1427
|
|
|
1372
|
-
###
|
|
1428
|
+
### Diagnostika
|
|
1373
1429
|
|
|
1374
|
-
|
|
|
1375
|
-
|
|
1376
|
-
| `td_sync_status` |
|
|
1377
|
-
| `td_force_sync` |
|
|
1430
|
+
| Nástroj | Popis |
|
|
1431
|
+
|---------|-------|
|
|
1432
|
+
| `td_sync_status` | Stav synchronizace |
|
|
1433
|
+
| `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í) |
|
|
1378
1434
|
|
|
1379
|
-
##
|
|
1435
|
+
## Příklady použití
|
|
1380
1436
|
|
|
1381
|
-
###
|
|
1437
|
+
### Seznam projektů
|
|
1382
1438
|
```
|
|
1383
|
-
|
|
1439
|
+
Zobraz mi seznam všech projektů v Todocko
|
|
1384
1440
|
```
|
|
1385
1441
|
|
|
1386
|
-
###
|
|
1442
|
+
### Seznam úkolů
|
|
1387
1443
|
```
|
|
1388
|
-
|
|
1389
|
-
|
|
1444
|
+
Jaké mám úkoly ve stavu "todo"?
|
|
1445
|
+
Zobraz úkoly projektu TODO
|
|
1390
1446
|
```
|
|
1391
1447
|
|
|
1392
|
-
###
|
|
1448
|
+
### Detail úkolu
|
|
1393
1449
|
```
|
|
1394
|
-
|
|
1450
|
+
Jaké jsou detaily úkolu TODO-15?
|
|
1395
1451
|
```
|
|
1396
1452
|
|
|
1397
|
-
###
|
|
1453
|
+
### Vytvoření úkolu
|
|
1398
1454
|
```
|
|
1399
|
-
|
|
1400
|
-
|
|
1455
|
+
Vytvoř nový úkol v projektu PROJ s názvem "Opravit bug v přihlášení" a prioritou high
|
|
1456
|
+
Vytvoř úkol s deadline na 2026-03-15 a scheduledDate na 2026-03-10
|
|
1401
1457
|
```
|
|
1402
1458
|
|
|
1403
|
-
###
|
|
1459
|
+
### Aktualizace úkolu
|
|
1404
1460
|
```
|
|
1405
|
-
|
|
1406
|
-
|
|
1407
|
-
|
|
1461
|
+
Označ úkol PROJ-5 jako dokončený
|
|
1462
|
+
Přiřaď úkol TODO-10 uživateli s ID xyz
|
|
1463
|
+
Nastav scheduledDate úkolu TODO-10 na zítra
|
|
1408
1464
|
```
|
|
1409
1465
|
|
|
1410
|
-
###
|
|
1466
|
+
### Logování času
|
|
1411
1467
|
```
|
|
1412
|
-
|
|
1468
|
+
Zaloguj 2 hodiny práce na úkol TODO-15 s popisem "Implementace feature"
|
|
1413
1469
|
```
|
|
1414
1470
|
|
|
1415
|
-
###
|
|
1471
|
+
### Práce s přílohami
|
|
1416
1472
|
```
|
|
1417
|
-
|
|
1418
|
-
|
|
1419
|
-
|
|
1473
|
+
Nahraj soubor /home/user/report.pdf jako přílohu k úkolu TODO-15
|
|
1474
|
+
Jaké přílohy má úkol TODO-15?
|
|
1475
|
+
Smaž přílohu s ID xyz
|
|
1420
1476
|
```
|
|
1421
1477
|
|
|
1422
|
-
###
|
|
1478
|
+
### Sdílené projekty
|
|
1423
1479
|
```
|
|
1424
|
-
|
|
1425
|
-
|
|
1426
|
-
|
|
1480
|
+
Zobraz sdílené projekty
|
|
1481
|
+
Jaké úkoly jsou ve sdíleném projektu?
|
|
1482
|
+
Označ úkol jako nasazený na produkci
|
|
1427
1483
|
```
|
|
1428
1484
|
|
|
1429
1485
|
### Deployment stages
|
|
1430
1486
|
```
|
|
1431
|
-
|
|
1432
|
-
|
|
1487
|
+
Jaké deployment stages má projekt?
|
|
1488
|
+
Vytvoř novou deployment stage "Staging" pro sdílený projekt
|
|
1433
1489
|
```
|
|
1434
1490
|
|
|
1435
|
-
### Sub
|
|
1491
|
+
### Sub-úkoly
|
|
1436
1492
|
```
|
|
1437
|
-
|
|
1438
|
-
|
|
1493
|
+
Vytvoř sub-úkol k úkolu TODO-15 v projektu TODO
|
|
1494
|
+
Odpoj úkol TODO-20 od rodičovského úkolu (parentTaskId: null)
|
|
1439
1495
|
```
|
|
1440
1496
|
|
|
1441
|
-
###
|
|
1497
|
+
### Přehledy a analytika
|
|
1442
1498
|
```
|
|
1443
|
-
|
|
1444
|
-
|
|
1445
|
-
|
|
1446
|
-
|
|
1447
|
-
|
|
1448
|
-
|
|
1499
|
+
Jaký mám dnes přehled? (dashboard summary)
|
|
1500
|
+
Jak je vytížený tým tento týden?
|
|
1501
|
+
Jaké úkoly jsou po termínu?
|
|
1502
|
+
Zobraz úkoly naplánované na příští týden
|
|
1503
|
+
Analyzuj závislosti v projektu TODO
|
|
1504
|
+
Jaké mám opakující se úkoly?
|
|
1449
1505
|
```
|
|
1450
1506
|
|
|
1451
|
-
##
|
|
1507
|
+
## Linux CLI (`todo`) (TODO-160)
|
|
1452
1508
|
|
|
1453
|
-
|
|
1509
|
+
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`.
|
|
1510
|
+
|
|
1511
|
+
📖 **Podrobný návod: [CLI.md](CLI.md)**
|
|
1512
|
+
|
|
1513
|
+
```bash
|
|
1514
|
+
# Přidání úkolu (bez -p použije první projekt)
|
|
1515
|
+
todo add "Opravit login"
|
|
1516
|
+
todo add "Opravit login" -p TODO --priority high --scheduled today
|
|
1517
|
+
|
|
1518
|
+
# Změna stavu (identifikace kódem úkolu)
|
|
1519
|
+
todo done TODO-160 # status=done
|
|
1520
|
+
todo start TODO-160 # status=in_progress
|
|
1521
|
+
todo mv TODO-160 review # backlog|todo|in_progress|review|done|recurring
|
|
1522
|
+
|
|
1523
|
+
# Worklog
|
|
1524
|
+
todo log TODO-160 1h30m "ladění OAuth"
|
|
1525
|
+
todo worklogs TODO-160 # tabulka worklogů
|
|
1526
|
+
|
|
1527
|
+
# Strojový výstup na všech příkazech
|
|
1528
|
+
todo add "X" --json
|
|
1529
|
+
```
|
|
1530
|
+
|
|
1531
|
+
- **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`.
|
|
1532
|
+
- **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ě).
|
|
1533
|
+
- **Exit kódy:** `0` úspěch, `1` user/business chyba (neznámý kód, špatný stav/čas), `2` config (chybí mnemonic).
|
|
1534
|
+
- **Barvy** jen v TTY a při nenastaveném `NO_COLOR`.
|
|
1535
|
+
- **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.
|
|
1536
|
+
|
|
1537
|
+
## Bezpečnost
|
|
1538
|
+
|
|
1539
|
+
**Důležité:** Vaše zálohovací fráze (mnemonic) je citlivý údaj!
|
|
1540
|
+
|
|
1541
|
+
- Nikdy ji nesdílejte v přímé konverzaci s AI
|
|
1542
|
+
- MCP server frázi nevystavuje přes žádný nástroj: nejde ji z Todočka přečíst ani vypsat
|
|
1543
|
+
- To ale neznamená, že k ní AI nemá přístup. Agent, který umí spouštět příkazy nebo číst
|
|
1544
|
+
soubory (Claude Code a podobní), si `~/.claude.json` nebo `~/.claude/settings.json`
|
|
1545
|
+
přečte stejně jako kterýkoli jiný soubor. Konfigurace chrání frázi před nástroji MCP,
|
|
1546
|
+
ne před shellem. (TODO-441)
|
|
1547
|
+
- Kdokoli s vaší frází má plný přístup k vašim datům
|
|
1548
|
+
|
|
1549
|
+
### Kontrola argumentů a cest (TODO-441)
|
|
1550
|
+
|
|
1551
|
+
- Hodnoty argumentů se kontrolují proti typu, který nástroj deklaruje. `isBlocked: "false"`
|
|
1552
|
+
se dřív ukládalo jako `true` (neprázdný řetězec je pravdivý), teď je to chyba.
|
|
1553
|
+
- Datová pole (`deadline`, `scheduledDate`, `loggedAt`, `recurrenceEndDate`, `startDate`,
|
|
1554
|
+
`endDate`, …) musí být `YYYY-MM-DD`; kde schéma mluví o datetime (`completedAt`,
|
|
1555
|
+
`expiresAt`, `from`/`to` v activity logu), projde i ISO datetime. `deadline: "zítra"`
|
|
1556
|
+
se dřív uložilo doslova a nikdo se to nedozvěděl.
|
|
1557
|
+
- Přílohy: cesty se vyhodnocují až po rozpadnutí symlinků, takže odkaz uvnitř povoleného
|
|
1558
|
+
adresáře už nevede ven. Stahování nově odmítá tečkové soubory (stejně jako nahrávání)
|
|
1559
|
+
a nepřepíše existující soubor, dokud nepošleš `overwrite: true`.
|
|
1560
|
+
|
|
1561
|
+
### WebSocket Origin (TODO-169)
|
|
1562
|
+
|
|
1563
|
+
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.
|
|
1564
|
+
|
|
1565
|
+
### Rotace zapisovacího klíče sdílených projektů (TODO-268)
|
|
1566
|
+
|
|
1567
|
+
Když vlastník sdíleného projektu někoho vyhodí, aplikace vymění zapisovací klíč
|
|
1568
|
+
projektu na relayi. Klíč odvozený z `ownerSecret` tím přestane platit a relay
|
|
1569
|
+
s ním odmítne každý zápis.
|
|
1454
1570
|
|
|
1455
|
-
|
|
1456
|
-
|
|
1457
|
-
|
|
1458
|
-
|
|
1459
|
-
like any other file. The configuration keeps the phrase away from MCP tools, not from a
|
|
1460
|
-
shell. (TODO-441)
|
|
1461
|
-
- Anyone with your phrase has full access to your data
|
|
1571
|
+
MCP server si nový klíč načte ze sloupce `projectRef.writeKey`, který do jeho
|
|
1572
|
+
databáze přiteče běžným syncem AppOwnera. Kontrola běží při startu a pak každou
|
|
1573
|
+
minutu, takže po rotaci může být zhruba minuta, kdy zápisy do toho jednoho
|
|
1574
|
+
projektu relay odmítá a řádky čekají lokálně. Čtení rotace neovlivňuje.
|
|
1462
1575
|
|
|
1463
|
-
###
|
|
1576
|
+
### Komu klíč patří: nárok versus grant (TODO-440)
|
|
1464
1577
|
|
|
1465
|
-
|
|
1466
|
-
|
|
1467
|
-
|
|
1468
|
-
`startDate`, `endDate`, ...) must be `YYYY-MM-DD`; where the schema says datetime
|
|
1469
|
-
(`completedAt`, `expiresAt`, activity-log `from`/`to`) an ISO datetime is accepted too.
|
|
1470
|
-
`deadline: "zitra"` used to be stored verbatim with nothing reporting it.
|
|
1471
|
-
- Attachments: paths are judged after symlinks are resolved, so a link inside the allowed
|
|
1472
|
-
directory no longer leads out of it. Downloads now refuse dotfiles (as uploads already
|
|
1473
|
-
did) and never replace an existing file unless `overwrite: true` is passed.
|
|
1578
|
+
`projectMember.permission` si zapisuje sám člen, takže o tom, kdo dostane
|
|
1579
|
+
zapisovací klíč, rozhodovat nemůže. Vlastník si vede vlastní záznam ve své
|
|
1580
|
+
osobní instanci, kam žádný člen nedosáhne:
|
|
1474
1581
|
|
|
1475
|
-
|
|
1582
|
+
- `shareInvite` na každý vygenerovaný odkaz, její id cestuje v tokenu,
|
|
1583
|
+
- `memberGrant` na každého člena, jehož oprávnění vlastník nastavil ručně,
|
|
1584
|
+
a ten pozvánku přebíjí.
|
|
1476
1585
|
|
|
1477
|
-
|
|
1478
|
-
|
|
1479
|
-
|
|
1586
|
+
Člen si id pozvánky neukládá, ten řádek čtou i ostatní členové a mohli by si ho
|
|
1587
|
+
opsat. Ukládá si do `projectMember.inviteProof` HMAC vlastní identity klíčovaný
|
|
1588
|
+
id pozvánky; vlastník, který id má, ho ověří, cizí člen si ho pro sebe nevyrobí.
|
|
1589
|
+
Skutečné oprávnění je to nižší z nároku a záznamu.
|
|
1480
1590
|
|
|
1481
|
-
|
|
1482
|
-
|
|
1483
|
-
|
|
1484
|
-
|
|
1591
|
+
`td_list_shared_members` proto vlastníkovi vrací navíc `verifiedPermission`
|
|
1592
|
+
a `effectivePermission` a `td_update_shared_member` zapisuje `memberGrant`
|
|
1593
|
+
spolu se změnou nároku. Dokud to MCP neumělo, změnilo povýšení přes MCP jen
|
|
1594
|
+
nárok: člen zapisovací klíč nedostal a appka u něj začala hlásit, že si
|
|
1595
|
+
nárokuje víc, než má potvrzeno.
|
|
1485
1596
|
|
|
1486
|
-
##
|
|
1597
|
+
## Umístění dat
|
|
1487
1598
|
|
|
1488
|
-
|
|
1599
|
+
Databáze jsou uloženy v adresáři `~/.todocko/`:
|
|
1489
1600
|
|
|
1490
|
-
|
|
|
1491
|
-
|
|
1601
|
+
| Platforma | Cesta |
|
|
1602
|
+
|-----------|-------|
|
|
1492
1603
|
| Linux | `~/.todocko/` |
|
|
1493
1604
|
| macOS | `~/.todocko/` |
|
|
1494
1605
|
| Windows | `C:\Users\<user>\.todocko\` |
|
|
1495
1606
|
|
|
1496
|
-
|
|
1497
|
-
- `todocko.db` -
|
|
1498
|
-
- `todocko-shared.db` -
|
|
1607
|
+
Soubory:
|
|
1608
|
+
- `todocko.db` - vaše osobní data (úkoly, projekty)
|
|
1609
|
+
- `todocko-shared.db` - sdílené projekty
|
|
1499
1610
|
|
|
1500
|
-
##
|
|
1611
|
+
## Změna konfigurace
|
|
1501
1612
|
|
|
1502
1613
|
### Claude Code (CLI)
|
|
1503
1614
|
|
|
1504
|
-
|
|
1615
|
+
Po změně konfigurace v `~/.claude/settings.json` (např. změna mnemonicu) spusťte příkaz:
|
|
1505
1616
|
```
|
|
1506
1617
|
/mcp
|
|
1507
1618
|
```
|
|
1508
|
-
|
|
1619
|
+
Tím se MCP server restartuje s novou konfigurací.
|
|
1509
1620
|
|
|
1510
|
-
###
|
|
1621
|
+
### Přepnutí na jiný účet
|
|
1511
1622
|
|
|
1512
|
-
|
|
1623
|
+
Při změně mnemonicu na **jiný Todocko účet** je potřeba smazat lokální databázi:
|
|
1513
1624
|
|
|
1514
1625
|
```bash
|
|
1515
1626
|
# Linux/macOS
|
|
@@ -1519,126 +1630,182 @@ rm ~/.todocko/todocko.db
|
|
|
1519
1630
|
del %USERPROFILE%\.todocko\todocko.db
|
|
1520
1631
|
```
|
|
1521
1632
|
|
|
1522
|
-
|
|
1633
|
+
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.
|
|
1523
1634
|
|
|
1524
1635
|
## Troubleshooting
|
|
1525
1636
|
|
|
1526
|
-
### Server
|
|
1527
|
-
-
|
|
1528
|
-
-
|
|
1529
|
-
-
|
|
1637
|
+
### Server se nespustí
|
|
1638
|
+
- Zkontrolujte, že máte Node.js 24.20+
|
|
1639
|
+
- Zkontrolujte, že jste spustili `npm run build`
|
|
1640
|
+
- Zkontrolujte logy v Claude Desktop
|
|
1530
1641
|
|
|
1531
|
-
### Data
|
|
1532
|
-
-
|
|
1533
|
-
-
|
|
1534
|
-
-
|
|
1535
|
-
-
|
|
1642
|
+
### Data se nesynchronizují
|
|
1643
|
+
- Ověřte, že je zálohovací fráze správná (24 slov)
|
|
1644
|
+
- Zkontrolujte internetové připojení
|
|
1645
|
+
- Počkejte pár sekund na synchronizaci
|
|
1646
|
+
- Zkuste smazat `~/.todocko/todocko.db` a restartovat
|
|
1536
1647
|
|
|
1537
|
-
### Tools not visible
|
|
1538
|
-
- Restart Claude Desktop
|
|
1539
|
-
- In Claude Code, use `/mcp` for reload
|
|
1540
|
-
- Check the configuration file
|
|
1541
|
-
- Check the path to dist/index.js
|
|
1542
1648
|
|
|
1543
|
-
### `
|
|
1544
|
-
A shared project keeps its data in the **shared instance**, so the personal
|
|
1545
|
-
tools (`td_create_task`, `td_update_task`, `td_bulk_update_tasks`) refuse a
|
|
1546
|
-
write aimed at one and point at the `td_*_shared_*` counterpart.
|
|
1649
|
+
### `status: relay-blocked` v `td_sync_status` (TODO-112)
|
|
1547
1650
|
|
|
1548
|
-
|
|
1549
|
-
|
|
1550
|
-
|
|
1551
|
-
|
|
1651
|
+
Relay odpovídá na HTTPS, ale WebSocket nepropustí. Mezi strojem a relayí tedy
|
|
1652
|
+
něco blokuje upgrade spojení, typicky proxy nebo firewall, ne vada relaye.
|
|
1653
|
+
Zápisy se drží lokálně a odejdou, jakmile socket projde. Od `no-relay` se to
|
|
1654
|
+
liší tím, že tam neodpovídá vůbec nic, což znamená spíš výpadek sítě.
|
|
1552
1655
|
|
|
1553
|
-
|
|
1554
|
-
|
|
1555
|
-
|
|
1556
|
-
|
|
1656
|
+
### Nástroje nejsou viditelné
|
|
1657
|
+
- Restartujte Claude Desktop
|
|
1658
|
+
- V Claude Code použijte `/mcp` pro reload
|
|
1659
|
+
- Zkontrolujte konfigurační soubor
|
|
1660
|
+
- Zkontrolujte cestu k dist/index.js
|
|
1661
|
+
|
|
1662
|
+
### `project ... is a shared project` při zápisu
|
|
1663
|
+
Sdílený projekt má svá data ve **sdílené instanci**. Osobní nástroje
|
|
1664
|
+
(`td_create_task`, `td_update_task`, `td_bulk_update_tasks`) proto zápis do
|
|
1665
|
+
takového projektu odmítnou a pošlou tě na `td_*_shared_*` protějšek.
|
|
1666
|
+
|
|
1667
|
+
Dřív se zápis tiše uložil do osobní instance vedle skutečného řádku. Vznikly
|
|
1668
|
+
tím dvě kopie téhož úkolu v různých instancích, které se rozcházely: aplikace
|
|
1669
|
+
čte sdílenou stranu, MCP `td_list_tasks` osobní, takže každý ukazoval něco
|
|
1670
|
+
jiného a nic to nehlásilo. (TODO-318)
|
|
1671
|
+
|
|
1672
|
+
**Mazání zůstává povolené i pro sdílený projekt**, jinak by staré osobní kopie
|
|
1673
|
+
nešlo uklidit. `td_search_tasks` s `includeShared` ukáže obě kopie vedle sebe a
|
|
1674
|
+
je proto nejrychlejší způsob, jak zjistit, že je úkol rozdvojený.
|
|
1675
|
+
|
|
1676
|
+
### Kód úkolu se teď přidělit nedá (TODO-373)
|
|
1677
|
+
`td_create_task` odvozuje kód z nejvyššího, který v téhle kopii vidí. Když část
|
|
1678
|
+
účtu ještě nedorazila, je maximum nižší než skutečné a vznikne kód, který na
|
|
1679
|
+
relayi už existuje. Stalo se to 2026-09-23: v 07:01 kopie neměla TODO-360 až
|
|
1680
|
+
367 a server vyrobil TODO-353 a dál, v 09:33 už je nad stejným souborem měla
|
|
1681
|
+
a navázal správně na 368. Nic se nerozbilo jen proto, že 353 až 359 byla shodou
|
|
1682
|
+
okolností volná.
|
|
1683
|
+
|
|
1684
|
+
Před přidělením kódu se proto porovná počet zpráv: Evolu jich drží po jedné
|
|
1685
|
+
v `evolu_timestamp`, relay hlásí stejné číslo pro ownera. Naměřeno 81 130 na
|
|
1686
|
+
obou stranách. Když je kopie pozadu, zápis se odmítne a řekne, kolik zpráv
|
|
1687
|
+
chybí; až se sync dotáhne, projde. Když se relay zeptat nedá, zápis projde:
|
|
1688
|
+
odmítat i tam by z lokálně prvního nástroje udělalo nástroj závislý na síti.
|
|
1689
|
+
|
|
1690
|
+
Aktuální stav ukáže `td_sync_status` v poli `copy`.
|
|
1691
|
+
|
|
1692
|
+
**Sdílené projekty tenhle strážce nemají.** Jejich úkoly patří jinému ownerovi
|
|
1693
|
+
s vlastním počtem zpráv a zeptat se na něj chce jeho klíč, ne ten odvozený
|
|
1694
|
+
z mnemoniky. Měřit tam app ownera by vypadalo jako pokrytí a nebylo by.
|
|
1557
1695
|
|
|
1558
1696
|
### `Todocko MCP už nad touto databází běží` (TODO-341)
|
|
1559
|
-
|
|
1560
|
-
|
|
1561
|
-
|
|
1562
|
-
`PanicAbortReason: database is locked
|
|
1563
|
-
dbWorker.
|
|
1564
|
-
|
|
1697
|
+
Druhá instance nad stejnou zálohovací frází se odmítne nastartovat. Není to
|
|
1698
|
+
opatrnost navíc: klientská databáze jede v režimu `journal_mode=delete`
|
|
1699
|
+
s nulovým `busy_timeout`, takže druhý proces dostane SQLITE_BUSY okamžitě,
|
|
1700
|
+
Evolu z toho udělá `PanicAbortReason: database is locked` a **prvnímu** procesu
|
|
1701
|
+
umře dbWorker. Do TODO-341 tak nové okno tiše shodilo to, ve kterém jsi pracoval
|
|
1702
|
+
(projevilo se jako `status: worker-dead`, viz níž).
|
|
1565
1703
|
|
|
1566
|
-
|
|
1567
|
-
|
|
1568
|
-
|
|
1704
|
+
Zámek je soubor `~/.todocko/todocko-<owner>.lock` vedle databáze. Drží pid,
|
|
1705
|
+
který ho vzal; po pádu procesu se pozná jako neaktuální a další start si ho
|
|
1706
|
+
vezme.
|
|
1569
1707
|
|
|
1570
|
-
|
|
1571
|
-
|
|
1708
|
+
Samotné `process.kill(pid, 0)` na to nestačí (TODO-372). **Zombie procesem ten
|
|
1709
|
+
test projde**: proces, který skončil, ale rodič ho nesklidil, je pořád
|
|
1710
|
+
v tabulce procesů a signál 0 na něm uspěje. Zámek pak vypadá jako věčně držený
|
|
1711
|
+
a žádná nová instance se nespustí. Stalo se to 2026-09-22, kdy byl držitel ve
|
|
1712
|
+
stavu `Z` a jeho rodič zastavený `claude` ve stavu `Tl`, takže neměl kdo
|
|
1713
|
+
sklízet. Na Linuxu se proto čte stav z `/proc/<pid>/stat` a `Z` se bere jako
|
|
1714
|
+
mrtvý. Kde `/proc` není, zůstává původní chování.
|
|
1715
|
+
|
|
1716
|
+
Když potřebuješ druhou instanci doopravdy (třeba CLI `todo` vedle MCP), spusť ji
|
|
1717
|
+
s vlastním jménem databáze:
|
|
1572
1718
|
```bash
|
|
1573
1719
|
TODOCKO_INSTANCE=cli todo ...
|
|
1574
1720
|
```
|
|
1575
|
-
|
|
1576
|
-
|
|
1577
|
-
|
|
1578
|
-
database.
|
|
1579
|
-
|
|
1580
|
-
### Every `loadQuery` ends with a timeout (`loadQuery timed out after 15000ms`)
|
|
1721
|
+
Dostane `~/.todocko/todocko-cli-<owner>.db`, tedy vlastní lokální kopii, která
|
|
1722
|
+
se s tou první srovná přes relay. Povolené znaky jsou `a-z0-9-`, zbytek se
|
|
1723
|
+
zahodí; prázdná hodnota znamená výchozí databázi.
|
|
1581
1724
|
|
|
1582
|
-
|
|
1725
|
+
### Worker umřel za běhu (`status: worker-dead`)
|
|
1726
|
+
Proces normálně naběhl a po nějaké době přestal odpovídat. `td_sync_status`
|
|
1727
|
+
vrátí `status: "worker-dead"` a v `workerDefects` je panika i s časem. Dotazy
|
|
1728
|
+
v tomhle stavu selžou **hned**, ne až po 15 s. Řešení je `/mcp` reconnect.
|
|
1729
|
+
Nejčastější příčina je druhý MCP proces nad stejnou databází; od TODO-341 se
|
|
1730
|
+
druhá instance nenastartuje, takže tuhle cestu k mrtvému workeru už nemá jak
|
|
1731
|
+
způsobit.
|
|
1583
1732
|
|
|
1584
|
-
|
|
1585
|
-
creating the schema of the same database at the same time race each other. The
|
|
1586
|
-
loser gets `SqliteError: table evolu_version already exists` and its dbWorker
|
|
1587
|
-
stays dead for the life of the process. Typically on the first starts after an
|
|
1588
|
-
MCP upgrade that adds a table.
|
|
1733
|
+
### Každý `loadQuery` skončí timeoutem (`loadQuery timed out after 15000ms`)
|
|
1589
1734
|
|
|
1590
|
-
|
|
1591
|
-
every tool call returns `Evolu dbWorker never answered` immediately. Since
|
|
1592
|
-
TODO-317 the reason the worker died is recorded too, in `workerDefects` from
|
|
1593
|
-
`td_sync_status` and on stderr as `FATAL: Evolu dbWorker defect: ...`. It used to
|
|
1594
|
-
look healthy while every query hung until the client gave up 1800s later. The
|
|
1595
|
-
fix is a `/mcp` reconnect in Claude Code.
|
|
1735
|
+
Příčiny jsou dvě, poznáte je podle toho, co server řekne.
|
|
1596
1736
|
|
|
1597
|
-
**
|
|
1737
|
+
**1. Mrtvý dbWorker po závodu dvou procesů (TODO-316).** Dva MCP procesy, které
|
|
1738
|
+
současně zakládají schéma téže databáze, se porvou. Poražený dostane
|
|
1739
|
+
`SqliteError: table evolu_version already exists` a jeho dbWorker zůstane
|
|
1740
|
+
mrtvý do konce života procesu. Typicky při prvních startech po upgradu MCP,
|
|
1741
|
+
který přidá tabulku.
|
|
1598
1742
|
|
|
1599
|
-
|
|
1743
|
+
Od TODO-316 to server pozná při startu a **odmítne se nastartovat**: každé
|
|
1744
|
+
volání nástroje hned vrátí `Evolu dbWorker never answered`. Od TODO-317 se
|
|
1745
|
+
navíc zapíše i **proč** worker umřel, do `workerDefects` v `td_sync_status`
|
|
1746
|
+
a do stderr jako `FATAL: Evolu dbWorker defect: ...`. Dřív se tvářil
|
|
1747
|
+
zdravě a každý dotaz visel, dokud to klient po 1800 s nevzdal. Řešení je `/mcp`
|
|
1748
|
+
reconnect v Claude Code.
|
|
1600
1749
|
|
|
1601
|
-
|
|
1602
|
-
|
|
1603
|
-
|
|
1604
|
-
|
|
1605
|
-
|
|
1606
|
-
|
|
1607
|
-
Then `/mcp` reconnect in Claude Code.
|
|
1750
|
+
**2. Databáze, kterou nový driver neotevře.** Od TODO-448 je klientská databáze
|
|
1751
|
+
šifrovaná a starou, plaintextovou, nový driver odmítne: `file is not a database`.
|
|
1752
|
+
Symptom je stejný jako u všech vad dbWorkeru, tedy `Evolu dbWorker never answered`
|
|
1753
|
+
u každého volání. Řešení je smazat `~/.todocko/todocko*-<ownerId>.db` a nechat
|
|
1754
|
+
data stáhnout z relaye; předtím se ujistit přes `td_sync_status`, že nic nečeká
|
|
1755
|
+
na odeslání.
|
|
1608
1756
|
|
|
1609
|
-
|
|
1757
|
+
Dřív tu stával mismatch native bindingu better-sqlite3 (`ERR_DLOPEN_FAILED` po
|
|
1758
|
+
upgradu Node nebo přepnutí mezi nvm a brew). `@evolu/nodejs` 4.4 ho nahradilo
|
|
1759
|
+
předpřipraveným SQLite, takže se nic nekompiluje a tahle třída chyb zmizela.
|
|
1610
1760
|
|
|
1611
|
-
##
|
|
1761
|
+
## Vývoj
|
|
1612
1762
|
|
|
1613
1763
|
```bash
|
|
1614
|
-
#
|
|
1764
|
+
# Instalace závislostí
|
|
1615
1765
|
npm install
|
|
1616
1766
|
|
|
1617
1767
|
# Build
|
|
1618
1768
|
npm run build
|
|
1619
1769
|
|
|
1620
|
-
# Watch mode
|
|
1770
|
+
# Watch mode pro vývoj
|
|
1621
1771
|
npm run dev
|
|
1622
1772
|
|
|
1623
|
-
#
|
|
1773
|
+
# Testy
|
|
1624
1774
|
npm test
|
|
1625
1775
|
|
|
1626
|
-
#
|
|
1627
|
-
TODOCKO_MNEMONIC="
|
|
1776
|
+
# Ruční spuštění
|
|
1777
|
+
TODOCKO_MNEMONIC="vaše fráze" npm start
|
|
1628
1778
|
```
|
|
1629
1779
|
|
|
1630
1780
|
### Testy
|
|
1631
1781
|
|
|
1632
|
-
Vitest
|
|
1633
|
-
od TODO-229
|
|
1782
|
+
Vitest. **Sada běží v CI** (`ci.yml`, push i PR na `main`)
|
|
1783
|
+
od TODO-229 – do té doby CI spouštěla jen build, takže se nikdo nedozvěděl, že
|
|
1634
1784
|
`helpers.test.ts` na Node 18/20 **ani neprojde importem**: přes `helpers.ts`
|
|
1635
1785
|
tahal `../evolu.js`, jehož inicializace při načtení modulu spadne na
|
|
1636
1786
|
`crypto.getRandomValues must be defined`.
|
|
1637
1787
|
|
|
1638
1788
|
Proto jsou funkce bez závislosti na Evolu v **`src/tools/pure.ts`** a testují se
|
|
1639
1789
|
odtud. `helpers.ts` je re-exportuje, takže volající se nemění. Když píšeš helper,
|
|
1640
|
-
který Evolu nepotřebuje, patří do `pure.ts`
|
|
1790
|
+
který Evolu nepotřebuje, patří do `pure.ts` – jinak ho nejde testovat bez
|
|
1641
1791
|
nastartované databáze.
|
|
1642
1792
|
|
|
1643
|
-
Závazná verze je **Node 24.20 nebo novější**
|
|
1793
|
+
Závazná verze je **Node 24.20 nebo novější** – je v `engines` a Evolu v8 na
|
|
1644
1794
|
starším neběží. Na té jede `ci.yml` i `release.yml`.
|
|
1795
|
+
|
|
1796
|
+
### Vydání
|
|
1797
|
+
|
|
1798
|
+
```bash
|
|
1799
|
+
npm version patch # nebo minor / major
|
|
1800
|
+
git push --follow-tags
|
|
1801
|
+
```
|
|
1802
|
+
|
|
1803
|
+
Tag spustí `release.yml`: sestaví, pustí testy, ověří, že tag souhlasí
|
|
1804
|
+
s `package.json`, a vydání na npm **zařadí do fronty** i s podepsanou
|
|
1805
|
+
provenance. Žádné přihlašovací údaje k npm v repozitáři nejsou, runner si o
|
|
1806
|
+
krátkodobé oprávnění řekne sám přes trusted publishing (OIDC).
|
|
1807
|
+
|
|
1808
|
+
Fronta je tam schválně. K nikomu se verze nedostane, dokud ji neschválíš na
|
|
1809
|
+
npmjs.com v **Staged Packages**, případně přes `npm stage list todocko-mcp`
|
|
1810
|
+
a `npm stage approve <stage-id>`. Schválení chce 2FA, takže ani ovládnutý běh
|
|
1811
|
+
workflow nedokáže poslat verzi uživatelům sám.
|