@scardis/omnifocus-mcp 0.1.0

package/test/integration/fixtures.ts

@@ -0,0 +1,219 @@
+import { randomUUID } from "crypto";
+import { runSnippet } from "../../src/runtime/bridge.js";
+
+export interface TestFixture {
+  folderId: string;
+  folderName: string;
+}
+
+/**
+ * Creates a top-level OmniFocus folder named __MCP_TEST_<uuid>__.
+ * All test fixtures must be created inside this folder.
+ * Returns the folder's id.primaryKey.
+ */
+export async function createTestFolder(): Promise<TestFixture> {
+  const name = `__MCP_TEST_${randomUUID()}__`;
+
+  // We need a create-folder snippet for fixtures.
+  // Since core CRUD lands in the next change, we inline a minimal creation here.
+  const { spawnSync } = await import("child_process");
+  const script = `
+    (function() {
+      try {
+        var app = Application('OmniFocus');
+        app.includeStandardAdditions = true;
+        var snippet = (function() {
+          var name = ${JSON.stringify(name)};
+          var snip = "(() => { var f = new Folder(" + JSON.stringify(name) + "); return JSON.stringify({ok:true,data:{id:f.id.primaryKey,name:f.name}}); })()";
+          return snip;
+        })();
+        var result = app.evaluateJavascript(snippet);
+        $.NSFileHandle.fileHandleWithStandardOutput.writeData(
+          $.NSString.alloc.initWithString(result + '\\n').dataUsingEncoding($.NSUTF8StringEncoding)
+        );
+      } catch(e) {
+        $.NSFileHandle.fileHandleWithStandardOutput.writeData(
+          $.NSString.alloc.initWithString(JSON.stringify({ok:false,error:{name:e.name||'Error',message:e.message||String(e)}}) + '\\n').dataUsingEncoding($.NSUTF8StringEncoding)
+        );
+      }
+    })();
+  `;
+
+  const result = spawnSync("osascript", ["-l", "JavaScript"], {
+    input: script,
+    encoding: "utf-8",
+    timeout: 15_000,
+  });
+
+  const stdout = result.stdout || "";
+  const line = stdout.split("\n").find((l) => l.trim().startsWith("{"));
+  if (!line) throw new Error(`createTestFolder: no JSON in output: ${stdout}`);
+  const parsed = JSON.parse(line) as {
+    ok: boolean;
+    data?: { id: string; name: string };
+    error?: { message: string };
+  };
+  if (!parsed.ok || !parsed.data) {
+    throw new Error(`createTestFolder failed: ${parsed.error?.message}`);
+  }
+
+  return { folderId: parsed.data.id, folderName: parsed.data.name };
+}
+
+/**
+ * Removes the test fixture folder (and all contents) by ID.
+ */
+export async function cleanupTestFolder(folderId: string): Promise<void> {
+  const { spawnSync } = await import("child_process");
+  // deleteObject(folder) alone leaves the folder shell behind in OmniFocus.
+  // Must explicitly delete projects first, child folders recursively, then the folder.
+  const snippet = `(() => {
+    function deleteFolder(f) {
+      f.flattenedProjects.forEach(function(p) { deleteObject(p); });
+      f.folders.forEach(function(child) { deleteFolder(child); });
+      deleteObject(f);
+    }
+    var f = flattenedFolders.find(function(f){ return f.id.primaryKey === ${JSON.stringify(folderId)}; });
+    if (f) { deleteFolder(f); }
+    return JSON.stringify({ok:true,data:null});
+  })()`;
+  const script = `
+    (function() {
+      var app = Application('OmniFocus');
+      app.includeStandardAdditions = true;
+      try {
+        var result = app.evaluateJavascript(${JSON.stringify(snippet)});
+        $.NSFileHandle.fileHandleWithStandardOutput.writeData(
+          $.NSString.alloc.initWithString(result + '\\n').dataUsingEncoding($.NSUTF8StringEncoding)
+        );
+      } catch(e) {
+        $.NSFileHandle.fileHandleWithStandardOutput.writeData(
+          $.NSString.alloc.initWithString(JSON.stringify({ok:true,data:null}) + '\\n').dataUsingEncoding($.NSUTF8StringEncoding)
+        );
+      }
+    })();
+  `;
+  spawnSync("osascript", ["-l", "JavaScript"], {
+    input: script,
+    encoding: "utf-8",
+    timeout: 15_000,
+  });
+}
+
+/**
+ * Creates a project inside a fixture folder. Returns the project's id.primaryKey.
+ * Uses inline JXA so it does not depend on the create_project snippet.
+ */
+export async function createTestProject(
+  folderId: string,
+  name: string
+): Promise<string> {
+  const { spawnSync } = await import("child_process");
+  const snippet = `(() => {
+    var folder = flattenedFolders.find(function(f){ return f.id.primaryKey === ${JSON.stringify(folderId)}; });
+    if (!folder) throw new Error("Fixture folder not found: " + ${JSON.stringify(folderId)});
+    var proj = new Project(${JSON.stringify(name)}, folder);
+    return JSON.stringify({ok:true,data:{id:proj.id.primaryKey}});
+  })()`;
+  const script = `
+    (function() {
+      var app = Application('OmniFocus');
+      app.includeStandardAdditions = true;
+      try {
+        var r = app.evaluateJavascript(${JSON.stringify(snippet)});
+        $.NSFileHandle.fileHandleWithStandardOutput.writeData($.NSString.alloc.initWithString(r+'\\n').dataUsingEncoding($.NSUTF8StringEncoding));
+      } catch(e) {
+        $.NSFileHandle.fileHandleWithStandardOutput.writeData($.NSString.alloc.initWithString(JSON.stringify({ok:false,error:{name:e.name||'Error',message:e.message||String(e)}})+'\\n').dataUsingEncoding($.NSUTF8StringEncoding));
+      }
+    })();
+  `;
+  const result = spawnSync("osascript", ["-l", "JavaScript"], {
+    input: script,
+    encoding: "utf-8",
+    timeout: 15_000,
+  });
+  const line = (result.stdout || "").split("\n").find((l) => l.trim().startsWith("{"));
+  if (!line) throw new Error(`createTestProject: no JSON in output: ${result.stdout}`);
+  const parsed = JSON.parse(line) as { ok: boolean; data?: { id: string }; error?: { message: string } };
+  if (!parsed.ok || !parsed.data) throw new Error(`createTestProject failed: ${parsed.error?.message}`);
+  return parsed.data.id;
+}
+
+/**
+ * Creates a top-level tag. Returns the tag's id.primaryKey.
+ * Uses inline JXA so it does not depend on the create_tag snippet.
+ */
+export async function createTestTag(name: string): Promise<string> {
+  const { spawnSync } = await import("child_process");
+  const snippet = `(() => {
+    var tag = new Tag(${JSON.stringify(name)});
+    return JSON.stringify({ok:true,data:{id:tag.id.primaryKey}});
+  })()`;
+  const script = `
+    (function() {
+      var app = Application('OmniFocus');
+      app.includeStandardAdditions = true;
+      try {
+        var r = app.evaluateJavascript(${JSON.stringify(snippet)});
+        $.NSFileHandle.fileHandleWithStandardOutput.writeData($.NSString.alloc.initWithString(r+'\\n').dataUsingEncoding($.NSUTF8StringEncoding));
+      } catch(e) {
+        $.NSFileHandle.fileHandleWithStandardOutput.writeData($.NSString.alloc.initWithString(JSON.stringify({ok:false,error:{name:e.name||'Error',message:e.message||String(e)}})+'\\n').dataUsingEncoding($.NSUTF8StringEncoding));
+      }
+    })();
+  `;
+  const result = spawnSync("osascript", ["-l", "JavaScript"], {
+    input: script,
+    encoding: "utf-8",
+    timeout: 15_000,
+  });
+  const line = (result.stdout || "").split("\n").find((l) => l.trim().startsWith("{"));
+  if (!line) throw new Error(`createTestTag: no JSON in output: ${result.stdout}`);
+  const parsed = JSON.parse(line) as { ok: boolean; data?: { id: string }; error?: { message: string } };
+  if (!parsed.ok || !parsed.data) throw new Error(`createTestTag failed: ${parsed.error?.message}`);
+  return parsed.data.id;
+}
+
+/**
+ * Deletes a tag by id.primaryKey. Silent if not found.
+ * Uses inline JXA so it does not depend on the delete_tag snippet.
+ */
+export async function deleteTestTag(tagId: string): Promise<void> {
+  const { spawnSync } = await import("child_process");
+  const snippet = `(() => {
+    var tag = flattenedTags.find(function(t){ return t.id.primaryKey === ${JSON.stringify(tagId)}; });
+    if (tag) deleteObject(tag);
+    return JSON.stringify({ok:true,data:null});
+  })()`;
+  const script = `
+    (function() {
+      var app = Application('OmniFocus');
+      app.includeStandardAdditions = true;
+      try {
+        var r = app.evaluateJavascript(${JSON.stringify(snippet)});
+        $.NSFileHandle.fileHandleWithStandardOutput.writeData($.NSString.alloc.initWithString(r+'\\n').dataUsingEncoding($.NSUTF8StringEncoding));
+      } catch(e) {
+        $.NSFileHandle.fileHandleWithStandardOutput.writeData($.NSString.alloc.initWithString(JSON.stringify({ok:true,data:null})+'\\n').dataUsingEncoding($.NSUTF8StringEncoding));
+      }
+    })();
+  `;
+  spawnSync("osascript", ["-l", "JavaScript"], {
+    input: script,
+    encoding: "utf-8",
+    timeout: 15_000,
+  });
+}
+
+/**
+ * Helper: creates a fixture folder, runs fn, cleans up in afterAll.
+ * Usage: const fixture = await withTestFolder(async (f) => { ... });
+ */
+export async function withTestFolder<T>(
+  fn: (fixture: TestFixture) => Promise<T>
+): Promise<T> {
+  const fixture = await createTestFolder();
+  try {
+    return await fn(fixture);
+  } finally {
+    await cleanupTestFolder(fixture.folderId);
+  }
+}

