mcp-sunsama 0.2.0

package/.changeset/README.md

@@ -0,0 +1,8 @@
+# Changesets
+
+Hello and welcome! This folder has been automatically generated by `@changesets/cli`, a build tool that works
+with multi-package repos, or single-package repos to help you version and publish your code. You can
+find the full documentation for it [in our repository](https://github.com/changesets/changesets)
+
+We have a quick list of common questions to get you started engaging with this project in
+[our documentation](https://github.com/changesets/changesets/blob/main/docs/common-questions.md)

package/.changeset/config.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://unpkg.com/@changesets/config@3.1.1/schema.json",
+  "changelog": "@changesets/cli/changelog",
+  "commit": false,
+  "fixed": [],
+  "linked": [],
+  "access": "public",
+  "baseBranch": "main",
+  "updateInternalDependencies": "patch",
+  "ignore": []
+}

package/.claude/settings.local.json

@@ -0,0 +1,29 @@
+{
+  "permissions": {
+    "allow": [
+      "mcp__context7__resolve-library-id",
+      "mcp__context7__get-library-docs",
+      "mcp__sunsama__get-tasks-by-day",
+      "mcp__sunsama__get-user",
+      "mcp__time__get_current_time",
+      "mcp__sunsama__get-tasks-backlog",
+      "Bash(npm run typecheck:*)",
+      "Bash(find:*)",
+      "Bash(ls:*)",
+      "Bash(bun run build:*)",
+      "Bash(npm pack:*)",
+      "mcp__sequential-thinking__sequentialthinking",
+      "Bash(gh auth:*)"
+    ],
+    "deny": []
+  },
+  "enabledMcpjsonServers": [
+    "brave-search",
+    "context7",
+    "fetch",
+    "puppeteer",
+    "sequential-thinking",
+    "sunsama",
+    "time"
+  ]
+}

package/.env.example

@@ -0,0 +1,10 @@
+# MCP Server Configuration
+PORT=3002
+
+# Sunsama Authentication
+# Option 1: Use session token (recommended for server environments)
+SUNSAMA_SESSION_TOKEN=your-session-token-here
+
+# Option 2: Use email/password (for development/testing)
+# SUNSAMA_EMAIL=your-email@example.com
+# SUNSAMA_PASSWORD=your-password

package/CHANGELOG.md

@@ -0,0 +1,29 @@
+# mcp-sunsama
+
+## 0.2.0
+
+### Minor Changes
+
+- Initial release of MCP Sunsama Server
+
+  - Full CRUD task management (create, read, update, delete)
+  - Dual transport support (stdio and HTTP stream)
+  - User operations and stream management
+  - Task filtering by completion status
+  - Response optimization with task trimming
+  - Comprehensive TypeScript support with Zod validation
+  - Authentication support for session tokens and email/password
+
+## 1.0.0
+
+### Major Changes
+
+- Initial release of MCP Sunsama Server
+
+  - Full CRUD task management (create, read, update, delete)
+  - Dual transport support (stdio and HTTP stream)
+  - User operations and stream management
+  - Task filtering by completion status
+  - Response optimization with task trimming
+  - Comprehensive TypeScript support with Zod validation
+  - Authentication support for session tokens and email/password

package/CLAUDE.md

@@ -0,0 +1,137 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Development Commands
+
+```bash
+# Development
+bun run dev                 # Run server with .env file
+bun run typecheck          # TypeScript type checking
+bun run typecheck:watch    # Watch mode type checking
+bun run inspect            # MCP Inspector for debugging
+
+# Build and Distribution
+bun run build              # Compile TypeScript to dist/
+bun test                   # Run test suite
+
+# Version Management (Changeset)
+bun run changeset          # Create new changeset
+bun run version            # Apply changesets and update version
+bun run release            # Build and publish to npm
+```
+
+## Architecture Overview
+
+### Dual Transport MCP Server
+This server supports two transport modes with different authentication strategies:
+
+**Stdio Transport** (default):
+- Single global SunsamaClient authenticated at startup
+- Uses `SUNSAMA_EMAIL`/`SUNSAMA_PASSWORD` environment variables
+- Session maintained for entire server lifetime
+
+**HTTP Stream Transport**:
+- Per-request authentication via HTTP Basic Auth
+- Session-isolated SunsamaClient instances
+- Credentials provided in Authorization header
+
+Transport selection via `TRANSPORT_TYPE` environment variable ("stdio" | "httpStream").
+
+### Client Resolution Pattern
+`utils/client-resolver.ts` abstracts transport differences:
+- **Stdio**: Returns singleton client from global authentication
+- **HTTP**: Extracts client from session data (authenticated per request)
+- Throws standardized errors for unauthenticated requests
+
+### Response Optimization Strategy
+Two-tier optimization for large datasets:
+
+1. **Task Filtering** (`utils/task-filters.ts`): Filter by completion status before processing
+2. **Task Trimming** (`utils/task-trimmer.ts`): Remove non-essential fields to reduce payload by 60-80%
+
+Always apply filtering before trimming for efficiency.
+
+### Schema Architecture
+All tools use Zod schemas from `schemas.ts`:
+- Type-safe parameter validation
+- Automatic TypeScript inference
+- Comprehensive parameter documentation
+- Union types for completion filters
+
+## Key Patterns
+
+### Tool Structure
+Standard pattern for all MCP tools:
+```typescript
+server.addTool({
+  name: "tool-name",
+  description: "...",
+  parameters: toolSchema,
+  execute: async (args, {session, log}) => {
+    // 1. Extract/validate parameters
+    // 2. Get client via getSunsamaClient(session)
+    // 3. Call sunsama-api methods
+    // 4. Apply filtering/trimming if needed
+    // 5. Return formatted response
+  }
+});
+```
+
+### Authentication Flow
+- **Stdio**: `initializeStdioAuth()` creates global client at startup
+- **HTTP**: `httpStreamAuthenticator()` authenticates each request
+- Both store client in session data accessible via `getSunsamaClient()`
+
+### Configuration Management
+`config/transport.ts` handles environment-based configuration:
+- Zod validation for environment variables
+- Sensible defaults (stdio transport, port 3000)
+- Clear error messages for invalid configurations
+
+### Output Formatting
+- **JSON**: Single objects (user data)
+- **TSV**: Arrays (tasks, streams) - optimized for Claude's data processing
+- **Structured Logging**: Consistent patterns across all tools
+
+## Code Organization
+
+- `src/main.ts`: FastMCP server setup and tool definitions
+- `src/schemas.ts`: Zod validation schemas for all tools
+- `src/auth/`: Authentication strategies per transport type
+- `src/config/`: Environment configuration and validation
+- `src/utils/`: Reusable utilities (client resolution, filtering, formatting)
+
+## Important Notes
+
+### Version Synchronization
+Always keep FastMCP server version in `src/main.ts` (line ~32) synchronized with `package.json` version.
+
+### Environment Variables
+Required for stdio transport:
+- `SUNSAMA_EMAIL`: Sunsama account email
+- `SUNSAMA_PASSWORD`: Sunsama account password
+
+Optional:
+- `TRANSPORT_TYPE`: "stdio" (default) | "httpStream"
+- `PORT`: Server port (default: 3002, HTTP transport only)
+
+### Task Operations
+Full CRUD support:
+- **Read**: `get-tasks-by-day`, `get-tasks-backlog`, `get-streams`
+- **Write**: `create-task`, `update-task-complete`, `delete-task`
+
+All task operations support completion filtering and response trimming.
+
+### Testing Tools
+Use MCP Inspector for debugging: `bun run inspect`
+Configure different server variants in `mcp-inspector.json` for testing various scenarios.
+
+## Version Management
+
+**IMPORTANT**: Keep the FastMCP server version in sync with package.json version.
+
+When updating the version:
+1. Update `package.json` version (done automatically by changesets)
+2. Manually update the FastMCP server version in `src/main.ts`
+3. Both versions must be identical for consistency

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Robert Niimi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,143 @@
+# Sunsama MCP Server
+
+A Model Context Protocol (MCP) server that provides comprehensive task management capabilities through the Sunsama API. This server enables AI assistants to access Sunsama tasks, create new tasks, mark tasks complete, and manage your productivity workflow.
+
+## Features
+
+### 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
+- **Update Tasks** - Mark tasks as complete with custom timestamps
+- **Delete Tasks** - Permanently remove tasks from your workspace
+
+### User & Stream Operations
+- **User Information** - Access user profile, timezone, and group details
+- **Stream Management** - Get streams/channels for project organization
+- **Dual Transport** - Support for both stdio and HTTP stream MCP transports
+
+## Installation
+
+### Prerequisites
+- [Bun](https://bun.sh) runtime (for development)
+- Sunsama account with API access
+
+### Using NPX (Recommended)
+No installation required! Use directly with:
+```bash
+npx mcp-sunsama
+```
+
+### Development Setup
+1. Clone the repository:
+```bash
+git clone https://github.com/robertn702/mcp-sunsama.git
+cd mcp-sunsama
+```
+
+2. Install dependencies:
+```bash
+bun install
+```
+
+3. Set up your environment variables:
+```bash
+cp .env.example .env
+# Edit .env and add your Sunsama credentials
+```
+
+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)
+
+## Usage
+
+### Running the Server
+
+**Stdio Transport (default):**
+```bash
+bun run src/main.ts
+```
+
+**HTTP Stream Transport:**
+```bash
+MCP_TRANSPORT=httpStream PORT=3002 bun run src/main.ts
+```
+
+### Claude Desktop Configuration
+
+Add this configuration to your Claude Desktop MCP settings:
+
+```json
+{
+  "mcpServers": {
+    "sunsama": {
+      "command": "npx",
+      "args": ["mcp-sunsama"],
+      "env": {
+        "SUNSAMA_EMAIL": "your-email@example.com",
+        "SUNSAMA_PASSWORD": "your-password"
+      }
+    }
+  }
+}
+```
+
+## API Tools
+
+### Task Management
+- `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
+- `update-task-complete` - Mark tasks as complete
+- `delete-task` - Delete tasks permanently
+
+### User & Stream Operations
+- `get-user` - Get current user information
+- `get-streams` - Get streams/channels for project organization
+
+## Development
+
+### Running in Development
+```bash
+bun run dev
+```
+
+### Testing with MCP Inspector
+```bash
+bun run inspect
+```
+
+Then connect the MCP Inspector to test the tools interactively.
+
+### Build
+```bash
+bun run build
+```
+
+## 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.
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests if applicable
+5. Submit a pull request
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Support
+
+- [Sunsama API Documentation](https://help.sunsama.com) 
+- [sunsama-api Library](https://github.com/robertn702/sunsama-api) - The underlying API client
+- [Model Context Protocol Documentation](https://modelcontextprotocol.io)
+- [Issue Tracker](https://github.com/robertn702/mcp-sunsama/issues)

package/TODO_PREPUBLISH.md

@@ -0,0 +1,182 @@
+# MCP Sunsama - Pre-Publish Checklist
+
+## 🚨 Critical Blockers (Must Fix Before Publishing)
+
+### 1. Package Configuration Issues
+- [x] ✅ **Remove `"private": true`** from package.json (publishing now enabled)
+- [x] ✅ Add essential package.json metadata:
+  - [x] ✅ `"version": "0.1.0"`: Initial version
+  - [x] ✅ `"description": "MCP server for Sunsama API integration"`: Package description
+  - [x] ✅ `"type": "module"`: ES module support
+  - [x] ✅ `"keywords": ["mcp", "sunsama", "task-management", "api", "productivity"]`: Search keywords
+  - [x] ✅ `"author": "Robert Niimi <robertn702@gmail.com>"`: Author information
+  - [x] ✅ `"license": "MIT"`: License specification
+  - [x] ✅ `"repository": {"type": "git", "url": "https://github.com/robertn702/mcp-sunsama.git"}`: Git repository
+  - [x] ✅ `"homepage": "https://github.com/robertn702/mcp-sunsama#readme"`: Homepage URL
+  - [x] ✅ `"bugs": {"url": "https://github.com/robertn702/mcp-sunsama/issues"}`: Bug tracker
+  - [x] ✅ `"main": "dist/main.js"`: Entry point
+  - [x] ✅ `"types": "dist/main.d.ts"`: TypeScript definitions
+  - [x] ✅ `"bin": {"mcp-sunsama": "./dist/main.js"}`: CLI executable
+  - [x] ✅ `"publishConfig": {"access": "public"}`: NPM publish settings
+
+### 2. Build System Configuration
+- [x] ✅ **Fix tsconfig.json** - Build output now properly configured
+  - [x] ✅ Change `"noEmit": false`
+  - [x] ✅ Add `"outDir": "dist"`
+  - [x] ✅ Add `"declaration": true` for TypeScript definitions
+  - [x] ✅ Add `"declarationMap": true` for source maps
+  - [x] ✅ Add `"exclude": ["dist", "node_modules"]`
+  - [x] ✅ Remove `"allowImportingTsExtensions"` (incompatible with emit)
+
+### 3. Legal Requirements
+- [x] ✅ **Create LICENSE file** (MIT License to match author's other projects)
+
+## 🔥 High Priority Setup
+
+### 4. Changeset Configuration
+- [x] ✅ Install changeset: `bun add -D @changesets/cli`
+- [x] ✅ Initialize changeset: `bunx changeset init`
+- [x] ✅ Add changeset scripts to package.json:
+  ```json
+  {
+    "scripts": {
+      "changeset": "changeset",
+      "version": "changeset version", 
+      "release": "bun run build && changeset publish"
+    }
+  }
+  ```
+- [x] ✅ Configure changeset for public access
+
+### 5. Build Scripts & Inspection
+- [x] ✅ Build script exists: `"build": "bunx tsc"`
+- [ ] Add additional inspection scripts from mcp-openweathermap:
+  ```json
+  {
+    "scripts": {
+      "inspect:built": "bunx @modelcontextprotocol/inspector --config ./mcp-inspector.json --server sunsama-built",
+      "inspect:http": "bunx @modelcontextprotocol/inspector --config ./mcp-inspector.json --server sunsama-http"
+    }
+  }
+  ```
+- [x] ✅ Test build process: `bun run build`
+- [x] ✅ Verify dist/ directory is created with .js and .d.ts files
+
+### 6. Dependencies Audit
+- [x] ✅ Runtime dependencies properly classified
+- [x] ✅ **Fix dev dependencies**: Move TypeScript to devDependencies from peerDependencies
+- [x] ✅ Add missing `@changesets/cli` to devDependencies
+
+## 📋 Medium Priority Improvements
+
+### 7. Documentation Enhancements
+- [ ] Add npm installation instructions to README.md
+- [ ] Add npm version badge
+- [ ] Add license badge
+- [ ] Add contribution guidelines section
+- [ ] Update usage examples for npm installation
+- [ ] Add CLAUDE.md file following mcp-openweathermap pattern with:
+  - Development commands
+  - Architecture overview
+  - Core components documentation
+  - Version sync instructions (FastMCP server version)
+
+### 8. Package Architecture ✅ Confirmed
+- [x] ✅ **Executable CLI tool** (following mcp-openweathermap pattern)
+  - Uses `"bin"` field for CLI executable
+  - Server application distributed via npm
+  - Matches established MCP server pattern
+
+### 9. Testing Infrastructure
+- [ ] Add test files (currently no tests found)
+- [ ] Add `"test"` script that actually runs tests
+- [ ] Consider adding integration tests for Sunsama API
+- [ ] Add CI/CD workflow for automated testing
+
+## 🧪 Pre-Publish Testing Checklist
+
+### Phase 1: Fix Critical Issues
+- [x] ✅ Complete all critical blockers above
+- [x] ✅ Test TypeScript compilation: `bun run typecheck`
+- [x] ✅ Test build process: `bun run build`
+
+### Phase 2: Package Validation
+- [ ] Validate package contents: `npm pack --dry-run`
+- [ ] Review file list - ensure only necessary files included
+- [ ] Check package size is reasonable
+
+### Phase 3: Local Testing
+- [ ] Create test package: `npm pack`
+- [ ] Install .tgz file locally in test project
+- [ ] Verify import/require works correctly
+- [ ] Test actual MCP server functionality
+
+### Phase 4: Version Management
+- [ ] Create first changeset: `bunx changeset add`
+- [ ] Write meaningful changeset description
+- [ ] Run version bump: `bun run version`
+- [ ] Review generated CHANGELOG.md
+
+### Phase 5: Final Publish
+- [ ] **Important**: Update FastMCP server version in `src/main.ts` to match package.json version
+- [ ] Final build: `bun run build`
+- [ ] Final tests: `bun run test`
+- [ ] Publish: `bun run release`
+- [ ] Verify package appears on npm
+- [ ] Test installation from npm: `npm install mcp-sunsama`
+
+## 📊 Current Status Assessment
+
+### ✅ What's Good
+- ✅ Well-structured TypeScript codebase with full CRUD operations
+- ✅ Comprehensive task mutation tools (create, update-complete, delete)
+- ✅ Good README.md documentation
+- ✅ Modern build tooling (Bun) and TypeScript setup
+- ✅ Environment configuration handling with dual transport modes
+- ✅ Proper error handling and logging patterns
+- ✅ Schema validation with Zod
+
+### ✅ All Major Issues Resolved
+- [x] ✅ Package marked as private (blocks publishing) - FIXED
+- [x] ✅ No build output configuration (noEmit: true) - FIXED
+- [x] ✅ Missing LICENSE file - FIXED
+- [x] ✅ No changeset setup - FIXED
+- [x] ✅ Missing essential package.json metadata - FIXED
+- [x] ✅ TypeScript in wrong dependency category - FIXED
+
+### ✅ Architecture Confirmed
+- ✅ MCP server application (matches mcp-openweathermap pattern)
+- ✅ NPM publishing is appropriate distribution method
+- ✅ CLI executable pattern established
+- ✅ Dual transport support (stdio/HTTP) implemented
+
+## 🚀 Quick Start Command Sequence
+
+Ready for first publication:
+
+```bash
+# 1. Create first changeset
+bunx changeset add
+
+# 2. Version and publish
+bun run version
+bun run release
+```
+
+**All setup steps completed!** ✅
+
+## 📝 Important Notes
+
+- **Version Sync**: Always keep FastMCP server version in `src/main.ts` line ~31 synchronized with package.json version
+- **Package Type**: ✅ Confirmed as executable CLI tool (matches mcp-openweathermap pattern)
+- **Target Audience**: MCP users who want Sunsama task management integration
+- **Security**: ✅ No sensitive information in source code (uses environment variables)
+- **Architecture**: ✅ Dual transport MCP server with comprehensive task management tools
+
+## 🎯 Priority Order
+
+1. **Critical Blockers** (Sections 1-3): Must be completed before any publishing attempt
+2. **Changeset Setup** (Section 4): Required for version management
+3. **Build Verification** (Section 5): Ensure compilation works
+4. **Documentation** (Section 7): Improve user experience
+5. **Testing** (Section 9): Add comprehensive test coverage