## Date Operations MCP

Lightweight Model Context Protocol (MCP) server exposing common date/time operations powered by `date-fns`. Built on `fastmcp` with an HTTP stream transport.

### Features

- **now**: Current timestamp in ISO 8601
- **format**: Format a date using Unicode tokens (UTS #35)
- **add / subtract**: Add or subtract a duration from a date
- **difference**: Compute difference between two dates in a chosen unit
- **check**: Compare two dates (after, before, equal)

### Requirements

- Node.js 18+ (or 20+ recommended)

### Install

```bash
npm install
```

### Run (dev)

```bash
npm run dev
# Server listens on http://localhost:3000 (HTTP stream)
```

### Build & Run (prod)

```bash
npm run build
npm start
# Outputs to dist/ and runs Node on dist/index.js
```

### Client integration (MCP over HTTP stream)

This server uses `fastmcp` with `transportType: "httpStream"` on port `3000`. Point your MCP-capable client at `http://localhost:3000`.

- Claude Desktop / Cursor: Configure an MCP HTTP server pointing to `http://localhost:3000`. Refer to your client's MCP HTTP configuration docs and set the URL accordingly.

> Note: The server exposes an HTTP stream suitable for MCP-aware clients. It is not a conventional REST API.

### Tools

#### now

- **Description**: Get the current date/time.
- **Parameters**: none
- **Returns**: ISO 8601 string

Example result:

```json
"2025-01-01T12:34:56.789Z"
```

#### format

- **Description**: Format a date.
- **Parameters**:
  - `date` (string, ISO 8601)
  - `format` (string, Unicode tokens per date-fns v4)
- **Returns**: formatted string

Example call payload (conceptual):

```json
{
  "date": "2025-01-01T00:00:00.000Z",
  "format": "yyyy-MM-dd'T'HH:mm:ssXXX"
}
```

#### add

- **Description**: Add a duration to a date.
- **Parameters**:
  - `date` (string, ISO 8601)
  - `duration` (object) — all numeric fields are required; pass `0` if unused
    - `years`, `months`, `weeks`, `days`, `hours`, `minutes`, `seconds`
- **Returns**: ISO 8601 string (result date)

Example:

```json
{
  "date": "2025-01-01T00:00:00.000Z",
  "duration": {
    "years": 0,
    "months": 1,
    "weeks": 0,
    "days": 2,
    "hours": 0,
    "minutes": 30,
    "seconds": 0
  }
}
```

#### subtract

- **Description**: Subtract a duration from a date.
- **Parameters**: same shape as `add`
- **Returns**: ISO 8601 string (result date)

#### difference

- **Description**: Difference between two dates in a given unit.
- **Parameters**:
  - `dateFrom` (string, ISO 8601)
  - `dateTo` (string, ISO 8601)
  - `unit` (enum): `seconds | minutes | hours | days | weeks | months | years`
- **Returns**: human-readable string with the numeric difference and unit

Example:

```json
{
  "dateFrom": "2025-01-01T00:00:00.000Z",
  "dateTo": "2025-02-01T00:00:00.000Z",
  "unit": "days"
}
```

#### check

- **Description**: Compare two dates.
- **Parameters**:
  - `firstDate` (string, ISO 8601)
  - `secondDate` (string, ISO 8601)
  - `operator` (enum): `after | before | equal`
- **Returns**: human-readable string indicating the boolean result

Example:

```json
{
  "firstDate": "2025-01-02T00:00:00.000Z",
  "secondDate": "2025-01-01T00:00:00.000Z",
  "operator": "after"
}
```

### Notes and assumptions

- Dates are expected as ISO 8601 strings (UTC recommended).
- `format` uses Unicode tokens (UTS #35) as in date-fns v4.
- For `add`/`subtract`, provide all duration fields; use `0` when not needed.

### Project scripts

- **dev**: `tsx index.ts`
- **build**: `tsc` → emits `dist/`
- **start**: `node dist/index.js`
- **test**: `vitest --coverage`

### License

MIT © Denny Pradipta