package/test/integration/getTask.int.test.ts

@@ -0,0 +1,64 @@
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+import { runSnippet } from "../../src/runtime/bridge.js";
+import { createTestFolder, cleanupTestFolder, type TestFixture } from "./fixtures.js";
+import { TaskDetail } from "../../src/schemas/index.js";
+
+/**
+ * Integration test: get_task
+ *
+ * Creates a task with apostrophes and unicode in its name, retrieves by ID,
+ * asserts the name survives the round-trip. Proves Decision 2 end-to-end.
+ */
+describe("get_task (integration)", () => {
+  let fixture: TestFixture;
+  let taskId: string;
+  const taskName = "Finn's \"birthday\" — ▸ 🎉";
+  const taskNote = "Note with apostrophe's and line1\nline2";
+
+  beforeAll(async () => {
+    fixture = await createTestFolder();
+
+    // Create a project then a task inside it
+    const { spawnSync } = await import("child_process");
+    const createSnippet = `(() => {
+      var folder = flattenedFolders.find(function(f){ return f.id.primaryKey === ${JSON.stringify(fixture.folderId)}; });
+      if (!folder) throw new Error("Fixture folder not found");
+      var proj = new Project("TestProject", folder);
+      var task = new Task(${JSON.stringify(taskName)}, proj);
+      task.note = ${JSON.stringify(taskNote)};
+      return JSON.stringify({ok:true,data:{id:task.id.primaryKey}});
+    })()`;
+    const script = `
+      (function() {
+        var app = Application('OmniFocus');
+        app.includeStandardAdditions = true;
+        try {
+          var r = app.evaluateJavascript(${JSON.stringify(createSnippet)});
+          $.NSFileHandle.fileHandleWithStandardOutput.writeData($.NSString.alloc.initWithString(r+'\\n').dataUsingEncoding($.NSUTF8StringEncoding));
+        } catch(e) {
+          $.NSFileHandle.fileHandleWithStandardOutput.writeData($.NSString.alloc.initWithString(JSON.stringify({ok:false,error:{name:e.name,message:e.message}})+'\\n').dataUsingEncoding($.NSUTF8StringEncoding));
+        }
+      })();
+    `;
+    const result = spawnSync("osascript", ["-l", "JavaScript"], {
+      input: script, encoding: "utf-8", timeout: 15_000,
+    });
+    const line = (result.stdout || "").split("\n").find((l) => l.trim().startsWith("{"));
+    if (!line) throw new Error(`Could not create fixture task: ${result.stdout}`);
+    const parsed = JSON.parse(line) as { ok: boolean; data?: { id: string }; error?: { message: string } };
+    if (!parsed.ok || !parsed.data) throw new Error(`Create task failed: ${parsed.error?.message}`);
+    taskId = parsed.data.id;
+  });
+
+  afterAll(async () => {
+    await cleanupTestFolder(fixture.folderId);
+  });
+
+  it("retrieves task by ID with name and note intact (proves apostrophe/unicode safety)", async () => {
+    const raw = await runSnippet("get_task", { id: taskId });
+    const task = TaskDetail.parse(raw);
+    expect(task.id).toBe(taskId);
+    expect(task.name).toBe(taskName);
+    expect(task.note).toBe(taskNote);
+  });
+});

