omnifocus-mcp-enhanced 1.6.9 → 1.6.10

package/README.md

@@ -17,6 +17,7 @@ Enhanced Model Context Protocol (MCP) server for OmniFocus featuring **native cu
 
 ## 🆕 Latest Release
 
+- **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.
 - **v1.6.9** - Added task attachment support: `get_task_by_id` now lists attachment metadata, `dump_database` exports attachment/link metadata, and new `read_task_attachment` returns image attachments as MCP image content when possible.
 - **v1.6.8** - Added stable task move support via `move_task` and `edit_item` (`newProjectId/newProjectName/newParentTaskId/newParentTaskName/moveToInbox`) with duplicate-name protection and cycle-prevention checks.
 - **v1.6.6** - Added full Planned Date support (create/edit/read/filter/sort/export), including `plannedDate`/`newPlannedDate` and updated task displays.
@@ -217,6 +218,101 @@ Efficiently manage multiple tasks:
 }
 ```
 
+CLI tip for `mcporter`:
+
+```bash
+# Prefer explicit JSON args for complex arrays / nested objects
+mcporter call omnifocus.batch_add_items --args '{
+  "items": [
+    {
+      "type": "task",
+      "name": "Website Technical SEO",
+      "projectName": "SEO Project"
+    }
+  ]
+}'
+```
+
+If you pass a subtask with `parentTaskId` or `parentTaskName`, do not also pass `projectName`. Subtasks inherit the project from their parent task.
+
+Working `mcporter` examples:
+
+```bash
+# 1) Batch-create top-level tasks in a project
+mcporter call omnifocus.batch_add_items --args '{
+  "items": [
+    {
+      "type": "task",
+      "name": "Parent: Category A",
+      "projectName": "OmniFocus MCP Batch Test"
+    },
+    {
+      "type": "task",
+      "name": "Parent: Category B",
+      "projectName": "OmniFocus MCP Batch Test"
+    }
+  ]
+}'
+```
+
+```bash
+# 2) Create parent + child in one batch
+mcporter call omnifocus.batch_add_items --args '{
+  "items": [
+    {
+      "type": "task",
+      "name": "Parent: Category A",
+      "projectName": "OmniFocus MCP Batch Test"
+    },
+    {
+      "type": "task",
+      "name": "Child: A1",
+      "parentTaskName": "Parent: Category A"
+    }
+  ]
+}'
+```
+
+```bash
+# 3) Safer two-step flow when adding many subtasks to existing parents
+mcporter call omnifocus.batch_add_items --args '{
+  "items": [
+    {
+      "type": "task",
+      "name": "Child: A1",
+      "parentTaskName": "Parent: Category A"
+    },
+    {
+      "type": "task",
+      "name": "Child: A2",
+      "parentTaskName": "Parent: Category A"
+    },
+    {
+      "type": "task",
+      "name": "Child: B1",
+      "parentTaskName": "Parent: Category B"
+    }
+  ]
+}'
+```
+
+This will fail, by design:
+
+```bash
+mcporter call omnifocus.batch_add_items --args '{
+  "items": [
+    {
+      "type": "task",
+      "name": "Child: A1",
+      "projectName": "OmniFocus MCP Batch Test",
+      "parentTaskName": "Parent: Category A"
+    }
+  ]
+}'
+```
+
+Because a subtask must inherit its project from the parent task.
+
 ### 6. 🖼️ Attachment Inspection
 
 Discover images and linked files on a task first, then read only the attachment you need:

package/README.zh.md

@@ -13,6 +13,7 @@
 
 ## 🆕 最新版本
 
+- **v1.6.10** - 修复 `edit_item` 无法完成 Inbox 任务的问题，修复 AppleScript 对单引号/反斜杠等特殊字符的处理，修复特殊字符导致的 JSON 返回解析失败，并补充 `batch_add_items` / `mcporter` 的可直接运行示例与说明。
 - **v1.6.9** - 新增任务附件支持：`get_task_by_id` 会返回附件元信息，`dump_database` 导出附件/链接元信息，并新增 `read_task_attachment`，可在支持时直接把图片附件作为 MCP 图片内容返回。
 - **v1.6.6** - 新增 Planned Date（计划日期）全链路支持：创建/编辑/读取/过滤/排序/导出，包含 `plannedDate` / `newPlannedDate`。
 
@@ -212,6 +213,101 @@ get_custom_perspective_tasks {
 }
 ```
 
