mcp-sunsama 0.14.1 → 0.15.0

package/.env.example

@@ -1,10 +1,15 @@
 # MCP Server Configuration
-PORT=3002
+PORT=8080
 
-# Sunsama Authentication
-# Option 1: Use session token (recommended for server environments)
-SUNSAMA_SESSION_TOKEN=your-session-token-here
+# Transport Selection
+# Options: stdio (default) | http
+TRANSPORT_MODE=stdio
+
+# HTTP Transport Configuration (only used when TRANSPORT_MODE=http)
+HTTP_ENDPOINT=/mcp
 
-# Option 2: Use email/password (for development/testing)
-# SUNSAMA_EMAIL=your-email@example.com
-# SUNSAMA_PASSWORD=your-password
+# Sunsama Authentication
+# For stdio transport: Required
+# For HTTP transport: Provided via HTTP Basic Auth per request
+SUNSAMA_EMAIL=your-email@example.com
+SUNSAMA_PASSWORD=your-password

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # mcp-sunsama
 
+## 0.15.0
+
+### Minor Changes
+
+- f2a39f2: Add HTTP transport support with session management and comprehensive test suite
+
+  - Implement HTTP Stream transport alongside existing stdio transport
+  - Add dual-layer session caching (client cache + session manager)
+  - Implement TTL-based session management with configurable timeouts
+  - Add comprehensive unit test suite (251 tests)
+  - Add integration test suite for authenticated flows
+  - Reorganize tests into standard **tests** directory structure
+  - Add TypeScript types for better type safety in tests
+
 ## 0.14.1
 
 ### Patch Changes

package/CLAUDE.md

@@ -11,9 +11,16 @@ bun run typecheck          # TypeScript type checking
 bun run typecheck:watch    # Watch mode type checking
 bun run inspect            # MCP Inspector for debugging
 
+# Testing
+bun test                   # Run unit tests only
+bun test:unit              # Run unit tests only (alias)
+bun test:integration       # Run integration tests (requires credentials)
+bun test:all               # Run all tests
+bun test:watch             # Watch mode for unit tests
+
 # Build and Distribution
 bun run build              # Compile TypeScript to dist/
-bun test                   # Run test suite
+bun run prepublishOnly     # Run build before publish
 
 # Version Management (Changeset)
 bun run changeset          # Create new changeset
@@ -36,7 +43,21 @@ This server supports two transport modes with different authentication strategie
 - Session-isolated SunsamaClient instances
 - Credentials provided in Authorization header
 
-Transport selection via `TRANSPORT_TYPE` environment variable ("stdio" | "httpStream").
+Transport selection via `TRANSPORT_MODE` environment variable ("stdio" | "http").
+
+### Session Management Architecture
+For HTTP transport, the server implements dual-layer session caching:
+
+**Client Cache Layer** (`utils/client-resolver.ts`):
+- In-memory Map caching authenticated SunsamaClient instances
+- SHA-256 hashed credential keys for security
+- Automatic cache invalidation on authentication failure
+
+**Session Manager Layer** (`session/session-manager.ts`):
+- Manages session lifecycle with configurable TTL
+- Tracks session metadata (createdAt, lastAccessedAt)
+- Automatic cleanup of expired sessions
+- Transport reference management for proper cleanup
 
 ### Client Resolution Pattern
 `utils/client-resolver.ts` abstracts transport differences:
@@ -134,11 +155,32 @@ src/
 ├── resources/
 │   └── index.ts           # API documentation resource
 ├── auth/                  # Authentication strategies per transport type
+│   ├── stdio.ts           # Stdio transport authentication
+│   ├── http.ts            # HTTP Basic Auth parsing
+│   └── types.ts           # Shared auth types
+├── transports/
+│   ├── stdio.ts           # Stdio transport implementation
+│   └── http.ts            # HTTP Stream transport with session management
+├── session/
+│   └── session-manager.ts # Session lifecycle management
 ├── config/                # Environment configuration and validation
