mcp-sunsama 0.16.1 → 0.18.0

package/.claude/commands/upgrade-sunsama-api.md

@@ -0,0 +1,70 @@
+---
+description: Upgrade sunsama-api and add missing MCP tools
+model: claude-opus-4-6
+allowed-tools: Bash(bun:*), Bash(npm:*), Bash(cat:*), Bash(ls:*), Read, Write, Edit, Glob, Grep
+---
+
+Upgrade the sunsama-api dependency to the latest version and ensure all new endpoints are wrapped as MCP tools.
+
+## Steps
+
+1. **Check current vs latest version**:
+   ```bash
+   cat package.json | grep sunsama-api
+   npm view sunsama-api version
+   ```
+   - If already on latest, inform user and stop
+
+2. **Upgrade the dependency**:
+   ```bash
+   bun add sunsama-api@latest
+   ```
+
+3. **Verify build passes**:
+   ```bash
+   bun run typecheck
+   bun test
+   ```
+   - If either fails, stop and report the issue
+
+4. **Analyze new API methods**:
+   - Read `node_modules/sunsama-api/dist/types/client/index.d.ts` to find the method class hierarchy
+   - Read each method class file to enumerate all public methods on `SunsamaClient`
+   - Compare against existing tools in `src/tools/` to find unwrapped methods
+   - Report: "Found X new methods not wrapped as MCP tools: [list]"
+
+5. **For each unwrapped method**:
+   - Read the method signature and JSDoc from the sunsama-api type definitions
+   - Read the corresponding types from `node_modules/sunsama-api/dist/types/types/api.d.ts`
+   - Add the appropriate Zod schema to `src/schemas.ts` following existing patterns
+   - Add the tool implementation to the appropriate file in `src/tools/`:
+     - User operations → `user-tools.ts`
+     - Task operations → `task-tools.ts`
+     - Stream operations → `stream-tools.ts`
+     - Calendar operations → `calendar-tools.ts`
+   - Update `src/tools/index.ts` if a new tools file was created
+
+6. **Verify new tools work**:
+   ```bash
+   bun run typecheck
+   bun test
+   ```
+
+7. **Create changeset**:
+   - If only dependency bump (no new tools): patch changeset
+   - If new tools added: minor changeset
+   - Write changeset to `.changeset/` with descriptive summary
+
+8. **Report summary**:
+   - Previous version → new version
+   - New methods found
+   - Tools added (if any)
+   - Changeset created
+
+## Notes
+
+- Follow existing patterns in `src/tools/` for tool structure
+- Use `withTransportClient` wrapper for all tools
+- Prefer `formatJsonResponse` for single objects, `formatTsvResponse` for arrays
+- Don't use `as` type assertions — if needed, request schema exports from sunsama-api
+- Run typecheck after each file modification to catch errors early

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # mcp-sunsama
 