package/test/integration/listFoldersFiltered.int.test.ts

@@ -0,0 +1,98 @@
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+import { spawnSync } from "child_process";
+import { runSnippet } from "../../src/runtime/bridge.js";
+import { createTestFolder, cleanupTestFolder, type TestFixture } from "./fixtures.js";
+import { FolderSummary } from "../../src/schemas/index.js";
+import { z } from "zod";
+
+const FolderSummaryArray = z.array(FolderSummary);
+
+/**
+ * Creates a folder and immediately drops it (active = false).
+ * Returns the folder id.
+ */
+async function createDroppedFolder(name: string): Promise<string> {
+  const snippet = `(() => {
+    var f = new Folder(${JSON.stringify(name)});
+    f.active = false;
+    return JSON.stringify({ok:true,data:{id:f.id.primaryKey}});
+  })()`;
+  const script = `(function(){
+    var app = Application('OmniFocus');
+    app.includeStandardAdditions = true;
+    try {
+      var r = app.evaluateJavascript(${JSON.stringify(snippet)});
+      $.NSFileHandle.fileHandleWithStandardOutput.writeData($.NSString.alloc.initWithString(r+'\\n').dataUsingEncoding($.NSUTF8StringEncoding));
+    } catch(e) {
+      $.NSFileHandle.fileHandleWithStandardOutput.writeData($.NSString.alloc.initWithString(JSON.stringify({ok:false,error:{message:String(e)}})+'\\n').dataUsingEncoding($.NSUTF8StringEncoding));
+    }
+  })();`;
+  const result = spawnSync("osascript", ["-l", "JavaScript"], { input: script, encoding: "utf-8", timeout: 15_000 });
+  const line = (result.stdout || "").split("\n").find((l) => l.trim().startsWith("{"));
+  if (!line) throw new Error(`createDroppedFolder: no JSON in output: ${result.stdout}`);
+  const parsed = JSON.parse(line) as { ok: boolean; data?: { id: string }; error?: { message: string } };
+  if (!parsed.ok || !parsed.data) throw new Error(`createDroppedFolder failed: ${parsed.error?.message}`);
+  return parsed.data.id;
+}
+
+async function deleteFolder(folderId: string): Promise<void> {
+  const snippet = `(() => {
+    var f = flattenedFolders.find(function(f){ return f.id.primaryKey === ${JSON.stringify(folderId)}; });
+    if (f) deleteObject(f);
+    return JSON.stringify({ok:true,data:null});
+  })()`;
+  const script = `(function(){
+    var app = Application('OmniFocus');
+    app.includeStandardAdditions = true;
+    try {
+      var r = app.evaluateJavascript(${JSON.stringify(snippet)});
+      $.NSFileHandle.fileHandleWithStandardOutput.writeData($.NSString.alloc.initWithString(r+'\\n').dataUsingEncoding($.NSUTF8StringEncoding));
+    } catch(_) {}
+  })();`;
+  spawnSync("osascript", ["-l", "JavaScript"], { input: script, encoding: "utf-8", timeout: 15_000 });
+}
+
+describe("list_folders filtering (integration)", () => {
+  let activeFixture: TestFixture;
+  let droppedFolderId: string;
+
+  beforeAll(async () => {
+    activeFixture = await createTestFolder();
+    droppedFolderId = await createDroppedFolder(`__MCP_DROPPED_FOLDER_TEST__`);
+  });
+
+  afterAll(async () => {
+    await cleanupTestFolder(activeFixture.folderId);
+    await deleteFolder(droppedFolderId);
+  });
+
+  it("no filter returns all folders including dropped", async () => {
+    const raw = await runSnippet("list_folders", {});
+    const folders = FolderSummaryArray.parse(raw);
+    const ids = folders.map((f) => f.id);
+    expect(ids).toContain(activeFixture.folderId);
+    expect(ids).toContain(droppedFolderId);
+  });
+
+  it("status filter 'active' returns only active folders", async () => {
+    const raw = await runSnippet("list_folders", { filter: { status: "active" } });
+    const folders = FolderSummaryArray.parse(raw);
+    expect(folders.every((f) => f.status === "active")).toBe(true);
+    expect(folders.some((f) => f.id === activeFixture.folderId)).toBe(true);
+    expect(folders.some((f) => f.id === droppedFolderId)).toBe(false);
+  });
+
+  it("status filter 'dropped' returns only dropped folders", async () => {
+    const raw = await runSnippet("list_folders", { filter: { status: "dropped" } });
+    const folders = FolderSummaryArray.parse(raw);
+    expect(folders.every((f) => f.status === "dropped")).toBe(true);
+    expect(folders.some((f) => f.id === droppedFolderId)).toBe(true);
+    expect(folders.some((f) => f.id === activeFixture.folderId)).toBe(false);
+  });
+
+  it("limit caps the number of returned folders", async () => {
+    const raw = await runSnippet("list_folders", { limit: 1 });
+    const folders = FolderSummaryArray.parse(raw);
+    expect(folders.length).toBeLessThanOrEqual(1);
+  });
+});