-├── utils/                 # Reusable utilities (client resolution, filtering, formatting)
+│   ├── transport.ts       # Transport mode configuration
+│   └── session-config.ts  # Session TTL configuration
+├── utils/                 # Reusable utilities
+│   ├── client-resolver.ts # Transport-agnostic client resolution
+│   ├── task-filters.ts    # Task completion filtering
+│   ├── task-trimmer.ts    # Response size optimization
+│   └── to-tsv.ts          # TSV formatting utilities
 ├── schemas.ts             # Zod validation schemas for all tools
-├── schemas.test.ts        # Comprehensive test suite for all Zod schemas
 └── main.ts                # Streamlined server setup (47 lines vs 1162 before)
+
+__tests__/
+├── unit/                  # Unit tests (251+ tests, no auth required)
+│   ├── auth/              # Auth utility tests
+│   ├── config/            # Configuration tests
+│   └── session/           # Session management tests
+└── integration/           # Integration tests (requires credentials)
+    └── http-transport.test.ts
 ```
 
 ### Tool Architecture Improvements
@@ -159,6 +201,29 @@ src/
 - **Zod Schema Integration**: Full TypeScript inference from Zod schemas
 - **Eliminated `any` Types**: All parameters properly typed with generated types
 
+## Testing Architecture
+
+### Test Organization
+Tests are organized in the `__tests__/` directory following standard conventions:
+
+**Unit Tests** (`__tests__/unit/`):
+- Run without authentication requirements
+- Test individual components in isolation
+- Fast execution for TDD workflow
+- Run with `bun test` or `bun test:unit`
+
+**Integration Tests** (`__tests__/integration/`):
+- Require real Sunsama credentials
+- Test full HTTP transport flow
+- Validate session management
+- Run with `bun test:integration`
+
+### Test Patterns
+- Use Bun's built-in test runner with pattern matching
+- TypeScript types from MCP SDK for type-safe testing
+- Generic helper functions for request/response handling
+- Mock transports for unit testing session management
+
 ## Important Notes
 
 ### Version Synchronization
@@ -170,8 +235,11 @@ Required for stdio transport:
 - `SUNSAMA_PASSWORD`: Sunsama account password
 
 Optional:
-- `TRANSPORT_TYPE`: "stdio" (default) | "httpStream"
+- `TRANSPORT_MODE`: "stdio" (default) | "http"
 - `PORT`: Server port (default: 3002, HTTP transport only)
+- `SESSION_TTL`: Session timeout in milliseconds (default: 3600000 / 1 hour)
+- `CLIENT_IDLE_TIMEOUT`: Client idle timeout in milliseconds (default: 900000 / 15 minutes)
+- `MAX_SESSIONS`: Maximum concurrent sessions for HTTP transport (default: 100)
 
 ### Task Operations
 Full CRUD support:

package/Dockerfile

@@ -25,7 +25,7 @@ COPY package.json ./
 RUN bun install --production --frozen-lockfile
 
 # Set environment defaults for containerized deployment
-ENV TRANSPORT_TYPE=httpStream
+ENV TRANSPORT_MODE=http
 ENV PORT=3000
 
 # Expose HTTP port

package/README.md

@@ -48,22 +48,44 @@ cp .env.example .env
 Environment variables:
 - `SUNSAMA_EMAIL` - Your Sunsama account email (required for stdio transport)
 - `SUNSAMA_PASSWORD` - Your Sunsama account password (required for stdio transport)
-- `SUNSAMA_SESSION_TOKEN` - Alternative session token authentication (optional)
-- `PORT` - Server port for HTTP transport (default: 3002)
-- `MCP_TRANSPORT` - Transport type: `stdio` or `httpStream` (default: stdio)
+- `TRANSPORT_MODE` - Transport type: `stdio` (default) or `http`
+- `PORT` - Server port for HTTP transport (default: 8080)
+- `HTTP_ENDPOINT` - MCP endpoint path (default: `/mcp`)
+- `SESSION_TTL` - Session timeout in milliseconds (default: 3600000 / 1 hour)
+- `CLIENT_IDLE_TIMEOUT` - Client idle timeout in milliseconds (default: 900000 / 15 minutes)
+- `MAX_SESSIONS` - Maximum concurrent sessions for HTTP transport (default: 100)
 
 ## Usage
 
-### Running the Server
+### Transport Modes
 
-**Stdio Transport (default):**
+This server supports two transport modes:
+
+#### Stdio Transport (Default)
+For local AI assistants (Claude Desktop, Cursor, etc.):
+```bash
+bun run dev
+# or
+TRANSPORT_MODE=stdio bun run src/main.ts
+```
+
+#### HTTP Stream Transport
+For remote access and web-based integrations:
 ```bash
