mclocks-datetime-util 0.0.2 → 0.0.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +132 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,132 @@
|
|
|
1
|
+
# mclocks-datetime-util
|
|
2
|
+
|
|
3
|
+
An MCP (Model Context Protocol) server that gives AI assistants the ability to answer time/date questions across multiple timezones. It converts between datetime formats and epoch timestamps, calculates days between dates or days until a target date, supports flexible locale settings for weekday names in multiple languages, and integrates with the [mclocks](https://github.com/bayashi/mclocks) desktop clock app configuration.
|
|
4
|
+
|
|
5
|
+
## Features
|
|
6
|
+
|
|
7
|
+
7 tools for datetime operations:
|
|
8
|
+
|
|
9
|
+
| Tool | Description |
|
|
10
|
+
|------|-------------|
|
|
11
|
+
| **`current-time`** | Get the current time in your configured timezones |
|
|
12
|
+
| **`convert-time`** | Convert a datetime string or epoch timestamp to multiple timezones |
|
|
13
|
+
| **`next-weekday`** | Find the date of the next occurrence of a given weekday |
|
|
14
|
+
| **`date-to-weekday`** | Get the day of the week for a given date |
|
|
15
|
+
| **`days-until`** | Count the number of days from today until a specified date |
|
|
16
|
+
| **`days-between`** | Count the number of days between two dates |
|
|
17
|
+
| **`date-offset`** | Calculate the date N days before or after a given date |
|
|
18
|
+
|
|
19
|
+
### Highlights
|
|
20
|
+
|
|
21
|
+
- **Zero configuration** — works out of the box with sensible timezone defaults
|
|
22
|
+
- **mclocks integration** — automatically reads your mclocks `config.json` so the timezones you've set up are reflected in AI responses
|
|
23
|
+
- **Epoch conversion** — supports seconds, milliseconds, microseconds, and nanoseconds
|
|
24
|
+
- **Flexible input** — accepts ISO 8601, common date formats (e.g. `March 15, 2026`), and BigQuery-style datetime (`2024-01-01 12:00:00 UTC`)
|
|
25
|
+
- **Locale support** — weekday names in multiple languages via the `locale` setting
|
|
26
|
+
|
|
27
|
+
## Prerequisites
|
|
28
|
+
|
|
29
|
+
- [Node.js](https://nodejs.org/) v18 or later
|
|
30
|
+
|
|
31
|
+
## Setup
|
|
32
|
+
|
|
33
|
+
Add the following to your MCP configuration file and restart the application. The MCP server will be automatically downloaded and started.
|
|
34
|
+
|
|
35
|
+
- **Cursor**: `.cursor/mcp.json` in your project root, or global `~/.cursor/mcp.json`
|
|
36
|
+
- **Claude Desktop** (`claude_desktop_config.json`): [Windows] `%APPDATA%\Claude\`, [macOS] `~/Library/Application Support/Claude/`, [Linux] `~/.config/Claude/`
|
|
37
|
+
|
|
38
|
+
```json
|
|
39
|
+
{
|
|
40
|
+
"mcpServers": {
|
|
41
|
+
"mclocks-datetime-util": {
|
|
42
|
+
"command": "npx",
|
|
43
|
+
"args": ["-y", "mclocks-datetime-util"]
|
|
44
|
+
}
|
|
45
|
+
}
|
|
46
|
+
}
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
## Configuration
|
|
50
|
+
|
|
51
|
+
### Automatic mclocks config detection
|
|
52
|
+
|
|
53
|
+
If you use the [mclocks](https://github.com/bayashi/mclocks) desktop app, the MCP server automatically reads your `config.json` and uses:
|
|
54
|
+
|
|
55
|
+
- **`clocks`** — Timezones from your clocks become default conversion targets
|
|
56
|
+
- **`convtz`** — Default source timezone for datetime strings without timezone info
|
|
57
|
+
- **`usetz`** — Controls strict timezone conversion mode
|
|
58
|
+
- **`locale`** — Language for weekday names (e.g. `ja`, `pt`, `de`)
|
|
59
|
+
|
|
60
|
+
Config file locations:
|
|
61
|
+
|
|
62
|
+
- Windows: `C:\Users\{USER}\AppData\Roaming\com.bayashi.mclocks\config.json`
|
|
63
|
+
- macOS: `/Users/{USER}/Library/Application Support/com.bayashi.mclocks/config.json`
|
|
64
|
+
|
|
65
|
+
### Without mclocks
|
|
66
|
+
|
|
67
|
+
The server works perfectly fine without the mclocks app. When no config is found, it uses these default timezones:
|
|
68
|
+
|
|
69
|
+
`UTC`, `America/New_York`, `America/Los_Angeles`, `Europe/London`, `Europe/Berlin`, `Asia/Tokyo`, `Asia/Shanghai`, `Asia/Kolkata`, `Australia/Sydney`
|
|
70
|
+
|
|
71
|
+
### Environment variables
|
|
72
|
+
|
|
73
|
+
Override config settings (or configure without `config.json`) using environment variables. They take priority over `config.json` values.
|
|
74
|
+
|
|
75
|
+
| Variable | Description | Default |
|
|
76
|
+
|---|---|---|
|
|
77
|
+
| `MCLOCKS_CONFIG_PATH` | Path to `config.json` (usually auto-detected) | auto-detect |
|
|
78
|
+
| `MCLOCKS_LOCALE` | Locale for weekday names (e.g. `ja`, `pt`, `de`) | `en` |
|
|
79
|
+
| `MCLOCKS_CONVTZ` | Default source timezone (e.g. `Asia/Tokyo`) | *(none)* |
|
|
80
|
+
| `MCLOCKS_USETZ` | Set to `true` for strict timezone conversion | `false` |
|
|
81
|
+
|
|
82
|
+
Example with environment variables:
|
|
83
|
+
|
|
84
|
+
```json
|
|
85
|
+
{
|
|
86
|
+
"mcpServers": {
|
|
87
|
+
"mclocks-datetime-util": {
|
|
88
|
+
"command": "npx",
|
|
89
|
+
"args": ["-y", "mclocks-datetime-util"],
|
|
90
|
+
"env": {
|
|
91
|
+
"MCLOCKS_LOCALE": "ja",
|
|
92
|
+
"MCLOCKS_CONVTZ": "Asia/Tokyo"
|
|
93
|
+
}
|
|
94
|
+
}
|
|
95
|
+
}
|
|
96
|
+
}
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
You can also specify a custom config path via the `--config` CLI flag:
|
|
100
|
+
|
|
101
|
+
```json
|
|
102
|
+
{
|
|
103
|
+
"mcpServers": {
|
|
104
|
+
"mclocks-datetime-util": {
|
|
105
|
+
"command": "npx",
|
|
106
|
+
"args": ["-y", "mclocks-datetime-util", "--config", "/path/to/config.json"]
|
|
107
|
+
}
|
|
108
|
+
}
|
|
109
|
+
}
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
## Example usage
|
|
113
|
+
|
|
114
|
+
Once configured, you can ask your AI assistant:
|
|
115
|
+
|
|
116
|
+
- "What time is it now?"
|
|
117
|
+
- "What time is it in Jakarta?"
|
|
118
|
+
- "Convert 1705312200 epoch to datetime"
|
|
119
|
+
- "Convert 2024-01-15T10:30:00Z to Asia/Tokyo"
|
|
120
|
+
- "Next Friday is what date?"
|
|
121
|
+
- "What day of the week is 2026-12-25?"
|
|
122
|
+
- "How many days until Christmas?"
|
|
123
|
+
- "How many days between 2026-01-01 and 2026-12-31?"
|
|
124
|
+
- "What date is 90 days from 2026-04-01?"
|
|
125
|
+
|
|
126
|
+
## License
|
|
127
|
+
|
|
128
|
+
[The Artistic License 2.0](https://github.com/bayashi/mclocks/blob/main/LICENSE)
|
|
129
|
+
|
|
130
|
+
## Author
|
|
131
|
+
|
|
132
|
+
Dai Okabayashi: https://github.com/bayashi
|