+`mcporter` 调用提示：
+
+```bash
+# 复杂数组 / 嵌套对象，建议明确使用 --args JSON
+mcporter call omnifocus.batch_add_items --args '{
+  "items": [
+    {
+      "type": "task",
+      "name": "网站技术 SEO",
+      "projectName": "SEO 项目"
+    }
+  ]
+}'
+```
+
+如果某条子任务传了 `parentTaskId` 或 `parentTaskName`，就不要再传 `projectName`。子任务会自动继承父任务所在项目。
+
+可直接运行的 `mcporter` 示例：
+
+```bash
+# 1）批量创建项目下的顶层任务
+mcporter call omnifocus.batch_add_items --args '{
+  "items": [
+    {
+      "type": "task",
+      "name": "父任务：分类A",
+      "projectName": "OmniFocus MCP 批量测试"
+    },
+    {
+      "type": "task",
+      "name": "父任务：分类B",
+      "projectName": "OmniFocus MCP 批量测试"
+    }
+  ]
+}'
+```
+
+```bash
+# 2）单次批量里同时创建父任务和子任务
+mcporter call omnifocus.batch_add_items --args '{
+  "items": [
+    {
+      "type": "task",
+      "name": "父任务：分类A",
+      "projectName": "OmniFocus MCP 批量测试"
+    },
+    {
+      "type": "task",
+      "name": "子任务：A1",
+      "parentTaskName": "父任务：分类A"
+    }
+  ]
+}'
+```
+
+```bash
+# 3）更稳妥的两步法：父任务已存在时，再批量创建多个子任务
+mcporter call omnifocus.batch_add_items --args '{
+  "items": [
+    {
+      "type": "task",
+      "name": "子任务：A1",
+      "parentTaskName": "父任务：分类A"
+    },
+    {
+      "type": "task",
+      "name": "子任务：A2",
+      "parentTaskName": "父任务：分类A"
+    },
+    {
+      "type": "task",
+      "name": "子任务：B1",
+      "parentTaskName": "父任务：分类B"
+    }
+  ]
+}'
+```
+
+下面这种写法会失败，这属于预期行为：
+
+```bash
+mcporter call omnifocus.batch_add_items --args '{
+  "items": [
+    {
+      "type": "task",
+      "name": "子任务：A1",
+      "projectName": "OmniFocus MCP 批量测试",
+      "parentTaskName": "父任务：分类A"
+    }
+  ]
+}'
+```
+
+因为子任务必须继承父任务所在项目，不能再单独传 `projectName`。
+
 ### 6. 🖼️ 附件查看
 
 先读取任务和附件元信息，再按需打开具体附件：

package/dist/tools/definitions/batchAddItems.js