-bun run src/main.ts
+TRANSPORT_MODE=http PORT=8080 bun run src/main.ts
 ```
 
-**HTTP Stream Transport:**
+**HTTP Endpoints:**
+- MCP Endpoint: `POST http://localhost:8080/mcp`
+- Health Check: `GET http://localhost:8080/`
+
+**Authentication:**
+HTTP requests require HTTP Basic Auth with your Sunsama credentials:
 ```bash
-MCP_TRANSPORT=httpStream PORT=3002 bun run src/main.ts
+curl -X POST http://localhost:8080/mcp \
+  -H "Authorization: Basic $(echo -n 'your-email:your-password' | base64)" \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'
 ```
 
 ### Claude Desktop Configuration
@@ -121,6 +143,15 @@ bun run inspect
 
 Then connect the MCP Inspector to test the tools interactively.
 
+### Testing
+```bash
+bun test                   # Run unit tests only
+bun test:unit              # Run unit tests only (alias)
+bun test:integration       # Run integration tests (requires credentials)
+bun test:all               # Run all tests
+bun test:watch             # Watch mode for unit tests
+```
+
 ### Build and Type Checking
 ```bash
 bun run build              # Compile TypeScript to dist/
@@ -146,9 +177,32 @@ src/
 ├── resources/
 │   └── index.ts           # API documentation resource
 ├── auth/                  # Authentication strategies
+│   ├── stdio.ts           # Stdio transport authentication
+│   ├── http.ts            # HTTP Basic Auth parsing
+│   └── types.ts           # Shared auth types
+├── transports/
+│   ├── stdio.ts           # Stdio transport implementation
+│   └── http.ts            # HTTP Stream transport with session management
+├── session/
+│   └── session-manager.ts # Session lifecycle management
 ├── config/                # Environment configuration
+│   ├── transport.ts       # Transport mode configuration
+│   └── session-config.ts  # Session TTL configuration
 ├── utils/                 # Utilities (filtering, trimming, etc.)
+│   ├── client-resolver.ts # Transport-agnostic client resolution
+│   ├── task-filters.ts    # Task completion filtering
+│   ├── task-trimmer.ts    # Response size optimization
+│   └── to-tsv.ts          # TSV formatting utilities
+├── schemas.ts             # Zod validation schemas
 └── main.ts                # Server setup (47 lines vs 1162 before refactoring)
+
+__tests__/
+├── unit/                  # Unit tests (no auth required)
+│   ├── auth/              # Auth utility tests
+│   ├── config/            # Configuration tests
+│   └── session/           # Session management tests
+└── integration/           # Integration tests (requires credentials)
+    └── http-transport.test.ts
 ```
 
 **Key Features:**
@@ -157,12 +211,14 @@ src/
 - **Shared Utilities**: Common patterns extracted to reduce duplication
 - **Error Handling**: Standardized error handling across all tools
 - **Response Optimization**: Task filtering and trimming for large datasets
+- **Session Management**: Dual-layer caching with TTL-based lifecycle management
+- **Test Coverage**: 251+ unit tests and comprehensive integration tests
 
 ## Authentication
 
 **Stdio Transport:** Requires `SUNSAMA_EMAIL` and `SUNSAMA_PASSWORD` environment variables.
 
-**HTTP Transport:** The Sunsama credentials are passed in the HTTP request. No environment variables needed.
+**HTTP Transport:** Credentials provided via HTTP Basic Auth per request. No environment variables needed for credentials.
 
 ## Contributing
 

package/__tests__/integration/http-transport.test.ts

