mcp-sunsama 0.3.0 → 0.5.0

package/dev/prd-get-archived-tasks.md

@@ -0,0 +1,156 @@
+# Product Requirements Document: get-archived-tasks Tool
+
+## Overview
+This document outlines the requirements for implementing the `get-archived-tasks` MCP tool for the Sunsama MCP Server, providing access to archived task history with pagination and filtering capabilities.
+
+## Background
+With the update to sunsama-api v0.6.1, the `getArchivedTasks()` method is now available, enabling access to tasks that have been archived in Sunsama. This is a high-priority feature that provides essential access to historical task data for productivity analysis and task retrieval.
+
+## Objectives
+- Provide MCP tool access to archived tasks in Sunsama
+- Enable pagination for efficient handling of large archived task datasets  
+- Maintain response optimization patterns established in the codebase
+
+## Functional Requirements
+
+### FR1: Core Functionality
+- **Tool Name**: `get-archived-tasks`
+- **API Method**: `sunsamaClient.getArchivedTasks(offset?, limit?)`
+- **Purpose**: Retrieve archived tasks with optional pagination and completion filtering
+
+### FR2: Parameters
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `offset` | number | No | 0 | Pagination offset for archived tasks |
+| `limit` | number | No | 100 | Maximum number of archived tasks to return (max: 1000) |
+
+### FR3: Response Format
+- **Format**: TSV (Tab-Separated Values) with pagination metadata header
+- **Content**: Trimmed Task objects using existing `trimTasksForResponse()` utility
+- **Pagination Metadata**: Include offset, limit, count, hasMore flag, and nextOffset
+- **Optimization**: Apply task trimming for response efficiency
+
+### FR4: Enhanced Pagination
+- **Pattern**: Fetch limit+1 to determine if more results are available
+- **Context**: Provide LLM with clear indication of whether to fetch more data
+- **Metadata**: Include pagination information in response header
+
+### FR5: Error Handling
+- Authentication errors from client resolver
+- Invalid pagination parameters (negative offset, excessive limit)
+- Network/API errors with descriptive messages
+- Consistent error logging pattern matching existing tools
+
+## Technical Requirements
+
+### TR1: Schema Definition
+```typescript
+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 300)"),
+});
+```
+
+### TR2: Tool Implementation Pattern
+- Follow existing tool structure from `get-tasks-by-day` and `get-tasks-backlog`
+- Use `getSunsamaClient()` for transport-agnostic client resolution
+- Apply `trimTasksForResponse()` for response optimization
+- Use `toTsv()` for consistent array output formatting
+
+### TR3: Logging Requirements
+- Info logs for operation start with parameters
+- Success logs with task counts and pagination info
+- Error logs with parameter context and error details
+- Consistent log structure matching existing tools
+
+### TR4: Authentication
+- Leverage existing dual transport authentication system
+- Support both stdio and HTTP Stream transport modes
+- Use session-based client resolution pattern
+
+## Non-Functional Requirements
+
+### NFR1: Performance
+- **Response Optimization**: Apply task trimming to reduce payload by 60-80%
+- **Efficient Filtering**: Filter by completion status before trimming
+- **Pagination Support**: Handle large archived task datasets efficiently
+
+### NFR2: Consistency
+- **Code Patterns**: Follow established patterns in `src/main.ts`
+- **Error Handling**: Match existing error handling approach
+- **Response Format**: Consistent with other task list endpoints (TSV)
+- **Logging**: Maintain logging pattern consistency
+
+### NFR3: Maintainability
+- **Schema Validation**: Use Zod for type-safe parameter validation
+- **Type Safety**: Leverage TypeScript inference from schemas
+- **Documentation**: Clear parameter descriptions and usage notes
+
+## Integration Requirements
+
+### IR1: Schema Integration
+- Add `getArchivedTasksSchema` to `src/schemas.ts`
+- Include in schema exports
+- Import in `src/main.ts`
+
+### IR2: Utility Integration
+- Use existing `filterTasksByCompletion()` from `utils/task-filters.ts`
+- Use existing `trimTasksForResponse()` from `utils/task-trimmer.ts`
+- Use existing `toTsv()` from `utils/to-tsv.ts`
+- Use existing `getSunsamaClient()` from `utils/client-resolver.ts`
+
+### IR3: Documentation Updates
+- Update server instructions to include `get-archived-tasks` tool
+- Add tool description to embedded documentation resource
+- Update parameter descriptions and usage examples
+
+## Testing Requirements
+
+### T1: Functional Testing
+- Test with valid pagination parameters (offset/limit)
+- Test with different completion filters ("all", "incomplete", "completed")
+- Test with edge cases (offset=0, large limits)
+- Verify TSV output format correctness
+
+### T2: Error Testing
+- Test with invalid parameters (negative offset, excessive limit)
+- Test authentication failure scenarios
+- Test network error handling
+- Verify error message clarity and consistency
+
+### T3: Integration Testing
+- Test with MCP Inspector (`bun run inspect`)
+- Verify compatibility with both stdio and HTTP Stream transports
+- Test response optimization (filtering + trimming)
+- Validate against existing sample data
+
+## Success Criteria
+- [ ] Tool successfully retrieves archived tasks via `getArchivedTasks()` API
+- [ ] Pagination works correctly with offset/limit parameters
+- [ ] Completion filtering functions consistently with other task tools
+- [ ] Response optimization reduces payload size by 60-80%
+- [ ] Error handling provides clear, actionable error messages
+- [ ] Integration testing passes with MCP Inspector
+- [ ] Code follows established patterns and maintains consistency
+
+## Implementation Priority
+**High Priority** - This tool provides essential access to archived task history and is identified as a critical gap in the current MCP server functionality.
+
+## Dependencies
+- sunsama-api v0.6.1+ (already updated)
+- Existing utility functions in `utils/` directory
+- Existing schema patterns in `src/schemas.ts`
+- Existing authentication and transport infrastructure
+
+## Risk Assessment
+- **Low Risk**: Implementation follows well-established patterns
+- **API Stability**: Method is available and documented in sunsama-api
+- **Testing Coverage**: Sample data available for validation
+- **Integration**: Minimal impact on existing functionality
+
+---
+
+**Document Version**: 1.0  
+**Created**: 2025-06-20  
+**Author**: Implementation Team  
+**Status**: Ready for Implementation

