omnifocus-mcp-enhanced 1.8.0 → 1.9.0

package/README.md

@@ -44,6 +44,7 @@ Want to see where the project is heading next? See the [roadmap](docs/roadmap/20
 
 ## 🆕 Latest Release
 
+- **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.
@@ -521,8 +522,13 @@ 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
+
 ### 📊 Analytics & Tracking
-23. **get_today_completed_tasks** - View today's completed tasks
+26. **get_today_completed_tasks** - View today's completed tasks
 
 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 +661,35 @@ 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}
+```
+
 ## 🔧 Configuration
 
 ### Claude Code

package/dist/server.js

@@ -31,10 +31,14 @@ 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';
 // Create an MCP server
 const server = new McpServer({
     name: "OmniFocus MCP",
-    version: "1.8.0"
+    version: "1.9.0"
 });
 // Register tools
 server.tool("dump_database", "Gets the current state of your OmniFocus database", dumpDatabaseTool.schema.shape, dumpDatabaseTool.handler);
@@ -66,6 +70,10 @@ 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);
 // Start the MCP server
 const transport = new StdioServerTransport();
 // Use await with server.connect to ensure proper connection

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
+        };
+    }
+}

package/dist/tools/definitions/duplicateTask.js

@@ -0,0 +1,42 @@
+import { z } from 'zod';
+import { duplicateTask } from '../primitives/duplicateTask.js';
+export const schema = z.object({
+    taskId: z.string().optional().describe('The ID of the task to duplicate'),
+    taskName: z.string().optional().describe('The name of the task to duplicate (as fallback if ID not provided)'),
+    newName: z.string().optional().describe('Optional new name for the duplicated task (keeps the original name if omitted)'),
+    includeSubtasks: z.boolean().optional().describe('Whether to include the task\'s subtasks in the copy (default: true)')
+});
+export async function handler(args, _extra) {
+    try {
+        if (!args.taskId && !args.taskName) {
+            return {
+                content: [{ type: 'text', text: 'Either taskId or taskName must be provided to duplicate a task.' }],
+                isError: true
+            };
+        }
+        const result = await duplicateTask(args);
+        if (result.success) {
+            const subtaskText = (result.childrenCount && result.childrenCount > 0)
+                ? ` with ${result.childrenCount} subtask(s)`
+                : '';
+            return {
+                content: [{
+                        type: 'text',
+                        text: `✅ Duplicated task as "${result.name}"${subtaskText}.\n\nid: ${result.newTaskId}`
+                    }]
+            };
+        }
+        return {
+            content: [{ type: 'text', text: `Failed to duplicate task: ${result.error}` }],
+            isError: true
+        };
+    }
+    catch (err) {
+        const error = err;
+        console.error(`Tool execution error: ${error.message}`);
+        return {
+            content: [{ type: 'text', text: `Error duplicating task: ${error.message}` }],
+            isError: true
+        };
+    }
+}

package/dist/tools/primitives/appendToNote.js

@@ -0,0 +1,122 @@
+import { executeAppleScript } from '../../utils/scriptExecution.js';
+import { buildAppleScriptJsonHelpers } from '../../utils/appleScriptJson.js';
+import { escapeAppleScriptString } from '../../utils/appleScriptString.js';
+/**
+ * Generate pure AppleScript that appends text to an item's note without overwriting.
+ */
+export function generateAppleScript(params) {
+    const id = params.id ? escapeAppleScriptString(params.id) : '';
+    const name = params.name ? escapeAppleScriptString(params.name) : '';
+    const itemType = params.itemType;
+    const singularTypeLabel = itemType === 'task' ? 'task' : 'project';
+    const listName = itemType === 'task' ? 'flattened tasks' : 'flattened projects';
+    const appendText = escapeAppleScriptString(params.text);
+    // Separator handling:
+    // - Default (undefined): use AppleScript's `linefeed` constant for a real newline.
+    // - Explicit string: embed it as an escaped literal (empty string means no separator).
+    const useDefaultNewline = params.separator === undefined;
+    const separatorExpr = useDefaultNewline
+        ? 'linefeed'
+        : `"${escapeAppleScriptString(params.separator)}"`;
+    const jsonHelpers = buildAppleScriptJsonHelpers();
+    if (!id && !name) {
+        return `return "{\\\"success\\\":false,\\\"error\\\":\\\"Either id or name must be provided\\\"}"`;
+    }
+    if (!params.text) {
+        return `return "{\\\"success\\\":false,\\\"error\\\":\\\"text must be provided\\\"}"`;
+    }
+    let script = `
+${jsonHelpers}
+  try
+    tell application "OmniFocus"
+      tell front document
+        -- Find the item
+        set foundItem to missing value
+`;
+    if (id) {
+        script += `
+        -- Try to find by ID first
+        try
+          set foundItem to first ${itemType === 'task' ? 'flattened task' : 'flattened project'} where id = "${id}"
+        end try
+`;
+    }
+    if (name) {
+        script += `
+        -- Resolve by name with duplicate protection
+        if foundItem is missing value then
+          set nameMatches to (${listName} where name = "${name}")
+          set nameMatchCount to count of nameMatches
+
+          if nameMatchCount = 1 then
+            set foundItem to item 1 of nameMatches
+          else if nameMatchCount > 1 then
+            return "{\\\"success\\\":false,\\\"error\\\":\\"" & my jsonEscape("Ambiguous ${singularTypeLabel} name: ${name}. Multiple matches found; please use id.") & "\\\"}"
+          end if
+        end if
+`;
+    }
+    script += `
+        if foundItem is not missing value then
+          set itemName to name of foundItem
+          set itemId to id of foundItem as string
+
+          -- Read the existing note (may be empty)
+          set existingNote to note of foundItem
+          if existingNote is missing value then
+            set existingNote to ""
+          end if
+
+          -- Append text, using the separator only when there is existing content
+          if existingNote is "" then
+            set newNote to "${appendText}"
+          else
+            set newNote to existingNote & ${separatorExpr} & "${appendText}"
+          end if
+
+          set note of foundItem to newNote
+
+          return "{\\\"success\\\":true,\\\"id\\\":\\"" & my jsonEscape(itemId) & "\\",\\\"name\\\":\\"" & my jsonEscape(itemName) & "\\\"}"
+        else
+          return "{\\\"success\\\":false,\\\"error\\\":\\\"Item not found\\\"}"
+        end if
+      end tell
+    end tell
+  on error errorMessage
+    return "{\\\"success\\\":false,\\\"error\\\":\\"" & my jsonEscape(errorMessage) & "\\\"}"
+  end try
+  `;
+    return script;
+}
+/**
+ * Append text to a task or project note in OmniFocus (non-destructive).
+ */
+export async function appendToNote(params) {
+    try {
+        if (!params.id && !params.name) {
+            return { success: false, error: 'Either id or name must be provided' };
+        }
+        if (!params.text) {
+            return { success: false, error: 'text must be provided' };
+        }
+        const script = generateAppleScript(params);
+        console.error('Executing AppleScript for note append...');
+        const stdout = await executeAppleScript(script);
+        console.error('AppleScript stdout:', stdout);
+        try {
+            const result = JSON.parse(stdout);
+            if (!result.success) {
+                return { success: false, error: result.error };
+            }
+            return { success: true, id: result.id, name: result.name };
+        }
+        catch (parseError) {
+            console.error('Error parsing AppleScript result:', parseError);
+            return { success: false, error: `Failed to parse result: ${stdout}` };
+        }
+    }
+    catch (error) {
+        console.error('Error in appendToNote:', error);
+        return { success: false, error: error?.message || 'Unknown error in appendToNote' };
+    }
+}

package/dist/tools/primitives/appendToNote.test.js

@@ -0,0 +1,45 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { generateAppleScript } from './appendToNote.js';
+test('appendToNote appends with a real newline (linefeed) separator by default', () => {
+    const script = generateAppleScript({
+        itemType: 'task',
+        name: 'My Task',
+        text: 'progress update'
+    });
+    // Reads existing note, appends using AppleScript's linefeed constant (real newline).
+    assert.match(script, /set existingNote to note of foundItem/);
+    assert.match(script, /set newNote to existingNote & linefeed & "progress update"/);
+    assert.match(script, /set note of foundItem to newNote/);
+});
+test('appendToNote respects an explicit empty separator', () => {
+    const script = generateAppleScript({
+        itemType: 'task',
+        name: 'My Task',
+        text: 'more',
+        separator: ''
+    });
+    assert.match(script, /set newNote to existingNote & "" & "more"/);
+});
+test('appendToNote targets flattened projects when itemType is project', () => {
+    const script = generateAppleScript({
+        itemType: 'project',
+        name: 'My Project',
+        text: 'note'
+    });
+    assert.match(script, /flattened projects where name = "My Project"/);
+    assert.doesNotMatch(script, /flattened tasks where name = "My Project"/);
+});
+test('appendToNote keeps apostrophes and doubles backslashes in text', () => {
+    const script = generateAppleScript({
+        itemType: 'task',
+        name: 'T',
+        text: "didn't work in C:\\Temp"
+    });
+    assert.match(script, /didn't work in C:\\\\Temp/);
+    assert.doesNotMatch(script, /\\'/);
+});
+test('appendToNote errors when neither id nor name provided', () => {
+    const script = generateAppleScript({ itemType: 'task', text: 'x' });
+    assert.match(script, /Either id or name must be provided/);
+});

package/dist/tools/primitives/countTasks.js

@@ -0,0 +1,34 @@
+import { executeOmniFocusScript } from '../../utils/scriptExecution.js';
+import { applyClientSideFilters } from './filterTasks.js';
+/**
+ * Count tasks matching the given filters without returning the full task list.
+ * Reuses the same OmniJS filter script and client-side filters as filter_tasks,
+ * but returns only aggregate counts (fast "how many" queries, low token cost).
+ */
+export async function countTasks(options = {}) {
+    const { perspective = 'all', exactTagMatch = false, sortBy = 'name', sortOrder = 'asc' } = options;
+    // Fetch a large set so client-side filters (tags/defer/planned) have full data.
+    const result = await executeOmniFocusScript('@filterTasks.js', {
+        ...options,
+        perspective,
+        exactTagMatch,
+        limit: 100000,
+        sortBy,
+        sortOrder
+    });
+    if (result && typeof result === 'object') {
+        const data = result;
+        if (data.error) {
+            throw new Error(data.error);
+        }
+        const tasks = Array.isArray(data.tasks) ? data.tasks : [];
+        const filtered = applyClientSideFilters(tasks, options);
+        const byStatus = {};
+        for (const task of filtered) {
+            const status = (task && task.taskStatus) ? String(task.taskStatus) : 'Unknown';
+            byStatus[status] = (byStatus[status] || 0) + 1;
+        }
+        return { total: filtered.length, byStatus };
+    }
+    throw new Error('Unexpected result format from OmniFocus');
+}

package/dist/tools/primitives/duplicateTask.js

@@ -0,0 +1,27 @@
+import { executeOmniFocusScript } from '../../utils/scriptExecution.js';
+export async function duplicateTask(params) {
+    try {
+        if (!params.taskId && !params.taskName) {
+            return { success: false, error: 'Either taskId or taskName must be provided' };
+        }
+        const result = await executeOmniFocusScript('@duplicateTask.js', {
+            taskId: params.taskId || null,
+            taskName: params.taskName || null,
+            newName: params.newName || null,
+            includeSubtasks: params.includeSubtasks !== undefined ? params.includeSubtasks : true
+        });
+        if (!result || result.success !== true) {
+            return { success: false, error: (result && result.error) || 'Failed to duplicate task' };
+        }
+        return {
+            success: true,
+            newTaskId: result.newTaskId,
+            name: result.name,
+            childrenCount: result.childrenCount
+        };
+    }
+    catch (error) {
+        console.error('Error in duplicateTask:', error);
+        return { success: false, error: error?.message || 'Unknown error in duplicateTask' };
+    }
+}

package/dist/tools/primitives/duplicateTask.test.js

@@ -0,0 +1,85 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { readFileSync } from 'node:fs';
+import vm from 'node:vm';
+function runDuplicateScript(context) {
+    const script = readFileSync(new URL('../../utils/omnifocusScripts/duplicateTask.js', import.meta.url), 'utf8');
+    return JSON.parse(vm.runInNewContext(script, context));
+}
+function makeTask(id, name, children = []) {
+    const task = {
+        id: { primaryKey: id },
+        name,
+        parent: null,
+        containingProject: null,
+        children
+    };
+    return task;
+}
+test('duplicateTask resolves by id and reports subtask count', () => {
+    const child = makeTask('c1', 'Child');
+    const source = makeTask('t1', 'Parent', [child]);
+    const clone = makeTask('t1-copy', 'Parent', [makeTask('c1-copy', 'Child')]);
+    const result = runDuplicateScript({
+        injectedArgs: { taskId: 't1', includeSubtasks: true },
+        flattenedTasks: [source, child],
+        inbox: { ending: 'inbox-end' },
+        duplicateTasks: (_tasks, _loc) => [clone],
+        deleteObject: () => { }
+    });
+    assert.equal(result.success, true);
+    assert.equal(result.newTaskId, 't1-copy');
+    assert.equal(result.childrenCount, 1);
+});
+test('duplicateTask renames the copy when newName provided', () => {
+    const source = makeTask('t1', 'Original');
+    const clone = makeTask('t1-copy', 'Original');
+    const result = runDuplicateScript({
+        injectedArgs: { taskId: 't1', newName: 'Renamed Copy' },
+        flattenedTasks: [source],
+        inbox: { ending: 'inbox-end' },
+        duplicateTasks: () => [clone],
+        deleteObject: () => { }
+    });
+    assert.equal(result.success, true);
+    assert.equal(result.name, 'Renamed Copy');
+});
+test('duplicateTask strips subtasks when includeSubtasks is false', () => {
+    const source = makeTask('t1', 'Parent');
+    const cloneChildren = [makeTask('cc1', 'CC1'), makeTask('cc2', 'CC2')];
+    const clone = makeTask('t1-copy', 'Parent', cloneChildren);
+    const deleted = [];
+    const result = runDuplicateScript({
+        injectedArgs: { taskId: 't1', includeSubtasks: false },
+        flattenedTasks: [source],
+        inbox: { ending: 'inbox-end' },
+        duplicateTasks: () => [clone],
+        deleteObject: (obj) => { deleted.push(obj.id.primaryKey); }
+    });
+    assert.equal(result.success, true);
+    assert.deepEqual(deleted, ['cc1', 'cc2']);
+});
+test('duplicateTask rejects ambiguous name matches', () => {
+    const a = makeTask('a', 'Dup');
+    const b = makeTask('b', 'Dup');
+    const result = runDuplicateScript({
+        injectedArgs: { taskName: 'Dup' },
+        flattenedTasks: [a, b],
+        inbox: { ending: 'inbox-end' },
+        duplicateTasks: () => [],
+        deleteObject: () => { }
+    });
+    assert.equal(result.success, false);
+    assert.match(result.error, /Ambiguous task name/);
+});
+test('duplicateTask errors when task not found', () => {
+    const result = runDuplicateScript({
+        injectedArgs: { taskId: 'missing' },
+        flattenedTasks: [],
+        inbox: { ending: 'inbox-end' },
+        duplicateTasks: () => [],
+        deleteObject: () => { }
+    });
+    assert.equal(result.success, false);
+    assert.match(result.error, /Task not found/);
+});

package/dist/utils/omnifocusScripts/duplicateTask.js

@@ -0,0 +1,76 @@
+// Duplicate an OmniFocus task, including its subtasks, using Omni Automation.
+(() => {
+  try {
+    var args = typeof injectedArgs !== "undefined" ? injectedArgs : {};
+    var taskId = args.taskId || null;
+    var taskName = args.taskName || null;
+    var newName = args.newName || null;
+    var includeSubtasks = args.includeSubtasks !== undefined ? args.includeSubtasks : true;
+
+    if (!taskId && !taskName) {
+      return JSON.stringify({ success: false, error: "Either taskId or taskName must be provided" });
+    }
+
+    // Resolve the source task with duplicate-name protection.
+    var matches = flattenedTasks.filter(function (candidate) {
+      if (taskId) return candidate.id.primaryKey === taskId;
+      return candidate.name === taskName;
+    });
+
+    if (matches.length === 0) {
+      return JSON.stringify({ success: false, error: "Task not found" });
+    }
+    if (matches.length > 1 && !taskId) {
+      return JSON.stringify({
+        success: false,
+        error: "Ambiguous task name: " + taskName + ". Multiple matches found; please use taskId."
+      });
+    }
+
+    var source = matches[0];
+
+    // Determine the drop location (same container as the source task).
+    var location;
+    if (source.parent) {
+      location = source.parent.ending;
+    } else if (source.containingProject) {
+      location = source.containingProject.ending;
+    } else {
+      location = inbox.ending;
+    }
+
+    // duplicateTasks preserves subtasks natively.
+    var duplicated = duplicateTasks([source], location);
+    var newTask = duplicated && duplicated.length ? duplicated[0] : null;
+
+    if (!newTask) {
+      return JSON.stringify({ success: false, error: "Duplication failed: no task returned" });
+    }
+
+    // Optionally rename the duplicate.
+    if (newName) {
+      newTask.name = newName;
+    }
+
+    // Optionally strip subtasks if the caller does not want them.
+    if (!includeSubtasks && newTask.children && newTask.children.length > 0) {
+      // Iterate over a copy since deletion mutates the collection.
+      var children = newTask.children.slice();
+      children.forEach(function (child) {
+        deleteObject(child);
+      });
+    }
+
+    return JSON.stringify({
+      success: true,
+      newTaskId: newTask.id.primaryKey,
+      name: newTask.name,
+      childrenCount: newTask.children ? newTask.children.length : 0
+    });
+  } catch (error) {
+    return JSON.stringify({
+      success: false,
+      error: error && error.message ? error.message : String(error)
+    });
+  }
+})();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "omnifocus-mcp-enhanced",
   "type": "module",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "description": "🚀 NEW: Native Custom Perspective Access! Enhanced MCP server with OmniFocus custom perspective support, hierarchical task display, AI-optimized tool selection, and comprehensive task management",
   "main": "dist/server.js",
   "bin": {

package/src/server.ts

@@ -33,11 +33,15 @@ 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';
 
 // Create an MCP server
 const server = new McpServer({
   name: "OmniFocus MCP",
-  version: "1.8.0"
+  version: "1.9.0"
 });
 
 // Register tools
@@ -221,6 +225,28 @@ server.tool(
   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
+);
+
 // Start the MCP server
 const transport = new StdioServerTransport();
 

package/src/tools/definitions/appendToNote.ts

@@ -0,0 +1,46 @@
+import { z } from 'zod';
+import { appendToNote, AppendToNoteParams } from '../primitives/appendToNote.js';
+import { RequestHandlerExtra } from '@modelcontextprotocol/sdk/shared/protocol.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: z.infer<typeof schema>, _extra: RequestHandlerExtra) {
+  try {
+    if (!args.id && !args.name) {
+      return {
+        content: [{ type: 'text' as const, text: 'Either id or name must be provided to append to a note.' }],
+        isError: true
+      };
+    }
+
+    const result = await appendToNote(args as AppendToNoteParams);
+
+    if (result.success) {
+      const itemTypeLabel = args.itemType === 'task' ? 'Task' : 'Project';
+      return {
+        content: [{
+          type: 'text' as const,
+          text: `✅ Appended text to ${itemTypeLabel} "${result.name}" note.\n\nid: ${result.id}`
+        }]
+      };
+    }
+
+    return {
+      content: [{ type: 'text' as const, text: `Failed to append to note: ${result.error}` }],
+      isError: true
+    };
+  } catch (err: unknown) {
+    const error = err as Error;
+    console.error(`Tool execution error: ${error.message}`);
+    return {
+      content: [{ type: 'text' as const, text: `Error appending to note: ${error.message}` }],
+      isError: true
+    };
+  }
+}

package/src/tools/definitions/countTasks.ts

@@ -0,0 +1,45 @@
+import { z } from 'zod';
+import { countTasks, CountTasksOptions } from '../primitives/countTasks.js';
+import { RequestHandlerExtra } from '@modelcontextprotocol/sdk/shared/protocol.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: z.infer<typeof schema>, _extra: RequestHandlerExtra) {
+  try {
+    const result = await countTasks(args as CountTasksOptions);
+
+    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' as const,
+        text: `# Task Count\n\n**Total: ${result.total}**\n\nBy status:\n${breakdown}`
+      }]
+    };
+  } catch (err: unknown) {
+    const error = err as Error;
+    console.error(`Tool execution error: ${error.message}`);
+    return {
+      content: [{ type: 'text' as const, text: `Error counting tasks: ${error.message}` }],
+      isError: true
+    };
+  }
+}

