mcp-sunsama 0.8.0 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # 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
+
+- 953ecb7: Add update-task-notes tool for updating task notes content
+
+  - New `update-task-notes` tool supports updating task notes with HTML or Markdown content
+  - Accepts either `{html: string}` or `{markdown: string}` content format (mutually exclusive)
+  - Includes optional `limitResponsePayload` parameter for response optimization
+  - Integrates with Sunsama's collaborative editing system for proper synchronization
+  - Follows established patterns for tool implementation and error handling
+  - Updates API documentation, README, and CLAUDE.md with new tool information
+
 ## 0.8.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)
@@ -127,7 +129,7 @@ Optional:
 ### Task Operations
 Full CRUD support:
 - **Read**: `get-tasks-by-day`, `get-tasks-backlog`, `get-archived-tasks`, `get-task-by-id`, `get-streams`
-- **Write**: `create-task`, `update-task-complete`, `update-task-planned-time`, `update-task-snooze-date`, `update-task-backlog`, `delete-task`
+- **Write**: `create-task`, `update-task-complete`, `update-task-planned-time`, `update-task-notes`, `update-task-snooze-date`, `update-task-backlog`, `delete-task`
 
 Task read operations support response trimming. `get-tasks-by-day` includes completion filtering. `get-archived-tasks` includes enhanced pagination with hasMore flag for LLM decision-making.
 

package/README.md