package/dist/config/transport.d.ts

@@ -3,13 +3,15 @@
  * Supports both stdio and httpStream transports based on environment variables
  */
 export type TransportType = "stdio" | "httpStream";
-export interface TransportConfig {
-    transportType: TransportType;
-    httpStream?: {
+export type TransportConfig = {
+    transportType: "stdio";
+} | {
+    transportType: "httpStream";
+    httpStream: {
         port: number;
-        endpoint: string;
+        endpoint: `/${string}`;
     };
-}
+};
 /**
  * Gets the transport configuration based on environment variables
  *

package/dist/config/transport.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../../src/config/transport.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,YAAY,CAAC;AAEnD,MAAM,WAAW,eAAe;IAC9B,aAAa,EAAE,aAAa,CAAC;IAC7B,UAAU,CAAC,EAAE;QACX,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC;CACH;AAcD;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,IAAI,eAAe,CA0BpD;AAED;;GAEG;AACH,wBAAgB,qBAAqB,IAAI,OAAO,CAE/C;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,OAAO,CAE1C"}
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../../src/config/transport.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,YAAY,CAAC;AAEnD,MAAM,MAAM,eAAe,GACvB;IACF,aAAa,EAAE,OAAO,CAAC;CACxB,GACG;IACF,aAAa,EAAE,YAAY,CAAC;IAC5B,UAAU,EAAE;QACV,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,EAAE,IAAI,MAAM,EAAE,CAAC;KACxB,CAAC;CACH,CAAC;AAgBF;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,IAAI,eAAe,CA0BpD;AAED;;GAEG;AACH,wBAAgB,qBAAqB,IAAI,OAAO,CAE/C;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,OAAO,CAE1C"}

package/dist/config/transport.js

@@ -12,7 +12,9 @@ const TransportEnvSchema = z.object({
         .transform(val => parseInt(val, 10))
         .pipe(z.number().min(1).max(65535))
         .optional(),
-    HTTP_ENDPOINT: z.string().default("/mcp")
+    HTTP_ENDPOINT: z.string().refine(val => val.startsWith("/"), {
+        message: "HTTP_ENDPOINT must start with '/'"
+    }).transform(val => val).default("/mcp")
 });
 /**
  * Gets the transport configuration based on environment variables

package/dist/main.js

@@ -16,7 +16,7 @@ if (transportConfig.transportType === "stdio") {
 }
 const server = new FastMCP({
     name: "Sunsama API Server",
-    version: "0.2.2",
+    version: "0.4.0",
     instructions: `
 This MCP server provides access to the Sunsama API for task and project management.
 
@@ -509,19 +509,12 @@ Required environment variables:
 if (transportConfig.transportType === "httpStream") {
     // Log startup information
     console.log(`HTTP Stream configuration: port=${transportConfig.httpStream?.port}, endpoint=${transportConfig.httpStream?.endpoint}`);
-    server.start({
-        transportType: "httpStream",
-        httpStream: {
-            port: transportConfig.httpStream.port
-        }
-    }).then(() => {
+    server.start(transportConfig).then(() => {
         console.log(`Sunsama MCP Server running on port ${transportConfig.httpStream.port}`);
         console.log(`HTTP endpoint: ${transportConfig.httpStream.endpoint}`);
         console.log("Authentication: HTTP Basic Auth with Sunsama credentials");
     });
 }
 else {
-    server.start({
-        transportType: "stdio"
-    });
+    server.start(transportConfig);
 }

package/dist/utils/task-trimmer.d.ts

@@ -1,4 +1,4 @@
-import type { Task } from "sunsama-api";
+import type { Task, TaskIntegration } from "sunsama-api";
 /**
  * Trimmed task type containing only essential properties for API responses.
  * Reduces response size by 60-80% while preserving core task information.
@@ -9,7 +9,10 @@ import type { Task } from "sunsama-api";
  */
 export type TrimmedTask = Pick<Task, '_id' | 'text' | 'completed' | 'assigneeId' | 'createdAt' | 'lastModified' | 'objectiveId' | 'completeDate' | 'timeEstimate' | 'dueDate' | 'notes' | 'streamIds'> & {
     /** Integration service name (e.g., 'website', 'googleCalendar') or null */
-    integration: string | null;
+    integration: {
+        service: TaskIntegration['service'];
+        url?: string;
+    } | null;
     /** Array of subtask titles only (simplified from full subtask objects) */
     subtasks: string[];
 };

package/dist/utils/task-trimmer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"task-trimmer.d.ts","sourceRoot":"","sources":["../../src/utils/task-trimmer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAExC;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,EAC/B,KAAK,GACL,MAAM,GACN,WAAW,GACX,YAAY,GACZ,WAAW,GACX,cAAc,GACd,aAAa,GACb,cAAc,GACd,cAAc,GACd,SAAS,GACT,OAAO,GACP,WAAW,CACd,GAAG;IACF,2EAA2E;IAC3E,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,0EAA0E;IAC1E,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,IAAI,GAAG,WAAW,CAiB3D;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,WAAW,EAAE,CAEjE"}
+{"version":3,"file":"task-trimmer.d.ts","sourceRoot":"","sources":["../../src/utils/task-trimmer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEzD;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,EAC/B,KAAK,GACL,MAAM,GACN,WAAW,GACX,YAAY,GACZ,WAAW,GACX,cAAc,GACd,aAAa,GACb,cAAc,GACd,cAAc,GACd,SAAS,GACT,OAAO,GACP,WAAW,CACd,GAAG;IACF,2EAA2E;IAC3E,WAAW,EAAE;QACX,OAAO,EAAE,eAAe,CAAC,SAAS,CAAC,CAAC;QACpC,GAAG,CAAC,EAAE,MAAM,CAAC;KACd,GAAG,IAAI,CAAC;IACT,0EAA0E;IAC1E,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,IAAI,GAAG,WAAW,CA4B3D;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,WAAW,EAAE,CAEjE"}

package/dist/utils/task-trimmer.js

@@ -22,6 +22,15 @@
  * @returns Trimmed task object with only essential properties
  */
 export function trimTaskForResponse(task) {
+    let integration = null;
+    // Extract minimal integration data: service type and URL if available
+    // Integration identifiers vary by service - some have URLs (websites), others have different properties
+    if (task.integration) {
+        integration = { service: task.integration.service };
+        if ("url" in task.integration.identifier) {
+            integration.url = task.integration.identifier.url;
+        }
+    }
     return {
         _id: task._id,
         assigneeId: task.assigneeId,
@@ -29,7 +38,7 @@ export function trimTaskForResponse(task) {
         completed: task.completed,
         createdAt: task.createdAt,
         dueDate: task.dueDate,
-        integration: task.integration?.service || null,
+        integration: integration,
         lastModified: task.lastModified,
         notes: task.notes,
         objectiveId: task.objectiveId,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-sunsama",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "MCP server for Sunsama API integration",
   "type": "module",
   "private": false,
@@ -23,9 +23,9 @@
   },
   "dependencies": {
     "@types/papaparse": "^5.3.16",
-    "fastmcp": "2.1.3",
+    "fastmcp": "3.3.1",
     "papaparse": "^5.5.3",
-    "sunsama-api": "0.3.0",
+    "sunsama-api": "0.6.1",
     "zod": "3.24.4"
   },
   "devDependencies": {

package/src/config/transport.ts

@@ -7,13 +7,17 @@ import { z } from "zod";
 
 export type TransportType = "stdio" | "httpStream";
 
-export interface TransportConfig {
-  transportType: TransportType;
-  httpStream?: {
+export type TransportConfig =
+  | {
+  transportType: "stdio";
+}
+  | {
+  transportType: "httpStream";
+  httpStream: {
     port: number;
-    endpoint: string;
+    endpoint: `/${string}`;
   };
-}
+};
 
 /**
  * Zod schema for validating transport-related environment variables
@@ -24,7 +28,9 @@ const TransportEnvSchema = z.object({
     .transform(val => parseInt(val, 10))
     .pipe(z.number().min(1).max(65535))
     .optional(),
-  HTTP_ENDPOINT: z.string().default("/mcp")
+  HTTP_ENDPOINT: z.string().refine(val => val.startsWith("/"), {
+    message: "HTTP_ENDPOINT must start with '/'"
+  }).transform(val => val as `/${string}`).default("/mcp")
 });
 
 /**

package/src/main.ts

@@ -8,6 +8,7 @@ import { getTransportConfig } from "./config/transport.js";
 import {
   createTaskSchema,
   deleteTaskSchema,
+  getArchivedTasksSchema,
   getStreamsSchema,
   getTasksBacklogSchema,
   getTasksByDaySchema,
@@ -28,17 +29,16 @@ if (transportConfig.transportType === "stdio") {
   await initializeStdioAuth();
 }
 
-
 const server = new FastMCP({
   name: "Sunsama API Server",
-  version: "0.3.0",
+  version: "0.5.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
+- Task operations: get tasks by day, get backlog tasks, get archived tasks
 - Stream operations: get streams/channels for the user's group
 
 Authentication is required for all operations. You can either:
@@ -188,6 +188,79 @@ server.addTool({
   }
 });
 
+server.addTool({
+  name: "get-archived-tasks",
+  description: "Get archived tasks with optional pagination",
+  parameters: getArchivedTasksSchema,
+  execute: async (args, {session, log}) => {
+    try {
+      // Extract and set defaults for parameters
+      const offset = args.offset || 0;
+      const requestedLimit = args.limit || 100;
+      
+      // Fetch limit + 1 to determine if there are more results
+      const fetchLimit = requestedLimit + 1;
+
+      log.info("Getting archived tasks", {
+        offset,
+        requestedLimit,
+        fetchLimit
+      });
+
+      // Get the appropriate client based on transport type
+      const sunsamaClient = getSunsamaClient(session as SessionData | null);
+
+      // Get archived tasks (fetch limit + 1 to check for more)
+      const allTasks = await sunsamaClient.getArchivedTasks(offset, fetchLimit);
+
+      // Determine if there are more results and slice to requested limit
+      const hasMore = allTasks.length > requestedLimit;
+      const tasks = hasMore ? allTasks.slice(0, requestedLimit) : allTasks;
+
+      // Trim tasks to reduce response size while preserving essential data
+      const trimmedTasks = trimTasksForResponse(tasks);
+
+      // Create pagination metadata
+      const paginationInfo = {
+        offset,
+        limit: requestedLimit,
+        count: tasks.length,
+        hasMore,
+        nextOffset: hasMore ? offset + requestedLimit : null
+      };
+
+      log.info("Successfully retrieved archived tasks", {
+        totalReturned: tasks.length,
+        hasMore,
+        offset,
+        requestedLimit
+      });
+
+      // Create response with pagination metadata header and TSV data
+      const responseText = `# Pagination: offset=${paginationInfo.offset}, limit=${paginationInfo.limit}, count=${paginationInfo.count}, hasMore=${paginationInfo.hasMore}, nextOffset=${paginationInfo.nextOffset || 'null'}
+${toTsv(trimmedTasks)}`;
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: responseText
+          }
+        ]
+      };
+
+    } catch (error) {
+      log.error("Failed to get archived tasks", {
+        offset: args.offset,
+        limit: args.limit,
+        error: error instanceof Error ? error.message : 'Unknown error'
+      });
+
+      throw new Error(`Failed to get archived tasks: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+  }
+});
+
 // Task Mutation Operations
 server.addTool({
   name: "create-task",
@@ -478,15 +551,32 @@ server.addResource({
       text: `# Sunsama MCP Server Documentation
 
 ## Overview
-This MCP server provides access to the Sunsama API for task and project management.
-Authentication is handled server-side using environment variables.
+This MCP server provides comprehensive access to the Sunsama API for task and project management.
+Supports dual transport modes with different authentication strategies.
+
+## Transport Modes
+
+### Stdio Transport (Default)
+- Single global authentication using environment variables
+- Session maintained for entire server lifetime
+- Best for single-user local development
+
+### HTTP Stream Transport  
+- Per-request authentication via HTTP Basic Auth
+- Session-isolated client instances
+- Supports multiple concurrent users
 
 ## Authentication
-The server authenticates to Sunsama using environment variables:
+
+### Stdio Transport
+Uses environment variables (authenticated once at startup):
 - \`SUNSAMA_EMAIL\`: Your Sunsama account email
 - \`SUNSAMA_PASSWORD\`: Your Sunsama account password
 
-Authentication happens automatically on server startup. No client-side authentication is required.
+### HTTP Stream Transport
+Uses HTTP Basic Auth headers (per-request authentication):
+- \`Authorization: Basic <base64(email:password)>\`
+- Credentials provided in each HTTP request
 
 ## Available Tools
 
@@ -495,93 +585,85 @@ Authentication happens automatically on server startup. No client-side authentic
   - Parameters: none
   - Returns: User object with profile, timezone, and primary group details
 
-### Task Operations
+### Task Management
 - **get-tasks-by-day**: Get tasks for a specific day with optional filtering
   - Parameters: 
     - \`day\` (required): Date in YYYY-MM-DD format
     - \`timezone\` (optional): Timezone string (e.g., "America/New_York")
-    - \`completionFilter\` (optional): Filter by completion status
-      - \`"all"\` (default): Return all tasks
-      - \`"incomplete"\`: Return only incomplete tasks
-      - \`"completed"\`: Return only completed tasks
-  - Returns: Array of filtered Task objects for the specified day
+    - \`completionFilter\` (optional): Filter by completion status ("all", "incomplete", "completed")
+  - Returns: TSV of filtered Task objects for the specified day
 
 - **get-tasks-backlog**: Get tasks from the backlog
   - Parameters: none  
-  - Returns: Array of Task objects from the backlog
+  - Returns: TSV of Task objects from the backlog
+
+- **get-archived-tasks**: Get archived tasks with optional pagination
+  - Parameters:
+    - \`offset\` (optional): Pagination offset (defaults to 0)
+    - \`limit\` (optional): Maximum number of tasks to return (defaults to 100, max: 1000)
+  - Returns: TSV of trimmed archived Task objects with pagination metadata header
+  - Pagination: Uses limit+1 pattern to determine if more results are available
+
+- **create-task**: Create a new task with optional properties
+  - Parameters:
+    - \`text\` (required): Task title/description
+    - \`notes\` (optional): Additional task notes
+    - \`streamIds\` (optional): Array of stream IDs to associate with task
+    - \`timeEstimate\` (optional): Time estimate in minutes
+    - \`dueDate\` (optional): Due date string (ISO format)
+    - \`snoozeUntil\` (optional): Snooze until date string (ISO format)
+    - \`private\` (optional): Whether the task is private
+    - \`taskId\` (optional): Custom task ID
+  - Returns: JSON with task creation result
+
+- **update-task-complete**: Mark a task as complete
+  - Parameters:
+    - \`taskId\` (required): The ID of the task to mark as complete
+    - \`completeOn\` (optional): Completion timestamp (ISO format)
+    - \`limitResponsePayload\` (optional): Whether to limit response size
+  - Returns: JSON with completion result
+
+- **delete-task**: Delete a task permanently
+  - Parameters:
+    - \`taskId\` (required): The ID of the task to delete
+    - \`limitResponsePayload\` (optional): Whether to limit response size
+    - \`wasTaskMerged\` (optional): Whether the task was merged before deletion
+  - Returns: JSON with deletion result
+
+- **update-task-snooze-date**: Reschedule tasks or move to backlog
+  - Parameters:
+    - \`taskId\` (required): The ID of the task to reschedule
+    - \`newDay\` (required): Target date in YYYY-MM-DD format, or null for backlog
+    - \`timezone\` (optional): Timezone string
+    - \`limitResponsePayload\` (optional): Whether to limit response size
+  - Returns: JSON with update result
 
 ### Stream Operations
 - **get-streams**: Get streams for the user's group
   - Parameters: none
-  - Returns: Array of Stream objects
-  - Note: Streams are called "channels" in the Sunsama UI. If a user requests channels, use this tool.
-
-## Data Types
-
-### User Object
-\`\`\`typescript
-{
-  _id: string;
-  email: string;
-  profile: {
-    _id: string;
-    email: string;
-    firstName: string;
-    lastName: string;
-    timezone: string;
-    avatarUrl?: string;
-  };
-  primaryGroup?: {
-    groupId: string;
-    name: string;
-    role?: string;
-  };
-}
-\`\`\`
-
-### Task Object
-\`\`\`typescript
-{
-  _id: string;
-  title: string;
-  description?: string;
-  status: string;
-  createdAt: string;
-  updatedAt: string;
-  scheduledDate?: string;
-  completedAt?: string;
-  streamId?: string;
-  userId: string;
-  groupId: string;
-}
-\`\`\`
-
-### Stream Object
-Note: Streams are called "channels" in the Sunsama UI.
-\`\`\`typescript
-{
-  _id: string;
-  name: string;
-  color?: string;
-  groupId: string;
-  isActive: boolean;
-  createdAt: string;
-  updatedAt: string;
-}
-\`\`\`
+  - Returns: TSV of Stream objects
+  - Note: Streams are called "channels" in the Sunsama UI
 
-## Error Handling
-- All operations require valid Sunsama authentication
-- Invalid dates will return validation errors
-- Network errors are handled gracefully with descriptive messages
-- Server maintains session state across tool calls
+## Response Optimization
+- **Task Filtering**: Applied before processing for efficiency
+- **Task Trimming**: Removes non-essential fields, reducing payload by 60-80%
+- **TSV Format**: Used for arrays to optimize data processing
 
 ## Environment Setup
-Required environment variables:
-- \`API_KEY\`: MCP server authentication key
+
+### Required (Stdio Transport)
 - \`SUNSAMA_EMAIL\`: Sunsama account email
 - \`SUNSAMA_PASSWORD\`: Sunsama account password
-- \`PORT\`: Server port (default: 3000)
+
+### Optional Configuration
+- \`TRANSPORT_TYPE\`: "stdio" (default) | "httpStream" 
+- \`PORT\`: Server port for HTTP transport (default: 3002)
+
+## Error Handling
+- Comprehensive parameter validation using Zod schemas
+- Graceful handling of network errors with descriptive messages
+- Session-specific error isolation in HTTP transport mode
+- Proper authentication error responses
       `.trim()
     };
   }
@@ -593,18 +675,11 @@ if (transportConfig.transportType === "httpStream") {
   // Log startup information
   console.log(`HTTP Stream configuration: port=${transportConfig.httpStream?.port}, endpoint=${transportConfig.httpStream?.endpoint}`);
 
-  server.start({
-    transportType: "httpStream",
-    httpStream: {
-      port: transportConfig.httpStream!.port
-    }
-  }).then(() => {
+  server.start(transportConfig).then(() => {
     console.log(`Sunsama MCP Server running on port ${transportConfig.httpStream!.port}`);
     console.log(`HTTP endpoint: ${transportConfig.httpStream!.endpoint}`);
     console.log("Authentication: HTTP Basic Auth with Sunsama credentials");
   });
 } else {
-  server.start({
-    transportType: "stdio"
-  });
+  server.start(transportConfig);
 }

package/src/schemas.ts

@@ -17,6 +17,12 @@ export const getTasksByDaySchema = z.object({
 // Get tasks backlog parameters (no parameters needed)
 export const getTasksBacklogSchema = z.object({});
 
+// Get archived tasks parameters
+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)"),
+});
+
 /**
  * User Operation Schemas
  */
@@ -161,6 +167,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 GetUserInput = z.infer<typeof getUserSchema>;
 export type GetStreamsInput = z.infer<typeof getStreamsSchema>;