# Date Operations MCP Server

A Model Context Protocol (MCP) server providing reliable date calculations with UK context, specifically designed for James Murrell's BA workflow.

## Features

- **Working Day Calculations**: Automatically excludes weekends and UK bank holidays
- **UK Bank Holiday Integration**: Fetches live data from GOV.UK API
- **Asana-Specific Helpers**: Follows James's rules (next working day at 4 PM, Friday → Monday)
- **Sprint Planning Tools**: Calculate sprint dates and current sprint information
- **UK Timezone**: All dates handled in Europe/London timezone (GMT/BST)

## Installation

```bash
# Clone or create the project directory
mkdir date-operations-mcp
cd date-operations-mcp

# Copy all the artifact files into the project:
# - package.json
# - tsconfig.json
# - src/index.ts
# - src/dateCalculations.ts
# - src/bankHolidays.ts
# - src/asanaHelpers.ts

# Install dependencies
npm install

# Build the project
npm run build
```

## Configuration for Claude Desktop

Add this to your Claude Desktop config file:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "date-operations": {
      "command": "node",
      "args": ["/absolute/path/to/date-operations-mcp/build/index.js"]
    }
  }
}
```

Replace `/absolute/path/to/date-operations-mcp` with your actual project path.

## Restart Claude Desktop

After updating the config file, restart Claude Desktop completely for the MCP server to load.

## Available Tools

### Basic Date Operations

**`get_today_uk`**
- Get current date in UK timezone
- No parameters required

**`get_next_working_day`**
- Get next working day after a given date
- Parameters: `from_date` (ISO format or "today")

**`calculate_working_days`**
- Add or subtract working days from a date
- Parameters: `start_date`, `num_days`, `direction` (forward/backward)

**`get_working_days_between`**
- Count working days between two dates
- Parameters: `start_date`, `end_date`

### UK Bank Holidays

**`is_uk_bank_holiday`**
- Check if a date is a UK bank holiday
- Parameters: `date`

**`get_upcoming_bank_holidays`**
- Get list of upcoming UK bank holidays
- Parameters: `months_ahead` (optional, default: 6)

### Sprint Planning

**`calculate_sprint_dates`**
- Calculate sprint start and end dates
- Parameters: `start_date`, `sprint_length_weeks`

**`get_current_sprint_info`**
- Get current sprint number and remaining days
- Parameters: `first_sprint_start`, `sprint_length_weeks`

### Asana Helpers

**`get_asana_due_date`**
- Get Asana due date following James's rules
- Parameters: `from_date` (optional, defaults to today)
- Returns next working day at 4:00 PM (Friday → Monday)

**`parse_asana_date_request`**
- Parse natural language requests
- Parameters: `request` (e.g., "tomorrow", "in 5 days", "in 2 weeks")
- Returns appropriate Asana due date

## Example Usage

Once configured, Claude will automatically use these tools when you ask date-related questions:

```
You: "What's 5 working days from today?"
Claude: [Uses calculate_working_days tool] That's Wednesday, October 29, 2025

You: "Create an Asana reminder for next week"
Claude: [Uses parse_asana_date_request tool] Setting due date to Monday, October 27, 2025 at 4:00 PM

You: "When do we finish the current sprint?"
Claude: [Uses get_current_sprint_info tool] Current sprint ends Friday, October 31, 2025
```

## Technical Details

- **Language**: TypeScript
- **Runtime**: Node.js
- **Date Library**: date-fns with timezone support
- **UK Holidays**: GOV.UK official API (cached for 24 hours)
- **Timezone**: Europe/London (handles GMT/BST automatically)

## Troubleshooting

**Server not showing up in Claude:**
1. Check the absolute path in your config file
2. Ensure `npm run build` completed successfully
3. Restart Claude Desktop completely
4. Check Claude Desktop logs for errors

**Date calculations seem wrong:**
1. Verify UK bank holiday API is accessible
2. Check your system timezone settings
3. Use `get_today_uk` tool to verify current date

## Testing

You can test the server before integrating with Claude:

```bash
# Run the built server directly
node build/index.js

# It should output: "Date Operations MCP Server running on stdio"
```

## Notes

- Bank holiday data is cached for 24 hours to reduce API calls
- All dates use UK timezone (Europe/London) with automatic GMT/BST handling
- Friday tasks automatically roll to Monday per James's Asana rules
- Working days exclude weekends AND UK bank holidays

---

## 📚 Want to Build Tools Like This?

This tool was built using the process documented in **["The Business Analyst's Guide to AI-Assisted Tool Development"](https://gumroad.com/l/ba-ai-tools)**.

Learn how to:
- Identify workflows worth automating
- Work effectively with AI as a collaborator
- Build production-ready tools without being a developer
- Avoid common pitfalls and mistakes

**£5 • Real code • Real examples • Real process**

**Get the guide:** https://murrelljames.gumroad.com/l/pvfww

**Repository:** https://github.com/cs97jjm3/ba-ai-tools-guide