mcp-sunsama 0.4.0 → 0.5.0

package/.claude/settings.local.json

@@ -1,4 +1,5 @@
 {
+  "includeCoAuthoredBy": false,
   "permissions": {
     "allow": [
       "mcp__context7__resolve-library-id",
@@ -17,7 +18,8 @@
       "Bash(npm ls:*)",
       "Bash(cat:*)",
       "Bash(grep:*)",
-      "Bash(mkdir:*)"
+      "Bash(mkdir:*)",
+      "mcp__fetch__fetch"
     ],
     "deny": []
   },

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # mcp-sunsama
 
+## 0.5.0
+
+### Minor Changes
+
+- 8478b69: Add get-archived-tasks tool with enhanced pagination
+
+  - Implement get-archived-tasks tool to access archived task history
+  - Add smart pagination with limit+1 pattern to determine if more results exist
+  - Include pagination metadata (hasMore flag, nextOffset, count) for LLM context
+  - Default limit set to 100 for optimal performance
+  - Response format includes TSV data with pagination header
+  - Update documentation in README.md and CLAUDE.md
+
 ## 0.4.0
 
 ### Minor Changes

package/CLAUDE.md

@@ -52,6 +52,14 @@ Two-tier optimization for large datasets:
 
 Always apply filtering before trimming for efficiency.
 
+### Enhanced Pagination Pattern
+The `get-archived-tasks` tool implements smart pagination:
+
+- **Limit+1 Pattern**: Fetches `requestedLimit + 1` to determine if more results exist
+- **Pagination Metadata**: Returns `hasMore` flag, `nextOffset`, and count information
+- **LLM Context**: Provides clear guidance for AI assistants on whether to continue fetching
+- **Response Format**: TSV data with pagination header for optimal processing
+
 ### Schema Architecture
 All tools use Zod schemas from `schemas.ts`:
 - Type-safe parameter validation
@@ -118,10 +126,10 @@ Optional:
 
 ### Task Operations
 Full CRUD support:
-- **Read**: `get-tasks-by-day`, `get-tasks-backlog`, `get-streams`
+- **Read**: `get-tasks-by-day`, `get-tasks-backlog`, `get-archived-tasks`, `get-streams`
 - **Write**: `create-task`, `update-task-complete`, `delete-task`
 
-All task operations support completion filtering and response trimming.
+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.
 
 ### Testing Tools
 Use MCP Inspector for debugging: `bun run inspect`
@@ -140,6 +148,4 @@ When updating the version:
 
 **IMPORTANT**: Never commit the `dev/` directory or any of its files to git. This directory contains development data including sample API responses and testing data that should remain local only.
 
-**IMPORTANT**: Never include "Claude" in git commit messages. Keep commit messages professional and focused on the actual changes made.
-
 **Branch Naming Convention**: Use the format `{type}/{short-name}` where `{type}` follows conventional commit naming convention (feat, fix, chore, refactor, docs, style, test, ci, etc.).

package/Dockerfile

@@ -0,0 +1,35 @@
+# ----- Build Stage -----
+FROM oven/bun:1-alpine AS builder
+WORKDIR /app
+
+# Copy package and configuration files
+COPY package.json bun.lock* tsconfig.json ./
+
+# Copy source code
+COPY src ./src
+
+# Install dependencies and build
+RUN bun install && bun run build
+
+# ----- Production Stage -----
+FROM oven/bun:1-alpine
+WORKDIR /app
+
+# Copy built artifacts
+COPY --from=builder /app/dist ./dist
+
+# Copy package.json for production install
+COPY package.json ./
+
+# Install only production dependencies
+RUN bun install --production --frozen-lockfile
+
+# Set environment defaults for containerized deployment
+ENV TRANSPORT_TYPE=httpStream
+ENV PORT=3000
+
+# Expose HTTP port
+EXPOSE 3000
+
+# Start the application
+CMD ["bun", "dist/main.js"]

package/README.md

@@ -6,7 +6,7 @@ A Model Context Protocol (MCP) server that provides comprehensive task managemen
 
 ### Task Management
 - **Create Tasks** - Create new tasks with notes, time estimates, due dates, and stream assignments
-- **Read Tasks** - Get tasks by day with completion filtering, access backlog tasks
+- **Read Tasks** - Get tasks by day with completion filtering, access backlog tasks, retrieve archived task history
 - **Update Tasks** - Mark tasks as complete with custom timestamps, reschedule tasks or move to backlog
 - **Delete Tasks** - Permanently remove tasks from your workspace
 
@@ -91,6 +91,7 @@ Add this configuration to your Claude Desktop MCP settings:
 - `create-task` - Create new tasks with optional properties
 - `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)
 - `update-task-complete` - Mark tasks as complete
 - `update-task-snooze-date` - Reschedule tasks to different dates or move to backlog
 - `delete-task` - Delete tasks permanently

package/TODO-0_5_0.md

@@ -0,0 +1,108 @@
+# Sunsama MCP Server - Implementation Status & Future Plans
+
+## Current Status (⚠️ Update Required)
+
+**Package Version**: sunsama-api v0.6.0 (updated 2025-06-20)
+
+The MCP server currently implements **61.5% coverage** (8/13 methods) of available methods in the sunsama-api package.
+
+**NEW METHODS AVAILABLE**: 5 additional methods are now available in sunsama-api v0.6.0 that need MCP tool implementation.
+
+### Implemented Tools
+
+#### User Operations
+- ✅ `get-user` → `SunsamaClient.getUser()`
+  - Returns user profile, timezone, and group information
+
+#### Task Operations
+- ✅ `get-tasks-by-day` → `SunsamaClient.getTasksByDay(day, timezone?)`
+  - Supports completion filtering (`all`, `incomplete`, `completed`)
+  - Includes task trimming for response optimization
+- ✅ `get-tasks-backlog` → `SunsamaClient.getTasksBacklog()`
+  - Returns all backlog tasks with trimming optimization
+- ✅ `create-task` → `SunsamaClient.createTask(text, options?)`
+  - Full parameter support: notes, timeEstimate, dueDate, streamIds, etc.
+- ✅ `update-task-complete` → `SunsamaClient.updateTaskComplete(taskId, completeOn?, limitResponsePayload?)`
+  - Mark tasks as complete with optional timestamp
+- ✅ `delete-task` → `SunsamaClient.deleteTask(taskId, limitResponsePayload?, wasTaskMerged?)`
+  - Permanent task deletion
+- ✅ `update-task-snooze-date` → `SunsamaClient.updateTaskSnoozeDate(taskId, newDay, options?)`
+  - Reschedule tasks or move to backlog
+
+#### Stream Operations
+- ✅ `get-streams` → `SunsamaClient.getStreamsByGroupId()`
+  - Returns all available streams (channels) for the user's group
+
+## Future Enhancements
+
+### 1. Archived Tasks (Priority: Medium)
+**Status**: Research needed - API exists but not in sunsama-api package
+
+**Description**: Implement support for retrieving archived tasks
+- **API Endpoint**: `/get-archived-tasks` (confirmed in dev/user-stories/)
+- **Parameters**: `userId`, `groupId`, `offset`, `limit`, optional filters
+- **Returns**: Archived tasks with `archivedAt` timestamps
+
+**Implementation Steps**:
+1. **Upstream Work**: Add `getArchivedTasks()` method to sunsama-api package
+2. **MCP Tool**: Implement `get-archived-tasks` tool with:
+   - Pagination support (`offset`, `limit`)
+   - Date range filtering (`dateFrom`, `dateTo`)
+   - Stream filtering
+   - Response trimming optimization
+
+### 2. Enhanced Task Management (Priority: Low)
+**Potential Extensions**:
+- Task bulk operations (bulk delete, bulk complete)
+- Task search/filtering by content
+- Task time tracking integration
+- Task dependency management
+
+### 3. Advanced Stream Operations (Priority: Low)
+**Potential Extensions**:
+- Stream creation/modification (if API supports)
+- Stream-specific task queries
+- Stream statistics/analytics
+
+### 4. Performance Optimizations (Priority: Low)
+**Current Optimizations**:
+- ✅ Task filtering before processing
+- ✅ Response payload trimming (60-80% reduction)
+- ✅ Dual transport support (stdio/HTTP)
+
+**Future Optimizations**:
+- Response caching for frequently accessed data
+- Batch operations for multiple task updates
+- Streaming responses for large datasets
+
+## Development Notes
+
+### Architecture Strengths
+- Complete dual transport support (stdio + HTTP stream)
+- Robust authentication handling per transport type
+- Comprehensive error handling and validation
+- Response optimization strategies
+- Type-safe parameter validation with Zod schemas
+
+### Maintenance Tasks
+- ✅ Version synchronization (package.json ↔ src/main.ts)
+- Monitor sunsama-api updates for new methods
+- Update dependencies regularly
+- Maintain test coverage
+
+### Contributing Guidelines
+- Follow existing patterns in `src/main.ts`
+- Use Zod schemas for parameter validation
+- Implement response trimming for large datasets
+- Support both transport modes
+- Add comprehensive tool descriptions
+
+## Conclusion
+
+The current implementation provides complete coverage of the sunsama-api package with a robust, well-architected foundation. Future enhancements should focus on:
+
+1. **Upstream API Development**: Contributing archived tasks functionality to sunsama-api
+2. **Advanced Features**: Building on the solid foundation for enhanced productivity workflows
+3. **Performance**: Continuous optimization as usage scales
+
+The codebase is well-positioned for extension and maintenance with clear patterns and comprehensive documentation.

package/TODO.md

@@ -0,0 +1,152 @@
+# Sunsama MCP Server - v0.6.0 Implementation Plan
+
+## 📊 Status Overview
+- **sunsama-api Version**: 0.6.0 (updated from 0.3.1)
+- **Currently Implemented**: 8/13 methods (61.5% coverage)
+- **New Methods Available**: 5 methods ready for implementation
+
+## 🚀 High Priority - Implement First
+
+### 1. `get-archived-tasks` Tool
+**API Method**: `getArchivedTasks(offset?, limit?)`
+- **Impact**: High - Access to archived task history
+- **Complexity**: Low - Standard read operation with pagination
+- **Sample Data**: Available at `/dev/sample-data/get-archived-tasks/`
+
+**Implementation Tasks**:
+- [ ] Add `getArchivedTasksSchema` to `src/schemas.ts`
+- [ ] Implement tool in `src/main.ts` 
+- [ ] Apply task trimming optimization
+- [ ] Use TSV output format
+- [ ] Add pagination support (offset/limit)
+- [ ] Test with MCP Inspector
+
+**Schema**:
+```typescript
+export const getArchivedTasksSchema = z.object({
+  offset: z.number().min(0).optional(),
+  limit: z.number().min(1).max(100).optional()
+});
+```
+
+### 2. `get-task-by-id` Tool  
+**API Method**: `getTaskById(taskId)`
+- **Impact**: High - Essential for task debugging and inspection
+- **Complexity**: Low - Simple lookup operation
+- **Returns**: Single Task object or null
+
+**Implementation Tasks**:
+- [ ] Add `getTaskByIdSchema` to `src/schemas.ts`
+- [ ] Implement tool in `src/main.ts`
+- [ ] Use JSON output format (single object)
+- [ ] Handle null responses gracefully
+- [ ] Add comprehensive error handling
+- [ ] Test with valid and invalid task IDs
+
+**Schema**:
+```typescript
+export const getTaskByIdSchema = z.object({
+  taskId: z.string().min(1).describe("The ID of the task to retrieve")
+});
+```
+
+## 🔧 Medium Priority - Implement After High Priority
+
+### 3. `update-task-notes` Tool
+**API Method**: `updateTaskNotes(taskId, notes, notesMarkdown, options?)`
+- **Impact**: Medium - Enhanced task content management  
+- **Complexity**: High - Requires CollabSnapshot handling
+- **Research Needed**: CollabSnapshot format and usage
+
+**Implementation Tasks**:
+- [ ] Research CollabSnapshot parameter requirements
+- [ ] Add `updateTaskNotesSchema` to `src/schemas.ts`
+- [ ] Implement tool in `src/main.ts`
+- [ ] Handle HTML and Markdown note formats
+- [ ] Test with existing tasks that have notes
+- [ ] Validate collaborative editing scenarios
+
+## 🛠️ Low Priority - Utility Functions
+
+### 4. `get-user-timezone` Tool
+**API Method**: `getUserTimezone()`
+- **Impact**: Low - Utility function (already used internally)
+- **Complexity**: Low - Simple getter
+- **Note**: Already called internally by `get-tasks-by-day`
+
+**Implementation Tasks**:
+- [ ] Add schema (no parameters)
+- [ ] Implement standalone tool
+- [ ] Return timezone string
+- [ ] Test timezone format consistency
+
+### 5. `generate-task-id` Tool
+**API Method**: `SunsamaClient.generateTaskId()` (static)
+- **Impact**: Low - Developer convenience
+- **Complexity**: Low - Static method call
+- **Note**: No authentication required
+
+**Implementation Tasks**:
+- [ ] Add schema (no parameters)
+- [ ] Implement tool using static method
+- [ ] Return 24-character hex string
+- [ ] Test ID format compatibility
+
+## 📋 Implementation Patterns
+
+### Standard Tool Structure
+```typescript
+server.addTool({
+  name: "tool-name",
+  description: "Clear description of functionality",
+  parameters: toolSchema,
+  execute: async (args, {session, log}) => {
+    try {
+      log.info("Operation starting", { params });
+      
+      const sunsamaClient = getSunsamaClient(session as SessionData | null);
+      const result = await sunsamaClient.methodName(args);
+      
+      // Apply optimizations if needed
+      const optimizedResult = optimizeResponse(result);
+      
+      log.info("Operation completed", { resultInfo });
+      
+      return {
+        content: [{
+          type: "text", 
+          text: formatOutput(optimizedResult)
+        }]
+      };
+    } catch (error) {
+      log.error("Operation failed", { error: error.message });
+      throw new Error(`Failed to [operation]: ${error.message}`);
+    }
+  }
+});
+```
+
+### Response Format Guidelines
+- **Arrays**: Use TSV format with `toTsv()` and apply `trimTasksForResponse()`
+- **Single Objects**: Use JSON format with `JSON.stringify(obj, null, 2)`
+- **Large Datasets**: Always apply trimming optimizations
+
+## 🎯 Success Criteria
+- [ ] All 5 new methods have corresponding MCP tools
+- [ ] 100% test coverage with MCP Inspector
+- [ ] Response optimization applied consistently  
+- [ ] Error handling follows established patterns
+- [ ] Documentation updated in server instructions
+- [ ] Version bump in `src/main.ts` matches `package.json`
+
+## 🔄 Development Workflow
+1. **Implement High Priority tools first** (archived tasks, task by ID)
+2. **Test each tool individually** before proceeding
+3. **Update schemas and imports in batches**
+4. **Apply consistent patterns** from existing tools
+5. **Update server version** and documentation
+6. **Final integration testing** with full tool suite
+
+---
+*Target: Complete implementation of all 5 new sunsama-api v0.6.0 methods*  
+*Goal: Achieve 100% coverage (13/13 methods implemented)*

package/bun.lock

@@ -7,7 +7,7 @@
         "@types/papaparse": "^5.3.16",
         "fastmcp": "3.3.1",
         "papaparse": "^5.5.3",
-        "sunsama-api": "0.3.1",
+        "sunsama-api": "0.6.1",
         "zod": "3.24.4",
       },
       "devDependencies": {
@@ -268,12 +268,16 @@
 
     "isexe": ["isexe@2.0.0", "", {}, "sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw=="],
 
+    "isomorphic.js": ["isomorphic.js@0.2.5", "", {}, "sha512-PIeMbHqMt4DnUP3MA/Flc0HElYjMXArsw1qwJZcm9sqR8mq3l8NYizFMty0pWwE/tzIGH3EKK5+jes5mAr85yw=="],
+
     "js-yaml": ["js-yaml@3.14.1", "", { "dependencies": { "argparse": "^1.0.7", "esprima": "^4.0.0" }, "bin": { "js-yaml": "bin/js-yaml.js" } }, "sha512-okMH7OXXJ7YrN9Ok3/SXrnu4iX9yOk+25nqX4imS2npuvTYDmo/QEZoqwZkYaIDk3jVvBOTOIEgEhaLOynBS9g=="],
 
     "json-schema-traverse": ["json-schema-traverse@0.4.1", "", {}, "sha512-xbbCH5dCYU5T8LcEhhuh7HJ88HXuW3qsI3Y0zOZFKfZEHcpWiHU/Jxzk629Brsab/mMiHQti9wMP+845RPe3Vg=="],
 
     "jsonfile": ["jsonfile@4.0.0", "", { "optionalDependencies": { "graceful-fs": "^4.1.6" } }, "sha512-m6F1R3z8jjlf2imQHS2Qez5sjKWQzbuuhuJ/FKYFRZvPE3PuHcSMVZzfsLhGVOkfd20obL5SWEBew5ShlquNxg=="],
 
+    "lib0": ["lib0@0.2.108", "", { "dependencies": { "isomorphic.js": "^0.2.4" }, "bin": { "0gentesthtml": "bin/gentesthtml.js", "0serve": "bin/0serve.js", "0ecdsa-generate-keypair": "bin/0ecdsa-generate-keypair.js" } }, "sha512-+3eK/B0SqYoZiQu9fNk4VEc6EX8cb0Li96tPGKgugzoGj/OdRdREtuTLvUW+mtinoB2mFiJjSqOJBIaMkAGhxQ=="],
+
     "locate-path": ["locate-path@5.0.0", "", { "dependencies": { "p-locate": "^4.1.0" } }, "sha512-t7hw9pI+WvuwNJXwk5zVHpyhIqzg2qTlklJOf0mVxGSbe3Fp2VieZcduNYjaLDoy6p9uGpQEGWG87WpMKlNq8g=="],
 
     "lodash.startcase": ["lodash.startcase@4.4.0", "", {}, "sha512-+WKqsK294HMSc2jEbNgpHpd0JfIBhp7rEV4aqXWqFr6AlXov+SlcgB1Fv01y2kGe3Gc8nMW7VA0SrGuSkRfIEg=="],
@@ -422,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.3.1", "", { "dependencies": { "graphql": "^16.11.0", "graphql-tag": "^2.12.6", "tough-cookie": "^5.1.2", "tslib": "^2.8.1", "zod": "^3.25.64" } }, "sha512-X0as5S6Wf3Pr9u1Ze/5Z9YzHfMNBxTqloMr9FmwOfPr3XXiDjstuGHAB6quRf0VhcUK56pOBm8y8rs3o3diOHA=="],
+    "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=="],
 
     "term-size": ["term-size@2.2.1", "", {}, "sha512-wK0Ri4fOGjv/XPy8SBHZChl8CM7uMc5VML7SqiQ0zG7+J5Vr+RMQDoHa2CNT6KHUnTGIXH34UDMkPzAUyapBZg=="],
 
@@ -478,6 +482,8 @@
 
     "yargs-parser": ["yargs-parser@22.0.0", "", {}, "sha512-rwu/ClNdSMpkSrUb+d6BRsSkLUq1fmfsY6TOpYzTwvwkg1/NRG85KBy3kq++A8LKQwX6lsu+aWad+2khvuXrqw=="],
 
+    "yjs": ["yjs@13.6.27", "", { "dependencies": { "lib0": "^0.2.99" } }, "sha512-OIDwaflOaq4wC6YlPBy2L6ceKeKuF7DeTxx+jPzv1FHn9tCZ0ZwSRnUBxD05E3yed46fv/FWJbvR+Ud7x0L7zw=="],
+
     "yoctocolors": ["yoctocolors@2.1.1", "", {}, "sha512-GQHQqAopRhwU8Kt1DDM8NjibDXHC8eoh1erhGAJPEyveY9qqVeXvVikNKrDz69sHowPMorbPUrH/mx8c50eiBQ=="],
 
     "zod": ["zod@3.24.4", "", {}, "sha512-OdqJE9UDRPwWsrHjLN2F8bPxvwJBK22EHLWtanu0LSYr5YqzsaaW3RMgmjwr8Rypg5k+meEJdSPXJZXE/yqOMg=="],

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.4.0",
+  "version": "0.5.0",
   "description": "MCP server for Sunsama API integration",
   "type": "module",
   "private": false,
@@ -25,7 +25,7 @@
     "@types/papaparse": "^5.3.16",
     "fastmcp": "3.3.1",
     "papaparse": "^5.5.3",
-    "sunsama-api": "0.3.1",
+    "sunsama-api": "0.6.1",
     "zod": "3.24.4"
   },
   "devDependencies": {

package/src/main.ts

@@ -8,6 +8,7 @@ import { getTransportConfig } from "./config/transport.js";
 import {
   createTaskSchema,
   deleteTaskSchema,
+  getArchivedTasksSchema,
   getStreamsSchema,
   getTasksBacklogSchema,
   getTasksByDaySchema,
@@ -30,14 +31,14 @@ if (transportConfig.transportType === "stdio") {
 
 const server = new FastMCP({
   name: "Sunsama API Server",
-  version: "0.4.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:
@@ -187,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",
@@ -477,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
 
@@ -494,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()
     };
   }

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>;