mcp-zero/README.md

307 lines
6.4 KiB
Markdown
Raw Permalink Normal View History

# MCP Time Server
2025-08-16 13:23:45 +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** - 让时间处理变得简单而强大! 🚀