package/test/integration/listProjects.int.test.ts

@@ -0,0 +1,73 @@
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+import { runSnippet } from "../../src/runtime/bridge.js";
+import { createTestFolder, cleanupTestFolder, type TestFixture } from "./fixtures.js";
+import { z } from "zod";
+import { ProjectSummary } from "../../src/schemas/index.js";
+
+/**
+ * Integration test: list_projects
+ *
+ * Creates a fixture folder with a child project, calls the real bridge,
+ * asserts the fixture project appears with the correct folder path.
+ */
+describe("list_projects (integration)", () => {
+  let fixture: TestFixture;
+  let projectId: string;
+  const projectName = `TestProject_${Date.now()}`;
+
+  beforeAll(async () => {
+    fixture = await createTestFolder();
+
+    // Create a project inside the fixture folder via inline snippet
+    const { spawnSync } = await import("child_process");
+    const folderName = fixture.folderName;
+    const createSnippet = `(() => {
+      var folder = flattenedFolders.find(function(f){ return f.id.primaryKey === ${JSON.stringify(fixture.folderId)}; });
+      if (!folder) throw new Error("Fixture folder not found");
+      var p = new Project(${JSON.stringify(projectName)}, folder);
+      return JSON.stringify({ok:true,data:{id:p.id.primaryKey}});
+    })()`;
+    const script = `
+      (function() {
+        var app = Application('OmniFocus');
+        app.includeStandardAdditions = true;
+        try {
+          var r = app.evaluateJavascript(${JSON.stringify(createSnippet)});
+          $.NSFileHandle.fileHandleWithStandardOutput.writeData($.NSString.alloc.initWithString(r+'\\n').dataUsingEncoding($.NSUTF8StringEncoding));
+        } catch(e) {
+          $.NSFileHandle.fileHandleWithStandardOutput.writeData($.NSString.alloc.initWithString(JSON.stringify({ok:false,error:{name:e.name,message:e.message}})+'\\n').dataUsingEncoding($.NSUTF8StringEncoding));
+        }
+      })();
+    `;
+    const result = spawnSync("osascript", ["-l", "JavaScript"], {
+      input: script, encoding: "utf-8", timeout: 15_000,
+    });
+    const line = (result.stdout || "").split("\n").find((l) => l.trim().startsWith("{"));
+    if (!line) throw new Error(`Could not create fixture project: ${result.stdout}`);
+    const parsed = JSON.parse(line) as { ok: boolean; data?: { id: string }; error?: { message: string } };
+    if (!parsed.ok || !parsed.data) throw new Error(`Create project failed: ${parsed.error?.message}`);
+    projectId = parsed.data.id;
+  });
+
+  afterAll(async () => {
+    await cleanupTestFolder(fixture.folderId);
+  });
+
+  it("returns the fixture project with correct folder path", async () => {
+    const raw = await runSnippet("list_projects", {});
+    const projects = z.array(ProjectSummary).parse(raw);
+    const found = projects.find((p) => p.id === projectId);
+    expect(found).toBeDefined();
+    expect(found!.name).toBe(projectName);
+    expect(found!.folderPath).toBe(fixture.folderName);
+  });
+
+  it("returns id.primaryKey for every project", async () => {
+    const raw = await runSnippet("list_projects", {});
+    const projects = z.array(ProjectSummary).parse(raw);
+    for (const p of projects) {
+      expect(p.id).toBeTruthy();
+      expect(typeof p.id).toBe("string");
+    }
+  });
+});