+## 0.18.0
+
+### Minor Changes
+
+- f806778: Add three new tools for sunsama-api 0.14.0 endpoints:
+
+  - `reorder-task` — move a task to a specific 0-based position within a day
+  - `create-calendar-event` — create a new calendar event (with optional stream links, visibility, and task seed)
+  - `update-calendar-event` — update an existing calendar event (requires full CalendarEventUpdateData)
+
+- f806778: Add `update-task-uncomplete` tool to mark a completed task as incomplete, wrapping the previously missing `SunsamaClient.updateTaskUncomplete()` method.
+
+### Patch Changes
+
+- 846299b: Fix HTTP transport returning 401 for all errors instead of only authentication failures. Non-auth errors (transport failures, unexpected exceptions) now correctly return 500.
+- c1badc0: Fix HTTP transport tools always falling through to stdio client. The MCP SDK provides `sessionId` as a string on the `extra` object, not a nested `session` object. `client-resolver` now checks `extra.sessionId` to look up the per-request authenticated client in `SessionManager`.
+- d3f81d7: Add retry with exponential backoff for 429 rate limit errors during login. Both stdio startup auth and HTTP per-request auth now retry up to 3 times (delays: 1s, 5s, 15s) when `SunsamaAuthError` contains "429". Non-429 errors are rethrown immediately.
+- 3f0070a: Eliminate any types in shared tool infrastructure. ToolConfig is now generic over the Zod schema so tool execute functions receive properly typed args. ToolContext.client is typed as SunsamaClient and session as unknown, removing the catch-all index signature.
+- af74a9d: Update sunsama-api dependency to 0.14.0 (bug fix release — no new endpoints).
+
+## 0.17.0
+
+### Minor Changes
+
+- 26000bd: Add subtask management support
+
+  - Update sunsama-api dependency to 0.13.1
+  - Add 5 new subtask management tools:
+    - `add-subtask` - Create a subtask with a title in one call (recommended)
+    - `create-subtasks` - Create multiple subtasks for a task (bulk operations)
+    - `update-subtask-title` - Update the title of a subtask
+    - `complete-subtask` - Mark a subtask as complete
+    - `uncomplete-subtask` - Mark a subtask as incomplete
+  - Update README and CLAUDE.md documentation
+
+- e3336cf: Add session token authentication support for users with SSO/OAuth login. Users can now authenticate using `SUNSAMA_SESSION_TOKEN` environment variable (stdio) or Bearer token authentication (HTTP) as an alternative to email/password credentials.
+
 ## 0.16.1
 
 ### Patch Changes

package/CLAUDE.md

@@ -182,7 +182,7 @@ src/
 ├── tools/
 │   ├── shared.ts          # Common utilities and tool wrapper patterns
 │   ├── user-tools.ts      # User operations (get-user)
-│   ├── task-tools.ts      # Task operations (15 tools)
+│   ├── task-tools.ts      # Task operations (20 tools)
 │   ├── stream-tools.ts    # Stream operations (get-streams)
 │   └── index.ts           # Export all tools
 ├── resources/
@@ -226,13 +226,14 @@ __tests__/
 
 **Resource-Based Organization**:
 - **User Tools**: Single tool for user operations
-- **Task Tools**: 15 tools organized by function (query, lifecycle, update)
+- **Task Tools**: 20 tools organized by function (query, lifecycle, update, subtasks)
 - **Stream Tools**: Single tool for stream operations
 
 **Type Safety Improvements**:
 - **Parameter Destructuring**: Function signatures directly destructure typed parameters
 - **Zod Schema Integration**: Full TypeScript inference from Zod schemas
 - **Eliminated `any` Types**: All parameters properly typed with generated types
+- **Avoid Type Assertions**: Don't use `as` casts if possible. Never use `as unknown as X` — this bypasses all type checking. If you reach for these, stop and find a type-safe alternative (generics, type guards, schema validation, etc.)
 
 ## Testing Architecture
 
@@ -278,6 +279,7 @@ Optional:
 Full CRUD support:
 - **Read**: `get-tasks-by-day`, `get-tasks-backlog`, `get-archived-tasks`, `get-task-by-id`, `get-streams`
 - **Write**: `create-task` (with GitHub/Gmail integration support), `update-task-complete`, `update-task-planned-time`, `update-task-notes`, `update-task-snooze-date`, `update-task-backlog`, `update-task-stream`, `update-task-text`, `update-task-due-date`, `delete-task`
+- **Subtasks**: `add-subtask` (recommended), `create-subtasks` (bulk), `update-subtask-title`, `complete-subtask`, `uncomplete-subtask`
 
 Task read operations support response trimming. `get-tasks-by-day` includes completion filtering. `get-archived-tasks` includes enhanced pagination with hasMore flag for LLM decision-making.
 

package/README.md

@@ -12,6 +12,7 @@ A Model Context Protocol (MCP) server that provides comprehensive task managemen
 - **Create Tasks** - Create new tasks with notes, time estimates, due dates, stream assignments, and GitHub/Gmail integrations
 - **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
