@scardis/omnifocus-mcp 0.1.0

package/src/schemas/shapes.ts

@@ -0,0 +1,267 @@
+import { z } from "zod";
+import {
+  IdSchema,
+  ProjectType,
+  ProjectStatus,
+  TaskStatus,
+  TagStatus,
+  FolderStatus,
+  EntityType,
+} from "./enums.js";
+
+// ─── Recurrence ──────────────────────────────────────────────────────────────
+
+const RepetitionFrequency = z.enum(["daily", "weekly", "monthly", "yearly"]);
+const RepetitionMethod = z.enum(["fixed", "dueDate", "start"]);
+const DayOfWeek = z.enum(["sunday", "monday", "tuesday", "wednesday", "thursday", "friday", "saturday"]);
+
+export const RepetitionRuleInput = z
+  .object({
+    frequency: RepetitionFrequency,
+    interval: z.number().int().positive().default(1),
+    daysOfWeek: z.array(DayOfWeek).optional(),
+    method: RepetitionMethod,
+  })
+  .refine(
+    (d) => d.daysOfWeek === undefined || d.frequency === "weekly",
+    { message: "daysOfWeek is only valid when frequency is 'weekly'" }
+  );
+
+export const RepetitionRuleDetail = z.object({
+  frequency: RepetitionFrequency,
+  interval: z.number(),
+  daysOfWeek: z.array(DayOfWeek).optional(),
+  method: RepetitionMethod,
+});
+
+// ─── Task ────────────────────────────────────────────────────────────────────
+
+export const TaskSummary = z.object({
+  id: IdSchema,
+  name: z.string(),
+  status: TaskStatus,
+  flagged: z.boolean(),
+  containerId: IdSchema.nullable(),
+  containerType: z.enum(["project", "inbox", "task"]).nullable(),
+  dueDate: z.string().datetime().nullable(),
+  tagIds: z.array(IdSchema),
+});
+
+export const ListTasksFilter = z.object({
+  flagged: z.literal(true).optional(),
+  status: z.array(TaskStatus).optional(),
+  tagId: IdSchema.optional(),
+  dueBeforeDate: z.string().datetime().optional(),
+});
+
+export const TaskDetail = z.object({
+  id: IdSchema,
+  name: z.string(),
+  note: z.string(),
+  status: TaskStatus,
+  flagged: z.boolean(),
+  deferDate: z.string().datetime().nullable(),
+  plannedDate: z.string().datetime().nullable(),
+  dueDate: z.string().datetime().nullable(),
+  completionDate: z.string().datetime().nullable(),
+  estimatedMinutes: z.number().nullable(),
+  containerId: IdSchema.nullable(),
+  containerType: z.enum(["project", "inbox", "task"]).nullable(),
+  tagIds: z.array(IdSchema),
+  parentTaskId: IdSchema.nullable(),
+  repetitionRule: RepetitionRuleDetail.nullable(),
+});
+
+export const CreateTaskInput = z
+  .object({
+    name: z.string().min(1),
+    note: z.string().optional(),
+    flagged: z.boolean().optional(),
+    deferDate: z.string().datetime().optional(),
+    plannedDate: z.string().datetime().optional(),
+    dueDate: z.string().datetime().optional(),
+    estimatedMinutes: z.number().int().positive().optional(),
+    projectId: IdSchema.optional(),
+    parentTaskId: IdSchema.optional(),
+    tagIds: z.array(IdSchema).optional(),
+    repetitionRule: RepetitionRuleInput.optional(),
+  })
+  .refine((d) => !(d.projectId && d.parentTaskId), {
+    message: "Provide projectId or parentTaskId, not both",
+  });
+
+export const EditTaskInput = z.object({
+  id: IdSchema,
+  name: z.string().min(1).optional(),
+  note: z.string().optional(),
+  flagged: z.boolean().optional(),
+  deferDate: z.string().datetime().nullable().optional(),
+  plannedDate: z.string().datetime().nullable().optional(),
+  dueDate: z.string().datetime().nullable().optional(),
+  estimatedMinutes: z.number().int().positive().nullable().optional(),
+  tagIds: z.array(IdSchema).optional(),
+  repetitionRule: RepetitionRuleInput.nullable().optional(),
+});
+
+// ─── Project ─────────────────────────────────────────────────────────────────
+
+export const ReviewIntervalInput = z.object({
+  steps: z.number().int().positive(),
+  unit: z.enum(["days", "weeks", "months", "years"]),
+});
+
+export const CreateProjectInput = z.object({
+  name: z.string().min(1),
+  folderId: IdSchema.optional(),
+  note: z.string().optional(),
+  type: ProjectType.optional(),
+  status: z.enum(["active", "onHold"]).optional(),
+  flagged: z.boolean().optional(),
+  deferDate: z.string().datetime().optional(),
+  dueDate: z.string().datetime().optional(),
+  reviewInterval: ReviewIntervalInput.optional(),
+  tagIds: z.array(IdSchema).optional(),
+});
+
+export const EditProjectInput = z.object({
+  id: IdSchema,
+  name: z.string().min(1).optional(),
+  note: z.string().optional(),
+  type: ProjectType.optional(),
+  status: z.enum(["active", "onHold"]).optional(),
+  flagged: z.boolean().optional(),
+  deferDate: z.string().datetime().nullable().optional(),
+  dueDate: z.string().datetime().nullable().optional(),
+  reviewInterval: ReviewIntervalInput.optional(),
+  tagIds: z.array(IdSchema).optional(),
+});
+
+export const MoveTaskInput = z
+  .object({
+    id: IdSchema,
+    projectId: IdSchema.optional(),
+    parentTaskId: IdSchema.optional(),
+  })
+  .refine(
+    (d) => (d.projectId !== undefined) !== (d.parentTaskId !== undefined),
+    { message: "Exactly one of projectId or parentTaskId must be provided" }
+  );
+
+export const MoveProjectInput = z.object({
+  id: IdSchema,
+  folderId: IdSchema.nullable(),
+});
+
+export const ListFoldersFilter = z.object({
+  status: FolderStatus.optional(),
+});
+
+export const ListTagsFilter = z.object({
+  status: TagStatus.optional(),
+});
+
+export const ListProjectsFilter = z.object({
+  status: z.array(ProjectStatus).optional(),
+  folderId: IdSchema.optional(),
+  flagged: z.literal(true).optional(),
+});
+
+export const ProjectSummary = z.object({
+  id: IdSchema,
+  name: z.string(),
+  folderPath: z.string(),
+  folderId: IdSchema.nullable(),
+  status: ProjectStatus,
+  type: ProjectType,
+  flagged: z.boolean(),
+});
+
+export const ProjectDetail = z.object({
+  id: IdSchema,
+  name: z.string(),
+  note: z.string(),
+  folderPath: z.string(),
+  status: ProjectStatus,
+  type: ProjectType,
+  flagged: z.boolean(),
+  deferDate: z.string().datetime().nullable(),
+  dueDate: z.string().datetime().nullable(),
+  completionDate: z.string().datetime().nullable(),
+  reviewInterval: z.string().nullable(),
+  nextReviewDate: z.string().datetime().nullable(),
+  lastReviewDate: z.string().datetime().nullable(),
+  tagIds: z.array(IdSchema),
+});
+
+export const CreateFolderInput = z.object({
+  name: z.string().min(1),
+  parentFolderId: IdSchema.optional(),
+});
+
+export const EditFolderInput = z.object({
+  id: IdSchema,
+  name: z.string().min(1),
+});
+
+// ─── Folder ──────────────────────────────────────────────────────────────────
+
+export const FolderSummary = z.object({
+  id: IdSchema,
+  name: z.string(),
+  path: z.string(),
+  parentId: IdSchema.nullable(),
+  status: FolderStatus,
+});
+
+export const FolderDetail = z.object({
+  id: IdSchema,
+  name: z.string(),
+  path: z.string(),
+  parentId: IdSchema.nullable(),
+  status: FolderStatus,
+  childFolderIds: z.array(IdSchema),
+  projectIds: z.array(IdSchema),
+});
+
+export const CreateTagInput = z.object({
+  name: z.string().min(1),
+  parentTagId: IdSchema.optional(),
+});
+
+export const EditTagInput = z
+  .object({
+    id: IdSchema,
+    name: z.string().min(1).optional(),
+    status: TagStatus.optional(),
+  })
+  .refine((d) => d.name !== undefined || d.status !== undefined, {
+    message: "Provide at least one of name or status",
+  });
+
+// ─── Tag ─────────────────────────────────────────────────────────────────────
+
+export const TagSummary = z.object({
+  id: IdSchema,
+  name: z.string(),
+  path: z.string(),
+  parentId: IdSchema.nullable(),
+  status: TagStatus,
+});
+
+export const TagDetail = z.object({
+  id: IdSchema,
+  name: z.string(),
+  path: z.string(),
+  parentId: IdSchema.nullable(),
+  status: TagStatus,
+  childTagIds: z.array(IdSchema),
+});
+
+// ─── Resolution ──────────────────────────────────────────────────────────────
+
+export const ResolveCandidate = z.object({
+  id: IdSchema,
+  name: z.string(),
+  path: z.string(),
+  type: EntityType,
+});