package/test/integration/listProjectsFiltered.int.test.ts

@@ -0,0 +1,96 @@
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+import { runSnippet } from "../../src/runtime/bridge.js";
+import { createTestFolder, cleanupTestFolder, createTestProject, type TestFixture } from "./fixtures.js";
+import { ProjectSummary } from "../../src/schemas/index.js";
+import { z } from "zod";
+
+const ProjectSummaryArray = z.array(ProjectSummary);
+
+describe("list_projects filtering (integration)", () => {
+  let fixture: TestFixture;
+  let activeProjectId: string;
+  let flaggedProjectId: string;
+  let completedProjectId: string;
+
+  beforeAll(async () => {
+    fixture = await createTestFolder();
+
+    // Active unflagged project
+    activeProjectId = await createTestProject(fixture.folderId, "__mcp_active_proj__");
+
+    // Flagged project
+    const flaggedRaw = await runSnippet("create_project", {
+      name: "__mcp_flagged_proj__",
+      folderId: fixture.folderId,
+      flagged: true,
+    });
+    flaggedProjectId = (flaggedRaw as { id: string }).id;
+
+    // Completed project
+    completedProjectId = await createTestProject(fixture.folderId, "__mcp_done_proj__");
+    await runSnippet("complete_project", { id: completedProjectId });
+  });
+
+  afterAll(async () => {
+    await cleanupTestFolder(fixture.folderId);
+  });
+
+  it("returns folderId and flagged on each project summary", async () => {
+    const raw = await runSnippet("list_projects", { filter: { folderId: fixture.folderId } });
+    const projects = ProjectSummaryArray.parse(raw);
+    expect(projects.length).toBeGreaterThan(0);
+    for (const p of projects) {
+      expect(p).toHaveProperty("folderId");
+      expect(p).toHaveProperty("flagged");
+      expect(typeof p.flagged).toBe("boolean");
+    }
+  });
+
+  it("default excludes done and dropped projects", async () => {
+    const raw = await runSnippet("list_projects", { filter: { folderId: fixture.folderId } });
+    const projects = ProjectSummaryArray.parse(raw);
+    expect(projects.some((p) => p.id === completedProjectId)).toBe(false);
+    expect(projects.some((p) => p.id === activeProjectId)).toBe(true);
+  });
+
+  it("explicit status filter retrieves done projects", async () => {
+    const raw = await runSnippet("list_projects", {
+      filter: { folderId: fixture.folderId, status: ["done"] },
+    });
+    const projects = ProjectSummaryArray.parse(raw);
+    expect(projects.some((p) => p.id === completedProjectId)).toBe(true);
+    expect(projects.every((p) => p.status === "done")).toBe(true);
+  });
+
+  it("folderId filter returns only projects in that subtree", async () => {
+    const raw = await runSnippet("list_projects", { filter: { folderId: fixture.folderId } });
+    const projects = ProjectSummaryArray.parse(raw);
+    expect(projects.every((p) => p.folderId === fixture.folderId)).toBe(true);
+  });
+
+  it("flagged filter returns only flagged projects", async () => {
+    const raw = await runSnippet("list_projects", {
+      filter: { folderId: fixture.folderId, flagged: true },
+    });
+    const projects = ProjectSummaryArray.parse(raw);
+    expect(projects.length).toBeGreaterThan(0);
+    expect(projects.every((p) => p.flagged)).toBe(true);
+    expect(projects.some((p) => p.id === flaggedProjectId)).toBe(true);
+    expect(projects.some((p) => p.id === activeProjectId)).toBe(false);
+  });
+
+  it("limit caps the number of returned projects", async () => {
+    const raw = await runSnippet("list_projects", { limit: 1 });
+    const projects = ProjectSummaryArray.parse(raw);
+    expect(projects.length).toBeLessThanOrEqual(1);
+  });
+
+  it("non-existent folderId returns not-found error", async () => {
+    await expect(
+      runSnippet("list_projects", { filter: { folderId: "nonexistent-id-xyz" } })
+    ).rejects.toSatisfy((e: unknown) => {
+      const err = e as Record<string, unknown>;
+      return err.name === "ExecutionError" && err.errorName === "NotFoundError";
+    });
+  });
+});

