mcp-sunsama 0.6.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # mcp-sunsama
 
+## 0.8.0
+
+### Minor Changes
+
+- 6585510: feat: add update-task-planned-time tool for updating task time estimates
+
+  This adds a new MCP tool that allows users to update the planned time (time estimate) for existing tasks in Sunsama. The tool accepts a task ID and time estimate in minutes, with optional response payload limiting.
+
+  Features:
+
+  - Update task time estimates in minutes (converted to seconds for API)
+  - Support for clearing time estimates by setting to 0
+  - Comprehensive input validation and error handling
+  - Full test coverage including edge cases
+  - Documentation updates for README and CLAUDE.md
+
+  The implementation follows established patterns in the codebase and leverages the existing sunsama-api updateTaskPlannedTime method.
+
+## 0.7.0
+
+### Minor Changes
+
+- 3394176: Add get-task-by-id tool for retrieving specific tasks by their unique identifier
+
+  - Add `get-task-by-id` MCP tool that retrieves a specific task by its ID
+  - Add `getTaskByIdSchema` with taskId parameter validation
+  - Return complete task object if found, null if not found
+  - Follow standard tool patterns for authentication, error handling, and logging
+  - Update documentation in README.md and CLAUDE.md
+  - Maintain consistent JSON response format for single object retrieval
+
 ## 0.6.0
 
 ### Minor Changes

package/CLAUDE.md

@@ -126,8 +126,8 @@ Optional:
 
 ### Task Operations
 Full CRUD support:
-- **Read**: `get-tasks-by-day`, `get-tasks-backlog`, `get-archived-tasks`, `get-streams`
-- **Write**: `create-task`, `update-task-complete`, `update-task-snooze-date`, `update-task-backlog`, `delete-task`
+- **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`
 
 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

@@ -92,7 +92,9 @@ Add this configuration to your Claude Desktop MCP settings:
 - `get-tasks-by-day` - Get tasks for a specific day with completion filtering
 - `get-tasks-backlog` - Get backlog tasks
 - `get-archived-tasks` - Get archived tasks with pagination (includes hasMore flag for LLM context)
+- `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-snooze-date` - Reschedule tasks to different dates
 - `update-task-backlog` - Move tasks to the backlog
 - `delete-task` - Delete tasks permanently
@@ -140,7 +142,6 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 
 ## Support
 
-- [Sunsama API Documentation](https://help.sunsama.com) 
 - [sunsama-api Library](https://github.com/robertn702/sunsama-api) - The underlying API client
 - [Model Context Protocol Documentation](https://modelcontextprotocol.io)
 - [Issue Tracker](https://github.com/robertn702/mcp-sunsama/issues)

package/bun.lock

@@ -7,7 +7,7 @@
         "@types/papaparse": "^5.3.16",
         "fastmcp": "3.3.1",
         "papaparse": "^5.5.3",
-        "sunsama-api": "0.6.1",
+        "sunsama-api": "0.7.0",
         "zod": "3.24.4",
       },
       "devDependencies": {
@@ -426,7 +426,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.6.1", "", { "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-4GhOdrAMo99JIXv9GZg7+NQJu1uPRgGbmnKFWTCNzXYiSVicNPNv27vgqHa3kJtPo19x8sBf4gOYZYlw6b1Wgw=="],
+    "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=="],
 
     "term-size": ["term-size@2.2.1", "", {}, "sha512-wK0Ri4fOGjv/XPy8SBHZChl8CM7uMc5VML7SqiQ0zG7+J5Vr+RMQDoHa2CNT6KHUnTGIXH34UDMkPzAUyapBZg=="],
 

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, getTasksBacklogSchema, getTasksByDaySchema, getUserSchema, updateTaskBacklogSchema, updateTaskCompleteSchema, updateTaskSnoozeDateSchema } from "./schemas.js";
+import { createTaskSchema, deleteTaskSchema, getArchivedTasksSchema, getStreamsSchema, getTaskByIdSchema, getTasksBacklogSchema, getTasksByDaySchema, getUserSchema, updateTaskBacklogSchema, updateTaskCompleteSchema, 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,14 +16,15 @@ if (transportConfig.transportType === "stdio") {
 }
 const server = new FastMCP({
     name: "Sunsama API Server",
-    version: "0.6.0",
+    version: "0.8.0",
     instructions: `
 This MCP server provides access to the Sunsama API for task and project management.
 
 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
