@j0hanz/todokit-mcp 1.0.2 → 1.0.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.
Files changed (2) hide show
  1. package/README.md +93 -33
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # todokit-mcp
2
2
 
3
- <img src="docs/logo.png" alt="Filesystem Context MCP Server Logo" width="150">
3
+ <img src="docs/logo.png" alt="Todokit MCP Server Logo" width="150">
4
4
 
5
5
  An MCP server for Todokit, a task management and productivity tool with JSON storage.
6
6
 
@@ -21,7 +21,8 @@ An MCP server for Todokit, a task management and productivity tool with JSON sto
21
21
  - Rich filtering: status, priority, tags, due dates, and free-text search.
22
22
  - Tagging: tags are normalized (trimmed, lowercase, unique) and can be added or removed.
23
23
  - Safe deletion: dry-run delete returns previews for ambiguous matches.
24
- - JSON persistence with caching and atomic writes.
24
+ - JSON persistence with queued writes and atomic file writes.
25
+ - List summaries with counts (pending, completed, overdue).
25
26
 
26
27
  ## Quick Start
27
28
 
@@ -45,6 +46,12 @@ npx -y @j0hanz/todokit-mcp@latest
45
46
  npm install -g @j0hanz/todokit-mcp
46
47
  ```
47
48
 
49
+ Then run:
50
+
51
+ ```bash
52
+ todokit-mcp
53
+ ```
54
+
48
55
  ### From source
49
56
 
50
57
  ```bash
@@ -59,7 +66,7 @@ npm start
59
66
 
60
67
  ### Storage path
61
68
 
62
- By default, todos are stored in `todos.json` next to the server package (the project root when running from source). To control where data is written, set the `TODOKIT_TODO_FILE` environment variable to an absolute or relative path ending with `.json`.
69
+ By default, todos are stored in `todos.json` next to the server package (the project root when running from source). To control where data is written, set the `TODOKIT_TODO_FILE` environment variable to an absolute or relative path ending with `.json`. The directory is created as needed; if the file does not exist, the server starts with an empty list.
63
70
 
64
71
  Examples:
65
72
 
@@ -76,7 +83,9 @@ npx -y @j0hanz/todokit-mcp@latest
76
83
 
77
84
  ## Tools
78
85
 
79
- All tools return a JSON payload in both `content` (stringified) and `structuredContent` with the shape:
86
+ All tools return a JSON payload in both `content` (stringified) and `structuredContent`.
87
+
88
+ Success payload:
80
89
 
81
90
  ```json
82
91
  {
@@ -85,9 +94,16 @@ All tools return a JSON payload in both `content` (stringified) and `structuredC
85
94
  }