package/src/server.ts

@@ -0,0 +1,58 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { allTools } from "./tools/index.js";
+
+const server = new McpServer({
+  name: "omnifocus-mcp",
+  version: "0.1.0",
+});
+
+for (const tool of allTools) {
+  // Extract the shape from the zod object schema for registerTool.
+  // .refine() wraps in ZodEffects which has no .shape; unwrap via ._def.schema first.
+  const baseSchema =
+    tool.inputSchema instanceof z.ZodEffects
+      ? (tool.inputSchema._def.schema as z.AnyZodObject)
+      : (tool.inputSchema as z.AnyZodObject);
+  const inputShape = baseSchema.shape;
+
+  server.registerTool(
+    tool.name,
+    {
+      description: tool.description,
+      inputSchema: inputShape,
+    },
+    async (args: Record<string, unknown>) => {
+      try {
+        // Validate input (already parsed by MCP SDK, re-parse for our shape)
+        const input = tool.inputSchema.parse(args);
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const result = await (tool.handler as (input: any) => Promise<unknown>)(input);
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: JSON.stringify(result, null, 2),
+            },
+          ],
+        };
+      } catch (err) {
+        const message =
+          err instanceof Error ? err.message : String(err);
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: `Error: ${message}`,
+            },
+          ],
+          isError: true,
+        };
+      }
+    }
+  );
+}
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/src/snippets/complete_project.js