+- 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
 - Stream operations: get streams/channels for the user's group
 
 Authentication is required for all operations. You can either:
@@ -210,6 +211,57 @@ ${toTsv(trimmedTasks)}`;
         }
     }
 });
+server.addTool({
+    name: "get-task-by-id",
+    description: "Get a specific task by its ID",
+    parameters: getTaskByIdSchema,
+    execute: async (args, { session, log }) => {
+        try {
+            const { taskId } = args;
+            log.info("Getting task by ID", {
+                taskId: taskId
+            });
+            // Get the appropriate client based on transport type
+            const sunsamaClient = getSunsamaClient(session);
+            // Get the specific task by ID
+            const task = await sunsamaClient.getTaskById(taskId);
+            if (task) {
+                log.info("Successfully retrieved task by ID", {
+                    taskId: taskId,
+                    taskText: task.text
+                });
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify(task, null, 2)
+                        }
+                    ]
+                };
+            }
+            else {
+                log.info("Task not found", {
+                    taskId: taskId
+                });
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: "null"
+                        }
+                    ]
+                };
+            }
+        }
+        catch (error) {
+            log.error("Failed to get task by ID", {
+                taskId: args.taskId,
+                error: error instanceof Error ? error.message : 'Unknown error'
+            });
+            throw new Error(`Failed to get task by ID: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        }
+    }
+});
 // Task Mutation Operations
 server.addTool({
     name: "create-task",
@@ -470,6 +522,52 @@ server.addTool({
         }
     }
 });
