mcp-zero/README.md
yangyudong 82e579e11b feat: 初始化MCP时间服务器项目
添加核心功能模块包括时间工具集、服务器实现和测试
配置项目基础设置如ESLint、Prettier和Vitest
实现时间相关功能包括当前时间、时区信息和日期计算
添加README文档说明项目功能和使用方法
2025-08-17 00:39:43 +08:00

307 lines
6.4 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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** - 让时间处理变得简单而强大! 🚀