86
95
  ```
87
96
 
88
- When an error occurs, `ok` is false and `error` contains `{ code, message }`.
89
- The `result` shape is tool-specific.
90
- If a `query` matches multiple todos, tools return `E_AMBIGUOUS` with previews and a hint to use an exact `id`.
97
+ Error payload:
98
+
99
+ ```json
100
+ {
101
+ "ok": false,
102
+ "error": { "code": "E_CODE", "message": "Details" }
103
+ }
104
+ ```
105
+
106
+ The `result` shape is tool-specific. If a `query` matches multiple todos, tools return `E_AMBIGUOUS` with preview matches and a hint to use an exact `id`.
91
107
 
92
108
  ### add_todo
93
109
 
@@ -99,15 +115,27 @@ Add a new todo item.
99
115
  | description | string | No | - | Optional description (max 2000 chars) |
100
116
  | priority | string | No | normal | Priority level: low, normal, high |
101
117
  | dueDate | string | No | - | Due date in ISO format (YYYY-MM-DD) |
102
- | tags | array | No | - | Array of tags for categorization |
118
+ | tags | array | No | - | Array of tags (max 50, 1-50 chars) |
119
+
120
+ Result fields:
121
+
122
+ - `item` (todo)
123
+ - `summary`
124
+ - `nextActions`
103
125
 
104
126
  ### add_todos
105
127
 
106
128
  Add multiple todo items in one call.
107
129
 
108
- | Parameter | Type | Required | Default | Description |
109
- | :-------- | :---- | :------- | :------ | :---------------------------------------------- |
110
- | items | array | Yes | - | Array of todo objects (same fields as add_todo) |
130
+ | Parameter | Type | Required | Default | Description |
131
+ | :-------- | :---- | :------- | :------ | :---------------------------------------------------------- |
132
+ | items | array | Yes | - | Array of todo objects (same fields as add_todo, 1-50 items) |
133
+
134
+ Result fields:
135
+
136
+ - `items` (todos)
137
+ - `summary`
138
+ - `nextActions`
111
139
 
112
140
  ### list_todos
113
141
 
@@ -124,8 +152,16 @@ List todos with filtering, search, sorting, and pagination.
124
152
  | dueAfter | string | No | - | Filter todos due after this date (YYYY-MM-DD) |
125
153
  | sortBy | string | No | createdAt | Sort by: dueDate, priority, createdAt, title |
126
154
  | order | string | No | asc | Sort order: asc, desc |
127
- | limit | number | No | 50 | Max number of results |
128
- | offset | number | No | 0 | Number of results to skip |
155
+ | limit | number | No | 50 | Max number of results (1-200) |
156
+ | offset | number | No | 0 | Number of results to skip (0-10000) |
157
+
158
+ Result fields:
159
+
160
+ - `items` (todos)
161
+ - `summary`
162
+ - `counts` (`total`, `pending`, `completed`, `overdue`)
163
+ - `limit`
164
+ - `offset`
129
165
 
130
166
  ### update_todo
131
167
 
@@ -140,7 +176,7 @@ Update fields on a todo item. Provide either `id` or `query` to identify the tod
140
176
  | completed | boolean | No | - | Completion status |
141
177
  | priority | string | No | - | New priority level |
142
178
  | dueDate | string | No | - | New due date (YYYY-MM-DD) |
143
- | tags | array | No | - | Replace all tags |
179
+ | tags | array | No | - | Replace all tags (max 50) |
144
180
  | tagOps | object | No | - | Tag modifications to apply (add/remove arrays) |
145
181
  | clearFields | array | No | - | Fields to clear: description, dueDate, tags |
146
182
 
@@ -149,6 +185,12 @@ Notes:
149
185
  - If both `tags` and `tagOps` are provided, `tags` wins and replaces the list.
150
186
  - If no updatable fields are provided, the tool returns an error.
151
187
 
188
+ Result fields:
189
+
190
+ - `item` (todo)
191
+ - `summary`
192
+ - `nextActions`
193
+
152
194
  ### complete_todo
153
195
 
154
196
  Set completion status for a todo item. Provide either `id` or `query`.
@@ -159,6 +201,12 @@ Set completion status for a todo item. Provide either `id` or `query`.
159
201
  | query | string | No | - | Search text to find a single todo |
160
202
  | completed | boolean | No | true | Set completion status |
161
203
 
204
+ Result fields:
205
+
206
+ - `item` (todo)
207
+ - `summary` (includes already-complete or reopen messages)
208
+ - `nextActions`
209
+
162
210
  ### delete_todo
163
211
 
164
212
  Delete a todo item. Provide either `id` or `query`.
@@ -169,6 +217,14 @@ Delete a todo item. Provide either `id` or `query`.
169
217
  | query | string | No | - | Search text to find a single todo |
170
218
  | dryRun | boolean | No | false | Simulate deletion without changing data |
171
219
 
220
+ Result fields:
221
+
222
+ - `deletedIds` (array)
223
+ - `summary`
224
+ - `nextActions` (only when not dryRun)
225
+ - `dryRun` (when dryRun is true)
226
+ - `matches`, `totalMatches` (dry-run + multiple matches)
227
+
172
228
  ## Data Model
173
229
 
174
230
  A todo item has the following shape:
@@ -243,35 +299,39 @@ Add this to your `claude_desktop_config.json`:
243
299
 
244
300
  ### Scripts
245
301
 
246
- | Command | Description |
247
- | :---------------------- | :----------------------------------------------- |
248
- | npm run build | Compile TypeScript to JavaScript |
249
- | npm run dev | Run server in watch mode for development |
250
- | npm start | Run the built server |
251
- | npm run test | Run unit tests (node --test + tsx) |
252
- | npm run test:coverage | Run unit tests with coverage |
253
- | npm run lint | Run ESLint |
254
- | npm run format | Format with Prettier |
255
- | npm run type-check | Run TypeScript type checking |
256
- | npm run bench | Run benchmark suite |
257
- | npm run dup-check | Run duplicate code checks (jscpd) |
258
- | npm run maintainability | Run maintainability index report |
259
- | npm run inspector | Launch the MCP inspector (use with node dist/..) |
302
+ | Command | Description |
303
+ | :-------------------- | :---------------------------------------------------- |
304
+ | npm run build | Compile TypeScript to JavaScript |
305
+ | npm run dev | Run server in watch mode for development |
306
+ | npm start | Run the built server |
307
+ | npm run test | Run unit tests (node --test + tsx) |
308
+ | npm run test:coverage | Run unit tests with coverage |
309
+ | npm run lint | Run ESLint |
310
+ | npm run format | Format with Prettier |
311
+ | npm run format:check | Check formatting with Prettier |
312
+ | npm run type-check | Run TypeScript type checking |
313
+ | npm run dup-check | Run duplicate code checks (jscpd) |
314
+ | npm run clean | Remove the dist/ build output |
315
+ | npm run inspector | Launch the MCP inspector (pass server cmd after `--`) |
260
316
 
261
317
  ### Manual verification
262
318
 
263
319
  ```bash
264
320
  npm run build
265
- npx @modelcontextprotocol/inspector node dist/index.js
321
+ npm run inspector -- node dist/index.js
266
322
  ```
267
323
 
268
324
  ### Project structure
269
325
 
326
+ ```
270
327
  src/
271
- index.ts # MCP server entrypoint (stdio)
272
- tools/ # Tool registrations
273
- schemas/ # Zod input/output schemas
274
- lib/ # Storage, matching, shared helpers
328
+ index.ts # MCP server entrypoint (stdio)
329
+ tools/ # Tool registrations
330
+ schemas/ # Zod input/output schemas
331
+ lib/ # Storage, matching, shared helpers
332
+ tests/ # Unit tests
333
+ docs/ # Assets (logo)
334
+ ```
275
335
 
276
336
  ## Contributing
277
337
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@j0hanz/todokit-mcp",
3
- "version": "1.0.2",
3
+ "version": "1.0.3",
4
4
  "mcpName": "io.github.j0hanz/todokit",
5
5
  "description": "A MCP server for Todokit, a task management and productivity tool with JSON storage.",
6
6
  "type": "module",