2025-08-17 00:39:43 +08:00
|
|
|
|
# MCP Time Server
|
2025-08-16 13:23:45 +08:00
|
|
|
|
|
2025-08-17 00:39:43 +08:00
|
|
|
|
一个基于 Model Context Protocol (MCP) 的时间工具服务器,提供丰富的时间相关功能。
|
|
|
|
|
|
|
|
|
|
## 功能特性
|
|
|
|
|
|
|
|
|
|
### 时间工具
|
|
|
|
|
- **getCurrentTime**: 获取当前时间,支持多种时区和格式
|
|
|
|
|
- **getTimezone**: 获取时区信息,包括偏移量、缩写等
|
|
|
|
|
- **formatTime**: 格式化时间,支持多种格式和语言环境
|
|
|
|
|
- **calculateDateDifference**: 计算两个日期之间的差值
|
|
|
|
|
- **getWorldClock**: 获取多个时区的世界时钟
|
|
|
|
|
|
|
|
|
|
### 支持的时区
|
|
|
|
|
- 全球主要时区(如 Asia/Shanghai, America/New_York, Europe/London 等)
|
|
|
|
|
- UTC 和本地时区
|
|
|
|
|
- 自动夏令时检测
|
|
|
|
|
|
|
|
|
|
### 支持的格式
|
|
|
|
|
- ISO 8601 格式
|
|
|
|
|
- Unix 时间戳
|
|
|
|
|
- 本地化格式
|
|
|
|
|
- 自定义格式
|
|
|
|
|
|
|
|
|
|
## 安装和运行
|
|
|
|
|
|
|
|
|
|
### 安装依赖
|
|
|
|
|
```bash
|
|
|
|
|
npm install
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### 运行服务器
|
|
|
|
|
```bash
|
|
|
|
|
npm start
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### 运行测试
|
|
|
|
|
```bash
|
|
|
|
|
npm test
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### 代码检查
|
|
|
|
|
```bash
|
|
|
|
|
npm run lint
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## 项目结构
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
src/
|
|
|
|
|
├── index.js # MCP 服务器入口
|
|
|
|
|
├── tools/
|
|
|
|
|
│ ├── index.js # 工具导出
|
|
|
|
|
│ ├── current-time.js # 当前时间工具
|
|
|
|
|
│ ├── timezone.js # 时区信息工具
|
|
|
|
|
│ ├── format-time.js # 时间格式化工具
|
|
|
|
|
│ ├── date-calculator.js # 日期计算工具
|
|
|
|
|
│ └── world-clock.js # 世界时钟工具
|
|
|
|
|
tests/
|
|
|
|
|
└── time-tools.test.js # 测试文件
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## 使用示例
|
|
|
|
|
|
|
|
|
|
### 获取当前时间
|
|
|
|
|
```javascript
|
|
|
|
|
// 获取 UTC 时间
|
|
|
|
|
getCurrentTime({ timezone: 'UTC', format: 'iso' })
|
|
|
|
|
|
|
|
|
|
// 获取上海时间
|
|
|
|
|
getCurrentTime({ timezone: 'Asia/Shanghai', format: 'locale' })
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### 获取时区信息
|
|
|
|
|
```javascript
|
|
|
|
|
// 获取时区详细信息
|
|
|
|
|
getTimezone({ timezone: 'Asia/Shanghai' })
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### 格式化时间
|
|
|
|
|
```javascript
|
|
|
|
|
// 格式化时间
|
|
|
|
|
formatTime({
|
|
|
|
|
time: '2024-01-01T12:00:00Z',
|
|
|
|
|
format: 'custom',
|
|
|
|
|
customFormat: 'YYYY-MM-DD HH:mm:ss',
|
|
|
|
|
timezone: 'Asia/Shanghai'
|
|
|
|
|
})
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### 计算日期差值
|
|
|
|
|
```javascript
|
|
|
|
|
// 计算两个日期的差值
|
|
|
|
|
calculateDateDifference({
|
|
|
|
|
startDate: '2024-01-01',
|
|
|
|
|
endDate: '2024-12-31',
|
|
|
|
|
unit: 'days'
|
|
|
|
|
})
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### 获取世界时钟
|
|
|
|
|
```javascript
|
|
|
|
|
// 获取多个时区的时间
|
|
|
|
|
getWorldClock({
|
|
|
|
|
timezones: ['UTC', 'Asia/Shanghai', 'America/New_York'],
|
|
|
|
|
format: 'locale'
|
|
|
|
|
})
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## 技术栈
|
|
|
|
|
|
|
|
|
|
- **Node.js**: 运行时环境
|
|
|
|
|
- **MCP SDK**: Model Context Protocol 支持
|
|
|
|
|
- **Zod**: 参数验证
|
|
|
|
|
- **Vitest**: 测试框架
|
|
|
|
|
- **ESLint**: 代码检查
|
|
|
|
|
|
|
|
|
|
## 开发
|
|
|
|
|
|
|
|
|
|
### 添加新工具
|
|
|
|
|
1. 在 `src/tools/` 目录下创建新的工具文件
|
|
|
|
|
2. 实现工具的 `name`、`description`、`inputSchema` 和 `handler`
|
|
|
|
|
3. 在 `src/tools/index.js` 中导出新工具
|
|
|
|
|
4. 添加相应的测试用例
|
|
|
|
|
|
|
|
|
|
### 代码规范
|
|
|
|
|
- 使用 ESLint 进行代码检查
|
|
|
|
|
- 遵循 JavaScript 标准代码风格
|
|
|
|
|
- 所有工具必须包含完整的参数验证
|
|
|
|
|
- 返回格式必须符合 MCP 协议规范
|
|
|
|
|
|
|
|
|
|
## 许可证
|
|
|
|
|
|
|
|
|
|
MIT License
|
|
|
|
|
|
|
|
|
|
## 工具详情
|
|
|
|
|
|
|
|
|
|
### getCurrentTime
|
|
|
|
|
|
|
|
|
|
获取当前时间,支持指定时区和格式。
|
|
|
|
|
|
|
|
|
|
**参数:**
|
|
|
|
|
- `timezone` (可选): 时区标识符,如 'UTC', 'America/New_York'
|
|
|
|
|
- `format` (可选): 输出格式 ('iso', 'timestamp', 'locale')
|
|
|
|
|
|
|
|
|
|
**示例:**
|
|
|
|
|
```json
|
|
|
|
|
{
|
|
|
|
|
"timezone": "Asia/Shanghai",
|
|
|
|
|
"format": "iso"
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### getTimezone
|
|
|
|
|
|
|
|
|
|
获取指定时区的详细信息。
|
|
|
|
|
|
|
|
|
|
**参数:**
|
|
|
|
|
- `timezone` (必需): 时区标识符
|
|
|
|
|
|
|
|
|
|
**示例:**
|
|
|
|
|
```json
|
|
|
|
|
{
|
|
|
|
|
"timezone": "Europe/London"
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### formatTime
|
|
|
|
|
|
|
|
|
|
将时间格式化为指定格式。
|
|
|
|
|
|
|
|
|
|
**参数:**
|
|
|
|
|
- `time` (必需): 要格式化的时间
|
|
|
|
|
- `format` (可选): 输出格式 ('iso', 'timestamp', 'locale', 'custom')
|
|
|
|
|
- `timezone` (可选): 目标时区
|
|
|
|
|
- `locale` (可选): 本地化设置
|
|
|
|
|
- `customFormat` (可选): 自定义格式字符串 (当format为custom时使用)
|
|
|
|
|
|
|
|
|
|
**示例:**
|
|
|
|
|
```json
|
|
|
|
|
{
|
|
|
|
|
"time": "2024-01-01T12:00:00Z",
|
|
|
|
|
"format": "locale",
|
|
|
|
|
"timezone": "Asia/Tokyo",
|
|
|
|
|
"locale": "ja-JP"
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### calculateDateDifference
|
|
|
|
|
|
|
|
|
|
计算两个日期之间的差值。
|
|
|
|
|
|
|
|
|
|
**参数:**
|
|
|
|
|
- `startDate` (必需): 开始日期
|
|
|
|
|
- `endDate` (必需): 结束日期
|
|
|
|
|
- `unit` (可选): 计算单位 ('years', 'months', 'days', 'hours', 'minutes', 'seconds', 'milliseconds')
|
|
|
|
|
- `includeTime` (可选): 是否包含时间部分
|
|
|
|
|
|
|
|
|
|
**示例:**
|
|
|
|
|
```json
|
|
|
|
|
{
|
|
|
|
|
"startDate": "2024-01-01",
|
|
|
|
|
"endDate": "2024-12-31",
|
|
|
|
|
"unit": "days"
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### getWorldClock
|
|
|
|
|
|
|
|
|
|
获取多个时区的当前时间。
|
|
|
|
|
|
|
|
|
|
**参数:**
|
|
|
|
|
- `timezones` (可选): 时区列表,默认为 ['UTC', 'Asia/Shanghai', 'America/New_York', 'Europe/London']
|
|
|
|
|
- `format` (可选): 时间格式 ('iso', 'locale', 'custom'),默认为 'locale'
|
|
|
|
|
- `customFormat` (可选): 自定义格式模板 (当format为custom时使用)
|
|
|
|
|
- `includeOffset` (可选): 是否包含UTC偏移量信息,默认为 true
|
|
|
|
|
|
|
|
|
|
**示例:**
|
|
|
|
|
```json
|
|
|
|
|
{
|
|
|
|
|
"timezones": ["UTC", "America/New_York", "Asia/Shanghai", "Europe/London"],
|
|
|
|
|
"format": "locale",
|
|
|
|
|
"includeOffset": true
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## 开发
|
|
|
|
|
|
|
|
|
|
### 项目结构
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
mcp-time-server/
|
|
|
|
|
├── src/
|
|
|
|
|
│ ├── index.js # 主服务器文件
|
|
|
|
|
│ ├── tools/ # 工具模块
|
|
|
|
|
│ │ ├── index.js # 工具导出
|
|
|
|
|
│ │ ├── current-time.js
|
|
|
|
|
│ │ ├── timezone.js
|
|
|
|
|
│ │ ├── format-time.js
|
|
|
|
|
│ │ ├── date-calculator.js
|
|
|
|
|
│ │ └── world-clock.js
|
|
|
|
|
│ └── utils/ # 工具函数 (预留)
|
|
|
|
|
├── tests/ # 测试文件
|
|
|
|
|
└── bin/ # 可执行文件
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### 运行测试
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
npm test
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### 代码检查
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
npm run lint
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### 代码格式化
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
npm run format
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## 技术栈
|
|
|
|
|
|
|
|
|
|
- **Node.js** - 运行时环境
|
|
|
|
|
- **@modelcontextprotocol/sdk** - MCP 协议支持
|
|
|
|
|
- **Zod** - 数据验证
|
|
|
|
|
- **Vitest** - 测试框架
|
|
|
|
|
- **ESLint** - 代码检查
|
|
|
|
|
- **Prettier** - 代码格式化
|
|
|
|
|
|
|
|
|
|
## 许可证
|
|
|
|
|
|
|
|
|
|
MIT License
|
|
|
|
|
|
|
|
|
|
## 贡献
|
|
|
|
|
|
|
|
|
|
欢迎提交 Issue 和 Pull Request!
|
|
|
|
|
|
|
|
|
|
### 开发指南
|
|
|
|
|
|
|
|
|
|
1. Fork 项目
|
|
|
|
|
2. 创建功能分支 (`git checkout -b feature/amazing-feature`)
|
|
|
|
|
3. 提交更改 (`git commit -m 'Add some amazing feature'`)
|
|
|
|
|
4. 推送到分支 (`git push origin feature/amazing-feature`)
|
|
|
|
|
5. 打开 Pull Request
|
|
|
|
|
|
|
|
|
|
### 代码规范
|
|
|
|
|
|
|
|
|
|
- 使用 ESLint 和 Prettier 保持代码风格一致
|
|
|
|
|
- 编写测试用例覆盖新功能
|
|
|
|
|
- 遵循现有的代码结构和命名约定
|
|
|
|
|
- 添加适当的错误处理和参数验证
|
|
|
|
|
|
|
|
|
|
## 支持
|
|
|
|
|
|
|
|
|
|
如果您遇到问题或有建议,请:
|
|
|
|
|
|
|
|
|
|
1. 查看现有的 [Issues](../../issues)
|
|
|
|
|
2. 创建新的 Issue 描述问题
|
|
|
|
|
3. 提供详细的错误信息和复现步骤
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
**MCP Time Server** - 让时间处理变得简单而强大! 🚀
|