@@ -0,0 +1,73 @@
+/**
+ * complete_project.js — Mark a project complete by ID
+ *
+ * PASTE-TO-CONSOLE:
+ *   Replace ARGS_PLACEHOLDER with: { id: "your-project-id" }
+ *   Example: const args = { id: "jMBMptE7rJ1" };
+ */
+(() => {
+  const args = __ARGS__;
+
+  function NotFoundError(msg) { var e = new Error(msg); e.name = "NotFoundError"; return e; }
+
+  function isoOrNull(d) { return d ? d.toISOString() : null; }
+
+  function folderPath(project) {
+    var parts = [];
+    var container = project.parentFolder;
+    while (container) {
+      parts.unshift(container.name);
+      container = container.parent;
+    }
+    return parts.join(" \u25b8 ");
+  }
+
+  function projectType(project) {
+    if (project.containsSingletonActions) return "singleActions";
+    if (project.sequential) return "sequential";
+    return "parallel";
+  }
+
+  function projectStatus(project) {
+    var s = project.status;
+    if (s === Project.Status.Active) return "active";
+    if (s === Project.Status.OnHold) return "onHold";
+    if (s === Project.Status.Done) return "done";
+    if (s === Project.Status.Dropped) return "dropped";
+    return "active";
+  }
+
+  function reviewIntervalString(p) {
+    try {
+      var ri = p.reviewInterval;
+      if (!ri) return null;
+      return ri.steps + ' ' + ri.unit;
+    } catch(_) { return null; }
+  }
+
+  function projectDetail(project) {
+    return {
+      id: project.id.primaryKey,
+      name: project.name,
+      note: project.note || "",
+      folderPath: folderPath(project),
+      status: projectStatus(project),
+      type: projectType(project),
+      flagged: project.flagged || false,
+      deferDate: isoOrNull(project.deferDate),
+      dueDate: isoOrNull(project.dueDate),
+      completionDate: isoOrNull(project.completionDate),
+      reviewInterval: reviewIntervalString(project),
+      nextReviewDate: isoOrNull(project.nextReviewDate),
+      lastReviewDate: isoOrNull(project.lastReviewDate),
+      tagIds: (project.tags || []).map(function(t) { return t.id.primaryKey; }),
+    };
+  }
+
+  var project = flattenedProjects.find(function(p) { return p.id.primaryKey === args.id; });
+  if (!project) throw new NotFoundError("Project not found: " + args.id);
+
+  project.markComplete();
+
+  return JSON.stringify({ ok: true, data: projectDetail(project) });
+})();

