mcp-sunsama 0.12.1 → 0.13.0

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # mcp-sunsama
 
+## 0.13.0
+
+### Minor Changes
+
+- a39494b: Refactor to modular architecture with improved type safety
+
+  - **BREAKING**: Refactored codebase into modular, resource-based architecture
+  - **Major code organization improvements**:
+
+    - Extracted tools into separate files by resource type (user, task, stream)
+    - Reduced main.ts complexity by 96% (1162 → 47 lines)
+    - Created shared utilities for common patterns
+    - Moved API documentation to dedicated resources file
+
+  - **Complete type safety overhaul**:
+
+    - Eliminated all `any` types from function parameters
+    - Added proper TypeScript typing with Zod schema inference
+    - Implemented parameter destructuring for cleaner function signatures
+    - Added missing type exports to schemas
+
+  - **Enhanced developer experience**:
+
+    - Standardized error handling and logging across all tools
+    - Consistent response formatting with shared utilities
+    - Better code maintainability and testability
+    - Clear separation of concerns
+
+  - **New modular structure**:
+    ```
+    src/tools/
+    ├── shared.ts          # Common utilities and patterns
+    ├── user-tools.ts      # User operations
+    ├── task-tools.ts      # Task operations (14 tools)
+    ├── stream-tools.ts    # Stream operations
+    └── index.ts           # Export all tools
+    ```
+
+  This refactoring maintains 100% API compatibility while significantly improving code quality, type safety, and maintainability.
+
 ## 0.12.1
 
 ### Patch Changes

package/CLAUDE.md

@@ -72,18 +72,31 @@ All tools use Zod schemas from `schemas.ts`:
 ## Key Patterns
 
 ### Tool Structure
-Standard pattern for all MCP tools:
+Modern tool pattern using shared utilities and parameter destructuring:
 ```typescript
+// Old pattern (before refactoring)
 server.addTool({
   name: "tool-name",
   description: "...",
   parameters: toolSchema,
   execute: async (args, {session, log}) => {
-    // 1. Extract/validate parameters
-    // 2. Get client via getSunsamaClient(session)
+    const { param1, param2 } = args;
+    // Manual error handling, client resolution, etc.
+  }
+});
+
+// New pattern (current)
+export const toolName = createToolWrapper({
+  name: "tool-name", 
+  description: "...",
+  parameters: toolSchema,
+  execute: async ({ param1, param2 }: ToolInput, context: ToolContext) => {
+    // 1. Parameters automatically destructured and typed
+    // 2. Get client via getClient(context.session)
     // 3. Call sunsama-api methods
     // 4. Apply filtering/trimming if needed
-    // 5. Return formatted response
+    // 5. Return formatted response using formatters
+    // Error handling and logging handled by wrapper
   }
 });
 ```
@@ -106,17 +119,50 @@ server.addTool({
 
 ## Code Organization
 
-- `src/main.ts`: FastMCP server setup and tool definitions
-- `src/schemas.ts`: Zod validation schemas for all tools
-- `src/schemas.test.ts`: Comprehensive test suite for all Zod schemas including parameter validation, response schemas, and XOR patterns
-- `src/auth/`: Authentication strategies per transport type
-- `src/config/`: Environment configuration and validation
-- `src/utils/`: Reusable utilities (client resolution, filtering, formatting)
+### Refactored Modular Architecture (2024)
+
+The codebase has been refactored into a modular, resource-based architecture:
+
+```
+src/
+├── tools/
+│   ├── shared.ts          # Common utilities and tool wrapper patterns
+│   ├── user-tools.ts      # User operations (get-user)
+│   ├── task-tools.ts      # Task operations (14 tools)
+│   ├── stream-tools.ts    # Stream operations (get-streams)
+│   └── index.ts           # Export all tools
+├── resources/
+│   └── index.ts           # API documentation resource
+├── auth/                  # Authentication strategies per transport type
+├── config/                # Environment configuration and validation
+├── utils/                 # Reusable utilities (client resolution, filtering, formatting)
+├── 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)
+```
+
+### Tool Architecture Improvements
+
+**Shared Utilities** (`tools/shared.ts`):
+- `createToolWrapper()`: Standardized error handling and logging wrapper
+- `getClient()`: Session-aware client resolution
+- `formatJsonResponse()`, `formatTsvResponse()`: Consistent response formatting
+- `formatPaginatedTsvResponse()`: Specialized pagination support
+
+**Resource-Based Organization**:
+- **User Tools**: Single tool for user operations
+- **Task Tools**: 14 tools organized by function (query, lifecycle, update)
+- **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
 
 ## Important Notes
 
 ### Version Synchronization
-Always keep FastMCP server version in `src/main.ts` (line ~32) synchronized with `package.json` version.
+Always keep FastMCP server version in `src/main.ts` (line 19) synchronized with `package.json` version.
 
 ### Environment Variables
 Required for stdio transport:
@@ -144,7 +190,7 @@ Configure different server variants in `mcp-inspector.json` for testing various
 
 When updating the version:
 1. Update `package.json` version (done automatically by changesets)
-2. Manually update the FastMCP server version in `src/main.ts`
+2. Manually update the FastMCP server version in `src/main.ts` (line 19)
 3. Both versions must be identical for consistency
 
 ## Git Rules

package/README.md

@@ -121,11 +121,40 @@ bun run inspect
 
 Then connect the MCP Inspector to test the tools interactively.
 
-### Build
+### Build and Type Checking
 ```bash
-bun run build
+bun run build              # Compile TypeScript to dist/
+bun run typecheck          # Run TypeScript type checking
+bun run typecheck:watch    # Watch mode type checking
 ```
 
+### Code Architecture
+
+The server is organized with a modular, resource-based architecture:
+
+```
+src/
+├── tools/
+│   ├── shared.ts          # Common utilities and patterns
+│   ├── user-tools.ts      # User operations (get-user)
+│   ├── task-tools.ts      # Task operations (14 tools)
+│   ├── stream-tools.ts    # Stream operations (get-streams)
+│   └── index.ts           # Export all tools
+├── resources/
+│   └── index.ts           # API documentation resource
+├── auth/                  # Authentication strategies
+├── config/                # Environment configuration
+├── utils/                 # Utilities (filtering, trimming, etc.)
+└── main.ts                # Server setup (47 lines vs 1162 before refactoring)
+```
+
+**Key Features:**
+- **Type Safety**: Full TypeScript typing with Zod schema validation
+- **Parameter Destructuring**: Clean, explicit function signatures
+- **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
+
 ## Authentication
 
 **Stdio Transport:** Requires `SUNSAMA_EMAIL` and `SUNSAMA_PASSWORD` environment variables.