package/test/integration/listTagsFiltered.int.test.ts

@@ -0,0 +1,54 @@
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+import { runSnippet } from "../../src/runtime/bridge.js";
+import { createTestTag, deleteTestTag } from "./fixtures.js";
+import { TagSummary } from "../../src/schemas/index.js";
+import { z } from "zod";
+
+const TagSummaryArray = z.array(TagSummary);
+
+describe("list_tags filtering (integration)", () => {
+  let activeTagId: string;
+  let onHoldTagId: string;
+
+  beforeAll(async () => {
+    activeTagId = await createTestTag("__MCP_ACTIVE_TAG_TEST__");
+    onHoldTagId = await createTestTag("__MCP_ONHOLD_TAG_TEST__");
+    // Set onHold via edit_tag
+    await runSnippet("edit_tag", { id: onHoldTagId, status: "onHold" });
+  });
+
+  afterAll(async () => {
+    await deleteTestTag(activeTagId);
+    await deleteTestTag(onHoldTagId);
+  });
+
+  it("no filter returns all tags including onHold", async () => {
+    const raw = await runSnippet("list_tags", {});
+    const tags = TagSummaryArray.parse(raw);
+    const ids = tags.map((t) => t.id);
+    expect(ids).toContain(activeTagId);
+    expect(ids).toContain(onHoldTagId);
+  });
+
+  it("status filter 'active' returns only active tags", async () => {
+    const raw = await runSnippet("list_tags", { filter: { status: "active" } });
+    const tags = TagSummaryArray.parse(raw);
+    expect(tags.every((t) => t.status === "active")).toBe(true);
+    expect(tags.some((t) => t.id === activeTagId)).toBe(true);
+    expect(tags.some((t) => t.id === onHoldTagId)).toBe(false);
+  });
+
+  it("status filter 'onHold' returns only onHold tags", async () => {
+    const raw = await runSnippet("list_tags", { filter: { status: "onHold" } });
+    const tags = TagSummaryArray.parse(raw);
+    expect(tags.every((t) => t.status === "onHold")).toBe(true);
+    expect(tags.some((t) => t.id === onHoldTagId)).toBe(true);
+    expect(tags.some((t) => t.id === activeTagId)).toBe(false);
+  });
+
+  it("limit caps the number of returned tags", async () => {
+    const raw = await runSnippet("list_tags", { limit: 1 });
+    const tags = TagSummaryArray.parse(raw);
+    expect(tags.length).toBeLessThanOrEqual(1);
+  });
+});