package/src/snippets/complete_task.js

@@ -0,0 +1,85 @@
+/**
+ * complete_task.js — Mark a task complete by ID
+ *
+ * PASTE-TO-CONSOLE:
+ *   Replace ARGS_PLACEHOLDER with: { id: "your-task-id" }
+ *   Example: const args = { id: "jMBMptE7rJ1" };
+ */
+(() => {
+  const args = __ARGS__;
+
+  function NotFoundError(msg) { var e = new Error(msg); e.name = "NotFoundError"; return e; }
+
+  function isoOrNull(d) { return d ? d.toISOString() : null; }
+
+  function taskStatus(task) {
+    try {
+      const s = task.taskStatus;
+      if (s === Task.Status.Available) return "available";
+      if (s === Task.Status.Blocked) return "blocked";
+      if (s === Task.Status.Completed) return "complete";
+      if (s === Task.Status.Dropped) return "dropped";
+      if (s === Task.Status.DueSoon) return "dueSoon";
+      if (s === Task.Status.Next) return "next";
+      if (s === Task.Status.Overdue) return "overdue";
+      return "incomplete";
+    } catch(_) { return "incomplete"; }
+  }
+
+  function parseRepetitionRule(rule) {
+    if (!rule) return null;
+    try {
+      var parts = {};
+      (rule.ruleString || "").split(";").forEach(function(part) {
+        var kv = part.split("=");
+        if (kv.length === 2) parts[kv[0]] = kv[1];
+      });
+      var freqMap = { DAILY: "daily", WEEKLY: "weekly", MONTHLY: "monthly", YEARLY: "yearly" };
+      var frequency = freqMap[parts["FREQ"]] || "daily";
+      var interval = parts["INTERVAL"] ? parseInt(parts["INTERVAL"], 10) : 1;
+      var ABBR_DAY = { SU: "sunday", MO: "monday", TU: "tuesday", WE: "wednesday", TH: "thursday", FR: "friday", SA: "saturday" };
+      var daysOfWeek = parts["BYDAY"] ? parts["BYDAY"].split(",").map(function(a) { return ABBR_DAY[a]; }).filter(Boolean) : undefined;
+      var ms = String(rule.method);
+      var method = ms.indexOf("DueDate") >= 0 ? "dueDate" : ms.indexOf("DeferUntilDate") >= 0 ? "start" : "fixed";
+      var result = { frequency: frequency, interval: interval, method: method };
+      if (daysOfWeek && daysOfWeek.length > 0) result.daysOfWeek = daysOfWeek;
+      return result;
+    } catch(_) { return null; }
+  }
+
+  function taskDetail(task) {
+    var containerId = null;
+    var containerType = null;
+    if (task.parentTask) {
+      containerId = task.parentTask.id.primaryKey;
+      containerType = "task";
+    } else if (task.containingProject) {
+      containerId = task.containingProject.id.primaryKey;
+      containerType = "project";
+    }
+    return {
+      id: task.id.primaryKey,
+      name: task.name,
+      note: task.note || "",
+      status: taskStatus(task),
+      flagged: task.flagged || false,
+      deferDate: isoOrNull(task.deferDate),
+      plannedDate: isoOrNull(task.plannedDate),
+      dueDate: isoOrNull(task.dueDate),
+      completionDate: isoOrNull(task.completionDate),
+      estimatedMinutes: task.estimatedMinutes || null,
+      containerId: containerId,
+      containerType: containerType,
+      tagIds: (task.tags || []).map(function(t) { return t.id.primaryKey; }),
+      parentTaskId: task.parentTask ? task.parentTask.id.primaryKey : null,
+      repetitionRule: parseRepetitionRule(task.repetitionRule),
+    };
+  }
+
+  var task = flattenedTasks.find(function(t) { return t.id.primaryKey === args.id; });
+  if (!task) throw new NotFoundError("Task not found: " + args.id);
+
+  task.markComplete();
+
+  return JSON.stringify({ ok: true, data: taskDetail(task) });
+})();

