Timesheet Assistant MCP

# Timesheet Assistant MCP An MCP (Model Context Protocol) server for generating timesheets and submitting them to PSI Project Server (SharePoint-based timesheet systems). ## Features - **Timesheet Generation**: Generate daily, weekly, monthly, or custom date range timesheets - **PSI Integration**: Automated submission to PSI Project Server - **Activity Data Integration**: Works with [Activity Collector MCP](https://github.com/srdmathur/activity-collector-mcp) for data fetching - **Smart Summarization**: Automatically summarizes work descriptions to 255 characters - **Browser Automation**: Uses Puppeteer for SharePoint authentication and form filling - **Task Management**: Hierarchical task tree navigation for PSI ## Prerequisites **⚠️ Important**: This MCP requires [Activity Collector MCP](https://github.com/srdmathur/activity-collector-mcp) to fetch activity data from GitLab, GitHub, and Calendar services. ## Installation ### Via npx (Recommended) ```bash npx timesheet-assistant-mcp ``` ### Via npm ```bash npm install -g timesheet-assistant-mcp ``` ### From Source ```bash git clone https://github.com/sharadmathuratthepsi/timesheet-mcp.git cd timesheet-mcp npm install npm run build ``` ## Configuration ### For Claude Desktop Add to `~/Library/Application Support/Claude/claude_desktop_config.json`: ```json { "mcpServers": { "activity-collector": { "command": "npx", "args": ["activity-collector-mcp"] }, "timesheet-assistant": { "command": "npx", "args": ["timesheet-assistant-mcp"] } } } ``` ### For Claude Code (VS Code) Add to `~/Library/Application Support/Code/User/mcp.json`: ```json { "servers": { "activity-collector": { "type": "stdio", "command": "npx", "args": ["activity-collector-mcp"] }, "timesheet-assistant": { "type": "stdio", "command": "npx", "args": ["timesheet-assistant-mcp"] } } } ``` ### Configuration File Create `~/.timesheet-assistant-mcp-config.json`: ```json { "psi": { "url": "https://projectserver.thepsi.com/PWA/_layouts/15/pwa/Timesheet/MyTSSummary.aspx" } } ``` ## Usage ### First Time Setup 1. **Configure PSI credentials**: ``` Configure PSI with username: YOUR_USERNAME and password: YOUR_PASSWORD ``` ### Generating Timesheets - **Daily**: `Generate timesheet for today` - **Weekly**: `Generate timesheet for this week` - **Monthly**: `Generate timesheet for November 2024` - **Date Range**: `Generate timesheet from 2024-12-01 to 2024-12-07` ### Submitting to PSI 1. **Generate timesheet** (using Activity Collector MCP) 2. **Get PSI tasks** (call once, reuse for all days): ``` Get PSI tasks for 2024-12-05 ``` 3. **Select task** from the hierarchical tree 4. **Submit timesheet**: ``` Submit to PSI for 2024-12-05 with task index 3 and description "..." ``` ## Available Tools (8) ### Timesheet Generation (4 tools) - `generate_timesheet` - Generate monthly timesheet - `generate_weekly_timesheet` - Generate weekly timesheet - `generate_daily_timesheet` - Generate single day timesheet - `generate_date_range_timesheet` - Generate custom date range timesheet **Note**: These tools orchestrate the Activity Collector MCP to fetch data. ### PSI Integration (4 tools) - `configure_psi` - Configure PSI credentials - `get_psi_tasks` - Get available tasks from PSI (call once per timesheet period) - `submit_to_psi` - Submit timesheet entry to PSI - `inspect_psi_page` - Debug PSI page structure ## How It Works ### Timesheet Generation Flow 1. LLM calls timesheet generation tool (e.g., `generate_weekly_timesheet`) 2. Tool returns instructions for fetching data from Activity Collector MCP 3. LLM uses Activity Collector tools (`fetch_gitlab_activity`, `fetch_github_activity`, `fetch_google_calendar_events`) 4. LLM builds and formats the timesheet ### PSI Submission Flow 1. Call `get_psi_tasks` **once** to get available tasks 2. User selects a task by index 3. Call `submit_to_psi` for each day (reusing same task index) 4. Browser automation fills SharePoint form and saves ## PSI Integration Details - Uses Puppeteer for browser automation - Supports HTTP Basic Auth for SharePoint - Handles lazy-loaded accordion trees for task selection - Smart grid cell detection for SharePoint JSGrid - Automatic form filling with MouseEvent simulation ## Security - PSI credentials stored in `~/.timesheet-assistant-mcp-tokens.json` with restricted permissions (600) - Browser runs in non-headless mode by default (can see what's happening) - All data remains local ## Troubleshooting ### Activity Collector Not Available ``` Error: fetch_gitlab_activity tool not found ``` **Solution**: Install and configure [Activity Collector MCP](https://github.com/srdmathur/activity-collector-mcp) ### PSI Submission Fails ``` Error: Could not find hours cell ``` **Solution**: Run `inspect_psi_page` to check PSI page structure ### Browser Crashes **Solution**: Ensure Puppeteer dependencies are installed: ```bash npm install puppeteer ``` ## License MIT ## Contributing Issues and pull requests welcome! ## Author Sharad Mathur (sharad.mathur@thepsi.com) ## Related Projects - [Activity Collector MCP](https://github.com/srdmathur/activity-collector-mcp) - Required companion MCP for data fetching