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 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 to fetch activity data from GitLab, GitHub, and Calendar services.

Installation

Via npx (Recommended)

Via npm

From Source

Configuration

For Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

For Claude Code (VS Code)

Add to ~/Library/Application Support/Code/User/mcp.json:

Configuration File

Create ~/.timesheet-assistant-mcp-config.json:

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

Solution: Install and configure Activity Collector MCP

PSI Submission Fails

Solution: Run inspect_psi_page to check PSI page structure

Browser Crashes

Solution: Ensure Puppeteer dependencies are installed:

License

MIT

Contributing

Issues and pull requests welcome!

Author

Sharad Mathur (sharad.mathur@thepsi.com)

Related Projects

• Activity Collector MCP - Required companion MCP for data fetching