README.md•3.65 kB
## 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