@@ -0,0 +1,381 @@
+import { describe, test, expect, beforeAll, afterAll } from "bun:test";
+import type {
+  JSONRPCResponse,
+  JSONRPCError,
+  ListToolsResult,
+  CallToolResult
+} from "@modelcontextprotocol/sdk/types.js";
+
+/**
+ * Integration Tests for HTTP Transport
+ *
+ * These tests require real Sunsama credentials and will be skipped if
+ * SUNSAMA_EMAIL and SUNSAMA_PASSWORD are not set in environment.
+ *
+ * Run these tests locally with: bun test:integration
+ * They should NOT run in CI/CD pipelines.
+ */
+
+// Server info type (not provided by MCP SDK)
+interface ServerInfo {
+  name: string;
+  transport: string;
+  version: string;
+  activeSessions: number;
+}
+
+const SUNSAMA_EMAIL = process.env.SUNSAMA_EMAIL;
+const SUNSAMA_PASSWORD = process.env.SUNSAMA_PASSWORD;
+const TEST_PORT = process.env.TEST_PORT || "3099";
+const BASE_URL = `http://localhost:${TEST_PORT}`;
+
+const shouldRunIntegrationTests = Boolean(SUNSAMA_EMAIL && SUNSAMA_PASSWORD);
+
+// Helper to create Basic Auth header
+function createAuthHeader(email: string, password: string): string {
+  return `Basic ${Buffer.from(`${email}:${password}`).toString("base64")}`;
+}
+
+// Type-safe response interface for tests
+interface McpError {
+  code: number;
+  message: string;
+  data?: unknown;
+}
+
+interface McpResponse<T = any> {
+  jsonrpc: "2.0";
+  id: number | string;
+  result?: T;
+  error?: McpError;
+}
+
+// Helper to make MCP requests with properly typed responses
+async function mcpRequest<T = any>(method: string, params: Record<string, unknown> = {}, auth?: string): Promise<McpResponse<T>> {
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+    "Accept": "application/json, text/event-stream",
+  };
+
+  if (auth) {
+    headers["Authorization"] = auth;
+  }
+
+  const response = await fetch(`${BASE_URL}/mcp`, {
+    method: "POST",
+    headers,
+    body: JSON.stringify({
+      jsonrpc: "2.0",
+      method,
+      params,
+      id: Math.floor(Math.random() * 10000),
+    }),
+  });
+
+  return response.json() as Promise<McpResponse<T>>;
+}
+
+describe.skipIf(!shouldRunIntegrationTests)("HTTP Transport Integration Tests", () => {
+  beforeAll(() => {
+    console.log("\n🔧 Integration Test Setup");
+    console.log("═".repeat(50));
+    console.log(`Test server: ${BASE_URL}`);
+    console.log(`Using credentials: ${SUNSAMA_EMAIL}`);
+    console.log("Note: Server must be running separately on port", TEST_PORT);
+    console.log("═".repeat(50) + "\n");
+  });
+
+  afterAll(() => {
+    console.log("\n✅ Integration tests completed\n");
+  });
+
+  describe("Server Health", () => {
+    test("should return server info", async () => {
+      const response = await fetch(`${BASE_URL}/`);
+      const data = await response.json() as ServerInfo;
+
+      expect(response.status).toBe(200);
+      expect(data.name).toBe("mcp-sunsama");
+      expect(data.transport).toBe("http");
+      expect(data).toHaveProperty("activeSessions");
+      expect(data).toHaveProperty("version");
+    });
+  });
+
+  describe("Authentication", () => {
+    test("should authenticate with valid credentials", async () => {
+      const auth = createAuthHeader(SUNSAMA_EMAIL!, SUNSAMA_PASSWORD!);
+      const result = await mcpRequest("tools/list", {}, auth);
+
+      expect(result.error).toBeUndefined();
+      expect(result.result).toBeDefined();
+      expect(result.result.tools).toBeArray();
+      expect(result.result.tools.length).toBeGreaterThan(0);
+    });
+
+    test("should reject invalid credentials", async () => {
+      const auth = createAuthHeader("wrong@example.com", "wrongpassword");
+      const result = await mcpRequest("tools/list", {}, auth);
+
+      expect(result.error).toBeDefined();
+      expect(result.error!.code).toBe(-32000);
+      expect(result.error!.message).toContain("Authentication failed");
+    });
+
+    test("should reject missing authorization", async () => {
+      const result = await mcpRequest("tools/list", {});
+
+      expect(result.error).toBeDefined();
+      expect(result.error!.code).toBe(-32000);
+    });
+  });
+
+  describe("Session Caching", () => {
+    test("should cache authenticated sessions", async () => {
+      const auth = createAuthHeader(SUNSAMA_EMAIL!, SUNSAMA_PASSWORD!);
+
+      // First request - creates session
+      const result1 = await mcpRequest("tools/call", {
+        name: "get-user",
+        arguments: {},
+      }, auth);
+
+      expect(result1.error).toBeUndefined();
+      expect(result1.result).toBeDefined();
+
+      // Second request - should use cached session
+      const result2 = await mcpRequest("tools/call", {
+        name: "get-user",
+        arguments: {},
+      }, auth);
+
+      expect(result2.error).toBeUndefined();
+      expect(result2.result).toBeDefined();
+
+      // Both should return the same user
+      const user1 = JSON.parse(result1.result.content[0].text);
+      const user2 = JSON.parse(result2.result.content[0].text);
+
+      expect(user1._id).toBe(user2._id);
+      expect(user1.email).toBe(user2.email);
+    });
+
+    test("should create separate sessions for different credentials", async () => {
+      if (!process.env.SUNSAMA_EMAIL_2 || !process.env.SUNSAMA_PASSWORD_2) {
+        console.log("⏭️  Skipping multiple user test (SUNSAMA_EMAIL_2 not set)");
+        return;
+      }
+
+      const auth1 = createAuthHeader(SUNSAMA_EMAIL!, SUNSAMA_PASSWORD!);
+      const auth2 = createAuthHeader(
+        process.env.SUNSAMA_EMAIL_2,
+        process.env.SUNSAMA_PASSWORD_2
+      );
+
+      const result1 = await mcpRequest("tools/call", {
+        name: "get-user",
+        arguments: {},
+      }, auth1);
+
+      const result2 = await mcpRequest("tools/call", {
+        name: "get-user",
+        arguments: {},
+      }, auth2);
+
+      expect(result1.error).toBeUndefined();
+      expect(result2.error).toBeUndefined();
+
+      const user1 = JSON.parse(result1.result.content[0].text);
+      const user2 = JSON.parse(result2.result.content[0].text);
+
+      // Should be different users
+      expect(user1.email).not.toBe(user2.email);
+    });
+  });
+
+  describe("Tool Execution", () => {
+    const auth = createAuthHeader(SUNSAMA_EMAIL!, SUNSAMA_PASSWORD!);
+
+    test("should execute get-user tool", async () => {
+      const result = await mcpRequest("tools/call", {
+        name: "get-user",
+        arguments: {},
+      }, auth);
+
+      expect(result.error).toBeUndefined();
+      expect(result.result.content).toBeArray();
+      expect(result.result.content[0].type).toBe("text");
+
+      const user = JSON.parse(result.result.content[0].text);
+      expect(user).toHaveProperty("_id");
+      expect(user).toHaveProperty("email");
+      expect(user).toHaveProperty("profile");
+      expect(user.email).toBe(SUNSAMA_EMAIL);
+    });
+
+    test("should execute get-streams tool", async () => {
+      const result = await mcpRequest("tools/call", {
+        name: "get-streams",
+        arguments: {},
+      }, auth);
+
+      expect(result.error).toBeUndefined();
+      expect(result.result.content).toBeArray();
+
+      const response = result.result.content[0].text;
+      // Response should be TSV format
+      expect(response).toContain("\t"); // TSV uses tabs
+    });
+
+    test("should execute get-tasks-backlog tool", async () => {
+      const result = await mcpRequest("tools/call", {
+        name: "get-tasks-backlog",
+        arguments: {},
+      }, auth);
+
+      expect(result.error).toBeUndefined();
+      expect(result.result.content).toBeArray();
+
+      const response = result.result.content[0].text;
+      // Response should be TSV format
+      expect(typeof response).toBe("string");
+    });
+
+    test("should execute get-tasks-by-day tool", async () => {
+      const today = new Date().toISOString().split("T")[0]; // YYYY-MM-DD
+
+      const result = await mcpRequest("tools/call", {
+        name: "get-tasks-by-day",
+        arguments: {
+          day: today,
+          completionFilter: "all",
+        },
+      }, auth);
+
+      expect(result.error).toBeUndefined();
+      expect(result.result.content).toBeArray();
+
+      const response = result.result.content[0].text;
+      expect(typeof response).toBe("string");
+    });
+
+    test("should handle tool errors gracefully", async () => {
+      const result = await mcpRequest("tools/call", {
+        name: "get-task-by-id",
+        arguments: {
+          taskId: "non-existent-task-id-12345",
+        },
+      }, auth);
+
+      // Should return an error or empty result, not crash
+      expect(result).toBeDefined();
+    });
+  });
+
+  describe("Concurrent Requests", () => {
+    test("should handle multiple concurrent requests", async () => {
+      const auth = createAuthHeader(SUNSAMA_EMAIL!, SUNSAMA_PASSWORD!);
+
+      // Make 10 concurrent requests
+      const promises = Array.from({ length: 10 }, () =>
+        mcpRequest("tools/call", {
+          name: "get-user",
+          arguments: {},
+        }, auth)
+      );
+
+      const results = await Promise.all(promises);
+
+      // All should succeed
+      results.forEach((result) => {
+        expect(result.error).toBeUndefined();
+        expect(result.result).toBeDefined();
+      });
+
+      // All should return the same user
+      const users = results.map((r) => JSON.parse(r.result.content[0].text));
+      const firstUserId = users[0]._id;
+
+      users.forEach((user) => {
+        expect(user._id).toBe(firstUserId);
+      });
+    });
+
+    test("should handle concurrent requests with different credentials", async () => {
+      if (!process.env.SUNSAMA_EMAIL_2 || !process.env.SUNSAMA_PASSWORD_2) {
+        console.log("⏭️  Skipping concurrent multi-user test");
+        return;
+      }
+
+      const auth1 = createAuthHeader(SUNSAMA_EMAIL!, SUNSAMA_PASSWORD!);
+      const auth2 = createAuthHeader(
+        process.env.SUNSAMA_EMAIL_2,
+        process.env.SUNSAMA_PASSWORD_2
+      );
+
+      // 5 requests for each user, interleaved
+      const promises = Array.from({ length: 10 }, (_, i) =>
+        mcpRequest("tools/call", {
+          name: "get-user",
+          arguments: {},
+        }, i % 2 === 0 ? auth1 : auth2)
+      );
+
+      const results = await Promise.all(promises);
+
+      // All should succeed
+      results.forEach((result) => {
+        expect(result.error).toBeUndefined();
+      });
+
+      // Check that we got two different users
+      const users = results.map((r) => JSON.parse(r.result.content[0].text));
+      const uniqueEmails = new Set(users.map((u) => u.email));
+
+      expect(uniqueEmails.size).toBe(2);
+    });
+  });
+
+  describe("Error Recovery", () => {
+    test("should recover from transient failures", async () => {
+      const auth = createAuthHeader(SUNSAMA_EMAIL!, SUNSAMA_PASSWORD!);
+
+      // Make a valid request
+      const result1 = await mcpRequest("tools/call", {
+        name: "get-user",
+        arguments: {},
+      }, auth);
+
+      expect(result1.error).toBeUndefined();
+
+      // Make an invalid request
+      const result2 = await mcpRequest("tools/call", {
+        name: "invalid-tool-name",
+        arguments: {},
+      }, auth);
+
+      expect(result2.error).toBeDefined();
+
+      // Make another valid request - should still work
+      const result3 = await mcpRequest("tools/call", {
+        name: "get-user",
+        arguments: {},
+      }, auth);
+
+      expect(result3.error).toBeUndefined();
+    });
+  });
+});
+
+// Print helpful message if tests are skipped
+if (!shouldRunIntegrationTests) {
+  console.log("\n" + "⏭️".repeat(25));
+  console.log("⏭️  Integration tests SKIPPED");
+  console.log("⏭️");
+  console.log("⏭️  To run integration tests:");
+  console.log("⏭️  1. Set SUNSAMA_EMAIL and SUNSAMA_PASSWORD in .env");
+  console.log("⏭️  2. Start server: TRANSPORT_MODE=http PORT=3099 bun dev");
+  console.log("⏭️  3. Run tests: bun test:integration");
+  console.log("⏭️");
+  console.log("⏭️".repeat(25) + "\n");
+}