package/src/snippets/create_folder.js

@@ -0,0 +1,52 @@
+/**
+ * create_folder.js — Create a new folder in OmniFocus
+ *
+ * PASTE-TO-CONSOLE:
+ *   Replace ARGS_PLACEHOLDER with one of:
+ *     { name: "My Folder" }
+ *     { name: "Nested Folder", parentFolderId: "abc123" }
+ */
+(() => {
+  const args = __ARGS__;
+
+  function NotFoundError(msg) { var e = new Error(msg); e.name = "NotFoundError"; return e; }
+
+  function buildPath(folder) {
+    var parts = [];
+    var current = folder;
+    while (current) {
+      parts.unshift(current.name);
+      current = current.parent;
+    }
+    return parts.join(" \u25b8 ");
+  }
+
+  function folderStatus(folder) {
+    try {
+      return folder.active === false ? "dropped" : "active";
+    } catch(_) { return "active"; }
+  }
+
+  function folderDetail(folder) {
+    return {
+      id: folder.id.primaryKey,
+      name: folder.name,
+      path: buildPath(folder),
+      parentId: folder.parent ? folder.parent.id.primaryKey : null,
+      status: folderStatus(folder),
+      childFolderIds: (folder.folders || []).map(function(f) { return f.id.primaryKey; }),
+      projectIds: (folder.projects || []).map(function(p) { return p.id.primaryKey; }),
+    };
+  }
+
+  var folder;
+  if (args.parentFolderId) {
+    var parent = flattenedFolders.find(function(f) { return f.id.primaryKey === args.parentFolderId; });
+    if (!parent) throw new NotFoundError("Folder not found: " + args.parentFolderId);
+    folder = new Folder(args.name, parent);
+  } else {
+    folder = new Folder(args.name);
+  }
+
+  return JSON.stringify({ ok: true, data: folderDetail(folder) });
+})();

package/src/snippets/create_project.js

