mcp-sunsama 0.4.0 → 0.5.1

package/.claude/settings.local.json

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

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # mcp-sunsama
 
+## 0.5.1
+
+### Patch Changes
+
+- 005209d: Add prepublishOnly script to ensure build runs before publishing
+
+## 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/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/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

@@ -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, getStreamsSchema, getTasksBacklogSchema, getTasksByDaySchema, getUserSchema, updateTaskCompleteSchema, updateTaskSnoozeDateSchema } from "./schemas.js";
+import { createTaskSchema, deleteTaskSchema, getArchivedTasksSchema, getStreamsSchema, getTasksBacklogSchema, getTasksByDaySchema, getUserSchema, updateTaskCompleteSchema, 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,14 @@ if (transportConfig.transportType === "stdio") {
 }
 const server = new FastMCP({
     name: "Sunsama API Server",
-    version: "0.2.2",
+    version: "0.5.1",
     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:
@@ -149,6 +149,67 @@ 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);
+            // 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",
@@ -397,15 +458,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
 
@@ -414,93 +492,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
 
-### 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.
+- **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
 
-## Data Types
+- **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
 
-### 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;
-  };
-}
-\`\`\`
+- **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
 
-### 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;
-}
-\`\`\`
+- **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
 
-### 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;
-}
-\`\`\`
+- **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
 
-## 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
+### Stream Operations
+- **get-streams**: Get streams for the user's group
+  - Parameters: none
+  - Returns: TSV of Stream objects
+  - Note: Streams are called "channels" in the Sunsama UI
+
+## 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()
         };
     }
@@ -509,19 +579,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/schemas.d.ts

@@ -17,6 +17,16 @@ export declare const getTasksByDaySchema: z.ZodObject<{
     completionFilter?: "all" | "incomplete" | "completed" | undefined;
 }>;
 export declare const getTasksBacklogSchema: z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>;
+export declare const getArchivedTasksSchema: z.ZodObject<{
+    offset: z.ZodOptional<z.ZodNumber>;
+    limit: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    offset?: number | undefined;
+    limit?: number | undefined;
+}, {
+    offset?: number | undefined;
+    limit?: number | undefined;
+}>;
 /**
  * User Operation Schemas
  */
@@ -523,6 +533,7 @@ export declare const errorResponseSchema: z.ZodObject<{
 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>;
 export type CreateTaskInput = z.infer<typeof createTaskSchema>;

package/dist/schemas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../src/schemas.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../src/schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;GAEG;AAGH,eAAO,MAAM,sBAAsB,+CAA6C,CAAC;AAGjF,eAAO,MAAM,mBAAmB;;;;;;;;;;;;EAI9B,CAAC;AAGH,eAAO,MAAM,qBAAqB,gDAAe,CAAC;AAGlD,eAAO,MAAM,sBAAsB;;;;;;;;;EAGjC,CAAC;AAEH;;GAEG;AAGH,eAAO,MAAM,aAAa,gDAAe,CAAC;AAE1C;;GAEG;AAGH,eAAO,MAAM,gBAAgB,gDAAe,CAAC;AAE7C;;GAEG;AAGH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;EAS3B,CAAC;AAGH,eAAO,MAAM,wBAAwB;;;;;;;;;;;;EAInC,CAAC;AAGH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;EAI3B,CAAC;AAGH,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;EAKrC,CAAC;AAEH;;GAEG;AAGH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;EAO5B,CAAC;AAGH,eAAO,MAAM,WAAW;;;;;;;;;;;;EAItB,CAAC;AAGH,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAKrB,CAAC;AAGH,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAYrB,CAAC;AAGH,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;EAQvB,CAAC;AAEH;;GAEG;AAGH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAE7B,CAAC;AAGH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAG9B,CAAC;AAGH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAGhC,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;EAI9B,CAAC;AAEH;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAEtE,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AACrE,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AACzE,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAC3E,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AACzD,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE/D,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAC/D,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAC/E,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAC/D,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAEnF,MAAM,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAC9C,MAAM,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAC9C,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAClD,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAC9D,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAChE,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AACpE,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC"}

package/dist/schemas.js

@@ -12,6 +12,11 @@ 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
  */

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.1",
   "description": "MCP server for Sunsama API integration",
   "type": "module",
   "private": false,
@@ -19,13 +19,14 @@
     "inspect": "npx @modelcontextprotocol/inspector --config ./mcp-inspector.json --server sunsama",
     "changeset": "changeset",
     "version": "changeset version",
-    "release": "bun run build && changeset publish"
+    "release": "bun run build && changeset publish",
+    "prepublishOnly": "bun run build"
   },
   "dependencies": {
     "@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": {