添加核心功能模块包括时间工具集、服务器实现和测试 配置项目基础设置如ESLint、Prettier和Vitest 实现时间相关功能包括当前时间、时区信息和日期计算 添加README文档说明项目功能和使用方法
307 lines
6.4 KiB
Markdown
307 lines
6.4 KiB
Markdown
# MCP Time Server
|
||
|
||
一个基于 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** - 让时间处理变得简单而强大! 🚀 |