Timesheet MCP Server

# Timesheet MCP Server Simple timesheet automation server using Model Context Protocol (MCP) and NestJS. ## Features - **Fresh Token on Every Tool Call** - Automatically refreshes authentication token on each request - **Smart Authentication Handling** - Seamlessly handles token expiration and re-authenticates using MCP client credentials - **No Token Storage** - Config file is deleted on server startup for security; fresh login on every session - **Stateless Operation** - Each tool call is independent and self-authenticating - **5 Essential Tools** organized by domain: - **Authentication**: `whoami` - Get current user info, assigned projects, and modules - **Timesheets**: `create_new_timesheet_entry`, `list_user_timesheet_entries` - **Activities**: `list_all_available_work_activities` - **Daily Updates**: `create_daily_scrum_standup_update` ## Quick Setup ### 1. Install Dependencies ```bash npm install ``` ### 2. Configure Environment The server requires credentials to be configured in your MCP client's environment variables (not in a `.env` file on the server). This ensures credentials are never stored on the server. **TIMESHEET_USERNAME** and **TIMESHEET_PASSWORD** must be configured in your MCP client configuration: - For Claude Desktop: Configure in `claude_desktop_config.json` (see below) - For OpenCode: Configure in the MCP environment variables - For MCP Inspector: Set as environment variables before running Optional server-side `.env` file: ```env # Backend API (optional - defaults to https://timesheet.pinnacle.in:3000/api) API_BASE_URL=https://timesheet.pinnacle.in:3000/api # Node Environment NODE_ENV=production ``` **Note**: SSL certificate verification is automatically disabled in the code for self-signed certificates. ### 3. Build and Run ```bash npm run build npm run start ``` ## Authentication The server implements **stateless, fresh authentication** for every tool call: 1. **On Server Startup**: Config file is deleted to ensure a clean state 2. **On Every Tool Call**: - Attempts to use existing cached token (if available) - Automatically refreshes token via `/auth/refresh` endpoint - If token is expired or invalid, re-authenticates using `TIMESHEET_USERNAME` and `TIMESHEET_PASSWORD` from MCP client environment - If login fails, returns a clear error message 3. **No Token Persistence**: Tokens are saved to config file temporarily but deleted on next server restart This approach ensures: - ✅ Fresh authentication on every server session - ✅ Automatic token refresh without user intervention - ✅ Graceful handling of expired credentials - ✅ Clear error messages for troubleshooting - ✅ No sensitive data stored on disk between sessions ## Available Tools ### Authentication Tools #### `whoami` Get current authenticated user information with automatically fetched projects and modules. This tool: - Handles authentication automatically (refreshes token or logs in with MCP client credentials) - Returns fresh user details, all assigned projects, and modules within those projects - Provides clear error messages if credentials are missing or invalid - This is the primary starting tool for verifying authentication **Parameters**: None **Response**: ```json { "success": true, "message": "✓ User authenticated successfully!", "data": { "user": { "id": 41, "name": "John Doe", "username": "john.doe@company.com", "email": "john.doe@company.com", "roles": ["RESOURCE"], "managerId": 44 }, "projects": [ { "id": 9, "name": "Project Name", "project_id": 9 } ], "modules": [ { "id": 41, "name": "Pyramid2.0_UI Gateway", "project_id": 9 } ] } } ``` ### Timesheet Management Tools #### `create_new_timesheet_entry` Create a new daily timesheet entry with work details. **Parameters**: - `project_id` (number): Which project the work belongs to - `module_id` (number): Which module/component within the project - `activity_id` (number): The type of work (Development, Code Review, Testing, etc.) - `start_time` (string): Start time in HH:MM:SS format - `end_time` (string): End time in HH:MM:SS format - `duration` (number): Duration in minutes - `description` (string, min 10 chars): Detailed work description - `date` (string): Date in YYYY-MM-DD format **Example**: ```json { "project_id": 9, "module_id": 41, "activity_id": 11, "start_time": "09:00:00", "end_time": "10:00:00", "duration": 60, "description": "Working on user authentication module implementation", "date": "2025-11-04" } ``` #### `list_user_timesheet_entries` Fetch and display user's timesheet entries with pagination. **Parameters**: - `page` (number, optional, default: 1): Page number for pagination - `limit` (number, optional, default: 10, max: 100): Number of entries per page **Example**: ```json { "page": 1, "limit": 10 } ``` ### Activity Management Tools #### `list_all_available_work_activities` Get all available work activity types/categories that can be used when creating timesheet entries. **Parameters**: None **Response**: ```json { "success": true, "message": "✓ Available work activities fetched successfully!", "data": [ { "id": 1, "name": "Development", "description": "Development work" }, { "id": 11, "name": "Code Review", "description": "Code review activities" } ] } ``` ### Daily Updates Tools #### `create_daily_scrum_standup_update` Create a daily scrum standup update to report progress and blockers. **Parameters**: - `date` (string): Date in yyyy-MM-dd format - `yesterdays_progress` (string): Summary of work completed yesterday - `todays_priorities` (string): Main priorities and goals for today - `task_blockers` (string): Any blockers or impediments (or "None" if no blockers) **Example**: ```json { "date": "2025-11-04", "yesterdays_progress": "Completed user authentication module with tests", "todays_priorities": "Implement profile page and integrate with API", "task_blockers": "Waiting for backend API documentation" } ``` ## MCP Client Configuration ### For Claude Desktop Create/edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or appropriate config file for your OS: ```json { "mcpServers": { "timesheet-mcp": { "command": "node", "args": ["/path/to/timesheet-mcp/dist/main.js"], "env": { "NODE_ENV": "production", "API_BASE_URL": "https://timesheet.pinnacle.in:3000/api", "TIMESHEET_USERNAME": "your.email@company.com", "TIMESHEET_PASSWORD": "your-password" } } } } ``` **Windows Claude Desktop Path**: `%APPDATA%\Claude\claude_desktop_config.json` **Linux Claude Desktop Path**: `~/.config/claude/claude_desktop_config.json` ### For OpenCode Edit your OpenCode config file and add the MCP server configuration: ```json { "$schema": "https://opencode.ai/config.json", "mcp": { "timesheet-mcp": { "type": "local", "command": ["node", "/path/to/timesheet-mcp/dist/main.js"], "enabled": true, "environment": { "NODE_ENV": "production", "API_BASE_URL": "https://timesheet.pinnacle.in:3000/api", "TIMESHEET_USERNAME": "your.email@company.com", "TIMESHEET_PASSWORD": "your-password" } } } } ``` **Note**: The `"type": "local"` field is required for OpenCode to recognize the MCP server. ### For MCP Inspector ```bash npm run inspector ``` ## Architecture ``` src/ ├── common/ # Shared utilities and DTOs │ └── utils/ │ └── response.util.ts # MCP response formatting utility ├── auth/ # Authentication module │ ├── auth.module.ts │ ├── auth.service.ts │ ├── auth.tools.ts # whoami tool │ ├── auto-login.service.ts │ └── dto/ │ └── login.dto.ts ├── projects/ # Project management module │ ├── projects.module.ts │ ├── projects.service.ts │ └── projects.tools.ts # Project-related tools ├── timesheets/ # Timesheet module │ ├── timesheets.module.ts │ ├── timesheets.service.ts │ ├── timesheets.tools.ts # Timesheet creation and listing tools │ └── dto/ │ └── create-timesheet.dto.ts ├── activities/ # Activity management module │ ├── activities.module.ts │ ├── activities.service.ts │ └── activities.tools.ts # Activity listing tool ├── daily-updates/ # Daily scrum module │ ├── daily-updates.module.ts │ ├── daily-updates.service.ts │ ├── daily-updates.tools.ts # Daily scrum tool │ └── dto/ │ └── create-daily-scrum.dto.ts ├── config/ # Configuration management ├── shared/ # HTTP client & shared utilities ├── main.ts # Application entry point └── app.module.ts # Main application module ``` ## Design Principles - **Modular Architecture**: Each domain (auth, projects, timesheets, etc.) is a separate module - **Separation of Concerns**: Services handle business logic, tools handle MCP interface - **Descriptive Tool Names**: Tool names clearly indicate what they do for LLM decision making - **Response Utility**: Centralized MCP response formatting for consistency - **DTOs**: Type-safe data transfer between layers ## Philosophy This MCP server provides **simple API wrappers** - no AI, no smart parsing, no complex workflows. The LLM (Claude, GPT, etc.) handles all natural language processing and intelligence. The server just provides CRUD operations for the timesheet API. ## API Endpoints Used - `POST /api/auth/login` - User authentication - `GET /api/projects/user/{userId}` - Get user projects - `GET /api/modules/by-project?projectId={id}` - Get project modules - `GET /api/activities` - Get all activities - `POST /api/timesheets/create` - Create timesheet entry - `GET /api/timesheets/list/{userId}` - Get user timesheets ## License MIT