package/src/tools/definitions/duplicateTask.ts

@@ -0,0 +1,47 @@
+import { z } from 'zod';
+import { duplicateTask, DuplicateTaskParams } from '../primitives/duplicateTask.js';
+import { RequestHandlerExtra } from '@modelcontextprotocol/sdk/shared/protocol.js';
+
+export const schema = z.object({
+  taskId: z.string().optional().describe('The ID of the task to duplicate'),
+  taskName: z.string().optional().describe('The name of the task to duplicate (as fallback if ID not provided)'),
+  newName: z.string().optional().describe('Optional new name for the duplicated task (keeps the original name if omitted)'),
+  includeSubtasks: z.boolean().optional().describe('Whether to include the task\'s subtasks in the copy (default: true)')
+});
+
+export async function handler(args: z.infer<typeof schema>, _extra: RequestHandlerExtra) {
+  try {
+    if (!args.taskId && !args.taskName) {
+      return {
+        content: [{ type: 'text' as const, text: 'Either taskId or taskName must be provided to duplicate a task.' }],
+        isError: true
+      };
+    }
+
+    const result = await duplicateTask(args as DuplicateTaskParams);
+
+    if (result.success) {
+      const subtaskText = (result.childrenCount && result.childrenCount > 0)
+        ? ` with ${result.childrenCount} subtask(s)`
+        : '';
+      return {
+        content: [{
+          type: 'text' as const,
+          text: `✅ Duplicated task as "${result.name}"${subtaskText}.\n\nid: ${result.newTaskId}`
+        }]
+      };
+    }
+
+    return {
+      content: [{ type: 'text' as const, text: `Failed to duplicate task: ${result.error}` }],
+      isError: true
+    };
+  } catch (err: unknown) {
+    const error = err as Error;
+    console.error(`Tool execution error: ${error.message}`);
+    return {
+      content: [{ type: 'text' as const, text: `Error duplicating task: ${error.message}` }],
+      isError: true
+    };
+  }
+}

