omnifocus-mcp-enhanced 1.8.0 → 1.10.0

package/README.md

@@ -44,6 +44,8 @@ Want to see where the project is heading next? See the [roadmap](docs/roadmap/20
 
 ## 🆕 Latest Release
 
+- **v1.10.0** - Major capability expansion: **Tag Management** (`add_tag`, `edit_tag`, `remove_tag`, `search_tags`), **Task Notifications** (`list_task_notifications`, `add_task_notification`, `remove_task_notification` — absolute or due-relative reminders), plus first-class MCP **Prompts** (4 guided review workflows) and **Resources** (3 live JSON snapshots). Now 35 tools, 4 prompts, and 3 resources.
+- **v1.9.0** - Added 3 productivity tools: `append_to_note` (append text to a task/project note without overwriting), `count_tasks` (fast "how many" aggregate queries with a status breakdown, using the same filters as `filter_tasks`), and `duplicate_task` (clone a task with or without its subtasks, optionally renamed).
 - **v1.8.0** - Added full **Folder Management** support: `add_folder`, `edit_folder`, `remove_folder`, `list_folders`, and `get_folder`. Create nested folder hierarchies, rename/move folders (with cycle protection), and inspect folder contents (child projects + subfolders). Note: removing a folder permanently deletes all projects and tasks it contains.
 - **v1.7.0** - Added OmniFocus 4.7+ repeat rule support via `set_repetition_rule` (ICS rule strings, schedule type, anchor date, catch-up, end date, repetition count), mutually exclusive tag support via `exclusiveTags` on add/edit tools, and improved planned-date editing tests.
 - **v1.6.10** - Fixed Inbox task completion via `edit_item`, fixed AppleScript special-character handling for apostrophes/backslashes, fixed JSON result escaping for special characters, and clarified `batch_add_items` / `mcporter` usage with working examples.
@@ -67,6 +69,10 @@ Want to see where the project is heading next? See the [roadmap](docs/roadmap/20
 - **📊 Smart Querying** - Find tasks by ID, name, or complex criteria
 - **🔄 Full CRUD Operations** - Create, read, update, delete tasks and projects
 - **📁 Folder Management** - Full CRUD for folders with nested hierarchy, move/rename, and content inspection
+- **🏷️ Tag Management** - Full CRUD for tags with nesting, status control, and fuzzy search
+- **🔔 Task Notifications** - List, add, and remove reminders (absolute time or relative to due date)
+- **💬 MCP Prompts** - 4 guided review workflows (daily, weekly, inbox processing, project planning)
+- **📡 MCP Resources** - 3 live JSON snapshots (inbox, today, active projects)
 - **📅 Time Management** - Due, defer, planned dates, estimates, and scheduling
 - **🏷️ Advanced Tagging** - Tag-based filtering with exact/partial matching
 - **🚫 Mutually Exclusive Tags** - Automatically respects exclusive tag groups when applying tags
@@ -521,8 +527,48 @@ read_task_attachment {
 21. **list_folders** - 🆕 **NEW**: List all folders with IDs, parents, status, and project counts
 22. **get_folder** - 🆕 **NEW**: Get a single folder with its child projects and subfolders
 
+### ⚡ Productivity Tools (NEW)
+23. **append_to_note** - 🆕 **NEW**: Append text to a task/project note without overwriting
+24. **count_tasks** - 🆕 **NEW**: Fast "how many" queries with a status breakdown (same filters as filter_tasks)
+25. **duplicate_task** - 🆕 **NEW**: Clone a task with/without subtasks, optionally renamed
+
+### 🏷️ Tag Management Tools (NEW)
+26. **list_tags** - List all tags with IDs, parents, and active status
+27. **add_tag** - 🆕 **NEW**: Create a tag, optionally nested under a parent tag
+28. **edit_tag** - 🆕 **NEW**: Rename, change status (active/onHold/dropped), or move a tag
+29. **remove_tag** - 🆕 **NEW**: Delete a tag (tasks are kept, they just lose the tag)
+30. **search_tags** - 🆕 **NEW**: Search tags by name (fuzzy or exact)
+
+### 🔔 Notification Tools (NEW)
+31. **list_task_notifications** - 🆕 **NEW**: List reminders set on a task
+32. **add_task_notification** - 🆕 **NEW**: Add a reminder (absolute time or minutes relative to due date)
+33. **remove_task_notification** - 🆕 **NEW**: Remove a reminder by index, or remove all
+
 ### 📊 Analytics & Tracking
-23. **get_today_completed_tasks** - View today's completed tasks
+34. **get_today_completed_tasks** - View today's completed tasks
+
+> Note: `get_tasks_by_tag` (#14) and `list_tags` (#26) were available in earlier versions; the tag CRUD tools are new in v1.10.0.
+
+## 💬 MCP Prompts (NEW in v1.10.0)
+
+Guided review workflows that pull live OmniFocus data and hand the AI a structured plan of attack. In clients like Claude Desktop these appear as selectable prompts.
+
+| Prompt | Arguments | What it does |
+|---|---|---|
+| **daily_review** | – | Pulls overdue, due-soon, and flagged tasks; produces today's top 3 priorities |
+| **weekly_review** | – | GTD weekly review: classifies active projects as on track / at risk / stalled, proposes next actions |
+| **inbox_processing** | – | Walks inbox items one by one through GTD clarification (delete/defer/delegate/keep) |
+| **project_planning** | `project` | Breaks a project into sequenced, estimated next actions (fuzzy-matches the project name) |
+
+## 📡 MCP Resources (NEW in v1.10.0)
+
+Live JSON snapshots your AI client can read without calling a tool.
+
+| Resource URI | Contents |
+|---|---|
+| `omnifocus://inbox` | Current inbox tasks |
+| `omnifocus://today` | Overdue + due today + flagged, grouped |
+| `omnifocus://projects` | Active projects with task counts and stalled detection |
 
 Batch move feature roadmap (future): [docs/roadmap/2026-02-25-batch-move-tasks-plan.md](docs/roadmap/2026-02-25-batch-move-tasks-plan.md)
 
@@ -655,6 +701,78 @@ edit_folder {"name": "Key Clients", "newParentFolderName": ""}
 remove_folder {"name": "Old Archive"}
 ```
 
+### ⚡ Productivity Tools
+
+```bash
+# Append a progress note without overwriting the existing note
+append_to_note {
+  "itemType": "task",
+  "name": "Write report",
+  "text": "Drafted section 1 today"
+}
+
+# Fast count: how many flagged tasks are still actionable?
+count_tasks {
+  "flagged": true,
+  "taskStatus": ["Available", "Next", "DueSoon", "Overdue"]
+}
+
+# How many tasks remain in a project (by status breakdown)
+count_tasks {"projectFilter": "Website Redesign"}
+
+# Duplicate a task template with its subtasks
+duplicate_task {
+  "name": "Weekly Review Checklist",
+  "newName": "Weekly Review - 2026-03-02"
+}
+
+# Duplicate without subtasks
+duplicate_task {"taskId": "abc123", "includeSubtasks": false}
+```
+
+### 🏷️ Tag Management
+
+```bash
+# Search and list tags
+search_tags {"query": "work"}
+list_tags {"includeInactive": false}
+
+# Create a tag, optionally nested
+add_tag {"name": "Deep Work"}
+add_tag {"name": "Client A", "parentTagName": "Clients"}
+
+# Rename, pause, or move a tag ("" moves to root)
+edit_tag {"name": "Deep Work", "newName": "Focus"}
+edit_tag {"name": "Focus", "newStatus": "onHold"}
+edit_tag {"name": "Client A", "newParentTagName": ""}
+
+# Delete a tag (tasks are kept, they just lose the tag)
+remove_tag {"name": "Obsolete"}
+```
+
+### 🔔 Task Notifications
+
+```bash
+# See what reminders a task has
+list_task_notifications {"taskName": "Submit report"}
+
+# Remind at a fixed time
+add_task_notification {
+  "taskName": "Submit report",
+  "absoluteDate": "2026-03-05T09:00:00"
+}
+
+# Remind 30 minutes before the due date (requires a due date)
+add_task_notification {
+  "taskName": "Submit report",
+  "relativeMinutes": -30
+}
+
+# Remove one by index, or clear them all
+remove_task_notification {"taskName": "Submit report", "index": 0}
+remove_task_notification {"taskName": "Submit report", "removeAll": true}
+```
+
 ## 🔧 Configuration
 
 ### Claude Code

package/dist/context/omnifocusData.js

@@ -0,0 +1,60 @@
+import { executeOmniFocusScript } from '../utils/scriptExecution.js';
+import { applyClientSideFilters } from '../tools/primitives/filterTasks.js';
+/**
+ * Fetch raw task data using the shared OmniJS filter script, applying the
+ * same client-side filters as filter_tasks. Returns structured objects
+ * (not formatted markdown) so prompts and resources can serialize them.
+ */
+export async function fetchTasks(options = {}, limit = 1000) {
+    const result = await executeOmniFocusScript('@filterTasks.js', {
+        ...options,
+        perspective: options.perspective || 'all',
+        exactTagMatch: options.exactTagMatch ?? false,
+        limit: Math.max(limit * 5, 2000),
+        sortBy: options.sortBy || 'name',
+        sortOrder: options.sortOrder || 'asc'
+    });
+    if (!result || typeof result !== 'object') {
+        return [];
+    }
+    const data = result;
+    if (data.error) {
+        throw new Error(data.error);
+    }
+    const tasks = Array.isArray(data.tasks) ? data.tasks : [];
+    return applyClientSideFilters(tasks, options).slice(0, limit);
+}
+/**
+ * Compact a task down to the fields useful for planning prompts.
+ */
+export function slimTask(task) {
+    return {
+        id: task.id,
+        name: task.name,
+        note: task.note || '',
+        status: task.taskStatus || null,
+        flagged: !!task.flagged,
+        dueDate: task.dueDate || null,
+        deferDate: task.deferDate || null,
+        plannedDate: task.plannedDate || null,
+        estimatedMinutes: task.estimatedMinutes ?? null,
+        projectName: task.projectName || null,
+        inInbox: !!task.inInbox,
+        tags: (task.tags || []).map(tag => tag.name)
+    };
+}
+/**
+ * Fetch projects with task counts and stalled detection.
+ * status: 'active' | 'onHold' | 'done' | 'dropped' | 'all'
+ */
+export async function fetchProjects(status = 'active', limit = 500) {
+    const result = await executeOmniFocusScript('@listProjects.js', { status, limit });
+    const data = typeof result === 'string' ? JSON.parse(result) : result;
+    if (!data || typeof data !== 'object') {
+        return [];
+    }
+    if (data.success !== true) {
+        throw new Error(data.error || 'Unable to list OmniFocus projects');
+    }
+    return Array.isArray(data.projects) ? data.projects : [];
+}

package/dist/context/prompts.js

@@ -0,0 +1,156 @@
+import { z } from 'zod';
+import { fetchTasks, fetchProjects, slimTask } from './omnifocusData.js';
+function userMessage(text) {
+    return {
+        messages: [
+            {
+                role: 'user',
+                content: { type: 'text', text }
+            }
+        ]
+    };
+}
+const ENGAGEMENT_PROTOCOL = `engagement protocol:
+- ground every recommendation in the omnifocus data provided below.
+- keep clarification questions minimal; only ask when genuinely blocked.
+- after presenting the plan, ask whether to apply the changes in omnifocus now.
+- if the user approves, execute the tool calls and report the created/updated ids.
+- always ask for explicit confirmation before destructive operations
+  (remove_item, batch_remove_items, remove_folder, remove_tag).`;
+export function registerPrompts(server) {
+    // 1. Daily review
+    server.prompt('daily_review', 'daily planning review with overdue, due-soon, and flagged tasks.', async () => {
+        const [overdue, dueSoon, flagged] = await Promise.all([
+            fetchTasks({ overdue: true, taskStatus: ['Overdue'] }, 50),
+            fetchTasks({ dueThisWeek: true, taskStatus: ['Available', 'Next', 'DueSoon'] }, 50),
+            fetchTasks({ flagged: true, taskStatus: ['Available', 'Next', 'DueSoon', 'Overdue', 'Blocked'] }, 50)
+        ]);
+        const text = `run a focused daily review using the omnifocus data below.
+
+1) identify the highest-risk overdue items.
+2) review due-soon tasks and sequence today's execution.
+3) evaluate flagged work and confirm whether it is genuinely urgent.
+4) produce exactly three top priorities for today, each with a short rationale.
+5) call out anything that should be deferred, delegated, or dropped.
+
+${ENGAGEMENT_PROTOCOL}
+
+overdue_tasks_json:
+${JSON.stringify(overdue.map(slimTask))}
+
+due_soon_tasks_json:
+${JSON.stringify(dueSoon.map(slimTask))}
+
+flagged_tasks_json:
+${JSON.stringify(flagged.map(slimTask))}
+`;
+        return userMessage(text);
+    });
+    // 2. Weekly review
+    server.prompt('weekly_review', 'gtd-style weekly review with active projects and next-action coverage.', async () => {
+        const [projects, availableTasks] = await Promise.all([
+            fetchProjects('active', 500),
+            fetchTasks({ taskStatus: ['Available', 'Next'] }, 1000)
+        ]);
+        const stalled = projects.filter(project => project.isStalled);
+        const text = `run a gtd-style weekly review using the omnifocus data below.
+
+1) review all active projects and classify each as: on track, at risk, or stalled.
+2) a project is stalled when work remains but no task is available or next.
+   the data already flags these with "isStalled": true.
+3) propose one concrete next action for every stalled project.
+4) highlight projects that need due/defer date changes or scope adjustments.
+5) produce a concise weekly plan:
+   - top 5 project priorities
+   - key risks and blockers
+   - cleanup actions (drop, defer, delegate, or someday/maybe)
+
+${ENGAGEMENT_PROTOCOL}
+
+active_projects_json:
+${JSON.stringify(projects)}
+
+stalled_projects_json:
+${JSON.stringify(stalled)}
+
+available_tasks_json:
+${JSON.stringify(availableTasks.map(slimTask))}
+`;
+        return userMessage(text);
+    });
+    // 3. Inbox processing
+    server.prompt('inbox_processing', 'gtd inbox processing session with one-by-one clarification decisions.', async () => {
+        const inboxTasks = await fetchTasks({ perspective: 'inbox' }, 200);
+        const text = `run a gtd inbox processing session using the inbox data below.
+
+for each inbox item, guide a decision in this order:
+1) clarify the desired outcome and the very next action.
+2) decide whether to delete, defer, delegate, or keep it.
+3) if kept, assign the best target project (or keep in inbox if truly unassigned).
+4) propose relevant tags and whether it should be flagged.
+5) suggest due/defer dates only when there is a real deadline or start date.
+6) suggest estimated minutes when the task is actionable.
+
+respond with:
+- a prioritized processing queue
+- concrete update recommendations per item
+- a short batch action plan for the first five items
+
+${ENGAGEMENT_PROTOCOL}
+
+inbox_items_json:
+${JSON.stringify(inboxTasks.map(slimTask))}
+`;
+        return userMessage(text);
+    });
+    // 4. Project planning
+    server.prompt('project_planning', 'turn a project into clear, sequenced, executable next actions.', { project: z.string().describe('the name of the project to plan') }, async ({ project }) => {
+        const projectName = (project || '').trim();
+        if (projectName === '') {
+            throw new Error('project must not be empty.');
+        }
+        const allProjects = await fetchProjects('all', 1000);
+        const needle = projectName.toLowerCase();
+        const match = allProjects.find(candidate => candidate.name.toLowerCase() === needle) ||
+            allProjects.find(candidate => candidate.name.toLowerCase().includes(needle)) ||
+            null;
+        const projectTasks = match
+            ? await fetchTasks({ projectFilter: match.name, taskStatus: ['Available', 'Next', 'Blocked', 'DueSoon', 'Overdue'] }, 500)
+            : [];
+        const projectDetails = match
+            ? match
+            : { name: projectName, status: 'not_found', lookupNote: 'no matching project in omnifocus' };
+        const text = `plan this project into clear executable work.
+
+project name:
+${projectName}
+
+planning goals:
+1) summarize the project outcome in one concise sentence.
+2) evaluate current task coverage and identify missing steps.
+3) convert vague items into concrete next actions (verb-first, observable).
+4) sequence the work logically (dependencies first, then parallelizable actions).
+5) estimate effort in minutes for each next action and flag high-risk items.
+6) recommend what to do now, next, and later, plus what to defer or drop.
+
+output format:
+- project summary
+- work breakdown table: action | estimate | priority | dependency | suggested tags | due/defer | rationale
+- the first three actions to execute immediately
+- risk and blocker list with mitigation ideas
+
+notes:
+- if the project status is "not_found", plan from user intent and then ask
+  whether to create the project in omnifocus.
+
+${ENGAGEMENT_PROTOCOL}
+
+project_details_json:
+${JSON.stringify(projectDetails)}
+
+project_tasks_json:
+${JSON.stringify(projectTasks.map(slimTask))}
+`;
+        return userMessage(text);
+    });
+}

package/dist/context/resources.js

@@ -0,0 +1,57 @@
+import { fetchTasks, fetchProjects, slimTask } from './omnifocusData.js';
+function jsonResource(uri, payload) {
+    return {
+        contents: [
+            {
+                uri,
+                mimeType: 'application/json',
+                text: JSON.stringify(payload, null, 2)
+            }
+        ]
+    };
+}
+export function registerResources(server) {
+    // 1. Inbox snapshot
+    server.resource('inbox', 'omnifocus://inbox', {
+        description: 'Current OmniFocus inbox tasks (uncompleted, unprocessed items).',
+        mimeType: 'application/json'
+    }, async () => {
+        const tasks = await fetchTasks({ perspective: 'inbox' }, 200);
+        return jsonResource('omnifocus://inbox', {
+            snapshotAt: new Date().toISOString(),
+            count: tasks.length,
+            tasks: tasks.map(slimTask)
+        });
+    });
+    // 2. Today snapshot (overdue + due today + flagged)
+    server.resource('today', 'omnifocus://today', {
+        description: "Today's OmniFocus focus: overdue tasks, tasks due today, and flagged tasks.",
+        mimeType: 'application/json'
+    }, async () => {
+        const [overdue, dueToday, flagged] = await Promise.all([
+            fetchTasks({ overdue: true, taskStatus: ['Overdue'] }, 100),
+            fetchTasks({ dueToday: true, taskStatus: ['Available', 'Next', 'DueSoon', 'Overdue'] }, 100),
+            fetchTasks({ flagged: true, taskStatus: ['Available', 'Next', 'DueSoon', 'Overdue', 'Blocked'] }, 100)
+        ]);
+        return jsonResource('omnifocus://today', {
+            snapshotAt: new Date().toISOString(),
+            overdue: { count: overdue.length, tasks: overdue.map(slimTask) },
+            dueToday: { count: dueToday.length, tasks: dueToday.map(slimTask) },
+            flagged: { count: flagged.length, tasks: flagged.map(slimTask) }
+        });
+    });
+    // 3. Active projects snapshot
+    server.resource('projects', 'omnifocus://projects', {
+        description: 'All active OmniFocus projects with task counts and stalled-project detection.',
+        mimeType: 'application/json'
+    }, async () => {
+        const projects = await fetchProjects('active', 500);
+        const stalled = projects.filter(project => project.isStalled);
+        return jsonResource('omnifocus://projects', {
+            snapshotAt: new Date().toISOString(),
+            count: projects.length,
+            stalledCount: stalled.length,
+            projects
+        });
+    });
+}

package/dist/server.js

@@ -31,10 +31,26 @@ import * as editFolderTool from './tools/definitions/editFolder.js';
 import * as removeFolderTool from './tools/definitions/removeFolder.js';
 import * as listFoldersTool from './tools/definitions/listFolders.js';
 import * as getFolderTool from './tools/definitions/getFolder.js';
+// Import productivity tools
+import * as appendToNoteTool from './tools/definitions/appendToNote.js';
+import * as countTasksTool from './tools/definitions/countTasks.js';
+import * as duplicateTaskTool from './tools/definitions/duplicateTask.js';
+// Import tag management tools
+import * as addTagTool from './tools/definitions/addTag.js';
+import * as editTagTool from './tools/definitions/editTag.js';
+import * as removeTagTool from './tools/definitions/removeTag.js';
+import * as searchTagsTool from './tools/definitions/searchTags.js';
+// Import notification tools
+import * as listTaskNotificationsTool from './tools/definitions/listTaskNotifications.js';
+import * as addTaskNotificationTool from './tools/definitions/addTaskNotification.js';
+import * as removeTaskNotificationTool from './tools/definitions/removeTaskNotification.js';
+// Import prompts and resources
+import { registerPrompts } from './context/prompts.js';
+import { registerResources } from './context/resources.js';
 // Create an MCP server
 const server = new McpServer({
     name: "OmniFocus MCP",
-    version: "1.8.0"
+    version: "1.10.0"
 });
 // Register tools
 server.tool("dump_database", "Gets the current state of your OmniFocus database", dumpDatabaseTool.schema.shape, dumpDatabaseTool.handler);
@@ -66,6 +82,22 @@ server.tool("edit_folder", "Rename a folder or move it under a different parent
 server.tool("remove_folder", "Remove a folder from OmniFocus. WARNING: this also permanently deletes all projects and tasks contained in the folder.", removeFolderTool.schema.shape, removeFolderTool.handler);
 server.tool("list_folders", "List all OmniFocus folders with IDs, parent relationships, status, and project counts without loading tasks.", listFoldersTool.schema.shape, listFoldersTool.handler);
 server.tool("get_folder", "Get a single OmniFocus folder by ID or name, including its child projects and subfolders.", getFolderTool.schema.shape, getFolderTool.handler);
+// Productivity tools
+server.tool("append_to_note", "Append text to a task or project note without overwriting the existing note. Useful for logging progress or adding context.", appendToNoteTool.schema.shape, appendToNoteTool.handler);
+server.tool("count_tasks", "Count tasks matching filters without returning the full list. Fast 'how many' queries that return a total plus a breakdown by status. Uses the same filters as filter_tasks.", countTasksTool.schema.shape, countTasksTool.handler);
+server.tool("duplicate_task", "Duplicate an existing task, optionally with its subtasks, and optionally with a new name. Useful for template-based workflows.", duplicateTaskTool.schema.shape, duplicateTaskTool.handler);
+// Tag management tools
+server.tool("add_tag", "Create a new tag in OmniFocus, optionally nested under a parent tag.", addTagTool.schema.shape, addTagTool.handler);
+server.tool("edit_tag", "Rename a tag, change its status (active/onHold/dropped), or move it under a different parent tag (empty string moves to root).", editTagTool.schema.shape, editTagTool.handler);
+server.tool("remove_tag", "Delete a tag from OmniFocus. Tasks are not deleted; they simply lose the tag. Child tags are deleted with the parent.", removeTagTool.schema.shape, removeTagTool.handler);
+server.tool("search_tags", "Search OmniFocus tags by name with fuzzy or exact matching.", searchTagsTool.schema.shape, searchTagsTool.handler);
+// Notification tools
+server.tool("list_task_notifications", "List all notifications (reminders) set on a task, with their kind and fire time.", listTaskNotificationsTool.schema.shape, listTaskNotificationsTool.handler);
+server.tool("add_task_notification", "Add a notification (reminder) to a task. Use absoluteDate for a fixed time, or relativeMinutes for an offset from the task's due date (negative = before due).", addTaskNotificationTool.schema.shape, addTaskNotificationTool.handler);
+server.tool("remove_task_notification", "Remove a notification from a task by 0-based index, or remove all notifications with removeAll.", removeTaskNotificationTool.schema.shape, removeTaskNotificationTool.handler);
+// Register prompts (guided review workflows) and resources (live snapshots)
+registerPrompts(server);
+registerResources(server);
 // Start the MCP server
 const transport = new StdioServerTransport();
 // Use await with server.connect to ensure proper connection

package/dist/tools/definitions/addTag.js

@@ -0,0 +1,34 @@
+import { z } from 'zod';
+import { addTag } from '../primitives/addTag.js';
+export const schema = z.object({
+    name: z.string().describe('The name of the tag'),
+    parentTagName: z.string().optional().describe('The name of the parent tag to nest this tag under (created at the root level if not specified)')
+});
+export async function handler(args, _extra) {
+    try {
+        const result = await addTag(args);
+        if (result.success) {
+            const locationText = args.parentTagName
+                ? `under tag "${args.parentTagName}"`
+                : 'at the root level';
+            return {
+                content: [{
+                        type: 'text',
+                        text: `✅ Tag "${args.name}" created successfully ${locationText}.\n\nid: ${result.tagId}`
+                    }]
+            };
+        }
+        return {
+            content: [{ type: 'text', text: `Failed to create tag: ${result.error}` }],
+            isError: true
+        };
+    }
+    catch (err) {
+        const error = err;
+        console.error(`Tool execution error: ${error.message}`);
+        return {
+            content: [{ type: 'text', text: `Error creating tag: ${error.message}` }],
+            isError: true
+        };
+    }
+}

package/dist/tools/definitions/addTaskNotification.js

@@ -0,0 +1,35 @@
+import { z } from 'zod';
+import { addTaskNotification, formatNotification } from '../primitives/taskNotifications.js';
+export const schema = z.object({
+    taskId: z.string().optional().describe('The ID of the task'),
+    taskName: z.string().optional().describe('The name of the task (as fallback if ID not provided)'),
+    absoluteDate: z.string().optional().describe('Absolute notification time in ISO 8601 format (e.g. 2026-03-05T09:00:00). Use this OR relativeMinutes, not both.'),
+    relativeMinutes: z.number().optional().describe('Minutes relative to the task due date. Negative means before the due date (e.g. -30 = 30 minutes before). Requires the task to have a due date.')
+});
+export async function handler(args, _extra) {
+    try {
+        const result = await addTaskNotification(args);
+        if (!result.success) {
+            return {
+                content: [{ type: 'text', text: `Failed to add notification: ${result.error}` }],
+                isError: true
+            };
+        }
+        const total = (result.notifications || []).length;
+        const addedText = result.added ? formatNotification(result.added) : 'notification added';
+        return {
+            content: [{
+                    type: 'text',
+                    text: `✅ Added notification to "${result.taskName}".\n${addedText}\n\nTotal notifications: ${total}`
+                }]
+        };
+    }
+    catch (err) {
+        const error = err;
+        console.error(`Tool execution error: ${error.message}`);
+        return {
+            content: [{ type: 'text', text: `Error adding notification: ${error.message}` }],
+            isError: true
+        };
+    }
+}

package/dist/tools/definitions/appendToNote.js

@@ -0,0 +1,41 @@
+import { z } from 'zod';
+import { appendToNote } from '../primitives/appendToNote.js';
+export const schema = z.object({
+    id: z.string().optional().describe('The ID of the task or project'),
+    name: z.string().optional().describe('The name of the task or project (as fallback if ID not provided)'),
+    itemType: z.enum(['task', 'project']).describe("Type of item whose note to append to ('task' or 'project')"),
+    text: z.string().describe('The text to append to the existing note'),
+    separator: z.string().optional().describe('Separator inserted between the existing note and the new text (default: a newline). Pass an empty string to append with no separator.')
+});
+export async function handler(args, _extra) {
+    try {
+        if (!args.id && !args.name) {
+            return {
+                content: [{ type: 'text', text: 'Either id or name must be provided to append to a note.' }],
+                isError: true
+            };
+        }
+        const result = await appendToNote(args);
+        if (result.success) {
+            const itemTypeLabel = args.itemType === 'task' ? 'Task' : 'Project';
+            return {
+                content: [{
+                        type: 'text',
+                        text: `✅ Appended text to ${itemTypeLabel} "${result.name}" note.\n\nid: ${result.id}`
+                    }]
+            };
+        }
+        return {
+            content: [{ type: 'text', text: `Failed to append to note: ${result.error}` }],
+            isError: true
+        };
+    }
+    catch (err) {
+        const error = err;
+        console.error(`Tool execution error: ${error.message}`);
+        return {
+            content: [{ type: 'text', text: `Error appending to note: ${error.message}` }],
+            isError: true
+        };
+    }
+}

package/dist/tools/definitions/countTasks.js

@@ -0,0 +1,41 @@
+import { z } from 'zod';
+import { countTasks } from '../primitives/countTasks.js';
+export const schema = z.object({
+    taskStatus: z.array(z.string()).optional().describe('Filter by task status: Available, Next, Blocked, DueSoon, Overdue, Completed, Dropped'),
+    perspective: z.enum(['inbox', 'flagged', 'all']).optional().describe("Scope: 'inbox', 'flagged', or 'all' (default: all)"),
+    projectFilter: z.string().optional().describe('Only count tasks in projects whose name contains this text'),
+    tagFilter: z.union([z.string(), z.array(z.string())]).optional().describe('Only count tasks with these tags'),
+    exactTagMatch: z.boolean().optional().describe('Require exact tag name match (default: false)'),
+    flagged: z.boolean().optional().describe('Only count flagged (true) or unflagged (false) tasks'),
+    searchText: z.string().optional().describe('Only count tasks whose name or note contains this text'),
+    dueToday: z.boolean().optional().describe('Only count tasks due today'),
+    dueThisWeek: z.boolean().optional().describe('Only count tasks due this week'),
+    overdue: z.boolean().optional().describe('Only count overdue tasks'),
+    completedToday: z.boolean().optional().describe('Only count tasks completed today'),
+    completedThisWeek: z.boolean().optional().describe('Only count tasks completed this week'),
+    plannedToday: z.boolean().optional().describe('Only count tasks planned for today'),
+    plannedThisWeek: z.boolean().optional().describe('Only count tasks planned for this week')
+});
+export async function handler(args, _extra) {
+    try {
+        const result = await countTasks(args);
+        const statusEntries = Object.entries(result.byStatus).sort((a, b) => b[1] - a[1]);
+        const breakdown = statusEntries.length > 0
+            ? statusEntries.map(([status, count]) => `- ${status}: ${count}`).join('\n')
+            : '- (no matching tasks)';
+        return {
+            content: [{
+                    type: 'text',
+                    text: `# Task Count\n\n**Total: ${result.total}**\n\nBy status:\n${breakdown}`
+                }]
+        };
+    }
+    catch (err) {
+        const error = err;
+        console.error(`Tool execution error: ${error.message}`);
+        return {
+            content: [{ type: 'text', text: `Error counting tasks: ${error.message}` }],
+            isError: true
+        };
+    }
+}