mcp-sunsama 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # mcp-sunsama
 
+## 0.10.0
+
+### Minor Changes
+
+- 52e464c: Refactor update-task-notes schema to use XOR pattern for content parameters
+
+  - Replace nested content object with separate html and markdown parameters
+  - Implement XOR validation ensuring exactly one content type is provided
+  - Add comprehensive test coverage for the new schema pattern
+  - Update tool implementation to handle simplified parameter structure
+  - Update documentation across README.md, CLAUDE.md, and API docs
+
 ## 0.9.0
 
 ### Minor Changes

package/CLAUDE.md

@@ -66,6 +66,7 @@ All tools use Zod schemas from `schemas.ts`:
 - Automatic TypeScript inference
 - Comprehensive parameter documentation
 - Union types for completion filters
+- XOR schema patterns for mutually exclusive parameters (e.g., `update-task-notes` requires either `html` OR `markdown`, but not both)
 
 ## Key Patterns
 
@@ -106,6 +107,7 @@ server.addTool({
 
 - `src/main.ts`: FastMCP server setup and tool definitions
 - `src/schemas.ts`: Zod validation schemas for all tools
+- `src/schemas.test.ts`: Comprehensive test suite for all Zod schemas including parameter validation, response schemas, and XOR patterns
 - `src/auth/`: Authentication strategies per transport type
 - `src/config/`: Environment configuration and validation
 - `src/utils/`: Reusable utilities (client resolution, filtering, formatting)

package/README.md

@@ -95,7 +95,7 @@ Add this configuration to your Claude Desktop MCP settings:
 - `get-task-by-id` - Get a specific task by its ID
 - `update-task-complete` - Mark tasks as complete
 - `update-task-planned-time` - Update the planned time (time estimate) for tasks
-- `update-task-notes` - Update task notes content with HTML or Markdown
+- `update-task-notes` - Update task notes content (requires either `html` or `markdown` parameter)
 - `update-task-snooze-date` - Reschedule tasks to different dates
 - `update-task-backlog` - Move tasks to the backlog
 - `delete-task` - Delete tasks permanently

package/dist/main.js

@@ -16,7 +16,7 @@ if (transportConfig.transportType === "stdio") {
 }
 const server = new FastMCP({
     name: "Sunsama API Server",
-    version: "0.9.0",
+    version: "0.10.0",
     instructions: `
 This MCP server provides access to the Sunsama API for task and project management.
 
@@ -575,11 +575,15 @@ server.addTool({
     execute: async (args, { session, log }) => {
         try {
             // Extract parameters
-            const { taskId, content, limitResponsePayload } = args;
+            const { taskId, html, markdown, limitResponsePayload } = args;
+            // Create simplified content object with type and value
+            const content = html
+                ? { type: "html", value: html }
+                : { type: "markdown", value: markdown };
             log.info("Updating task notes", {
                 taskId: taskId,
-                contentType: 'html' in content ? 'html' : 'markdown',
-                contentLength: ('html' in content ? content.html : content.markdown).length,
+                contentType: content.type,
+                contentLength: content.value.length,
                 limitResponsePayload: limitResponsePayload
             });
             // Get the appropriate client based on transport type
@@ -588,12 +592,14 @@ server.addTool({
             const options = {};
             if (limitResponsePayload !== undefined)
                 options.limitResponsePayload = limitResponsePayload;
-            // Call sunsamaClient.updateTaskNotes(taskId, content, options)
-            const result = await sunsamaClient.updateTaskNotes(taskId, content, options);
+            // Build content object for API call
+            const apiContent = content.type === "html" ? { html: content.value } : { markdown: content.value };
+            // Call sunsamaClient.updateTaskNotes(taskId, apiContent, options)
+            const result = await sunsamaClient.updateTaskNotes(taskId, apiContent, options);
             log.info("Successfully updated task notes", {
                 taskId: taskId,
                 success: result.success,
-                contentType: 'html' in content ? 'html' : 'markdown'
+                contentType: content.type
             });
             return {
                 content: [
@@ -612,7 +618,7 @@ server.addTool({
         catch (error) {
             log.error("Failed to update task notes", {
                 taskId: args.taskId,
-                contentType: 'html' in args.content ? 'html' : 'markdown',
+                contentType: args.html ? 'html' : 'markdown',
                 error: error instanceof Error ? error.message : 'Unknown error'
             });
             throw new Error(`Failed to update task notes: ${error instanceof Error ? error.message : 'Unknown error'}`);
@@ -752,11 +758,11 @@ Uses HTTP Basic Auth headers (per-request authentication):
 - **update-task-notes**: Update task notes content
   - Parameters:
     - \`taskId\` (required): The ID of the task to update notes for
-    - \`content\` (required): Task notes content in either HTML or Markdown format
-      - \`{html: string}\` OR \`{markdown: string}\` (mutually exclusive)
+    - \`html\` (required XOR): HTML content for the task notes
+    - \`markdown\` (required XOR): Markdown content for the task notes
     - \`limitResponsePayload\` (optional): Whether to limit response size (defaults to true)
   - Returns: JSON with update result
-  - Note: Supports both HTML and Markdown content with automatic format conversion
+  - Note: Exactly one of \`html\` or \`markdown\` must be provided (mutually exclusive)
 
 ### Stream Operations
 - **get-streams**: Get streams for the user's group

package/dist/schemas.d.ts

@@ -1,4 +1,8 @@
 import { z } from "zod";
+/**
+ * Helper Schemas
+ */
+export declare const jsonStringSchema: z.ZodEffects<z.ZodString, any, string>;
 /**
  * Task Operation Schemas
  */
@@ -141,39 +145,34 @@ export declare const updateTaskPlannedTimeSchema: z.ZodObject<{
     timeEstimateMinutes: number;
     limitResponsePayload?: boolean | undefined;
 }>;
-export declare const updateTaskNotesSchema: z.ZodObject<{
+export declare const updateTaskNotesSchema: z.ZodIntersection<z.ZodObject<{
     taskId: z.ZodString;
-    content: z.ZodUnion<[z.ZodObject<{
-        html: z.ZodString;
-    }, "strip", z.ZodTypeAny, {
-        html: string;
-    }, {
-        html: string;
-    }>, z.ZodObject<{
-        markdown: z.ZodString;
-    }, "strip", z.ZodTypeAny, {
-        markdown: string;
-    }, {
-        markdown: string;
-    }>]>;
     limitResponsePayload: z.ZodOptional<z.ZodBoolean>;
 }, "strip", z.ZodTypeAny, {
     taskId: string;
-    content: {
-        html: string;
-    } | {
-        markdown: string;
-    };
     limitResponsePayload?: boolean | undefined;
 }, {
     taskId: string;
-    content: {
-        html: string;
-    } | {
-        markdown: string;
-    };
     limitResponsePayload?: boolean | undefined;
-}>;
+}>, z.ZodUnion<[z.ZodObject<{
+    html: z.ZodString;
+    markdown: z.ZodOptional<z.ZodNever>;
+}, "strip", z.ZodTypeAny, {
+    html: string;
+    markdown?: undefined;
+}, {
+    html: string;
+    markdown?: undefined;
+}>, z.ZodObject<{
+    markdown: z.ZodString;
+    html: z.ZodOptional<z.ZodNever>;
+}, "strip", z.ZodTypeAny, {
+    markdown: string;
+    html?: undefined;
+}, {
+    markdown: string;
+    html?: undefined;
+}>]>>;
 /**
  * Response Type Schemas (for validation and documentation)
  */

package/dist/schemas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../src/schemas.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../src/schemas.ts"],"names":[],"mappings":"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"}

package/dist/schemas.js

@@ -1,4 +1,16 @@
 import { z } from "zod";
+/**
+ * Helper Schemas
+ */
+export const jsonStringSchema = z.string().transform((str, ctx) => {
+    try {
+        return JSON.parse(str);
+    }
+    catch (error) {
+        ctx.addIssue({ code: 'custom', message: 'Invalid JSON' });
+        return z.NEVER;
+    }
+});
 /**
  * Task Operation Schemas
  */
@@ -76,19 +88,22 @@ export const updateTaskPlannedTimeSchema = z.object({
     timeEstimateMinutes: z.number().int().min(0).describe("Time estimate in minutes (use 0 to clear the time estimate)"),
     limitResponsePayload: z.boolean().optional().describe("Whether to limit the response payload size"),
 });
-// Update task notes parameters
-export const updateTaskNotesSchema = z.object({
+// Update task notes base parameters (without content)
+const updateTaskNotesBaseSchema = z.object({
     taskId: z.string().min(1, "Task ID is required").describe("The ID of the task to update notes for"),
-    content: z.union([
-        z.object({
-            html: z.string().describe("HTML content for the task notes")
-        }),
-        z.object({
-            markdown: z.string().describe("Markdown content for the task notes")
-        })
-    ]).describe("Task notes content in either HTML or Markdown format"),
     limitResponsePayload: z.boolean().optional().describe("Whether to limit the response payload size (defaults to true)"),
 });
+// Update task notes parameters with XOR content
+export const updateTaskNotesSchema = updateTaskNotesBaseSchema.and(z.union([
+    z.object({
+        html: z.string().describe("HTML content for the task notes"),
+        markdown: z.never().optional()
+    }),
+    z.object({
+        markdown: z.string().describe("Markdown content for the task notes"),
+        html: z.never().optional()
+    })
+]));
 /**
  * Response Type Schemas (for validation and documentation)
  */

package/dist/schemas.test.js

@@ -1,5 +1,5 @@
 import { describe, test, expect } from "bun:test";
-import { completionFilterSchema, getTasksByDaySchema, getTasksBacklogSchema, getArchivedTasksSchema, getUserSchema, getStreamsSchema, createTaskSchema, updateTaskCompleteSchema, deleteTaskSchema, updateTaskSnoozeDateSchema, updateTaskBacklogSchema, updateTaskPlannedTimeSchema, userProfileSchema, groupSchema, userSchema, taskSchema, streamSchema, userResponseSchema, tasksResponseSchema, streamsResponseSchema, errorResponseSchema, } from "./schemas.js";
+import { completionFilterSchema, getTasksByDaySchema, getTasksBacklogSchema, getArchivedTasksSchema, getUserSchema, getStreamsSchema, createTaskSchema, updateTaskCompleteSchema, deleteTaskSchema, updateTaskSnoozeDateSchema, updateTaskBacklogSchema, updateTaskPlannedTimeSchema, updateTaskNotesSchema, userProfileSchema, groupSchema, userSchema, taskSchema, streamSchema, userResponseSchema, tasksResponseSchema, streamsResponseSchema, errorResponseSchema, } from "./schemas.js";
 describe("Tool Parameter Schemas", () => {
     describe("completionFilterSchema", () => {
         test("should accept valid completion filter values", () => {
@@ -252,6 +252,74 @@ describe("Tool Parameter Schemas", () => {
             })).toThrow();
         });
     });
+    describe("updateTaskNotesSchema", () => {
+        test("should accept valid HTML content", () => {
+            const htmlInput = {
+                taskId: "task-123",
+                html: "<p>This is HTML content</p>",
+                limitResponsePayload: true,
+            };
+            expect(() => updateTaskNotesSchema.parse(htmlInput)).not.toThrow();
+        });
+        test("should accept valid Markdown content", () => {
+            const markdownInput = {
+                taskId: "task-123",
+                markdown: "# This is Markdown content",
+                limitResponsePayload: true,
+            };
+            expect(() => updateTaskNotesSchema.parse(markdownInput)).not.toThrow();
+        });
+        test("should accept minimal HTML input", () => {
+            const minimalHtmlInput = {
+                taskId: "task-123",
+                html: "<p>Simple HTML</p>",
+            };
+            expect(() => updateTaskNotesSchema.parse(minimalHtmlInput)).not.toThrow();
+        });
+        test("should accept minimal Markdown input", () => {
+            const minimalMarkdownInput = {
+                taskId: "task-123",
+                markdown: "Simple markdown",
+            };
+            expect(() => updateTaskNotesSchema.parse(minimalMarkdownInput)).not.toThrow();
+        });
+        test("should reject both HTML and Markdown provided", () => {
+            const invalidInput = {
+                taskId: "task-123",
+                html: "<p>HTML content</p>",
+                markdown: "Markdown content",
+            };
+            expect(() => updateTaskNotesSchema.parse(invalidInput)).toThrow();
+        });
+        test("should reject neither HTML nor Markdown provided", () => {
+            const invalidInput = {
+                taskId: "task-123",
+                limitResponsePayload: true,
+            };
+            expect(() => updateTaskNotesSchema.parse(invalidInput)).toThrow();
+        });
+        test("should reject empty task ID", () => {
+            expect(() => updateTaskNotesSchema.parse({
+                taskId: "",
+                html: "<p>Content</p>",
+            })).toThrow();
+            expect(() => updateTaskNotesSchema.parse({
+                markdown: "Content",
+            })).toThrow();
+        });
+        test("should accept empty HTML content", () => {
+            expect(() => updateTaskNotesSchema.parse({
+                taskId: "task-123",
+                html: "",
+            })).not.toThrow();
+        });
+        test("should accept empty Markdown content", () => {
+            expect(() => updateTaskNotesSchema.parse({
+                taskId: "task-123",
+                markdown: "",
+            })).not.toThrow();
+        });
+    });
 });
 describe("Response Schemas", () => {
     describe("userProfileSchema", () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-sunsama",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "MCP server for Sunsama API integration",
   "type": "module",
   "private": false,

package/src/main.ts

@@ -35,7 +35,7 @@ if (transportConfig.transportType === "stdio") {
 
 const server = new FastMCP({
   name: "Sunsama API Server",
-  version: "0.9.0",
+  version: "0.10.0",
   instructions: `
 This MCP server provides access to the Sunsama API for task and project management.
 
@@ -697,12 +697,17 @@ server.addTool({
   execute: async (args, {session, log}) => {
     try {
       // Extract parameters
-      const {taskId, content, limitResponsePayload} = args;
+      const {taskId, html, markdown, limitResponsePayload} = args;
+
+      // Create simplified content object with type and value
+      const content = html 
+        ? {type: "html" as const, value: html} 
+        : {type: "markdown" as const, value: markdown!};
 
       log.info("Updating task notes", {
         taskId: taskId,
-        contentType: 'html' in content ? 'html' : 'markdown',
-        contentLength: ('html' in content ? content.html : content.markdown).length,
+        contentType: content.type,
+        contentLength: content.value.length,
         limitResponsePayload: limitResponsePayload
       });
 
@@ -715,17 +720,20 @@ server.addTool({
       } = {};
       if (limitResponsePayload !== undefined) options.limitResponsePayload = limitResponsePayload;
 
-      // Call sunsamaClient.updateTaskNotes(taskId, content, options)
+      // Build content object for API call
+      const apiContent = content.type === "html" ? {html: content.value} : {markdown: content.value};
+
+      // Call sunsamaClient.updateTaskNotes(taskId, apiContent, options)
       const result = await sunsamaClient.updateTaskNotes(
         taskId,
-        content,
+        apiContent,
         options
       );
 
       log.info("Successfully updated task notes", {
         taskId: taskId,
         success: result.success,
-        contentType: 'html' in content ? 'html' : 'markdown'
+        contentType: content.type
       });
 
       return {
@@ -745,7 +753,7 @@ server.addTool({
     } catch (error) {
       log.error("Failed to update task notes", {
         taskId: args.taskId,
-        contentType: 'html' in args.content ? 'html' : 'markdown',
+        contentType: args.html ? 'html' : 'markdown',
         error: error instanceof Error ? error.message : 'Unknown error'
       });
 
@@ -893,11 +901,11 @@ Uses HTTP Basic Auth headers (per-request authentication):
 - **update-task-notes**: Update task notes content
   - Parameters:
     - \`taskId\` (required): The ID of the task to update notes for
-    - \`content\` (required): Task notes content in either HTML or Markdown format
-      - \`{html: string}\` OR \`{markdown: string}\` (mutually exclusive)
+    - \`html\` (required XOR): HTML content for the task notes
+    - \`markdown\` (required XOR): Markdown content for the task notes
     - \`limitResponsePayload\` (optional): Whether to limit response size (defaults to true)
   - Returns: JSON with update result
-  - Note: Supports both HTML and Markdown content with automatic format conversion
+  - Note: Exactly one of \`html\` or \`markdown\` must be provided (mutually exclusive)
 
 ### Stream Operations
 - **get-streams**: Get streams for the user's group

package/src/schemas.test.ts

@@ -12,6 +12,7 @@ import {
   updateTaskSnoozeDateSchema,
   updateTaskBacklogSchema,
   updateTaskPlannedTimeSchema,
+  updateTaskNotesSchema,
   userProfileSchema,
   groupSchema,
   userSchema,
@@ -351,6 +352,91 @@ describe("Tool Parameter Schemas", () => {
       ).toThrow();
     });
   });
+
+  describe("updateTaskNotesSchema", () => {
+    test("should accept valid HTML content", () => {
+      const htmlInput = {
+        taskId: "task-123",
+        html: "<p>This is HTML content</p>",
+        limitResponsePayload: true,
+      };
+      expect(() => updateTaskNotesSchema.parse(htmlInput)).not.toThrow();
+    });
+
+    test("should accept valid Markdown content", () => {
+      const markdownInput = {
+        taskId: "task-123",
+        markdown: "# This is Markdown content",
+        limitResponsePayload: true,
+      };
+      expect(() => updateTaskNotesSchema.parse(markdownInput)).not.toThrow();
+    });
+
+    test("should accept minimal HTML input", () => {
+      const minimalHtmlInput = {
+        taskId: "task-123",
+        html: "<p>Simple HTML</p>",
+      };
+      expect(() => updateTaskNotesSchema.parse(minimalHtmlInput)).not.toThrow();
+    });
+
+    test("should accept minimal Markdown input", () => {
+      const minimalMarkdownInput = {
+        taskId: "task-123",
+        markdown: "Simple markdown",
+      };
+      expect(() => updateTaskNotesSchema.parse(minimalMarkdownInput)).not.toThrow();
+    });
+
+    test("should reject both HTML and Markdown provided", () => {
+      const invalidInput = {
+        taskId: "task-123",
+        html: "<p>HTML content</p>",
+        markdown: "Markdown content",
+      };
+      expect(() => updateTaskNotesSchema.parse(invalidInput)).toThrow();
+    });
+
+    test("should reject neither HTML nor Markdown provided", () => {
+      const invalidInput = {
+        taskId: "task-123",
+        limitResponsePayload: true,
+      };
+      expect(() => updateTaskNotesSchema.parse(invalidInput)).toThrow();
+    });
+
+    test("should reject empty task ID", () => {
+      expect(() =>
+        updateTaskNotesSchema.parse({
+          taskId: "",
+          html: "<p>Content</p>",
+        })
+      ).toThrow();
+      expect(() =>
+        updateTaskNotesSchema.parse({
+          markdown: "Content",
+        })
+      ).toThrow();
+    });
+
+    test("should accept empty HTML content", () => {
+      expect(() =>
+        updateTaskNotesSchema.parse({
+          taskId: "task-123",
+          html: "",
+        })
+      ).not.toThrow();
+    });
+
+    test("should accept empty Markdown content", () => {
+      expect(() =>
+        updateTaskNotesSchema.parse({
+          taskId: "task-123",
+          markdown: "",
+        })
+      ).not.toThrow();
+    });
+  });
 });
 
 describe("Response Schemas", () => {

package/src/schemas.ts

@@ -1,5 +1,18 @@
 import { z } from "zod";
 
+/**
+ * Helper Schemas
+ */
+
+export const jsonStringSchema = z.string().transform((str, ctx) => {
+  try {
+    return JSON.parse(str);
+  } catch (error) {
+    ctx.addIssue({ code: 'custom', message: 'Invalid JSON' });
+    return z.NEVER;
+  }
+});
+
 /**
  * Task Operation Schemas
  */
@@ -94,19 +107,25 @@ export const updateTaskPlannedTimeSchema = z.object({
   limitResponsePayload: z.boolean().optional().describe("Whether to limit the response payload size"),
 });
 
-// Update task notes parameters
-export const updateTaskNotesSchema = z.object({
+// Update task notes base parameters (without content)
+const updateTaskNotesBaseSchema = z.object({
   taskId: z.string().min(1, "Task ID is required").describe("The ID of the task to update notes for"),
-  content: z.union([
+  limitResponsePayload: z.boolean().optional().describe("Whether to limit the response payload size (defaults to true)"),
+});
+
+// Update task notes parameters with XOR content
+export const updateTaskNotesSchema = updateTaskNotesBaseSchema.and(
+  z.union([
     z.object({ 
-      html: z.string().describe("HTML content for the task notes") 
+      html: z.string().describe("HTML content for the task notes"),
+      markdown: z.never().optional()
     }),
     z.object({ 
-      markdown: z.string().describe("Markdown content for the task notes") 
+      markdown: z.string().describe("Markdown content for the task notes"),
+      html: z.never().optional()
     })
-  ]).describe("Task notes content in either HTML or Markdown format"),
-  limitResponsePayload: z.boolean().optional().describe("Whether to limit the response payload size (defaults to true)"),
-});
+  ])
+);
 
 /**
  * Response Type Schemas (for validation and documentation)