@j0hanz/todokit-mcp 1.3.3 → 1.3.4

package/dist/index.js

@@ -3,13 +3,13 @@ import { readFileSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { parseArgs } from 'node:util';
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { McpServer, ResourceTemplate, } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import {} from '@modelcontextprotocol/sdk/types.js';
 import packageJson from '../package.json' with { type: 'json' };
 import { enableDefaultDiagnosticsSubscribers, publishLifecycleEvent, } from './diagnostics.js';
 import { closeDb } from './storage.js';
-import { registerAllTools } from './tools.js';
+import { registerAllTools, setInitializationGuard } from './tools.js';
 const LEVEL_RANKS = {
     debug: 10,
     info: 20,
@@ -96,10 +96,12 @@ const SERVER_VERSION = typeof packageJson.version === 'string' && packageJson.ve
     ? packageJson.version
     : '0.0.0';
 const DEFAULT_INSTRUCTIONS = 'Todokit to-do list manager';
+function resolveInstructionsPath() {
+    return resolve(dirname(fileURLToPath(import.meta.url)), 'instructions.md');
+}
 function loadServerInstructions() {
     try {
-        const instructionsPath = resolve(dirname(fileURLToPath(import.meta.url)), 'instructions.md');
-        const raw = readFileSync(instructionsPath, { encoding: 'utf8' });
+        const raw = readFileSync(resolveInstructionsPath(), { encoding: 'utf8' });
         const trimmed = raw.trim();
         return trimmed.length > 0 ? trimmed : DEFAULT_INSTRUCTIONS;
     }
@@ -107,6 +109,20 @@ function loadServerInstructions() {
         return DEFAULT_INSTRUCTIONS;
     }
 }
+function registerInstructionsResource(server) {
+    server.registerResource('internal://instructions', new ResourceTemplate('internal://instructions', { list: undefined }), { title: 'Todokit Instructions', mimeType: 'text/markdown' }, (uri) => {
+        const text = loadServerInstructions();
+        return {
+            contents: [
+                {
+                    uri: uri.href,
+                    text,
+                    mimeType: 'text/markdown',
+                },
+            ],
+        };
+    });
+}
 let shuttingDown = false;
 let activeServer = null;
 let disableDiagnostics = null;
@@ -161,6 +177,14 @@ export function createServer() {
         instructions: loadServerInstructions(),
         capabilities: { logging: {} },
     });
+    registerInstructionsResource(server);
+    let initialized = false;
+    const previousInitialized = server.server.oninitialized;
+    server.server.oninitialized = () => {
+        initialized = true;
+        previousInitialized?.();
+    };
+    setInitializationGuard(() => initialized);
     patchToolErrorResponses(server);
     registerAllTools(server);
     return server;
@@ -235,6 +259,11 @@ if (entrypoint && import.meta.url === pathToFileURL(entrypoint).href) {
         disableDiagnostics = enableDefaultDiagnosticsSubscribers({
             logger: (line) => {
                 logger.info(line);
+                if (activeServer?.isConnected()) {
+                    void activeServer
+                        .sendLoggingMessage({ level: 'info', data: { message: line } })
+                        .catch(() => undefined);
+                }
             },
         });
     }

package/dist/instructions.md

@@ -1,105 +1,39 @@
-# Todokit MCP Server — AI Usage Instructions
+# Todokit Instructions
 
-Use this server to manage a small, persistent todo list (JSON file storage). Prefer using these tools over "remembering" state in chat.
+> **Guidance for the Agent:** These instructions are available as a resource (`internal://instructions`) or prompt (`get-help`). Load them when you are confused about tool usage.
 
-## Operating Rules
+## 1. Core Capability
 
-- Use tools only when it changes or verifies the todo list (don't call tools "just to check").
-- Prefer `list_todos` to establish state before updating/completing/deleting.
-- Operate by `id` (all mutation tools require an exact `id`). If the user doesn't provide an id, list first and then ask which item to act on.
-- Batch-create with `add_todos` when adding multiple items.
-- Treat `delete_todo` as destructive: ask for explicit confirmation unless the user clearly requested deletion.
-- If request is vague, ask clarifying questions.
+- **Domain:** Manage a persistent local todo list stored in JSON.
+- **Primary Resources:** `Todo` items, list `counts`, `summary`, and `hint` metadata.
 
-### Strategies
+## 2. The "Golden Path" Workflows (Critical)
 
-- **Discovery:** Call `list_todos` (default: pending) to see current tasks. Use `status='all'` only if looking for completed items.
-- **Action:** Chain tools efficiently: `list` → confirm ID → `update`/`complete`. Use `add_todos` for multiple items.
+### Workflow A: Daily Triage
 
-## Data Model
+1. Call `list_todos` (default `status='pending'`).
+2. Call `add_todo` (single) or `add_todos` (batch) to capture new tasks.
+3. Call `update_todo` or `complete_todo` to keep the list current.
 
-- **Todo:** `id` (string), `description` (1-2000 chars), `priority` (low|medium|high), `category` (work|bug|testing|docs), `completed` (boolean), `dueAt` (optional ISO 8601 offset).
+> **Constraint:** Never guess IDs. Always list first.
 
-## Workflows
+### Workflow B: Cleanup & Verification
 
-### 1) Daily Triage
+1. Call `list_todos` with `status='completed'` to review finished items.
+2. Call `delete_todo` only when the user explicitly wants removal.
+3. Call `list_todos` again to confirm remaining items.
 
-```text
-list_todos(status='pending') → See what is open
-add_todos(...) → Add new items in bulk
-complete_todo(id=...) → Mark finished items
-```
+## 3. Tool Nuances & "Gotchas"
 
-## Tools
+- **`list_todos`**: Defaults to `status='pending'` and returns max 50 items; use `status='all'` to include completed items.
+- **`add_todos`**: Prefer for 2+ items to reduce calls.
+- **`update_todo`**: Requires at least one field; otherwise returns `E_BAD_REQUEST`.
+- **`delete_todo`**: Destructive and non-idempotent—confirm intent first.
+- **Storage behavior**: The JSON file is auto-deleted when all todos are completed.
 
-### add_todo
+## 4. Error Handling Strategy
 
-Create a new task.
-
-- **Use when:** User provides a single, clear task.
-- **Args:** `description` (req), `priority` (req), `category` (req), `dueAt` (opt).
-- **Returns:** `{ item, summary, nextActions }`
-
-### add_todos
-
-Create multiple tasks in one call.
-
-- **Use when:** User provides 2+ tasks or a list.
-- **Args:** `items` (array, 1-50 items).
-- **Returns:** `{ items, summary, nextActions }`
-
-### list_todos
-
-List todos with an optional status filter.
-
-- **Use when:** Checking potential duplicates, finding IDs, or reviewing workload.
-- **Args:** `status` (pending|completed|all, default: pending).
-- **Returns:** `{ items, summary, counts, truncated, hint }`
-
-### update_todo
-
-Update fields on a todo item.
-
-- **Use when:** Renaming, rescheduling, or changing priority/category.
-- **Args:** `id` (req), `description`, `priority`, `category`, `dueAt`.
-- **Returns:** `{ item, summary, nextActions }`
-
-### complete_todo
-
-Mark a todo as completed.
-
-- **Use when:** Task is done.
-- **Args:** `id` (req).
-- **Returns:** `{ item, summary, nextActions }`
-
-### delete_todo
-
-Delete a todo item by ID.
-
-- **Use when:** Removing mistakes or duplicates (prefer completion for finished work).
-- **Args:** `id` (req).
-- **Returns:** `{ deletedIds, summary, nextActions }`
-
-## Response Shape
-
-Success: `{ "ok": true, "result": { ... } }`
-Error: `{ "ok": false, "error": { "code": "...", "message": "..." } }`
-
-### Common Errors
-
-| Code                  | Meaning                   | Resolution                                |
-| --------------------- | ------------------------- | ----------------------------------------- |
-| `E_NOT_FOUND`         | Todo ID does not exist    | List todos to find correct ID             |
-| `E_INVALID_PARAMS`    | Schema validation failed  | Check enums (priority/category) and types |
-| `E_STORAGE_CONFLICT`  | File changed during write | Retry the operation                       |
-| `E_STORAGE_TOO_LARGE` | File exceeds 5MB          | Clean up old todos                        |
-
-## Limits
-
-- **Pagination:** `list_todos` returns max 50 items.
-- **Batch Size:** `add_todos` accepts max 50 items.
-- **Storage:** File is automatically deleted when all tasks are completed.
-
-## Security
-
-- This server writes to a local JSON file (`todos.json` by default). Do not store sensitive credentials or PII in todo descriptions.
+- **`E_NOT_FOUND`**: Call `list_todos` with the right `status` to locate the ID.
+- **`E_INVALID_PARAMS`**: Fix enum values or ISO-8601 date formats.
+- **`E_STORAGE_CONFLICT`**: Re-list then retry the mutation once.
+- **`E_STORAGE_TOO_LARGE`**: Complete/delete old items to reduce size.

package/dist/tools.d.ts

@@ -1,2 +1,3 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function setInitializationGuard(fn: () => boolean): void;
 export declare function registerAllTools(server: McpServer): void;

package/dist/tools.js

@@ -4,6 +4,81 @@ import { runWithRequestContext } from './requestContext.js';
 import { createErrorResponse, createToolResponse, getErrorMessage, } from './responses.js';
 import { AddTodoSchema, AddTodosSchema, CompleteTodoSchema, DefaultOutputSchema, DeleteTodoSchema, ListTodosFilterSchema, UpdateTodoSchema, } from './schema.js';
 import { addTodos, completeTodoById, deleteTodoById, getCodedErrorCode, getTodos, updateTodoById, } from './storage.js';
+const DEFAULT_TOOL_TIMEOUT_MS = 60_000;
+const TOOL_ABORT_ERROR_NAME = 'TodokitToolAbort';
+const TOOL_TIMEOUT_ERROR_NAME = 'TodokitToolTimeout';
+let isInitialized = () => true;
+export function setInitializationGuard(fn) {
+    isInitialized = fn;
+}
+function getToolTimeoutMs() {
+    const raw = process.env.TODOKIT_TOOL_TIMEOUT_MS?.trim();
+    if (!raw)
+        return DEFAULT_TOOL_TIMEOUT_MS;
+    const value = Number(raw);
+    if (!Number.isFinite(value) || !Number.isInteger(value)) {
+        return DEFAULT_TOOL_TIMEOUT_MS;
+    }
+    if (value <= 0)
+        return null;
+    return value;
+}
+function isDefined(value) {
+    return value !== null && value !== undefined;
+}
+function createAbortPromise(signal) {
+    if (!signal)
+        return null;
+    if (signal.aborted) {
+        const error = new Error('Tool cancelled');
+        error.name = TOOL_ABORT_ERROR_NAME;
+        return { promise: Promise.reject(error), cancel: () => undefined };
+    }
+    let listener = null;
+    const promise = new Promise((_, reject) => {
+        listener = () => {
+            const error = new Error('Tool cancelled');
+            error.name = TOOL_ABORT_ERROR_NAME;
+            reject(error);
+        };
+        signal.addEventListener('abort', listener, { once: true });
+    });
+    return {
+        promise,
+        cancel: () => {
+            if (listener) {
+                signal.removeEventListener('abort', listener);
+            }
+        },
+    };
+}
+function createTimeoutPromise(ms, message) {
+    let timeoutId;
+    const promise = new Promise((_, reject) => {
+        timeoutId = setTimeout(() => {
+            const error = new Error(message);
+            error.name = TOOL_TIMEOUT_ERROR_NAME;
+            reject(error);
+        }, ms);
+    });
+    return {
+        promise,
+        cancel: () => {
+            if (timeoutId !== undefined) {
+                clearTimeout(timeoutId);
+            }
+        },
+    };
+}
+function classifyInterruption(error) {
+    if (!(error instanceof Error))
+        return null;
+    if (error.name === TOOL_ABORT_ERROR_NAME)
+        return 'cancelled';
+    if (error.name === TOOL_TIMEOUT_ERROR_NAME)
+        return 'timeout';
+    return null;
+}
 function mapExecutionError(error, fallbackCode) {
     const coded = getCodedErrorCode(error);
     if (coded) {
@@ -56,6 +131,16 @@ function createWrappedHandler(tool, handler) {
         const requestId = randomUUID();
         publishToolCallWithId(tool, input, requestId);
         const start = nowMs();
+        if (!isInitialized()) {
+            const response = createErrorResponse('E_NOT_INITIALIZED', 'Server not initialized');
+            publishSuccessResult(tool, requestId, start, response);
+            return Promise.resolve(response);
+        }
+        if (extra.signal.aborted) {
+            const response = createErrorResponse('E_CANCELLED', 'Tool cancelled');
+            publishSuccessResult(tool, requestId, start, response);
+            return Promise.resolve(response);
+        }
         let result;
         try {
             result = runWithRequestContext({ requestId, tool }, () => handler(input, extra));
@@ -65,12 +150,29 @@ function createWrappedHandler(tool, handler) {
             const rejection = error instanceof Error ? error : new Error(String(error));
             return Promise.reject(rejection);
         }
-        return Promise.resolve(result)
+        const timeoutMs = getToolTimeoutMs();
+        const timeout = timeoutMs
+            ? createTimeoutPromise(timeoutMs, `Tool ${tool} timed out`)
+            : null;
+        const abort = createAbortPromise(extra.signal);
+        const race = Promise.race([Promise.resolve(result), timeout?.promise, abort?.promise].filter(isDefined));
+        return race
+            .finally(() => {
+            timeout?.cancel();
+            abort?.cancel();
+        })
             .then((resolved) => {
             publishSuccessResult(tool, requestId, start, resolved);
             return resolved;
         })
             .catch((error) => {
+            const interruption = classifyInterruption(error);
+            if (interruption) {
+                const code = interruption === 'timeout' ? 'E_TIMEOUT' : 'E_CANCELLED';
+                const response = createErrorResponse(code, error instanceof Error ? error.message : String(error));
+                publishSuccessResult(tool, requestId, start, response);
+                return response;
+            }
             publishFailureResult(tool, requestId, start);
             throw error;
         });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@j0hanz/todokit-mcp",
-  "version": "1.3.3",
+  "version": "1.3.4",
   "mcpName": "io.github.j0hanz/todokit",
   "description": "A MCP server for Todokit, a task management and productivity tool with JSON storage.",
   "type": "module",