@@ -12,9 +12,9 @@ export const schema = z.object({
         estimatedMinutes: z.number().optional().describe("Estimated time to complete the item, in minutes"),
         tags: z.array(z.string()).optional().describe("Tags to assign to the item"),
         // Task-specific properties
-        projectName: z.string().optional().describe("For tasks: The name of the project to add the task to"),
-        parentTaskId: z.string().optional().describe("For tasks: The ID of the parent task to create this task as a subtask"),
-        parentTaskName: z.string().optional().describe("For tasks: The name of the parent task to create this task as a subtask"),
+        projectName: z.string().optional().describe("For tasks: The project name for top-level tasks. Omit this when parentTaskId or parentTaskName is set."),
+        parentTaskId: z.string().optional().describe("For tasks: The parent task ID for subtasks. When this is set, do not also provide projectName."),
+        parentTaskName: z.string().optional().describe("For tasks: The parent task name for subtasks. Subtasks inherit project from their parent, so do not also provide projectName."),
         // Project-specific properties
         folderName: z.string().optional().describe("For projects: The name of the folder to add the project to"),
         sequential: z.boolean().optional().describe("For projects: Whether tasks in the project should be sequential")

package/dist/tools/definitions/plannedDateSchemas.test.js

@@ -37,6 +37,13 @@ test('batch_add_items schema preserves plannedDate for task and project', () =>
     assert.equal(parsed.items[0].plannedDate, '2026-02-14');
     assert.equal(parsed.items[1].plannedDate, '2026-02-15');
 });
+test('batch_add_items schema documents subtask project inheritance', () => {
+    const itemSchema = batchAddItemsSchema.shape.items._def.type;
+    const projectNameDescription = itemSchema.shape.projectName.description;
+    const parentTaskNameDescription = itemSchema.shape.parentTaskName.description;
+    assert.match(projectNameDescription, /omit this when parentTaskId or parentTaskName is set/i);
+    assert.match(parentTaskNameDescription, /subtasks inherit project from their parent/i);
+});
 test('edit_item schema preserves newPlannedDate', () => {
     const parsed = editItemSchema.parse({
         itemType: 'task',

package/dist/tools/primitives/addOmniFocusTask.js

@@ -1,11 +1,13 @@
 import { executeAppleScript } from '../../utils/scriptExecution.js';
 import { appleScriptDateCode } from '../../utils/dateFormatter.js';
+import { buildAppleScriptJsonHelpers } from '../../utils/appleScriptJson.js';
+import { escapeAppleScriptString } from '../../utils/appleScriptString.js';
 export function buildTagAssignmentScript(tags, targetVar) {
     if (!tags || tags.length === 0) {
         return '';
     }
     return tags.map(tag => {
-        const sanitizedTag = tag.replace(/['"\\]/g, '\\$&');
+        const sanitizedTag = escapeAppleScriptString(tag);
         return `
           try
             set theTag to missing value
@@ -26,8 +28,8 @@ export function buildTagAssignmentScript(tags, targetVar) {
  */
 export function generateAppleScript(params) {
     // Sanitize and prepare parameters for AppleScript
-    const name = params.name.replace(/['"\\]/g, '\\$&'); // Escape quotes and backslashes
-    const note = params.note?.replace(/['"\\]/g, '\\$&') || '';
+    const name = escapeAppleScriptString(params.name);
+    const note = params.note ? escapeAppleScriptString(params.note) : '';
     // Build date variables outside OmniFocus tell block to avoid locale parsing issues.
     const dueDateCode = params.dueDate ? appleScriptDateCode(params.dueDate, 'dueDateValue') : '';
     const deferDateCode = params.deferDate ? appleScriptDateCode(params.deferDate, 'deferDateValue') : '';
@@ -36,12 +38,14 @@ export function generateAppleScript(params) {
     const flagged = params.flagged === true;
     const estimatedMinutes = params.estimatedMinutes?.toString() || '';
     const tags = params.tags || [];
-    const projectName = params.projectName?.replace(/['"\\]/g, '\\$&') || '';
-    const parentTaskId = params.parentTaskId?.replace(/['"\\]/g, '\\$&') || '';
-    const parentTaskName = params.parentTaskName?.replace(/['"\\]/g, '\\$&') || '';
+    const projectName = params.projectName ? escapeAppleScriptString(params.projectName) : '';
+    const parentTaskId = params.parentTaskId ? escapeAppleScriptString(params.parentTaskId) : '';
+    const parentTaskName = params.parentTaskName ? escapeAppleScriptString(params.parentTaskName) : '';
+    const jsonHelpers = buildAppleScriptJsonHelpers();
     const tagAssignmentScript = buildTagAssignmentScript(tags, 'newTask');
     // Construct AppleScript with error handling
     let script = `
+${jsonHelpers}
   try
 ${datePreamble}
     tell application "OmniFocus"
@@ -53,7 +57,7 @@ ${datePreamble}
             set theParentTask to first flattened task where id = "${parentTaskId}"
             set newTask to make new task with properties {name:"${name}"} at end of tasks of theParentTask
           on error
-            return "{\\\"success\\\":false,\\\"error\\\":\\\"Parent task not found with ID: ${parentTaskId}\\\"}"
+            return "{\\\"success\\\":false,\\\"error\\\":\\"" & my jsonEscape("Parent task not found with ID: ${parentTaskId}") & "\\\"}"
           end try
         else if "${parentTaskName}" is not "" then
           -- Create subtask using parent task name
@@ -61,7 +65,7 @@ ${datePreamble}
             set theParentTask to first flattened task where name = "${parentTaskName}"
             set newTask to make new task with properties {name:"${name}"} at end of tasks of theParentTask
           on error
-            return "{\\\"success\\\":false,\\\"error\\\":\\\"Parent task not found with name: ${parentTaskName}\\\"}"
+            return "{\\\"success\\\":false,\\\"error\\\":\\"" & my jsonEscape("Parent task not found with name: ${parentTaskName}") & "\\\"}"
           end try
         else if "${projectName}" is not "" then
           -- Use specified project
@@ -69,7 +73,7 @@ ${datePreamble}
             set theProject to first flattened project where name = "${projectName}"
             set newTask to make new task with properties {name:"${name}"} at end of tasks of theProject
           on error
-            return "{\\\"success\\\":false,\\\"error\\\":\\\"Project not found: ${projectName}\\\"}"
+            return "{\\\"success\\\":false,\\\"error\\\":\\"" & my jsonEscape("Project not found: ${projectName}") & "\\\"}"
           end try
         else
           -- Use inbox of the document
@@ -86,16 +90,17 @@ ${datePreamble}
         
         -- Get the task ID
         set taskId to id of newTask as string
+        set taskNameValue to name of newTask
         
         -- Add tags if provided
         ${tagAssignmentScript}
         
         -- Return success with task ID
-        return "{\\\"success\\\":true,\\\"taskId\\\":\\"" & taskId & "\\",\\\"name\\\":\\"${name}\\"}"
+        return "{\\\"success\\\":true,\\\"taskId\\\":\\"" & my jsonEscape(taskId) & "\\",\\\"name\\\":\\"" & my jsonEscape(taskNameValue) & "\\\"}"
       end tell
     end tell
   on error errorMessage
-    return "{\\\"success\\\":false,\\\"error\\\":\\"" & errorMessage & "\\"}"
+    return "{\\\"success\\\":false,\\\"error\\\":\\"" & my jsonEscape(errorMessage) & "\\\"}"
   end try
   `;
     return script;

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

@@ -25,3 +25,21 @@ test('generateAppleScript builds date variables before OmniFocus tell block', ()
     assert.doesNotMatch(script, /set defer date of newTask to date "/);
     assert.doesNotMatch(script, /set planned date of newTask to date "/);
 });
+test('generateAppleScript keeps apostrophes and doubles backslashes in task text fields', () => {
+    const script = generateAppleScript({
+        name: "Review client's \\ draft",
+        note: "Check Bob's file in C:\\Temp"
+    });
+    assert.match(script, /make new inbox task with properties \{name:"Review client's \\\\ draft"\}/);
+    assert.match(script, /set note of newTask to "Check Bob's file in C:\\\\Temp"/);
+    assert.doesNotMatch(script, /\\'/);
+});
+test('generateAppleScript escapes JSON response values through AppleScript helper', () => {
+    const script = generateAppleScript({
+        name: "Review client's \\ draft"
+    });
+    assert.match(script, /on jsonEscape\(inputText\)/);
+    assert.match(script, /set taskNameValue to name of newTask/);
+    assert.match(script, /my jsonEscape\(taskId\)/);
+    assert.match(script, /my jsonEscape\(taskNameValue\)/);
+});

package/dist/tools/primitives/addProject.js

@@ -1,12 +1,14 @@
 import { executeAppleScript } from '../../utils/scriptExecution.js';
 import { appleScriptDateCode } from '../../utils/dateFormatter.js';
+import { buildAppleScriptJsonHelpers } from '../../utils/appleScriptJson.js';
+import { escapeAppleScriptString } from '../../utils/appleScriptString.js';
 /**
  * Generate pure AppleScript for project creation
  */
 export function generateAppleScript(params) {
     // Sanitize and prepare parameters for AppleScript
-    const name = params.name.replace(/['"\\]/g, '\\$&'); // Escape quotes and backslashes
-    const note = params.note?.replace(/['"\\]/g, '\\$&') || '';
+    const name = escapeAppleScriptString(params.name);
+    const note = params.note ? escapeAppleScriptString(params.note) : '';
     // Build date variables outside OmniFocus tell block to avoid locale parsing issues.
     const dueDateCode = params.dueDate ? appleScriptDateCode(params.dueDate, 'dueDateValue') : '';
     const deferDateCode = params.deferDate ? appleScriptDateCode(params.deferDate, 'deferDateValue') : '';
@@ -15,11 +17,12 @@ export function generateAppleScript(params) {
     const flagged = params.flagged === true;
     const estimatedMinutes = params.estimatedMinutes?.toString() || '';
     const tags = params.tags || [];
-    const folderName = params.folderName?.replace(/['"\\]/g, '\\$&') || '';
+    const folderName = params.folderName ? escapeAppleScriptString(params.folderName) : '';
     const sequential = params.sequential === true;
+    const jsonHelpers = buildAppleScriptJsonHelpers();
     const tagAssignmentScript = tags.length > 0
         ? tags.map(tag => {
-            const sanitizedTag = tag.replace(/['"\\]/g, '\\$&');
+            const sanitizedTag = escapeAppleScriptString(tag);
             return `
           try
             set theTag to missing value
@@ -37,6 +40,7 @@ export function generateAppleScript(params) {
         : '';
     // Construct AppleScript with error handling
     let script = `
+${jsonHelpers}
   try
 ${datePreamble}
     tell application "OmniFocus"
@@ -51,7 +55,7 @@ ${datePreamble}
             set theFolder to first flattened folder where name = "${folderName}"
             set newProject to make new project with properties {name:"${name}"} at end of projects of theFolder
           on error
-            return "{\\\"success\\\":false,\\\"error\\\":\\\"Folder not found: ${folderName}\\\"}"
+            return "{\\\"success\\\":false,\\\"error\\\":\\"" & my jsonEscape("Folder not found: ${folderName}") & "\\\"}"
           end try
         end if
         
@@ -66,16 +70,17 @@ ${datePreamble}
         
         -- Get the project ID
         set projectId to id of newProject as string
+        set projectNameValue to name of newProject
         
         -- Add tags if provided
         ${tagAssignmentScript}
         
         -- Return success with project ID
-        return "{\\\"success\\\":true,\\\"projectId\\\":\\"" & projectId & "\\",\\\"name\\\":\\"${name}\\"}"
+        return "{\\\"success\\\":true,\\\"projectId\\\":\\"" & my jsonEscape(projectId) & "\\",\\\"name\\\":\\"" & my jsonEscape(projectNameValue) & "\\\"}"
       end tell
     end tell
   on error errorMessage
-    return "{\\\"success\\\":false,\\\"error\\\":\\"" & errorMessage & "\\"}"
+    return "{\\\"success\\\":false,\\\"error\\\":\\"" & my jsonEscape(errorMessage) & "\\\"}"
   end try
   `;
     return script;

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

@@ -18,3 +18,21 @@ test('addProject date handling uses preamble variables outside OmniFocus tell bl
     assert.doesNotMatch(script, /set defer date of newProject to date "/);
     assert.doesNotMatch(script, /set planned date of newProject to date "/);
 });
+test('addProject keeps apostrophes and doubles backslashes in text fields', () => {
+    const script = generateAppleScript({
+        name: "Client's \\ Roadmap",
+        note: "Things that didn't work in C:\\Temp"
+    });
+    assert.match(script, /name:"Client's \\\\ Roadmap"/);
+    assert.match(script, /set note of newProject to "Things that didn't work in C:\\\\Temp"/);
+    assert.doesNotMatch(script, /\\'/);
+});
+test('addProject escapes JSON response values through AppleScript helper', () => {
+    const script = generateAppleScript({
+        name: "Client's \\ Roadmap"
+    });
+    assert.match(script, /on jsonEscape\(inputText\)/);
+    assert.match(script, /set projectNameValue to name of newProject/);
+    assert.match(script, /my jsonEscape\(projectId\)/);
+    assert.match(script, /my jsonEscape\(projectNameValue\)/);
+});

package/dist/tools/primitives/batchAddItems.js

@@ -1,5 +1,17 @@
 import { addOmniFocusTask } from './addOmniFocusTask.js';
 import { addProject } from './addProject.js';
+function validateBatchItem(item, index) {
+    if (item.type !== 'task') {
+        return undefined;
+    }
+    if (item.parentTaskId && item.parentTaskName) {
+        return `Item ${index + 1} ("${item.name}"): Use only one parent reference. Provide parentTaskId or parentTaskName, not both.`;
+    }
+    if ((item.parentTaskId || item.parentTaskName) && item.projectName) {
+        return `Item ${index + 1} ("${item.name}"): Do not provide projectName when parentTaskId or parentTaskName is set. Subtasks inherit project from their parent.`;
+    }
+    return undefined;
+}
 /**
  * Add multiple items (tasks or projects) to OmniFocus
  */
@@ -8,8 +20,16 @@ export async function batchAddItems(items) {
         // Results array to track individual operation outcomes
         const results = [];
         // Process each item in sequence
-        for (const item of items) {
+        for (const [index, item] of items.entries()) {
             try {
+                const validationError = validateBatchItem(item, index);
+                if (validationError) {
+                    results.push({
+                        success: false,
+                        error: validationError
+                    });
+                    continue;
+                }
                 if (item.type === 'task') {
                     // Extract task-specific params
                     const taskParams = {

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

@@ -0,0 +1,17 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { batchAddItems } from './batchAddItems.js';
+test('batchAddItems returns a clear validation error when a subtask also includes projectName', async () => {
+    const result = await batchAddItems([
+        {
+            type: 'task',
+            name: 'Child task',
+            projectName: 'Demo Project',
+            parentTaskName: 'Parent task'
+        }
+    ]);
+    assert.equal(result.success, false);
+    assert.equal(result.results.length, 1);
+    assert.equal(result.results[0].success, false);
+    assert.match(result.results[0].error || '', /Item 1 \("Child task"\): Do not provide projectName when parentTaskId or parentTaskName is set/);
+});