@@ -0,0 +1,107 @@
+/**
+ * create_project.js — Create a new project in OmniFocus
+ *
+ * PASTE-TO-CONSOLE:
+ *   Replace ARGS_PLACEHOLDER with one of:
+ *     { name: "My Project" }
+ *     { name: "My Project", folderId: "abc123" }
+ *     { name: "My Project", type: "sequential", status: "onHold" }
+ */
+(() => {
+  const args = __ARGS__;
+
+  function NotFoundError(msg) { var e = new Error(msg); e.name = "NotFoundError"; return e; }
+
+  function isoOrNull(d) { return d ? d.toISOString() : null; }
+
+  function folderPath(project) {
+    var parts = [];
+    var container = project.parentFolder;
+    while (container) {
+      parts.unshift(container.name);
+      container = container.parent;
+    }
+    return parts.join(" \u25b8 ");
+  }
+
+  function projectType(project) {
+    if (project.containsSingletonActions) return "singleActions";
+    if (project.sequential) return "sequential";
+    return "parallel";
+  }
+
+  function projectStatus(project) {
+    var s = project.status;
+    if (s === Project.Status.Active) return "active";
+    if (s === Project.Status.OnHold) return "onHold";
+    if (s === Project.Status.Done) return "done";
+    if (s === Project.Status.Dropped) return "dropped";
+    return "active";
+  }
+
+  function reviewIntervalString(p) {
+    try {
+      var ri = p.reviewInterval;
+      if (!ri) return null;
+      return ri.steps + ' ' + ri.unit;
+    } catch(_) { return null; }
+  }
+
+  function projectDetail(project) {
+    return {
+      id: project.id.primaryKey,
+      name: project.name,
+      note: project.note || "",
+      folderPath: folderPath(project),
+      status: projectStatus(project),
+      type: projectType(project),
+      flagged: project.flagged || false,
+      deferDate: isoOrNull(project.deferDate),
+      dueDate: isoOrNull(project.dueDate),
+      completionDate: isoOrNull(project.completionDate),
+      reviewInterval: reviewIntervalString(project),
+      nextReviewDate: isoOrNull(project.nextReviewDate),
+      lastReviewDate: isoOrNull(project.lastReviewDate),
+      tagIds: (project.tags || []).map(function(t) { return t.id.primaryKey; }),
+    };
+  }
+
+  var position;
+  if (args.folderId) {
+    var folder = flattenedFolders.find(function(f) { return f.id.primaryKey === args.folderId; });
+    if (!folder) throw new NotFoundError("Folder not found: " + args.folderId);
+    position = folder;
+  }
+
+  var project = position ? new Project(args.name, position) : new Project(args.name);
+
+  if (args.note !== undefined) project.note = args.note;
+  if (args.flagged !== undefined) project.flagged = args.flagged;
+  if (args.deferDate !== undefined && args.deferDate !== null) project.deferDate = new Date(args.deferDate);
+  if (args.dueDate !== undefined && args.dueDate !== null) project.dueDate = new Date(args.dueDate);
+
+  if (args.type !== undefined) {
+    project.sequential = args.type === "sequential";
+    project.containsSingletonActions = args.type === "singleActions";
+  }
+
+  if (args.status !== undefined) {
+    project.status = args.status === "onHold" ? Project.Status.OnHold : Project.Status.Active;
+  }
+
+  if (args.reviewInterval !== undefined && args.reviewInterval !== null) {
+    // Project.ReviewInterval is not constructible via evaluateJavascript;
+    // mutate the existing reviewInterval object in-place instead.
+    project.reviewInterval.steps = args.reviewInterval.steps;
+  }
+
+  if (args.tagIds && args.tagIds.length > 0) {
+    args.tagIds.forEach(function(tagId) {
+      var tag = flattenedTags.find(function(t) { return t.id.primaryKey === tagId; });
+      if (!tag) throw new NotFoundError("Tag not found: " + tagId);
+      project.addTag(tag);
+    });
+  }
+
+  return JSON.stringify({ ok: true, data: projectDetail(project) });
+})();

package/src/snippets/create_tag.js

@@ -0,0 +1,55 @@
+/**
+ * create_tag.js — Create a new tag in OmniFocus
+ *
+ * PASTE-TO-CONSOLE:
+ *   Replace ARGS_PLACEHOLDER with one of:
+ *     { name: "Waiting" }
+ *     { name: "Email", parentTagId: "abc123" }
+ */
+(() => {
+  const args = __ARGS__;
+
+  function NotFoundError(msg) { var e = new Error(msg); e.name = "NotFoundError"; return e; }
+
+  function buildPath(tag) {
+    var parts = [];
+    var current = tag;
+    while (current) {
+      parts.unshift(current.name);
+      current = current.parent;
+    }
+    return parts.join(" \u25b8 ");
+  }
+
+  function tagStatus(tag) {
+    try {
+      var s = tag.status;
+      if (s === Tag.Status.Active) return "active";
+      if (s === Tag.Status.OnHold) return "onHold";
+      if (s === Tag.Status.Dropped) return "dropped";
+      return "active";
+    } catch(_) { return "active"; }
+  }
+
+  function tagDetail(tag) {
+    return {
+      id: tag.id.primaryKey,
+      name: tag.name,
+      path: buildPath(tag),
+      parentId: tag.parent ? tag.parent.id.primaryKey : null,
+      status: tagStatus(tag),
+      childTagIds: (tag.children || []).map(function(c) { return c.id.primaryKey; }),
+    };
+  }
+
+  var tag;
+  if (args.parentTagId) {
+    var parent = flattenedTags.find(function(t) { return t.id.primaryKey === args.parentTagId; });
+    if (!parent) throw new NotFoundError("Tag not found: " + args.parentTagId);
+    tag = new Tag(args.name, parent);
+  } else {
+    tag = new Tag(args.name);
+  }
+
+  return JSON.stringify({ ok: true, data: tagDetail(tag) });
+})();