@iflow-mcp/omnifocus-mcp 1.2.3

package/dist/utils/scriptExecution.js

@@ -0,0 +1,113 @@
+import { exec } from 'child_process';
+import { promisify } from 'util';
+import { writeFileSync, unlinkSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+import { fileURLToPath } from 'url';
+import { dirname } from 'path';
+import { existsSync } from 'fs';
+const execAsync = promisify(exec);
+// Helper function to execute OmniFocus scripts
+export async function executeJXA(script) {
+    try {
+        // Write the script to a temporary file in the system temp directory
+        const tempFile = join(tmpdir(), `jxa_script_${Date.now()}.js`);
+        // Write the script to the temporary file
+        writeFileSync(tempFile, script);
+        // Execute the script using osascript
+        const { stdout, stderr } = await execAsync(`osascript -l JavaScript ${tempFile}`);
+        if (stderr) {
+            console.error("Script stderr output:", stderr);
+        }
+        // Clean up the temporary file
+        unlinkSync(tempFile);
+        // Parse the output as JSON
+        try {
+            const result = JSON.parse(stdout);
+            return result;
+        }
+        catch (e) {
+            console.error("Failed to parse script output as JSON:", e);
+            // If this contains a "Found X tasks" message, treat it as a successful non-JSON response
+            if (stdout.includes("Found") && stdout.includes("tasks")) {
+                return [];
+            }
+            return [];
+        }
+    }
+    catch (error) {
+        console.error("Failed to execute JXA script:", error);
+        throw error;
+    }
+}
+// Function to execute scripts in OmniFocus using the URL scheme
+// Update src/utils/scriptExecution.ts
+export async function executeOmniFocusScript(scriptPath, args) {
+    try {
+        // Get the actual script path (existing code remains the same)
+        let actualPath;
+        if (scriptPath.startsWith('@')) {
+            const scriptName = scriptPath.substring(1);
+            const __filename = fileURLToPath(import.meta.url);
+            const __dirname = dirname(__filename);
+            const distPath = join(__dirname, '..', 'utils', 'omnifocusScripts', scriptName);
+            const srcPath = join(__dirname, '..', '..', 'src', 'utils', 'omnifocusScripts', scriptName);
+            if (existsSync(distPath)) {
+                actualPath = distPath;
+            }
+            else if (existsSync(srcPath)) {
+                actualPath = srcPath;
+            }
+            else {
+                actualPath = join(__dirname, '..', 'omnifocusScripts', scriptName);
+            }
+        }
+        else {
+            actualPath = scriptPath;
+        }
+        // Read the script file
+        const scriptContent = readFileSync(actualPath, 'utf8');
+        // Create a temporary file for our JXA wrapper script
+        const tempFile = join(tmpdir(), `jxa_wrapper_${Date.now()}.js`);
+        // Escape the script content properly for use in JXA
+        const escapedScript = scriptContent.replace(/\\/g, '\\\\').replace(/`/g, '\\`').replace(/\$/g, '\\$');
+        // Create a JXA script that will execute our OmniJS script in OmniFocus
+        const jxaScript = `
+    function run() {
+      try {
+        const app = Application('OmniFocus');
+        app.includeStandardAdditions = true;
+        
+        // Run the OmniJS script in OmniFocus and capture the output
+        const result = app.evaluateJavascript(\`${escapedScript}\`);
+        
+        // Return the result
+        return result;
+      } catch (e) {
+        return JSON.stringify({ error: e.message });
+      }
+    }
+    `;
+        // Write the JXA script to the temporary file
+        writeFileSync(tempFile, jxaScript);
+        // Execute the JXA script using osascript
+        const { stdout, stderr } = await execAsync(`osascript -l JavaScript ${tempFile}`);
+        // Clean up the temporary file
+        unlinkSync(tempFile);
+        if (stderr) {
+            console.error("Script stderr output:", stderr);
+        }
+        // Parse the output as JSON
+        try {
+            return JSON.parse(stdout);
+        }
+        catch (parseError) {
+            console.error("Error parsing script output:", parseError);
+            return stdout;
+        }
+    }
+    catch (error) {
+        console.error("Failed to execute OmniFocus script:", error);
+        throw error;
+    }
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@iflow-mcp/omnifocus-mcp",
+  "type": "module",
+  "version": "1.2.3",
+  "description": "Model Context Protocol (MCP) server that integrates with OmniFocus for AI assistant interaction",
+  "main": "dist/server.js",
+  "bin": {
+    "omnifocus-mcp": "./cli.cjs"
+  },
+  "scripts": {
+    "build": "tsc && npm run copy-files && chmod 755 dist/server.js",
+    "copy-files": "mkdir -p dist/utils/omnifocusScripts && cp src/utils/omnifocusScripts/*.js dist/utils/omnifocusScripts/",
+    "start": "node dist/server.js",
+    "dev": "tsc -w"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.8.0",
+    "zod": "^3.22.4"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.19",
+    "typescript": "^5.3.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/themotionmachine/omnifocus-mcp-server.git"
+  },
+  "homepage": "https://github.com/themotionmachine/omnifocus-mcp-server",
+  "keywords": [
+    "omnifocus",
+    "mcp",
+    "claude",
+    "task-management",
+    "ai"
+  ],
+  "license": "MIT"
+}

package/src/omnifocustypes.ts

@@ -0,0 +1,89 @@
+// Core enums
+export namespace Task {
+  export enum Status {
+    Available,
+    Blocked,
+    Completed,
+    Dropped,
+    DueSoon,
+    Next,
+    Overdue
+  }
+
+  export enum RepetitionMethod {
+    DeferUntilDate,
+    DueDate,
+    Fixed,
+    None
+  }
+}
+export namespace Project {
+  export enum Status {
+    Active,
+    Done,
+    Dropped,
+    OnHold
+  }
+}
+export namespace Folder {
+  export enum Status {
+    Active,
+    Dropped
+  }
+}
+export namespace Tag {
+  export enum Status {
+    Active,
+    Dropped,
+    OnHold
+  }
+}
+// Minimal DatabaseObject interface
+export interface DatabaseObject {
+  id: { primaryKey: string };
+}
+// Minimal interfaces for core objects
+export interface TaskMinimal extends DatabaseObject {
+  name: string;
+  note: string;
+  flagged: boolean;
+  taskStatus: Task.Status;
+  dueDate: Date | null;
+  deferDate: Date | null;
+  effectiveDueDate: Date | null;
+  effectiveDeferDate: Date | null;
+  estimatedMinutes: number | null;
+  completedByChildren: boolean;
+  sequential: boolean;
+  tags: TagMinimal[];
+  containingProject: ProjectMinimal | null;
+  parent: TaskMinimal | null;
+  children: TaskMinimal[];
+  inInbox: boolean;
+}
+export interface ProjectMinimal extends DatabaseObject {
+  name: string;
+  note: string;
+  status: Project.Status;
+  dueDate: Date | null;
+  deferDate: Date | null;
+  effectiveDueDate: Date | null;
+  effectiveDeferDate: Date | null;
+  estimatedMinutes: number | null;
+  flagged: boolean;
+  sequential: boolean;
+  parentFolder: FolderMinimal | null;
+  tags: TagMinimal[];
+  tasks: TaskMinimal[];
+}
+export interface FolderMinimal extends DatabaseObject {
+  name: string;
+  status: Folder.Status;
+  parent: FolderMinimal | null;
+}
+export interface TagMinimal extends DatabaseObject {
+  name: string;
+  status: Tag.Status;
+  parent: TagMinimal | null;
+  active: boolean;
+}

package/src/server.ts

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// Import tool definitions
+import * as dumpDatabaseTool from './tools/definitions/dumpDatabase.js';
+import * as addOmniFocusTaskTool from './tools/definitions/addOmniFocusTask.js';
+import * as addProjectTool from './tools/definitions/addProject.js';
+import * as removeItemTool from './tools/definitions/removeItem.js';
+import * as editItemTool from './tools/definitions/editItem.js';
+import * as batchAddItemsTool from './tools/definitions/batchAddItems.js';
+import * as batchRemoveItemsTool from './tools/definitions/batchRemoveItems.js';
+import * as queryOmniFocusTool from './tools/definitions/queryOmnifocus.js';
+import * as listPerspectivesTool from './tools/definitions/listPerspectives.js';
+import * as getPerspectiveViewTool from './tools/definitions/getPerspectiveView.js';
+
+// Create an MCP server
+const server = new McpServer({
+  name: "OmniFocus MCP",
+  version: "1.0.0"
+});
+
+// Register tools
+server.tool(
+  "dump_database",
+  "Gets the current state of your OmniFocus database",
+  dumpDatabaseTool.schema.shape,
+  dumpDatabaseTool.handler
+);
+
+server.tool(
+  "add_omnifocus_task",
+  "Add a new task to OmniFocus",
+  addOmniFocusTaskTool.schema.shape,
+  addOmniFocusTaskTool.handler
+);
+
+server.tool(
+  "add_project",
+  "Add a new project to OmniFocus",
+  addProjectTool.schema.shape,
+  addProjectTool.handler
+);
+
+server.tool(
+  "remove_item",
+  "Remove a task or project from OmniFocus",
+  removeItemTool.schema.shape,
+  removeItemTool.handler
+);
+
+server.tool(
+  "edit_item",
+  "Edit a task or project in OmniFocus",
+  editItemTool.schema.shape,
+  editItemTool.handler
+);
+
+server.tool(
+  "batch_add_items",
+  "Add multiple tasks or projects to OmniFocus in a single operation",
+  batchAddItemsTool.schema.shape,
+  batchAddItemsTool.handler
+);
+
+server.tool(
+  "batch_remove_items",
+  "Remove multiple tasks or projects from OmniFocus in a single operation",
+  batchRemoveItemsTool.schema.shape,
+  batchRemoveItemsTool.handler
+);
+
+server.tool(
+  "query_omnifocus",
+  "Efficiently query OmniFocus database with powerful filters. Get specific tasks, projects, or folders without loading the entire database. Supports filtering by project, tags, status, due dates, and more. Much faster than dump_database for targeted queries.",
+  queryOmniFocusTool.schema.shape,
+  queryOmniFocusTool.handler
+);
+
+server.tool(
+  "list_perspectives",
+  "List all available perspectives in OmniFocus, including built-in perspectives (Inbox, Projects, Tags, etc.) and custom perspectives (Pro feature)",
+  listPerspectivesTool.schema.shape,
+  listPerspectivesTool.handler
+);
+
+server.tool(
+  "get_perspective_view",
+  "Get the items visible in a specific OmniFocus perspective. Shows what tasks and projects are displayed when viewing that perspective",
+  getPerspectiveViewTool.schema.shape,
+  getPerspectiveViewTool.handler
+);
+
+// Start the MCP server
+const transport = new StdioServerTransport();
+
+// Use await with server.connect to ensure proper connection
+(async function() {
+  try {
+    console.error("Starting MCP server...");
+    await server.connect(transport);
+    console.error("MCP Server connected and ready to accept commands from Claude");
+  } catch (err) {
+    console.error(`Failed to start MCP server: ${err}`);
+  }
+})();
+
+// For a cleaner shutdown if the process is terminated

package/src/tools/definitions/addOmniFocusTask.ts

@@ -0,0 +1,80 @@
+import { z } from 'zod';
+import { addOmniFocusTask, AddOmniFocusTaskParams } from '../primitives/addOmniFocusTask.js';
+import { RequestHandlerExtra } from '@modelcontextprotocol/sdk/shared/protocol.js';
+
+export const schema = z.object({
+  name: z.string().describe("The name of the task"),
+  note: z.string().optional().describe("Additional notes for the task"),
+  dueDate: z.string().optional().describe("The due date of the task in ISO format (YYYY-MM-DD or full ISO date)"),
+  deferDate: z.string().optional().describe("The defer date of the task in ISO format (YYYY-MM-DD or full ISO date)"),
+  flagged: z.boolean().optional().describe("Whether the task is flagged or not"),
+  estimatedMinutes: z.number().optional().describe("Estimated time to complete the task, in minutes"),
+  tags: z.array(z.string()).optional().describe("Tags to assign to the task"),
+  projectName: z.string().optional().describe("The name of the project to add the task to (will add to inbox if not specified)"),
+  // Hierarchy support
+  parentTaskId: z.string().optional().describe("ID of the parent task (preferred for accuracy)"),
+  parentTaskName: z.string().optional().describe("Name of the parent task (used if ID not provided; matched within project or globally if no project)"),
+  hierarchyLevel: z.number().int().min(0).optional().describe("Explicit level indicator for ordering in batch workflows (0=root) - ignored in single add")
+});
+
+export async function handler(args: z.infer<typeof schema>, extra: RequestHandlerExtra) {
+  try {
+    // Call the addOmniFocusTask function 
+    const result = await addOmniFocusTask(args as AddOmniFocusTaskParams);
+    console.error('[add_omnifocus_task] args:', JSON.stringify(args));
+    console.error('[add_omnifocus_task] result:', JSON.stringify(result));
+    
+    if (result.success) {
+      // Determine actual placement
+      const placement = (result as any).placement as 'parent' | 'project' | 'inbox' | undefined;
+      let locationText = '';
+      if (placement === 'parent') {
+        locationText = 'under the parent task';
+      } else if (placement === 'project') {
+        locationText = args.projectName ? `in project "${args.projectName}"` : 'in a project';
+      } else {
+        locationText = 'in your inbox';
+      }
+
+      const tagText = args.tags && args.tags.length > 0
+        ? ` with tags: ${args.tags.join(', ')}`
+        : '';
+
+      const dueDateText = args.dueDate
+        ? ` due on ${new Date(args.dueDate).toLocaleDateString()}`
+        : '';
+
+      // Warning if parent requested but not used
+      let placementWarning = '';
+      if ((args.parentTaskId || args.parentTaskName) && placement && placement !== 'parent') {
+        placementWarning = `\n⚠️ Parent not found; task created ${placement === 'project' ? 'in project' : 'in inbox'}.`;
+      }
+
+      return {
+        content: [{
+          type: "text" as const,
+          text: `✅ Task "${args.name}" created successfully ${locationText}${dueDateText}${tagText}.${placementWarning}`
+        }]
+      };
+    } else {
+      // Task creation failed
+      return {
+        content: [{
+          type: "text" as const,
+          text: `Failed to create 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 creating task: ${error.message}`
+      }],
+      isError: true
+    };
+  }
+} 

package/src/tools/definitions/addProject.ts

@@ -0,0 +1,67 @@
+import { z } from 'zod';
+import { addProject, AddProjectParams } from '../primitives/addProject.js';
+import { RequestHandlerExtra } from '@modelcontextprotocol/sdk/shared/protocol.js';
+
+export const schema = z.object({
+  name: z.string().describe("The name of the project"),
+  note: z.string().optional().describe("Additional notes for the project"),
+  dueDate: z.string().optional().describe("The due date of the project in ISO format (YYYY-MM-DD or full ISO date)"),
+  deferDate: z.string().optional().describe("The defer date of the project in ISO format (YYYY-MM-DD or full ISO date)"),
+  flagged: z.boolean().optional().describe("Whether the project is flagged or not"),
+  estimatedMinutes: z.number().optional().describe("Estimated time to complete the project, in minutes"),
+  tags: z.array(z.string()).optional().describe("Tags to assign to the project"),
+  folderName: z.string().optional().describe("The name of the folder to add the project to (will add to root if not specified)"),
+  sequential: z.boolean().optional().describe("Whether tasks in the project should be sequential (default: false)")
+});
+
+export async function handler(args: z.infer<typeof schema>, extra: RequestHandlerExtra) {
+  try {
+    // Call the addProject function 
+    const result = await addProject(args as AddProjectParams);
+    
+    if (result.success) {
+      // Project was added successfully
+      let locationText = args.folderName 
+        ? `in folder "${args.folderName}"` 
+        : "at the root level";
+        
+      let tagText = args.tags && args.tags.length > 0
+        ? ` with tags: ${args.tags.join(', ')}`
+        : "";
+        
+      let dueDateText = args.dueDate
+        ? ` due on ${new Date(args.dueDate).toLocaleDateString()}`
+        : "";
+        
+      let sequentialText = args.sequential
+        ? " (sequential)"
+        : " (parallel)";
+        
+      return {
+        content: [{
+          type: "text" as const,
+          text: `✅ Project "${args.name}" created successfully ${locationText}${dueDateText}${tagText}${sequentialText}.`
+        }]
+      };
+    } else {
+      // Project creation failed
+      return {
+        content: [{
+          type: "text" as const,
+          text: `Failed to create project: ${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 creating project: ${error.message}`
+      }],
+      isError: true
+    };
+  }
+} 

package/src/tools/definitions/batchAddItems.ts

@@ -0,0 +1,98 @@
+import { z } from 'zod';
+import { batchAddItems, BatchAddItemsParams } from '../primitives/batchAddItems.js';
+import { RequestHandlerExtra } from '@modelcontextprotocol/sdk/shared/protocol.js';
+
+export const schema = z.object({
+  items: z.array(z.object({
+    type: z.enum(['task', 'project']).describe("Type of item to add ('task' or 'project')"),
+    name: z.string().describe("The name of the item"),
+    note: z.string().optional().describe("Additional notes for the item"),
+    dueDate: z.string().optional().describe("The due date in ISO format (YYYY-MM-DD or full ISO date)"),
+    deferDate: z.string().optional().describe("The defer date in ISO format (YYYY-MM-DD or full ISO date)"),
+    flagged: z.boolean().optional().describe("Whether the item is flagged or not"),
+    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: ID of the parent task"),
+    parentTaskName: z.string().optional().describe("For tasks: Name of the parent task (scoped to project when provided)"),
+    tempId: z.string().optional().describe("For tasks: Temporary ID for within-batch references"),
+    parentTempId: z.string().optional().describe("For tasks: Reference to parent's tempId within the batch"),
+    hierarchyLevel: z.number().int().min(0).optional().describe("Optional ordering hint (0=root, 1=child, ...)"),
+    
+    // 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")
+  })).describe("Array of items (tasks or projects) to add")
+  ,
+  createSequentially: z.boolean().optional().describe("Process parents before children; when false, best-effort order will still try to resolve parents first")
+});
+
+export async function handler(args: z.infer<typeof schema>, extra: RequestHandlerExtra) {
+  try {
+    // Call the batchAddItems function
+    const result = await batchAddItems(args.items as BatchAddItemsParams[]);
+    
+    if (result.success) {
+      const successCount = result.results.filter(r => r.success).length;
+      const failureCount = result.results.filter(r => !r.success).length;
+      
+      let message = `✅ Successfully added ${successCount} items.`;
+      
+      if (failureCount > 0) {
+        message += ` ⚠️ Failed to add ${failureCount} items.`;
+      }
+      
+      // Include details about added items
+      const details = result.results.map((item, index) => {
+        if (item.success) {
+          const itemType = args.items[index].type;
+          const itemName = args.items[index].name;
+          return `- ✅ ${itemType}: "${itemName}"`;
+        } else {
+          const itemType = args.items[index].type;
+          const itemName = args.items[index].name;
+          return `- ❌ ${itemType}: "${itemName}" - Error: ${item.error}`;
+        }
+      }).join('\n');
+      
+      return {
+        content: [{
+          type: "text" as const,
+          text: `${message}\n\n${details}`
+        }]
+      };
+    } else {
+      console.error('[batch_add_items] failure result:', JSON.stringify(result));
+      // Batch operation failed completely or no items succeeded.
+      const failureDetails = (result.results && result.results.length > 0)
+        ? result.results.map((r, index) => {
+            const itemType = args.items[index].type;
+            const itemName = args.items[index].name;
+            return r.success
+              ? `- ✅ ${itemType}: \"${itemName}\"`
+              : `- ❌ ${itemType}: \"${itemName}\" - Error: ${r?.error || 'Unknown error'}`;
+          }).join('\\n')
+        : `No items processed. ${result.error || ''}`;
+
+      return {
+        content: [{
+          type: "text" as const,
+          text: `Failed to process batch operation.\\n\\n${failureDetails}`
+        }],
+        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 processing batch operation: ${error.message}`
+      }],
+      isError: true
+    };
+  }
+} 

package/src/tools/definitions/batchRemoveItems.ts

@@ -0,0 +1,80 @@
+import { z } from 'zod';
+import { batchRemoveItems, BatchRemoveItemsParams } from '../primitives/batchRemoveItems.js';
+import { RequestHandlerExtra } from '@modelcontextprotocol/sdk/shared/protocol.js';
+
+export const schema = z.object({
+  items: z.array(z.object({
+    id: z.string().optional().describe("The ID of the task or project to remove"),
+    name: z.string().optional().describe("The name of the task or project to remove (as fallback if ID not provided)"),
+    itemType: z.enum(['task', 'project']).describe("Type of item to remove ('task' or 'project')")
+  })).describe("Array of items (tasks or projects) to remove")
+});
+
+export async function handler(args: z.infer<typeof schema>, extra: RequestHandlerExtra) {
+  try {
+    // Validate that each item has at least an ID or name
+    for (const item of args.items) {
+      if (!item.id && !item.name) {
+        return {
+          content: [{
+            type: "text" as const,
+            text: "Each item must have either id or name provided to remove it."
+          }],
+          isError: true
+        };
+      }
+    }
+    
+    // Call the batchRemoveItems function
+    const result = await batchRemoveItems(args.items as BatchRemoveItemsParams[]);
+    
+    if (result.success) {
+      const successCount = result.results.filter(r => r.success).length;
+      const failureCount = result.results.filter(r => !r.success).length;
+      
+      let message = `✅ Successfully removed ${successCount} items.`;
+      
+      if (failureCount > 0) {
+        message += ` ⚠️ Failed to remove ${failureCount} items.`;
+      }
+      
+      // Include details about removed items
+      const details = result.results.map((item, index) => {
+        if (item.success) {
+          const itemType = args.items[index].itemType;
+          return `- ✅ ${itemType}: "${item.name}"`;
+        } else {
+          const itemType = args.items[index].itemType;
+          const identifier = args.items[index].id || args.items[index].name;
+          return `- ❌ ${itemType}: ${identifier} - Error: ${item.error}`;
+        }
+      }).join('\n');
+      
+      return {
+        content: [{
+          type: "text" as const,
+          text: `${message}\n\n${details}`
+        }]
+      };
+    } else {
+      // Batch operation failed completely
+      return {
+        content: [{
+          type: "text" as const,
+          text: `Failed to process batch removal: ${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 processing batch removal: ${error.message}`
+      }],
+      isError: true
+    };
+  }
+}