+- **Subtasks** - Add, update, complete, and manage subtasks within tasks
 - **Delete Tasks** - Permanently remove tasks from your workspace
 
 ### User & Stream Operations
@@ -111,6 +112,23 @@ Add this configuration to your Claude Desktop MCP settings:
 }
 ```
 
+### Claude Code Configuration
+
+Add the Sunsama MCP server using the Claude Code CLI:
+
+```bash
+claude mcp add sunsama --scope user \
+  -e SUNSAMA_EMAIL=your-email@example.com \
+  -e SUNSAMA_PASSWORD=your-password \
+  -- npx mcp-sunsama
+```
+
+**Scope Options:**
+- `--scope user` - Available across all projects (recommended)
+- `--scope project` - Only available in the current project
+
+After adding the server, restart Claude Code to connect to the Sunsama MCP server.
+
 ## API Tools
 
 ### Task Management
@@ -129,6 +147,13 @@ Add this configuration to your Claude Desktop MCP settings:
 - `update-task-backlog` - Move tasks to the backlog
 - `delete-task` - Delete tasks permanently
 
+#### Subtask Management
+- `add-subtask` - Create a subtask with a title in one call (recommended for single subtask creation)
+- `create-subtasks` - Create multiple subtasks for a task (low-level API for bulk operations)
+- `update-subtask-title` - Update the title of a subtask
+- `complete-subtask` - Mark a subtask as complete with optional completion timestamp
+- `uncomplete-subtask` - Mark a subtask as incomplete
+
 ### User & Stream Operations
 - `get-user` - Get current user information
 - `get-streams` - Get streams/channels for project organization

package/__tests__/unit/tools/api-coverage.test.ts

@@ -0,0 +1,128 @@
+import { describe, test, expect } from "bun:test";
+import { readdir, readFile } from "fs/promises";
+import { join } from "path";
+
+/**
+ * Extracts all public instance method names from sunsama-api client .d.ts files.
+ * Scans both base.d.ts and the methods/ subdirectory.
+ * Skips private, protected, static, and abstract members.
+ */
+async function getSunsamaClientMethods(): Promise<Set<string>> {
+  const clientDir = join(
+    import.meta.dir,
+    "../../../node_modules/sunsama-api/dist/types/client",
+  );
+
+  const methodsDir = join(clientDir, "methods");
+
+  const methodFiles = (await readdir(methodsDir))
+    .filter((f) => f.endsWith(".d.ts"))
+    .map((f) => join(methodsDir, f));
+
+  const allFiles = [join(clientDir, "base.d.ts"), ...methodFiles];
+
+  const methods = new Set<string>();
+
+  for (const file of allFiles) {
+    const content = await readFile(file, "utf-8");
+    const lines = content.split("\n");
+
+    for (const line of lines) {
+      // Skip comment lines (JSDoc, inline comments)
+      const trimmed = line.trim();
+      if (trimmed.startsWith("*") || trimmed.startsWith("//")) continue;
+
+      // Skip private, protected, static, abstract, and constructor declarations
+      if (
+        trimmed.startsWith("private ") ||
+        trimmed.startsWith("protected ") ||
+        trimmed.startsWith("static ") ||
+        trimmed.startsWith("abstract ") ||
+        trimmed.startsWith("constructor")
+      ) continue;
+
+      // Match a public instance method: 4 spaces indent + camelCase name + (
+      const match = line.match(/^    ([a-z][a-zA-Z]+)\(/);
+      if (match) {
+        methods.add(match[1]);
+      }
+    }
+  }
+
+  return methods;
+}
+
+/**
+ * Extracts all SunsamaClient methods called in the MCP tool implementations
+ * by scanning for `context.client.<methodName>` patterns.
+ */
+async function getWrappedMethods(): Promise<Set<string>> {
+  const toolsDir = join(import.meta.dir, "../../../src/tools");
+
+  const files = (await readdir(toolsDir)).filter(
+    (f) => f.endsWith(".ts") && f !== "shared.ts" && f !== "index.ts",
+  );
+
+  const methods = new Set<string>();
+  const callPattern = /context\.client\.([a-zA-Z]+)\(/g;
+
+  for (const file of files) {
+    const content = await readFile(join(toolsDir, file), "utf-8");
+    let match;
+    while ((match = callPattern.exec(content)) !== null) {
+      methods.add(match[1]);
+    }
+  }
+
+  return methods;
+}
+
+/**
+ * Methods intentionally not exposed as MCP tools.
+ * Add to this list with a comment explaining why.
+ */
+const INTENTIONALLY_EXCLUDED = new Set([
+  "getConfig",            // Client configuration — not useful as a standalone tool
+  "getSessionToken",      // Internal auth plumbing — session managed by the transport layer
+  "isAuthenticated",      // Auth checked at the transport layer, not exposed to LLMs
+  "login",                // Auth handled at startup (stdio) or per-request (HTTP)
+  "logout",               // Lifecycle managed by the server transport
+  "getUserTimezone",      // Used internally by tools (e.g. get-tasks-by-day) — not useful standalone
+]);
+
+describe("sunsama-api coverage", () => {
+  test("all public SunsamaClient methods are wrapped as MCP tools or explicitly excluded", async () => {
+    const clientMethods = await getSunsamaClientMethods();
+    const wrappedMethods = await getWrappedMethods();
+
+    const unwrapped = [...clientMethods].filter(
+      (m) => !wrappedMethods.has(m) && !INTENTIONALLY_EXCLUDED.has(m),
+    );
+
+    if (unwrapped.length > 0) {
+      console.error(
+        "\nUnwrapped SunsamaClient methods (add a tool or add to INTENTIONALLY_EXCLUDED):\n" +
+          unwrapped.map((m) => `  - ${m}`).join("\n"),
+      );
+    }
+
+    expect(unwrapped).toEqual([]);
+  });
+
+  test("INTENTIONALLY_EXCLUDED list contains only real SunsamaClient methods", async () => {
+    const clientMethods = await getSunsamaClientMethods();
+
+    const stale = [...INTENTIONALLY_EXCLUDED].filter(
+      (m) => !clientMethods.has(m),
+    );
+
+    if (stale.length > 0) {
+      console.error(
+        "\nStale entries in INTENTIONALLY_EXCLUDED (method no longer exists in sunsama-api):\n" +
+          stale.map((m) => `  - ${m}`).join("\n"),
+      );
+    }
+
+    expect(stale).toEqual([]);
+  });
+});

package/bun.lock

@@ -10,7 +10,7 @@
         "cors": "^2.8.5",
         "express": "^5.1.0",
         "papaparse": "^5.5.3",
-        "sunsama-api": "0.12.1",
+        "sunsama-api": "0.14.0",
         "zod": "3.24.4",
       },
       "devDependencies": {
@@ -397,7 +397,7 @@
 
     "strip-bom": ["strip-bom@3.0.0", "", {}, "sha512-vavAMRXOgBVNF6nyEEmL3DBK19iRpDcoIwW+swQ+CbGiu7lju6t+JklA1MHweoWtadgt4ISVUsXLyDq34ddcwA=="],
 
-    "sunsama-api": ["sunsama-api@0.12.1", "", { "dependencies": { "graphql": "^16.11.0", "graphql-tag": "^2.12.6", "marked": "^14.1.3", "tough-cookie": "^5.1.2", "tslib": "^2.8.1", "turndown": "^7.2.0", "yjs": "^13.6.27", "zod": "^3.25.64" } }, "sha512-F2GLJjanAeboP4vYg3VIKP8xxQ/8LLqHhNFx3lm9oONOSvLzVAXEJlwonESuUI/iIf93b2i/jYCJ/2guoUhRYQ=="],
+    "sunsama-api": ["sunsama-api@0.14.0", "", { "dependencies": { "graphql": "^16.11.0", "graphql-tag": "^2.12.6", "marked": "^14.1.3", "tough-cookie": "^5.1.2", "tslib": "^2.8.1", "turndown": "^7.2.0", "yjs": "^13.6.27", "zod": "^3.25.64" } }, "sha512-pXRy7naTES4/tjVHP/8H/kOgd4WaUTgNnPBT+aS5WC9Yqqiz+ajo3PT9dix8Yso0fw05lBjnC/hVPq19C00TMw=="],
 
     "term-size": ["term-size@2.2.1", "", {}, "sha512-wK0Ri4fOGjv/XPy8SBHZChl8CM7uMc5VML7SqiQ0zG7+J5Vr+RMQDoHa2CNT6KHUnTGIXH34UDMkPzAUyapBZg=="],
 

package/dist/auth/http.d.ts

@@ -17,6 +17,7 @@ export declare function stopClientCacheCleanup(): void;
 export declare function cleanupAllClients(): void;
 /**
  * Authenticate HTTP request and get or create cached client
+ * Supports both Basic Auth (email/password) and Bearer token authentication
  * Uses secure cache key (password hash) and race condition protection
  */
 export declare function authenticateHttpRequest(authHeader?: string): Promise<SessionData>;

package/dist/auth/http.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/auth/http.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAe9C;;GAEG;AACH,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAiBtF;AA+CD,wBAAgB,uBAAuB,IAAI,IAAI,CAQ9C;AAED;;GAEG;AACH,wBAAgB,sBAAsB,IAAI,IAAI,CAM7C;AAED;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,IAAI,CAYxC;AAED;;;GAGG;AACH,wBAAsB,uBAAuB,CAC3C,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,WAAW,CAAC,CAiEtB"}
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/auth/http.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAgB9C;;GAEG;AACH,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAiBtF;AAwDD,wBAAgB,uBAAuB,IAAI,IAAI,CAQ9C;AAED;;GAEG;AACH,wBAAgB,sBAAsB,IAAI,IAAI,CAM7C;AAED;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,IAAI,CAYxC;AAED;;;;GAIG;AACH,wBAAsB,uBAAuB,CAC3C,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,WAAW,CAAC,CA0ItB"}

package/dist/auth/http.js

@@ -1,5 +1,7 @@
 import { createHash } from "crypto";
 import { SunsamaClient } from "sunsama-api/client";
+import { AuthenticationError } from "./types.js";
+import { loginWithRetry } from "./retry.js";
 import { getSessionConfig } from "../config/session-config.js";
 // Client cache with TTL management (keyed by credential hash for security)
 const clientCache = new Map();
@@ -18,12 +20,12 @@ export function parseBasicAuth(authHeader) {
     const credentials = Buffer.from(base64Credentials, 'base64').toString('ascii');
     const colonIndex = credentials.indexOf(':');
     if (colonIndex === -1) {
-        throw new Error("Invalid Basic Auth format");
+        throw new AuthenticationError("Invalid Basic Auth format");
     }
     const email = credentials.substring(0, colonIndex);
     const password = credentials.substring(colonIndex + 1);
     if (!email || password === undefined) {
-        throw new Error("Invalid Basic Auth format");
+        throw new AuthenticationError("Invalid Basic Auth format");
     }
     return { email, password };
 }
@@ -36,6 +38,14 @@ function getCacheKey(email, password) {
         .update(`${email}:${password}`)
         .digest('hex');
 }
+/**
+ * Generate secure cache key from session token
+ */
+function getTokenCacheKey(token) {
+    return createHash('sha256')
+        .update(`token:${token}`)
+        .digest('hex');
+}
 /**
  * Check if a cached client is still valid based on TTL
  */
@@ -102,18 +112,80 @@ export function cleanupAllClients() {
 }
 /**
  * Authenticate HTTP request and get or create cached client
+ * Supports both Basic Auth (email/password) and Bearer token authentication
  * Uses secure cache key (password hash) and race condition protection
  */
 export async function authenticateHttpRequest(authHeader) {
-    if (!authHeader || !authHeader.startsWith('Basic ')) {
-        throw new Error("Basic Auth required");
+    if (!authHeader) {
+        throw new AuthenticationError("Authorization header required (Basic or Bearer)");
+    }
+    const isBearer = authHeader.startsWith('Bearer ');
+    const isBasic = authHeader.startsWith('Basic ');
+    if (!isBearer && !isBasic) {
+        throw new AuthenticationError("Authorization header must be Basic or Bearer");
     }
-    const { email, password } = parseBasicAuth(authHeader);
-    const cacheKey = getCacheKey(email, password);
     const now = Date.now();
+    let cacheKey;
+    let identifier;
+    if (isBearer) {
+        const token = authHeader.replace('Bearer ', '').trim();
+        if (!token) {
+            throw new AuthenticationError("Invalid Bearer token");
+        }
+        cacheKey = getTokenCacheKey(token);
+        identifier = 'token-user';
+        // Check for pending authentication (race condition protection)
+        if (authPromises.has(cacheKey)) {
+            console.error(`[Client Cache] Waiting for pending authentication for ${identifier}`);
+            return await authPromises.get(cacheKey);
+        }
+        // Check cache first
+        if (clientCache.has(cacheKey)) {
+            const cached = clientCache.get(cacheKey);
+            if (isClientValid(cached)) {
+                console.error(`[Client Cache] Reusing cached client for ${identifier}`);
+                cached.lastAccessedAt = now;
+                return cached;
+            }
+            else {
+                console.error(`[Client Cache] Cached client expired for ${identifier}, re-authenticating`);
+                try {
+                    cached.sunsamaClient.logout();
+                }
+                catch (err) {
+                    console.error(`[Client Cache] Error logging out expired client:`, err);
+                }
+                clientCache.delete(cacheKey);
+            }
+        }
+        // Create authentication promise for Bearer token
+        console.error(`[Client Cache] Creating new client for ${identifier}`);
+        const authPromise = (async () => {
+            try {
+                const sunsamaClient = new SunsamaClient({ sessionToken: token });
+                const sessionData = {
+                    sunsamaClient,
+                    createdAt: now,
+                    lastAccessedAt: now
+                };
+                clientCache.set(cacheKey, sessionData);
+                console.error(`[Client Cache] Cached new client for ${identifier} (total: ${clientCache.size})`);
+                return sessionData;
+            }
+            finally {
+                authPromises.delete(cacheKey);
+            }
+        })();
+        authPromises.set(cacheKey, authPromise);
+        return authPromise;
+    }
+    // Basic Auth flow
+    const { email, password } = parseBasicAuth(authHeader);
+    cacheKey = getCacheKey(email, password);
+    identifier = email;
     // Check for pending authentication (race condition protection)
     if (authPromises.has(cacheKey)) {
-        console.error(`[Client Cache] Waiting for pending authentication for ${email}`);
+        console.error(`[Client Cache] Waiting for pending authentication for ${identifier}`);
         return await authPromises.get(cacheKey);
     }
     // Check cache first
@@ -121,13 +193,13 @@ export async function authenticateHttpRequest(authHeader) {
         const cached = clientCache.get(cacheKey);
         // Check if still valid (lazy expiration)
         if (isClientValid(cached)) {
-            console.error(`[Client Cache] Reusing cached client for ${email}`);
+            console.error(`[Client Cache] Reusing cached client for ${identifier}`);
             // Update last accessed time (sliding window)
             cached.lastAccessedAt = now;
             return cached;
         }
         else {
-            console.error(`[Client Cache] Cached client expired for ${email}, re-authenticating`);
+            console.error(`[Client Cache] Cached client expired for ${identifier}, re-authenticating`);
             // Cleanup expired client
             try {
                 cached.sunsamaClient.logout();
@@ -139,11 +211,16 @@ export async function authenticateHttpRequest(authHeader) {
         }
     }
     // Create authentication promise to prevent concurrent authentications
-    console.error(`[Client Cache] Creating new client for ${email}`);
+    console.error(`[Client Cache] Creating new client for ${identifier}`);
     const authPromise = (async () => {
         try {
             const sunsamaClient = new SunsamaClient();
-            await sunsamaClient.login(email, password);
+            try {
+                await loginWithRetry(sunsamaClient, email, password);
+            }
+            catch (err) {
+                throw new AuthenticationError("Login failed: invalid credentials", err);
+            }
             const sessionData = {
                 sunsamaClient,
                 email,
@@ -151,7 +228,7 @@ export async function authenticateHttpRequest(authHeader) {
                 lastAccessedAt: now
             };
             clientCache.set(cacheKey, sessionData);
-            console.error(`[Client Cache] Cached new client for ${email} (total: ${clientCache.size})`);
+            console.error(`[Client Cache] Cached new client for ${identifier} (total: ${clientCache.size})`);
             return sessionData;
         }
         finally {

package/dist/auth/retry.d.ts

@@ -0,0 +1,8 @@
+import { SunsamaClient } from "sunsama-api/client";
+/**
+ * Calls sunsamaClient.login() with exponential backoff on 429 rate limit errors.
+ * Makes up to 4 attempts total (initial + 3 retries) with delays of 5s, 15s, 45s.
+ * Non-429 errors are rethrown immediately without retrying.
+ */
+export declare function loginWithRetry(client: SunsamaClient, email: string, password: string): Promise<void>;
+//# sourceMappingURL=retry.d.ts.map

package/dist/auth/retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../src/auth/retry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAKnD;;;;GAIG;AACH,wBAAsB,cAAc,CAClC,MAAM,EAAE,aAAa,EACrB,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CAoBf"}

package/dist/auth/retry.js

@@ -0,0 +1,25 @@
+import { SunsamaClient } from "sunsama-api/client";
+import { SunsamaAuthError } from "sunsama-api/errors";
+const RETRY_DELAYS = [1_000, 5_000, 15_000]; // ms
+/**
+ * Calls sunsamaClient.login() with exponential backoff on 429 rate limit errors.
+ * Makes up to 4 attempts total (initial + 3 retries) with delays of 5s, 15s, 45s.
+ * Non-429 errors are rethrown immediately without retrying.
+ */
+export async function loginWithRetry(client, email, password) {
+    for (let attempt = 0; attempt <= RETRY_DELAYS.length; attempt++) {
+        try {
+            await client.login(email, password);
+            return;
+        }
+        catch (err) {
+            const isRateLimit = err instanceof SunsamaAuthError && err.message.includes("429");
+            if (!isRateLimit || attempt === RETRY_DELAYS.length) {
+                throw err;
+            }
+            const delay = RETRY_DELAYS[attempt];
+            console.error(`[Auth] Rate limited (429). Retrying in ${delay / 1000}s (attempt ${attempt + 1}/${RETRY_DELAYS.length})`);
+            await new Promise((resolve) => setTimeout(resolve, delay));
+        }
+    }
+}

package/dist/auth/stdio.d.ts

@@ -1,6 +1,7 @@
 import { SunsamaClient } from "sunsama-api/client";
 /**
  * Initialize stdio authentication using environment variables
+ * Supports session token (SUNSAMA_SESSION_TOKEN) or email/password (SUNSAMA_EMAIL, SUNSAMA_PASSWORD)
  * @throws {Error} If credentials are missing or authentication fails
  */
 export declare function initializeStdioAuth(): Promise<SunsamaClient>;

package/dist/auth/stdio.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stdio.d.ts","sourceRoot":"","sources":["../../src/auth/stdio.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAOnD;;;GAGG;AACH,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,aAAa,CAAC,CAWlE;AAED;;;;GAIG;AACH,wBAAsB,sBAAsB,IAAI,OAAO,CAAC,aAAa,CAAC,CAMrE"}
+{"version":3,"file":"stdio.d.ts","sourceRoot":"","sources":["../../src/auth/stdio.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAQnD;;;;GAIG;AACH,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,aAAa,CAAC,CAoBlE;AAED;;;;GAIG;AACH,wBAAsB,sBAAsB,IAAI,OAAO,CAAC,aAAa,CAAC,CAMrE"}

package/dist/auth/stdio.js

@@ -1,18 +1,28 @@
 import { SunsamaClient } from "sunsama-api/client";
+import { loginWithRetry } from "./retry.js";
 /**
  * Cached authentication promise to prevent concurrent auth attempts
  */
 let authenticationPromise = null;
 /**
  * Initialize stdio authentication using environment variables
+ * Supports session token (SUNSAMA_SESSION_TOKEN) or email/password (SUNSAMA_EMAIL, SUNSAMA_PASSWORD)
  * @throws {Error} If credentials are missing or authentication fails
  */
 export async function initializeStdioAuth() {
+    // Prefer session token if available (useful for Google SSO users)
+    if (process.env.SUNSAMA_SESSION_TOKEN) {
+        const sunsamaClient = new SunsamaClient({
+            sessionToken: process.env.SUNSAMA_SESSION_TOKEN
+        });
+        return sunsamaClient;
+    }
+    // Fall back to email/password authentication
     if (!process.env.SUNSAMA_EMAIL || !process.env.SUNSAMA_PASSWORD) {
-        throw new Error("Sunsama credentials not configured. Please set SUNSAMA_EMAIL and SUNSAMA_PASSWORD environment variables.");
+        throw new Error("Sunsama credentials not configured. Please set SUNSAMA_SESSION_TOKEN or both SUNSAMA_EMAIL and SUNSAMA_PASSWORD environment variables.");
     }
     const sunsamaClient = new SunsamaClient();
-    await sunsamaClient.login(process.env.SUNSAMA_EMAIL, process.env.SUNSAMA_PASSWORD);
+    await loginWithRetry(sunsamaClient, process.env.SUNSAMA_EMAIL, process.env.SUNSAMA_PASSWORD);
     return sunsamaClient;
 }
 /**

package/dist/auth/types.d.ts

@@ -4,8 +4,15 @@ import { SunsamaClient } from "sunsama-api/client";
  */
 export interface SessionData extends Record<string, unknown> {
     sunsamaClient: SunsamaClient;
-    email: string;
+    email?: string;
     createdAt: number;
     lastAccessedAt: number;
 }
+/**
+ * Error thrown when authentication fails (missing/invalid credentials or login failure).
+ * Used to distinguish auth failures (401) from other server errors (500) in HTTP transport.
+ */
+export declare class AuthenticationError extends Error {
+    constructor(message: string, cause?: unknown);
+}
 //# sourceMappingURL=types.d.ts.map

package/dist/auth/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/auth/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEnD;;GAEG;AACH,MAAM,WAAW,WAAY,SAAQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAC1D,aAAa,EAAE,aAAa,CAAC;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;CACxB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/auth/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEnD;;GAEG;AACH,MAAM,WAAW,WAAY,SAAQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAC1D,aAAa,EAAE,aAAa,CAAC;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;;GAGG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;gBAChC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAO7C"}

package/dist/auth/types.js

@@ -1 +1,14 @@
 import { SunsamaClient } from "sunsama-api/client";
+/**
+ * Error thrown when authentication fails (missing/invalid credentials or login failure).
+ * Used to distinguish auth failures (401) from other server errors (500) in HTTP transport.
+ */
+export class AuthenticationError extends Error {
+    constructor(message, cause) {
+        super(message);
+        this.name = "AuthenticationError";
+        if (cause !== undefined) {
+            this.cause = cause;
+        }
+    }
+}

package/dist/constants.d.ts

@@ -4,7 +4,7 @@
  * VERSION is automatically synced from package.json by scripts/sync-version.ts
  * when running `bun run version`
  */
-export declare const VERSION = "0.16.1";
+export declare const VERSION = "0.18.0";
 export declare const SERVER_NAME = "Sunsama API Server";
 export declare const PACKAGE_NAME = "mcp-sunsama";
 //# sourceMappingURL=constants.d.ts.map