@@ -95,6 +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 (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/bun.lock

@@ -7,7 +7,7 @@
         "@types/papaparse": "^5.3.16",
         "fastmcp": "3.3.1",
         "papaparse": "^5.5.3",
-        "sunsama-api": "0.7.0",
+        "sunsama-api": "0.8.0",
         "zod": "3.24.4",
       },
       "devDependencies": {
@@ -58,6 +58,8 @@
 
     "@manypkg/get-packages": ["@manypkg/get-packages@1.1.3", "", { "dependencies": { "@babel/runtime": "^7.5.5", "@changesets/types": "^4.0.1", "@manypkg/find-root": "^1.1.0", "fs-extra": "^8.1.0", "globby": "^11.0.0", "read-yaml-file": "^1.1.0" } }, "sha512-fo+QhuU3qE/2TQMQmbVMqaQ6EWbMhi4ABWP+O4AM1NqPBuy0OrApV5LO6BrrgnhtAHS2NH6RrVk9OL181tTi8A=="],
 
+    "@mixmark-io/domino": ["@mixmark-io/domino@2.2.0", "", {}, "sha512-Y28PR25bHXUg88kCV7nivXrP2Nj2RueZ3/l/jdx6J9f8J4nsEGcgX0Qe6lt7Pa+J79+kPiJU3LguR6O/6zrLOw=="],
+
     "@modelcontextprotocol/sdk": ["@modelcontextprotocol/sdk@1.12.1", "", { "dependencies": { "ajv": "^6.12.6", "content-type": "^1.0.5", "cors": "^2.8.5", "cross-spawn": "^7.0.5", "eventsource": "^3.0.2", "express": "^5.0.1", "express-rate-limit": "^7.5.0", "pkce-challenge": "^5.0.0", "raw-body": "^3.0.0", "zod": "^3.23.8", "zod-to-json-schema": "^3.24.1" } }, "sha512-KG1CZhZfWg+u8pxeM/mByJDScJSrjjxLc8fwQqbsS8xCjBmQfMNEBTotYdNanKekepnfRI85GtgQlctLFpcYPw=="],
 
     "@nodelib/fs.scandir": ["@nodelib/fs.scandir@2.1.5", "", { "dependencies": { "@nodelib/fs.stat": "2.0.5", "run-parallel": "^1.1.9" } }, "sha512-vq24Bq3ym5HEQm2NKCr3yXDwjc7vTsEThRDnkp2DK9p1uqLR+DHurm/NOTo0KG7HYHU7eppKZj3MyqYuMBf62g=="],
@@ -282,6 +284,8 @@
 
     "lodash.startcase": ["lodash.startcase@4.4.0", "", {}, "sha512-+WKqsK294HMSc2jEbNgpHpd0JfIBhp7rEV4aqXWqFr6AlXov+SlcgB1Fv01y2kGe3Gc8nMW7VA0SrGuSkRfIEg=="],
 
+    "marked": ["marked@14.1.4", "", { "bin": { "marked": "bin/marked.js" } }, "sha512-vkVZ8ONmUdPnjCKc5uTRvmkRbx4EAi2OkTOXmfTDhZz3OFqMNBM1oTTWwTr4HY4uAEojhzPf+Fy8F1DWa3Sndg=="],
+
     "math-intrinsics": ["math-intrinsics@1.1.0", "", {}, "sha512-/IXtbwEk5HTPyEwyKX6hGkYXxM9nbj64B+ilVJnC/R6B0pH5G4V3b0pVbL7DBj4tkhBAppbQUlf6F6Xl9LHu1g=="],
 
     "mcp-proxy": ["mcp-proxy@5.1.0", "", { "dependencies": { "@modelcontextprotocol/sdk": "^1.12.1", "eventsource": "^4.0.0", "yargs": "^18.0.0" }, "bin": { "mcp-proxy": "dist/bin/mcp-proxy.js" } }, "sha512-6pfAdXFOvfpqse9dMLuQo8WTSFdD0al8vhr0Nx5EWv+dR6aTAHphdQj9NUP2xej2bhaWzJ5p8BRwbvXufOjJHA=="],
@@ -426,7 +430,7 @@
 
     "strtok3": ["strtok3@10.3.1", "", { "dependencies": { "@tokenizer/token": "^0.3.0" } }, "sha512-3JWEZM6mfix/GCJBBUrkA8p2Id2pBkyTkVCJKto55w080QBKZ+8R171fGrbiSp+yMO/u6F8/yUh7K4V9K+YCnw=="],
 
-    "sunsama-api": ["sunsama-api@0.7.0", "", { "dependencies": { "graphql": "^16.11.0", "graphql-tag": "^2.12.6", "tough-cookie": "^5.1.2", "tslib": "^2.8.1", "yjs": "^13.6.27", "zod": "^3.25.64" } }, "sha512-/wPvJrtE0rUftl7c+OuQdu27OYkTvd23jzcQoAUP2SilQ6QYnFeG/Fjdf6nfl/MFuz5B8mpviGJdSgqYjAkd0g=="],
+    "sunsama-api": ["sunsama-api@0.8.0", "", { "dependencies": { "graphql": "^16.11.0", "graphql-tag": "^2.12.6", "marked": "^14.1.3", "tough-cookie": "^5.1.2", "tslib": "^2.8.1", "turndown": "^7.2.0", "yjs": "^13.6.27", "zod": "^3.25.64" } }, "sha512-EiUqEc2OIDsmfCHQX54Pu+xZDfJBTMjHAcwhWqHVIWTp2emMyitUuSDvABEqupoXrzITZw+XW0lxNZUQaW4lqQ=="],
 
     "term-size": ["term-size@2.2.1", "", {}, "sha512-wK0Ri4fOGjv/XPy8SBHZChl8CM7uMc5VML7SqiQ0zG7+J5Vr+RMQDoHa2CNT6KHUnTGIXH34UDMkPzAUyapBZg=="],
 
@@ -446,6 +450,8 @@
 
     "tslib": ["tslib@2.8.1", "", {}, "sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w=="],
 
+    "turndown": ["turndown@7.2.0", "", { "dependencies": { "@mixmark-io/domino": "^2.2.0" } }, "sha512-eCZGBN4nNNqM9Owkv9HAtWRYfLA4h909E/WGAWWBpmB275ehNhZyk87/Tpvjbp0jjNl9XwCsbe6bm6CqFsgD+A=="],
+
     "type-is": ["type-is@2.0.1", "", { "dependencies": { "content-type": "^1.0.5", "media-typer": "^1.1.0", "mime-types": "^3.0.0" } }, "sha512-OZs6gsjF4vMp32qrCbiVSkrFmXtG/AZhY3t0iAMrMBiAZyV9oALtXO8hsrHbMXF9x6L3grlFuwW2oAz7cav+Gw=="],
 
     "typescript": ["typescript@5.8.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-p1diW6TqL9L07nNxvRMM7hMMw4c5XOo/1ibL4aAIGmSAt9slTE1Xgw5KWuof2uTOvCg9BY7ZRi+GaF+7sfgPeQ=="],

package/dist/main.js

@@ -3,7 +3,7 @@ import { FastMCP } from "fastmcp";
 import { httpStreamAuthenticator } from "./auth/http.js";
 import { initializeStdioAuth } from "./auth/stdio.js";
 import { getTransportConfig } from "./config/transport.js";
-import { createTaskSchema, deleteTaskSchema, getArchivedTasksSchema, getStreamsSchema, getTaskByIdSchema, getTasksBacklogSchema, getTasksByDaySchema, getUserSchema, updateTaskBacklogSchema, updateTaskCompleteSchema, updateTaskPlannedTimeSchema, updateTaskSnoozeDateSchema } from "./schemas.js";
+import { createTaskSchema, deleteTaskSchema, getArchivedTasksSchema, getStreamsSchema, getTaskByIdSchema, getTasksBacklogSchema, getTasksByDaySchema, getUserSchema, updateTaskBacklogSchema, updateTaskCompleteSchema, updateTaskNotesSchema, updateTaskPlannedTimeSchema, updateTaskSnoozeDateSchema } from "./schemas.js";
 import { getSunsamaClient } from "./utils/client-resolver.js";
 import { filterTasksByCompletion } from "./utils/task-filters.js";
 import { trimTasksForResponse } from "./utils/task-trimmer.js";
@@ -16,7 +16,7 @@ if (transportConfig.transportType === "stdio") {
 }
 const server = new FastMCP({
     name: "Sunsama API Server",
-    version: "0.8.0",
+    version: "0.10.0",
     instructions: `
 This MCP server provides access to the Sunsama API for task and project management.
 
@@ -24,7 +24,7 @@ Available tools:
 - Authentication: login, logout, check authentication status
 - User operations: get current user information
 - Task operations: get tasks by day, get backlog tasks, get archived tasks, get task by ID
-- Task mutations: create tasks, mark complete, delete tasks, reschedule tasks, update planned time
+- Task mutations: create tasks, mark complete, delete tasks, reschedule tasks, update planned time, update task notes
 - Stream operations: get streams/channels for the user's group
 
 Authentication is required for all operations. You can either:
@@ -568,6 +568,63 @@ server.addTool({
         }
     }
 });
+server.addTool({
+    name: "update-task-notes",
+    description: "Update the notes content for a task",
+    parameters: updateTaskNotesSchema,
+    execute: async (args, { session, log }) => {
+        try {
+            // Extract parameters
+            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: content.type,
+                contentLength: content.value.length,
+                limitResponsePayload: limitResponsePayload
+            });
+            // Get the appropriate client based on transport type
+            const sunsamaClient = getSunsamaClient(session);
+            // Build options object
+            const options = {};
+            if (limitResponsePayload !== undefined)
+                options.limitResponsePayload = limitResponsePayload;
+            // 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: content.type
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            success: result.success,
+                            taskId: taskId,
+                            notesUpdated: true,
+                            updatedFields: result.updatedFields
+                        })
+                    }
+                ]
+            };
+        }
+        catch (error) {
+            log.error("Failed to update task notes", {
+                taskId: args.taskId,
+                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'}`);
+        }
+    }
+});
 // Stream Operations
 server.addTool({
     name: "get-streams",
@@ -698,6 +755,15 @@ Uses HTTP Basic Auth headers (per-request authentication):
     - \`limitResponsePayload\` (optional): Whether to limit response size
   - Returns: JSON with update result
 
+- **update-task-notes**: Update task notes content
+  - Parameters:
+    - \`taskId\` (required): The ID of the task to update notes for
+    - \`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: Exactly one of \`html\` or \`markdown\` must be provided (mutually exclusive)
+
 ### Stream Operations
 - **get-streams**: Get streams for the user's group
   - Parameters: none

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,6 +145,34 @@ export declare const updateTaskPlannedTimeSchema: z.ZodObject<{
     timeEstimateMinutes: number;
     limitResponsePayload?: boolean | undefined;
 }>;
+export declare const updateTaskNotesSchema: z.ZodIntersection<z.ZodObject<{
+    taskId: z.ZodString;
+    limitResponsePayload: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    taskId: string;
+    limitResponsePayload?: boolean | undefined;
+}, {
+    taskId: 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)
  */
@@ -575,6 +607,7 @@ export type UpdateTaskCompleteInput = z.infer<typeof updateTaskCompleteSchema>;
 export type DeleteTaskInput = z.infer<typeof deleteTaskSchema>;
 export type UpdateTaskSnoozeDateInput = z.infer<typeof updateTaskSnoozeDateSchema>;
 export type UpdateTaskPlannedTimeInput = z.infer<typeof updateTaskPlannedTimeSchema>;
+export type UpdateTaskNotesInput = z.infer<typeof updateTaskNotesSchema>;
 export type User = z.infer<typeof userSchema>;
 export type Task = z.infer<typeof taskSchema>;
 export type Stream = z.infer<typeof streamSchema>;

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":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;GAEG;AAEH,eAAO,MAAM,gBAAgB,wCAO3B,CAAC;AAEH;;GAEG;AAGH,eAAO,MAAM,sBAAsB,+CAA6C,CAAC;AAGjF,eAAO,MAAM,mBAAmB;;;;;;;;;;;;EAI9B,CAAC;AAGH,eAAO,MAAM,qBAAqB,gDAAe,CAAC;AAGlD,eAAO,MAAM,sBAAsB;;;;;;;;;EAGjC,CAAC;AAGH,eAAO,MAAM,iBAAiB;;;;;;EAE5B,CAAC;AAEH;;GAEG;AAGH,eAAO,MAAM,aAAa,gDAAe,CAAC;AAE1C;;GAEG;AAGH,eAAO,MAAM,gBAAgB,gDAAe,CAAC;AAE7C;;GAEG;AAGH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;EAS3B,CAAC;AAGH,eAAO,MAAM,wBAAwB;;;;;;;;;;;;EAInC,CAAC;AAGH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;EAI3B,CAAC;AAGH,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;EAKrC,CAAC;AAGH,eAAO,MAAM,uBAAuB;;;;;;;;;;;;EAIlC,CAAC;AAGH,eAAO,MAAM,2BAA2B;;;;;;;;;;;;EAItC,CAAC;AASH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;KAWjC,CAAC;AAEF;;GAEG;AAGH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;EAO5B,CAAC;AAGH,eAAO,MAAM,WAAW;;;;;;;;;;;;EAItB,CAAC;AAGH,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAKrB,CAAC;AAGH,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAYrB,CAAC;AAGH,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;EAQvB,CAAC;AAEH;;GAEG;AAGH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAE7B,CAAC;AAGH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAG9B,CAAC;AAGH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAGhC,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;EAI9B,CAAC;AAEH;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAEtE,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AACrE,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AACzE,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAC3E,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AACjE,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AACzD,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE/D,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAC/D,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAC/E,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAC/D,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AACnF,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AACrF,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEzE,MAAM,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAC9C,MAAM,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAC9C,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAClD,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAC9D,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAChE,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AACpE,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC"}

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,6 +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 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"),
+    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.8.0",
+  "version": "0.10.0",
   "description": "MCP server for Sunsama API integration",
   "type": "module",
   "private": false,
@@ -26,7 +26,7 @@
     "@types/papaparse": "^5.3.16",
     "fastmcp": "3.3.1",
     "papaparse": "^5.5.3",
-    "sunsama-api": "0.7.0",
+    "sunsama-api": "0.8.0",
     "zod": "3.24.4"
   },
   "devDependencies": {

package/src/main.ts

@@ -16,6 +16,7 @@ import {
   getUserSchema,
   updateTaskBacklogSchema,
   updateTaskCompleteSchema,
+  updateTaskNotesSchema,
   updateTaskPlannedTimeSchema,
   updateTaskSnoozeDateSchema
 } from "./schemas.js";
@@ -34,7 +35,7 @@ if (transportConfig.transportType === "stdio") {
 
 const server = new FastMCP({
   name: "Sunsama API Server",
-  version: "0.8.0",
+  version: "0.10.0",
   instructions: `
 This MCP server provides access to the Sunsama API for task and project management.
 
@@ -42,7 +43,7 @@ Available tools:
 - Authentication: login, logout, check authentication status
 - User operations: get current user information
 - Task operations: get tasks by day, get backlog tasks, get archived tasks, get task by ID
-- Task mutations: create tasks, mark complete, delete tasks, reschedule tasks, update planned time
+- Task mutations: create tasks, mark complete, delete tasks, reschedule tasks, update planned time, update task notes
 - Stream operations: get streams/channels for the user's group
 
 Authentication is required for all operations. You can either:
@@ -689,6 +690,78 @@ server.addTool({
   }
 });
 
+server.addTool({
+  name: "update-task-notes",
+  description: "Update the notes content for a task",
+  parameters: updateTaskNotesSchema,
+  execute: async (args, {session, log}) => {
+    try {
+      // Extract parameters
+      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: content.type,
+        contentLength: content.value.length,
+        limitResponsePayload: limitResponsePayload
+      });
+
+      // Get the appropriate client based on transport type
+      const sunsamaClient = getSunsamaClient(session as SessionData | null);
+
+      // Build options object
+      const options: {
+        limitResponsePayload?: boolean;
+      } = {};
+      if (limitResponsePayload !== undefined) options.limitResponsePayload = limitResponsePayload;
+
+      // 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: content.type
+      });
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({
+              success: result.success,
+              taskId: taskId,
+              notesUpdated: true,
+              updatedFields: result.updatedFields
+            })
+          }
+        ]
+      };
+
+    } catch (error) {
+      log.error("Failed to update task notes", {
+        taskId: args.taskId,
+        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'}`);
+    }
+  }
+});
+
 // Stream Operations
 server.addTool({
   name: "get-streams",
@@ -825,6 +898,15 @@ Uses HTTP Basic Auth headers (per-request authentication):
     - \`limitResponsePayload\` (optional): Whether to limit response size
   - Returns: JSON with update result
 
+- **update-task-notes**: Update task notes content
+  - Parameters:
+    - \`taskId\` (required): The ID of the task to update notes for
+    - \`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: Exactly one of \`html\` or \`markdown\` must be provided (mutually exclusive)
+
 ### Stream Operations
 - **get-streams**: Get streams for the user's group
   - Parameters: none

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,6 +107,26 @@ export const updateTaskPlannedTimeSchema = z.object({
   limitResponsePayload: z.boolean().optional().describe("Whether to limit the response payload size"),
 });
 
+// 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"),
+  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)
  */
@@ -196,6 +229,7 @@ export type UpdateTaskCompleteInput = z.infer<typeof updateTaskCompleteSchema>;
 export type DeleteTaskInput = z.infer<typeof deleteTaskSchema>;
 export type UpdateTaskSnoozeDateInput = z.infer<typeof updateTaskSnoozeDateSchema>;
 export type UpdateTaskPlannedTimeInput = z.infer<typeof updateTaskPlannedTimeSchema>;
+export type UpdateTaskNotesInput = z.infer<typeof updateTaskNotesSchema>;
 
 export type User = z.infer<typeof userSchema>;
 export type Task = z.infer<typeof taskSchema>;