# Tempo MCP Server

MCP (Model Context Protocol) server for Tempo time tracking with full support for **roles** and **accounts**.

## Features

- **Auto-generate timesheets from git commits** - scans all your repos and creates worklogs automatically
- Create worklogs with role and account attributes
- Automatically fetch account from Jira issue
- **Auto-fallback to active account** when issue's account is closed/archived
- **Quick sprint meeting logging** - just specify project and minutes
- Update and delete worklogs
- List worklogs for date ranges
- Get available work attributes and roles

## Installation

```bash
npm install
npm run build
```

## Configuration

### Getting your API tokens

**Tempo API Token:**
1. Go to [Tempo > Settings](https://app.tempo.io/settings) in your Jira instance
2. Click on **API Integration** in the left sidebar
3. Click **New Token**
4. Give it a name (e.g., "Claude Code MCP")
5. Select permissions: **Manage Worklogs** (or Full Access)
6. Copy the generated token

**Jira API Token:**
1. Go to [Atlassian API Tokens](https://id.atlassian.com/manage-profile/security/api-tokens)
2. Click **Create API token**
3. Give it a label (e.g., "Claude Code MCP")
4. Copy the generated token

### Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `TEMPO_API_TOKEN` | Yes | Tempo API token (get from Tempo > Settings > API Integration) |
| `JIRA_API_TOKEN` | Yes | Jira API token (get from id.atlassian.com/manage-profile/security/api-tokens) |
| `JIRA_EMAIL` | Yes | Jira account email |
| `JIRA_BASE_URL` | Yes | Jira base URL (e.g., https://company.atlassian.net) |
| `JIRA_ACCOUNT_FIELD_ID` | No | Custom field ID for Tempo account (default: 10026) |
| `DEFAULT_ROLE` | No | Default role for worklogs (default: Dev) |
| `DEFAULT_PROJECTS_DIR` | No | Default directory for git repos (e.g., C:/Users/you/Projects) |
| `DEFAULT_MONDAY_MEETING_ISSUE` | No | Jira issue for Monday team meeting (default: BS-14) |

> **Note:** `gitAuthor` defaults to `JIRA_EMAIL` since they're the same for all developers.

## Usage with Claude Code

### Quick Setup (one command)

**Linux/macOS:**
```bash
claude mcp add tempo-mcp -s user \
  -e TEMPO_API_TOKEN=your-tempo-token \
  -e JIRA_API_TOKEN=your-jira-token \
  -e JIRA_EMAIL=your-email@company.com \
  -e JIRA_BASE_URL=https://company.atlassian.net \
  -e DEFAULT_PROJECTS_DIR=/home/you/projects \
  -- npx -y github:Henry-Workshop/tempo-mcp
```

**Windows (PowerShell):**
```powershell
claude mcp add tempo-mcp -s user `
  -e TEMPO_API_TOKEN=your-tempo-token `
  -e JIRA_API_TOKEN=your-jira-token `
  -e JIRA_EMAIL=your-email@company.com `
  -e JIRA_BASE_URL=https://company.atlassian.net `
  -e DEFAULT_PROJECTS_DIR=C:/Users/you/Projects `
  -- npx.cmd -y github:Henry-Workshop/tempo-mcp
```

### Example configuration in claude.json

```json
{
  "mcpServers": {
    "tempo-mcp": {
      "command": "npx",
      "args": ["-y", "github:Henry-Workshop/tempo-mcp"],
      "env": {
        "TEMPO_API_TOKEN": "your-tempo-token",
        "JIRA_API_TOKEN": "your-jira-token",
        "JIRA_EMAIL": "your-email@company.com",
        "JIRA_BASE_URL": "https://company.atlassian.net",
        "DEFAULT_PROJECTS_DIR": "C:/Users/you/Projects"
      }
    }
  }
}
```

## Available Tools

### tempo_generate_timesheet

**The main feature!** Automatically generate your weekly timesheet from git commits.

```json
{
  "weekStart": "2025-12-01",
  "gitAuthor": "your-email@company.com",
  "projectsDir": "C:/Users/you/Projects",
  "dryRun": true,
  "mondayMeetingIssue": "BS-14"
}
```

| Parameter | Required | Description |
|-----------|----------|-------------|
| `weekStart` | Yes | Monday date of the week (YYYY-MM-DD) |
| `gitAuthor` | Yes | Your git author email or name |
| `projectsDir` | Yes | Directory containing all your git repositories |
| `dryRun` | No | If true, shows plan without creating worklogs (default: false) |
| `mondayMeetingIssue` | No | Jira issue for Monday team meeting (default: BS-14) |

**What it does:**
1. Scans all git repos in `projectsDir`
2. Extracts your commits for Monday-Thursday
3. Parses Jira issue keys from commit messages (e.g., `PROJ-123`)
4. Distributes 8h/day based on commit count per issue
5. Adds 15min daily sprint meeting (on the main project of the day)
6. Adds 15min Monday team sync on BS-14
7. Generates client-friendly descriptions from commit messages
8. Creates worklogs in Tempo

**Example usage in Claude Code:**
- "fait ma feuille de temps de cette semaine"
- "generate my timesheet for last week"
- "do my timesheet for the week of december 1st in dry run mode"

**Important:** Your commit messages should include Jira issue keys (e.g., `PROJ-123 fix: description`). Commits without issue keys will be flagged as warnings.

---

### tempo_log_sprint_meeting

Quick way to log time for sprint meetings (daily, planning, retro). Automatically finds the "Sprint Meetings" issue for the project.

```json
{
  "projectKey": "PROJ",
  "timeSpentMinutes": 15,
  "description": "Daily",
  "date": "2025-11-27"
}
```

**Example usage in Claude Code:**
- "add 15 mins for sprint meetings for BERGA"
- "log daily 15 mins to CRC project"

### tempo_create_worklog

Create a new worklog with role and account support.

```json
{
  "issueKey": "PROJ-123",
  "timeSpentHours": 1.5,
  "date": "2025-11-27",
  "description": "Working on feature",
  "role": "Dev",
  "accountKey": "ACCOUNT-KEY"
}
```

If `accountKey` is not provided, it will be automatically fetched from the Jira issue. If the account is closed/archived, it will automatically find an active account from recent project issues.

### tempo_get_worklogs

Retrieve worklogs for a date range.

```json
{
  "startDate": "2025-11-01",
  "endDate": "2025-11-30"
}
```

### tempo_update_worklog

Update an existing worklog.

```json
{
  "worklogId": "12345",
  "timeSpentHours": 2,
  "description": "Updated description"
}
```

### tempo_delete_worklog

Delete a worklog.

```json
{
  "worklogId": "12345"
}
```

### tempo_get_work_attributes

Get available work attributes (roles, accounts configuration).

### tempo_get_roles

Get available Tempo roles.

## License

MIT