+server.addTool({
+    name: "update-task-planned-time",
+    description: "Update the planned time (time estimate) for a task",
+    parameters: updateTaskPlannedTimeSchema,
+    execute: async (args, { session, log }) => {
+        try {
+            // Extract parameters
+            const { taskId, timeEstimateMinutes, limitResponsePayload } = args;
+            log.info("Updating task planned time", {
+                taskId: taskId,
+                timeEstimateMinutes: timeEstimateMinutes,
+                limitResponsePayload: limitResponsePayload
+            });
+            // Get the appropriate client based on transport type
+            const sunsamaClient = getSunsamaClient(session);
+            // Call sunsamaClient.updateTaskPlannedTime(taskId, timeEstimateMinutes, limitResponsePayload)
+            const result = await sunsamaClient.updateTaskPlannedTime(taskId, timeEstimateMinutes, limitResponsePayload);
+            log.info("Successfully updated task planned time", {
+                taskId: taskId,
+                timeEstimateMinutes: timeEstimateMinutes,
+                success: result.success
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            success: result.success,
+                            taskId: taskId,
+                            timeEstimateMinutes: timeEstimateMinutes,
+                            updatedFields: result.updatedFields
+                        })
+                    }
+                ]
+            };
+        }
+        catch (error) {
+            log.error("Failed to update task planned time", {
+                taskId: args.taskId,
+                timeEstimateMinutes: args.timeEstimateMinutes,
+                error: error instanceof Error ? error.message : 'Unknown error'
+            });
+            throw new Error(`Failed to update task planned time: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        }
+    }
+});
 // Stream Operations
 server.addTool({
     name: "get-streams",
@@ -561,6 +659,11 @@ Uses HTTP Basic Auth headers (per-request authentication):
   - Returns: TSV of trimmed archived Task objects with pagination metadata header
   - Pagination: Uses limit+1 pattern to determine if more results are available
 
+- **get-task-by-id**: Get a specific task by its ID
+  - Parameters:
+    - \`taskId\` (required): The ID of the task to retrieve
+  - Returns: JSON with complete Task object if found, or null if not found
+
 - **create-task**: Create a new task with optional properties
   - Parameters:
     - \`text\` (required): Task title/description

package/dist/schemas.d.ts

@@ -27,6 +27,13 @@ export declare const getArchivedTasksSchema: z.ZodObject<{
     offset?: number | undefined;
     limit?: number | undefined;
 }>;
+export declare const getTaskByIdSchema: z.ZodObject<{
+    taskId: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    taskId: string;
+}, {
+    taskId: string;
+}>;
 /**
  * User Operation Schemas
  */
@@ -49,22 +56,22 @@ export declare const createTaskSchema: z.ZodObject<{
     taskId: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     text: string;
+    taskId?: string | undefined;
     notes?: string | undefined;
     streamIds?: string[] | undefined;
     timeEstimate?: number | undefined;
     dueDate?: string | undefined;
     snoozeUntil?: string | undefined;
     private?: boolean | undefined;
-    taskId?: string | undefined;
 }, {
     text: string;
+    taskId?: string | undefined;
     notes?: string | undefined;
     streamIds?: string[] | undefined;
     timeEstimate?: number | undefined;
     dueDate?: string | undefined;
     snoozeUntil?: string | undefined;
     private?: boolean | undefined;
-    taskId?: string | undefined;
 }>;
 export declare const updateTaskCompleteSchema: z.ZodObject<{
     taskId: z.ZodString;
@@ -121,6 +128,19 @@ export declare const updateTaskBacklogSchema: z.ZodObject<{
     timezone?: string | undefined;
     limitResponsePayload?: boolean | undefined;
 }>;
+export declare const updateTaskPlannedTimeSchema: z.ZodObject<{
+    taskId: z.ZodString;
+    timeEstimateMinutes: z.ZodNumber;
+    limitResponsePayload: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    taskId: string;
+    timeEstimateMinutes: number;
+    limitResponsePayload?: boolean | undefined;
+}, {
+    taskId: string;
+    timeEstimateMinutes: number;
+    limitResponsePayload?: boolean | undefined;
+}>;
 /**
  * Response Type Schemas (for validation and documentation)
  */
@@ -547,12 +567,14 @@ export type CompletionFilter = z.infer<typeof completionFilterSchema>;
 export type GetTasksByDayInput = z.infer<typeof getTasksByDaySchema>;
 export type GetTasksBacklogInput = z.infer<typeof getTasksBacklogSchema>;
 export type GetArchivedTasksInput = z.infer<typeof getArchivedTasksSchema>;
+export type GetTaskByIdInput = z.infer<typeof getTaskByIdSchema>;
 export type GetUserInput = z.infer<typeof getUserSchema>;
 export type GetStreamsInput = z.infer<typeof getStreamsSchema>;
 export type CreateTaskInput = z.infer<typeof createTaskSchema>;
 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 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":"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"}

package/dist/schemas.js

@@ -17,6 +17,10 @@ export const getArchivedTasksSchema = z.object({
     offset: z.number().int().min(0).optional().describe("Pagination offset (defaults to 0)"),
     limit: z.number().int().min(1).max(1000).optional().describe("Maximum number of tasks to return (defaults to 100)"),
 });
+// Get task by ID parameters
+export const getTaskByIdSchema = z.object({
+    taskId: z.string().min(1, "Task ID is required").describe("The ID of the task to retrieve"),
+});
 /**
  * User Operation Schemas
  */
@@ -66,6 +70,12 @@ export const updateTaskBacklogSchema = z.object({
     timezone: z.string().optional().describe("Timezone string (e.g., 'America/New_York'). If not provided, uses user's default timezone"),
     limitResponsePayload: z.boolean().optional().describe("Whether to limit the response payload size"),
 });
+// Update task planned time parameters
+export const updateTaskPlannedTimeSchema = z.object({
+    taskId: z.string().min(1, "Task ID is required").describe("The ID of the task to update planned time for"),
+    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"),
+});
 /**
  * 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, 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, 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", () => {
@@ -202,6 +202,56 @@ describe("Tool Parameter Schemas", () => {
             expect(() => updateTaskBacklogSchema.parse({})).toThrow();
         });
     });
+    describe("updateTaskPlannedTimeSchema", () => {
+        test("should accept valid task planned time input", () => {
+            const validInput = {
+                taskId: "task-123",
+                timeEstimateMinutes: 45,
+                limitResponsePayload: true,
+            };
+            expect(() => updateTaskPlannedTimeSchema.parse(validInput)).not.toThrow();
+        });
+        test("should accept minimal required input", () => {
+            const minimalInput = {
+                taskId: "task-123",
+                timeEstimateMinutes: 30
+            };
+            expect(() => updateTaskPlannedTimeSchema.parse(minimalInput)).not.toThrow();
+        });
+        test("should accept zero time estimate", () => {
+            const zeroInput = {
+                taskId: "task-123",
+                timeEstimateMinutes: 0
+            };
+            expect(() => updateTaskPlannedTimeSchema.parse(zeroInput)).not.toThrow();
+        });
+        test("should reject empty task ID", () => {
+            expect(() => updateTaskPlannedTimeSchema.parse({
+                taskId: "",
+                timeEstimateMinutes: 30
+            })).toThrow();
+            expect(() => updateTaskPlannedTimeSchema.parse({
+                timeEstimateMinutes: 30
+            })).toThrow();
+        });
+        test("should reject negative time estimate", () => {
+            expect(() => updateTaskPlannedTimeSchema.parse({
+                taskId: "task-123",
+                timeEstimateMinutes: -1
+            })).toThrow();
+        });
+        test("should reject non-integer time estimate", () => {
+            expect(() => updateTaskPlannedTimeSchema.parse({
+                taskId: "task-123",
+                timeEstimateMinutes: 30.5
+            })).toThrow();
+        });
+        test("should reject missing time estimate", () => {
+            expect(() => updateTaskPlannedTimeSchema.parse({
+                taskId: "task-123"
+            })).toThrow();
+        });
+    });
 });
 describe("Response Schemas", () => {
     describe("userProfileSchema", () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-sunsama",
-  "version": "0.6.0",
+  "version": "0.8.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.6.1",
+    "sunsama-api": "0.7.0",
     "zod": "3.24.4"
   },
   "devDependencies": {

package/src/main.ts

@@ -10,11 +10,13 @@ import {
   deleteTaskSchema,
   getArchivedTasksSchema,
   getStreamsSchema,
+  getTaskByIdSchema,
   getTasksBacklogSchema,
   getTasksByDaySchema,
   getUserSchema,
   updateTaskBacklogSchema,
   updateTaskCompleteSchema,
+  updateTaskPlannedTimeSchema,
   updateTaskSnoozeDateSchema
 } from "./schemas.js";
 import { getSunsamaClient } from "./utils/client-resolver.js";
@@ -32,14 +34,15 @@ if (transportConfig.transportType === "stdio") {
 
 const server = new FastMCP({
   name: "Sunsama API Server",
-  version: "0.6.0",
+  version: "0.8.0",
   instructions: `
 This MCP server provides access to the Sunsama API for task and project management.
 
 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
+- 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
 - Stream operations: get streams/channels for the user's group
 
 Authentication is required for all operations. You can either:
@@ -262,6 +265,64 @@ ${toTsv(trimmedTasks)}`;
   }
 });
 
+server.addTool({
+  name: "get-task-by-id",
+  description: "Get a specific task by its ID",
+  parameters: getTaskByIdSchema,
+  execute: async (args, {session, log}) => {
+    try {
+      const {taskId} = args;
+
+      log.info("Getting task by ID", {
+        taskId: taskId
+      });
+
+      // Get the appropriate client based on transport type
+      const sunsamaClient = getSunsamaClient(session as SessionData | null);
+
+      // Get the specific task by ID
+      const task = await sunsamaClient.getTaskById(taskId);
+
+      if (task) {
+        log.info("Successfully retrieved task by ID", {
+          taskId: taskId,
+          taskText: task.text
+        });
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(task, null, 2)
+            }
+          ]
+        };
+      } else {
+        log.info("Task not found", {
+          taskId: taskId
+        });
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: "null"
+            }
+          ]
+        };
+      }
+
+    } catch (error) {
+      log.error("Failed to get task by ID", {
+        taskId: args.taskId,
+        error: error instanceof Error ? error.message : 'Unknown error'
+      });
+
+      throw new Error(`Failed to get task by ID: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+  }
+});
+
 // Task Mutation Operations
 server.addTool({
   name: "create-task",
@@ -571,6 +632,63 @@ server.addTool({
   }
 });
 
+server.addTool({
+  name: "update-task-planned-time",
+  description: "Update the planned time (time estimate) for a task",
+  parameters: updateTaskPlannedTimeSchema,
+  execute: async (args, {session, log}) => {
+    try {
+      // Extract parameters
+      const {taskId, timeEstimateMinutes, limitResponsePayload} = args;
+
+      log.info("Updating task planned time", {
+        taskId: taskId,
+        timeEstimateMinutes: timeEstimateMinutes,
+        limitResponsePayload: limitResponsePayload
+      });
+
+      // Get the appropriate client based on transport type
+      const sunsamaClient = getSunsamaClient(session as SessionData | null);
+
+      // Call sunsamaClient.updateTaskPlannedTime(taskId, timeEstimateMinutes, limitResponsePayload)
+      const result = await sunsamaClient.updateTaskPlannedTime(
+        taskId,
+        timeEstimateMinutes,
+        limitResponsePayload
+      );
+
+      log.info("Successfully updated task planned time", {
+        taskId: taskId,
+        timeEstimateMinutes: timeEstimateMinutes,
+        success: result.success
+      });
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({
+              success: result.success,
+              taskId: taskId,
+              timeEstimateMinutes: timeEstimateMinutes,
+              updatedFields: result.updatedFields
+            })
+          }
+        ]
+      };
+
+    } catch (error) {
+      log.error("Failed to update task planned time", {
+        taskId: args.taskId,
+        timeEstimateMinutes: args.timeEstimateMinutes,
+        error: error instanceof Error ? error.message : 'Unknown error'
+      });
+
+      throw new Error(`Failed to update task planned time: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+  }
+});
+
 // Stream Operations
 server.addTool({
   name: "get-streams",
@@ -668,6 +786,11 @@ Uses HTTP Basic Auth headers (per-request authentication):
   - Returns: TSV of trimmed archived Task objects with pagination metadata header
   - Pagination: Uses limit+1 pattern to determine if more results are available
 
+- **get-task-by-id**: Get a specific task by its ID
+  - Parameters:
+    - \`taskId\` (required): The ID of the task to retrieve
+  - Returns: JSON with complete Task object if found, or null if not found
+
 - **create-task**: Create a new task with optional properties
   - Parameters:
     - \`text\` (required): Task title/description

package/src/schemas.test.ts

@@ -11,6 +11,7 @@ import {
   deleteTaskSchema,
   updateTaskSnoozeDateSchema,
   updateTaskBacklogSchema,
+  updateTaskPlannedTimeSchema,
   userProfileSchema,
   groupSchema,
   userSchema,
@@ -283,6 +284,73 @@ describe("Tool Parameter Schemas", () => {
       ).toThrow();
     });
   });
+
+  describe("updateTaskPlannedTimeSchema", () => {
+    test("should accept valid task planned time input", () => {
+      const validInput = {
+        taskId: "task-123",
+        timeEstimateMinutes: 45,
+        limitResponsePayload: true,
+      };
+      expect(() => updateTaskPlannedTimeSchema.parse(validInput)).not.toThrow();
+    });
+
+    test("should accept minimal required input", () => {
+      const minimalInput = { 
+        taskId: "task-123", 
+        timeEstimateMinutes: 30 
+      };
+      expect(() => updateTaskPlannedTimeSchema.parse(minimalInput)).not.toThrow();
+    });
+
+    test("should accept zero time estimate", () => {
+      const zeroInput = { 
+        taskId: "task-123", 
+        timeEstimateMinutes: 0 
+      };
+      expect(() => updateTaskPlannedTimeSchema.parse(zeroInput)).not.toThrow();
+    });
+
+    test("should reject empty task ID", () => {
+      expect(() =>
+        updateTaskPlannedTimeSchema.parse({ 
+          taskId: "", 
+          timeEstimateMinutes: 30 
+        })
+      ).toThrow();
+      expect(() =>
+        updateTaskPlannedTimeSchema.parse({ 
+          timeEstimateMinutes: 30 
+        })
+      ).toThrow();
+    });
+
+    test("should reject negative time estimate", () => {
+      expect(() =>
+        updateTaskPlannedTimeSchema.parse({ 
+          taskId: "task-123", 
+          timeEstimateMinutes: -1 
+        })
+      ).toThrow();
+    });
+
+    test("should reject non-integer time estimate", () => {
+      expect(() =>
+        updateTaskPlannedTimeSchema.parse({ 
+          taskId: "task-123", 
+          timeEstimateMinutes: 30.5 
+        })
+      ).toThrow();
+    });
+
+    test("should reject missing time estimate", () => {
+      expect(() =>
+        updateTaskPlannedTimeSchema.parse({ 
+          taskId: "task-123" 
+        })
+      ).toThrow();
+    });
+  });
 });
 
 describe("Response Schemas", () => {

package/src/schemas.ts

@@ -23,6 +23,11 @@ export const getArchivedTasksSchema = z.object({
   limit: z.number().int().min(1).max(1000).optional().describe("Maximum number of tasks to return (defaults to 100)"),
 });
 
+// Get task by ID parameters
+export const getTaskByIdSchema = z.object({
+  taskId: z.string().min(1, "Task ID is required").describe("The ID of the task to retrieve"),
+});
+
 /**
  * User Operation Schemas
  */
@@ -82,6 +87,13 @@ export const updateTaskBacklogSchema = z.object({
   limitResponsePayload: z.boolean().optional().describe("Whether to limit the response payload size"),
 });
 
+// Update task planned time parameters
+export const updateTaskPlannedTimeSchema = z.object({
+  taskId: z.string().min(1, "Task ID is required").describe("The ID of the task to update planned time for"),
+  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"),
+});
+
 /**
  * Response Type Schemas (for validation and documentation)
  */
@@ -175,6 +187,7 @@ export type CompletionFilter = z.infer<typeof completionFilterSchema>;
 export type GetTasksByDayInput = z.infer<typeof getTasksByDaySchema>;
 export type GetTasksBacklogInput = z.infer<typeof getTasksBacklogSchema>;
 export type GetArchivedTasksInput = z.infer<typeof getArchivedTasksSchema>;
+export type GetTaskByIdInput = z.infer<typeof getTaskByIdSchema>;
 export type GetUserInput = z.infer<typeof getUserSchema>;
 export type GetStreamsInput = z.infer<typeof getStreamsSchema>;
 
@@ -182,6 +195,7 @@ export type CreateTaskInput = z.infer<typeof createTaskSchema>;
 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 User = z.infer<typeof userSchema>;
 export type Task = z.infer<typeof taskSchema>;