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)

npx timesheet-assistant-mcp

Via npm

npm install -g timesheet-assistant-mcp

From Source

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:

{
  "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:

{
  "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:

{
  "psi": {
    "url": "https://projectserver.thepsi.com/PWA/_layouts/15/pwa/Timesheet/MyTSSummary.aspx"
  }
}

Usage

First Time Setup

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

Generate timesheet (using Activity Collector MCP)
Get PSI tasks (call once, reuse for all days):
```
Get PSI tasks for 2024-12-05
```
Select task from the hierarchical tree

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

LLM calls timesheet generation tool (e.g., generate_weekly_timesheet)
Tool returns instructions for fetching data from Activity Collector MCP
LLM uses Activity Collector tools (fetch_gitlab_activity, fetch_github_activity, fetch_google_calendar_events)
LLM builds and formats the timesheet

PSI Submission Flow

Call get_psi_tasks once to get available tasks
User selects a task by index
Call submit_to_psi for each day (reusing same task index)
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

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:

npm install puppeteer

License

MIT

Contributing

Issues and pull requests welcome!

Author

Sharad Mathur (sharad.mathur@thepsi.com)

Activity Collector MCP - Required companion MCP for data fetching

Package detail