mcp-zero/README.md

MCP Time Server

一个基于 Model Context Protocol (MCP) 的时间工具服务器，提供丰富的时间相关功能。

功能特性

时间工具

• getCurrentTime: 获取当前时间，支持多种时区和格式
• getTimezone: 获取时区信息，包括偏移量、缩写等
• formatTime: 格式化时间，支持多种格式和语言环境
• calculateDateDifference: 计算两个日期之间的差值
• getWorldClock: 获取多个时区的世界时钟

支持的时区

• 全球主要时区（如 Asia/Shanghai, America/New_York, Europe/London 等）
• UTC 和本地时区
• 自动夏令时检测

支持的格式

• ISO 8601 格式
• Unix 时间戳
• 本地化格式
• 自定义格式

安装和运行

安装依赖

npm install

运行服务器

npm start

运行测试

npm test

代码检查

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    # 测试文件

使用示例

获取当前时间

// 获取 UTC 时间
getCurrentTime({ timezone: 'UTC', format: 'iso' })

// 获取上海时间
getCurrentTime({ timezone: 'Asia/Shanghai', format: 'locale' })

获取时区信息

// 获取时区详细信息
getTimezone({ timezone: 'Asia/Shanghai' })

格式化时间

// 格式化时间
formatTime({ 
  time: '2024-01-01T12:00:00Z', 
  format: 'custom',
  customFormat: 'YYYY-MM-DD HH:mm:ss',
  timezone: 'Asia/Shanghai'
})

计算日期差值

// 计算两个日期的差值
calculateDateDifference({
  startDate: '2024-01-01',
  endDate: '2024-12-31',
  unit: 'days'
})

获取世界时钟

// 获取多个时区的时间
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')

示例：

{
  "timezone": "Asia/Shanghai",
  "format": "iso"
}

getTimezone

获取指定时区的详细信息。

参数：

• timezone (必需): 时区标识符

示例：

{
  "timezone": "Europe/London"
}

formatTime

将时间格式化为指定格式。

参数：

• time (必需): 要格式化的时间
• format (可选): 输出格式 ('iso', 'timestamp', 'locale', 'custom')
• timezone (可选): 目标时区
• locale (可选): 本地化设置
• customFormat (可选): 自定义格式字符串 (当format为custom时使用)

示例：

{
  "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 (可选): 是否包含时间部分

示例：

{
  "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

示例：

{
  "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/                  # 可执行文件

运行测试

npm test

代码检查

npm run lint

代码格式化

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
2. 创建新的 Issue 描述问题
3. 提供详细的错误信息和复现步骤

---

MCP Time Server - 让时间处理变得简单而强大！ 🚀