package/src/tools/primitives/appendToNote.test.ts

@@ -0,0 +1,54 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { generateAppleScript } from './appendToNote.js';
+
+test('appendToNote appends with a real newline (linefeed) separator by default', () => {
+  const script = generateAppleScript({
+    itemType: 'task',
+    name: 'My Task',
+    text: 'progress update'
+  });
+
+  // Reads existing note, appends using AppleScript's linefeed constant (real newline).
+  assert.match(script, /set existingNote to note of foundItem/);
+  assert.match(script, /set newNote to existingNote & linefeed & "progress update"/);
+  assert.match(script, /set note of foundItem to newNote/);
+});
+
+test('appendToNote respects an explicit empty separator', () => {
+  const script = generateAppleScript({
+    itemType: 'task',
+    name: 'My Task',
+    text: 'more',
+    separator: ''
+  });
+
+  assert.match(script, /set newNote to existingNote & "" & "more"/);
+});
+
+test('appendToNote targets flattened projects when itemType is project', () => {
+  const script = generateAppleScript({
+    itemType: 'project',
+    name: 'My Project',
+    text: 'note'
+  });
+
+  assert.match(script, /flattened projects where name = "My Project"/);
+  assert.doesNotMatch(script, /flattened tasks where name = "My Project"/);
+});
+
+test('appendToNote keeps apostrophes and doubles backslashes in text', () => {
+  const script = generateAppleScript({
+    itemType: 'task',
+    name: 'T',
+    text: "didn't work in C:\\Temp"
+  });
+
+  assert.match(script, /didn't work in C:\\\\Temp/);
+  assert.doesNotMatch(script, /\\'/);
+});
+
+test('appendToNote errors when neither id nor name provided', () => {
+  const script = generateAppleScript({ itemType: 'task', text: 'x' } as any);
+  assert.match(script, /Either id or name must be provided/);
+});

package/src/tools/primitives/appendToNote.ts

@@ -0,0 +1,150 @@
+import { executeAppleScript } from '../../utils/scriptExecution.js';
+import { buildAppleScriptJsonHelpers } from '../../utils/appleScriptJson.js';
+import { escapeAppleScriptString } from '../../utils/appleScriptString.js';
+
+// Interface for append-to-note parameters
+export interface AppendToNoteParams {
+  id?: string;                   // ID of the task or project
+  name?: string;                 // Name of the task or project (fallback if ID not provided)
+  itemType: 'task' | 'project';  // Type of item whose note is being appended to
+  text: string;                  // Text to append to the note
+  separator?: string;            // Separator between existing note and new text (default: newline)
+}
+
+/**
+ * Generate pure AppleScript that appends text to an item's note without overwriting.
+ */
+export function generateAppleScript(params: AppendToNoteParams): string {
+  const id = params.id ? escapeAppleScriptString(params.id) : '';
+  const name = params.name ? escapeAppleScriptString(params.name) : '';
+  const itemType = params.itemType;
+  const singularTypeLabel = itemType === 'task' ? 'task' : 'project';
+  const listName = itemType === 'task' ? 'flattened tasks' : 'flattened projects';
+  const appendText = escapeAppleScriptString(params.text);
+  // Separator handling:
+  // - Default (undefined): use AppleScript's `linefeed` constant for a real newline.
+  // - Explicit string: embed it as an escaped literal (empty string means no separator).
+  const useDefaultNewline = params.separator === undefined;
+  const separatorExpr = useDefaultNewline
+    ? 'linefeed'
+    : `"${escapeAppleScriptString(params.separator as string)}"`;
+  const jsonHelpers = buildAppleScriptJsonHelpers();
+
+  if (!id && !name) {
+    return `return "{\\\"success\\\":false,\\\"error\\\":\\\"Either id or name must be provided\\\"}"`;
+  }
+
+  if (!params.text) {
+    return `return "{\\\"success\\\":false,\\\"error\\\":\\\"text must be provided\\\"}"`;
+  }
+
+  let script = `
+${jsonHelpers}
+  try
+    tell application "OmniFocus"
+      tell front document
+        -- Find the item
+        set foundItem to missing value
+`;
+
+  if (id) {
+    script += `
+        -- Try to find by ID first
+        try
+          set foundItem to first ${itemType === 'task' ? 'flattened task' : 'flattened project'} where id = "${id}"
+        end try
+`;
+  }
+
+  if (name) {
+    script += `
+        -- Resolve by name with duplicate protection
+        if foundItem is missing value then
+          set nameMatches to (${listName} where name = "${name}")
+          set nameMatchCount to count of nameMatches
+
+          if nameMatchCount = 1 then
+            set foundItem to item 1 of nameMatches
+          else if nameMatchCount > 1 then
+            return "{\\\"success\\\":false,\\\"error\\\":\\"" & my jsonEscape("Ambiguous ${singularTypeLabel} name: ${name}. Multiple matches found; please use id.") & "\\\"}"
+          end if
+        end if
+`;
+  }
+
+  script += `
+        if foundItem is not missing value then
+          set itemName to name of foundItem
+          set itemId to id of foundItem as string
+
+          -- Read the existing note (may be empty)
+          set existingNote to note of foundItem
+          if existingNote is missing value then
+            set existingNote to ""
+          end if
+
+          -- Append text, using the separator only when there is existing content
+          if existingNote is "" then
+            set newNote to "${appendText}"
+          else
+            set newNote to existingNote & ${separatorExpr} & "${appendText}"
+          end if
+
+          set note of foundItem to newNote
+
+          return "{\\\"success\\\":true,\\\"id\\\":\\"" & my jsonEscape(itemId) & "\\",\\\"name\\\":\\"" & my jsonEscape(itemName) & "\\\"}"
+        else
+          return "{\\\"success\\\":false,\\\"error\\\":\\\"Item not found\\\"}"
+        end if
+      end tell
+    end tell
+  on error errorMessage
+    return "{\\\"success\\\":false,\\\"error\\\":\\"" & my jsonEscape(errorMessage) & "\\\"}"
+  end try
+  `;
+
+  return script;
+}
+
+/**
+ * Append text to a task or project note in OmniFocus (non-destructive).
+ */
+export async function appendToNote(params: AppendToNoteParams): Promise<{
+  success: boolean,
+  id?: string,
+  name?: string,
+  error?: string
+}> {
+  try {
+    if (!params.id && !params.name) {
+      return { success: false, error: 'Either id or name must be provided' };
+    }
+    if (!params.text) {
+      return { success: false, error: 'text must be provided' };
+    }
+
+    const script = generateAppleScript(params);
+
+    console.error('Executing AppleScript for note append...');
+
+    const stdout = await executeAppleScript(script);
+
+    console.error('AppleScript stdout:', stdout);
+
+    try {
+      const result = JSON.parse(stdout);
+
+      if (!result.success) {
+        return { success: false, error: result.error };
+      }
+
+      return { success: true, id: result.id, name: result.name };
+    } catch (parseError) {
+      console.error('Error parsing AppleScript result:', parseError);
+      return { success: false, error: `Failed to parse result: ${stdout}` };
+    }
+  } catch (error: any) {
+    console.error('Error in appendToNote:', error);
+    return { success: false, error: error?.message || 'Unknown error in appendToNote' };
+  }
+}

package/src/tools/primitives/countTasks.ts

@@ -0,0 +1,53 @@
+import { executeOmniFocusScript } from '../../utils/scriptExecution.js';
+import { FilterTasksOptions, applyClientSideFilters } from './filterTasks.js';
+
+export interface CountTasksOptions extends FilterTasksOptions {}
+
+export interface CountTasksResult {
+  total: number;
+  byStatus: Record<string, number>;
+}
+
+/**
+ * Count tasks matching the given filters without returning the full task list.
+ * Reuses the same OmniJS filter script and client-side filters as filter_tasks,
+ * but returns only aggregate counts (fast "how many" queries, low token cost).
+ */
+export async function countTasks(options: CountTasksOptions = {}): Promise<CountTasksResult> {
+  const {
+    perspective = 'all',
+    exactTagMatch = false,
+    sortBy = 'name',
+    sortOrder = 'asc'
+  } = options;
+
+  // Fetch a large set so client-side filters (tags/defer/planned) have full data.
+  const result = await executeOmniFocusScript('@filterTasks.js', {
+    ...options,
+    perspective,
+    exactTagMatch,
+    limit: 100000,
+    sortBy,
+    sortOrder
+  });
+
+  if (result && typeof result === 'object') {
+    const data = result as any;
+    if (data.error) {
+      throw new Error(data.error);
+    }
+
+    const tasks: any[] = Array.isArray(data.tasks) ? data.tasks : [];
+    const filtered = applyClientSideFilters(tasks, options);
+
+    const byStatus: Record<string, number> = {};
+    for (const task of filtered) {
+      const status = (task && task.taskStatus) ? String(task.taskStatus) : 'Unknown';
+      byStatus[status] = (byStatus[status] || 0) + 1;
+    }
+
+    return { total: filtered.length, byStatus };
+  }
+
+  throw new Error('Unexpected result format from OmniFocus');
+}

package/src/tools/primitives/duplicateTask.test.ts

@@ -0,0 +1,104 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { readFileSync } from 'node:fs';
+import vm from 'node:vm';
+
+function runDuplicateScript(context: Record<string, unknown>): any {
+  const script = readFileSync(
+    new URL('../../utils/omnifocusScripts/duplicateTask.js', import.meta.url),
+    'utf8'
+  );
+  return JSON.parse(vm.runInNewContext(script, context) as string);
+}
+
+function makeTask(id: string, name: string, children: any[] = []) {
+  const task: any = {
+    id: { primaryKey: id },
+    name,
+    parent: null,
+    containingProject: null,
+    children
+  };
+  return task;
+}
+
+test('duplicateTask resolves by id and reports subtask count', () => {
+  const child = makeTask('c1', 'Child');
+  const source = makeTask('t1', 'Parent', [child]);
+  const clone = makeTask('t1-copy', 'Parent', [makeTask('c1-copy', 'Child')]);
+
+  const result = runDuplicateScript({
+    injectedArgs: { taskId: 't1', includeSubtasks: true },
+    flattenedTasks: [source, child],
+    inbox: { ending: 'inbox-end' },
+    duplicateTasks: (_tasks: any[], _loc: unknown) => [clone],
+    deleteObject: () => {}
+  });
+
+  assert.equal(result.success, true);
+  assert.equal(result.newTaskId, 't1-copy');
+  assert.equal(result.childrenCount, 1);
+});
+
+test('duplicateTask renames the copy when newName provided', () => {
+  const source = makeTask('t1', 'Original');
+  const clone = makeTask('t1-copy', 'Original');
+
+  const result = runDuplicateScript({
+    injectedArgs: { taskId: 't1', newName: 'Renamed Copy' },
+    flattenedTasks: [source],
+    inbox: { ending: 'inbox-end' },
+    duplicateTasks: () => [clone],
+    deleteObject: () => {}
+  });
+
+  assert.equal(result.success, true);
+  assert.equal(result.name, 'Renamed Copy');
+});
+
+test('duplicateTask strips subtasks when includeSubtasks is false', () => {
+  const source = makeTask('t1', 'Parent');
+  const cloneChildren = [makeTask('cc1', 'CC1'), makeTask('cc2', 'CC2')];
+  const clone = makeTask('t1-copy', 'Parent', cloneChildren);
+  const deleted: string[] = [];
+
+  const result = runDuplicateScript({
+    injectedArgs: { taskId: 't1', includeSubtasks: false },
+    flattenedTasks: [source],
+    inbox: { ending: 'inbox-end' },
+    duplicateTasks: () => [clone],
+    deleteObject: (obj: any) => { deleted.push(obj.id.primaryKey); }
+  });
+
+  assert.equal(result.success, true);
+  assert.deepEqual(deleted, ['cc1', 'cc2']);
+});
+
+test('duplicateTask rejects ambiguous name matches', () => {
+  const a = makeTask('a', 'Dup');
+  const b = makeTask('b', 'Dup');
+
+  const result = runDuplicateScript({
+    injectedArgs: { taskName: 'Dup' },
+    flattenedTasks: [a, b],
+    inbox: { ending: 'inbox-end' },
+    duplicateTasks: () => [],
+    deleteObject: () => {}
+  });
+
+  assert.equal(result.success, false);
+  assert.match(result.error, /Ambiguous task name/);
+});
+
+test('duplicateTask errors when task not found', () => {
+  const result = runDuplicateScript({
+    injectedArgs: { taskId: 'missing' },
+    flattenedTasks: [],
+    inbox: { ending: 'inbox-end' },
+    duplicateTasks: () => [],
+    deleteObject: () => {}
+  });
+
+  assert.equal(result.success, false);
+  assert.match(result.error, /Task not found/);
+});

package/src/tools/primitives/duplicateTask.ts

@@ -0,0 +1,51 @@
+import { executeOmniFocusScript } from '../../utils/scriptExecution.js';
+
+export interface DuplicateTaskParams {
+  taskId?: string;
+  taskName?: string;
+  newName?: string;          // Optional name for the duplicated task
+  includeSubtasks?: boolean; // Whether to keep subtasks in the copy (default: true)
+}
+
+interface DuplicateTaskScriptResult {
+  success: boolean;
+  newTaskId?: string;
+  name?: string;
+  childrenCount?: number;
+  error?: string;
+}
+
+export async function duplicateTask(params: DuplicateTaskParams): Promise<{
+  success: boolean,
+  newTaskId?: string,
+  name?: string,
+  childrenCount?: number,
+  error?: string
+}> {
+  try {
+    if (!params.taskId && !params.taskName) {
+      return { success: false, error: 'Either taskId or taskName must be provided' };
+    }
+
+    const result = await executeOmniFocusScript('@duplicateTask.js', {
+      taskId: params.taskId || null,
+      taskName: params.taskName || null,
+      newName: params.newName || null,
+      includeSubtasks: params.includeSubtasks !== undefined ? params.includeSubtasks : true
+    }) as DuplicateTaskScriptResult;
+
+    if (!result || result.success !== true) {
+      return { success: false, error: (result && result.error) || 'Failed to duplicate task' };
+    }
+
+    return {
+      success: true,
+      newTaskId: result.newTaskId,
+      name: result.name,
+      childrenCount: result.childrenCount
+    };
+  } catch (error: any) {
+    console.error('Error in duplicateTask:', error);
+    return { success: false, error: error?.message || 'Unknown error in duplicateTask' };
+  }
+}

package/src/utils/omnifocusScripts/duplicateTask.js

@@ -0,0 +1,76 @@
+// Duplicate an OmniFocus task, including its subtasks, using Omni Automation.
+(() => {
+  try {
+    var args = typeof injectedArgs !== "undefined" ? injectedArgs : {};
+    var taskId = args.taskId || null;
+    var taskName = args.taskName || null;
+    var newName = args.newName || null;
+    var includeSubtasks = args.includeSubtasks !== undefined ? args.includeSubtasks : true;
+
+    if (!taskId && !taskName) {
+      return JSON.stringify({ success: false, error: "Either taskId or taskName must be provided" });
+    }
+
+    // Resolve the source task with duplicate-name protection.
+    var matches = flattenedTasks.filter(function (candidate) {
+      if (taskId) return candidate.id.primaryKey === taskId;
+      return candidate.name === taskName;
+    });
+
+    if (matches.length === 0) {
+      return JSON.stringify({ success: false, error: "Task not found" });
+    }
+    if (matches.length > 1 && !taskId) {
+      return JSON.stringify({
+        success: false,
+        error: "Ambiguous task name: " + taskName + ". Multiple matches found; please use taskId."
+      });
+    }
+
+    var source = matches[0];
+
+    // Determine the drop location (same container as the source task).
+    var location;
+    if (source.parent) {
+      location = source.parent.ending;
+    } else if (source.containingProject) {
+      location = source.containingProject.ending;
+    } else {
+      location = inbox.ending;
+    }
+
+    // duplicateTasks preserves subtasks natively.
+    var duplicated = duplicateTasks([source], location);
+    var newTask = duplicated && duplicated.length ? duplicated[0] : null;
+
+    if (!newTask) {
+      return JSON.stringify({ success: false, error: "Duplication failed: no task returned" });
+    }
+
+    // Optionally rename the duplicate.
+    if (newName) {
+      newTask.name = newName;
+    }
+
+    // Optionally strip subtasks if the caller does not want them.
+    if (!includeSubtasks && newTask.children && newTask.children.length > 0) {
+      // Iterate over a copy since deletion mutates the collection.
+      var children = newTask.children.slice();
+      children.forEach(function (child) {
+        deleteObject(child);
+      });
+    }
+
+    return JSON.stringify({
+      success: true,
+      newTaskId: newTask.id.primaryKey,
+      name: newTask.name,
+      childrenCount: newTask.children ? newTask.children.length : 0
+    });
+  } catch (error) {
+    return JSON.stringify({
+      success: false,
+      error: error && error.message ? error.message : String(error)
+    });
+  }
+})();