🚀 TimezoneToolkit 中文文档

TimezoneToolkit 是一个强大的时间和时区工具包，借助 Model Context Protocol (MCP) 开发。它提供了丰富功能，能帮助用户轻松处理日期、时间、时区转换以及天文计算等任务。

🚀 快速开始

TimezoneToolkit 能让你便捷地进行时间和时区相关操作。你可以获取不同时区的当前时间、计算日出日落时间、进行时区转换等。

✨ 主要特性

• 多时区支持：内置全球主要时区信息
• 日期时间操作：包括时间加减、格式化等功能
• 天文计算：日出日落、潮汐等自然现象计算
• JSON RPC 支持：通过 MCP 协议与 Claude Desktop 集成

📦 安装指南

先决条件

• Node.js 18.x 或更高版本
• npm 9.x 或更高版本
• 最新版的 Claude Desktop

安装步骤

# 下载项目源码
git clone https://github.com/yourusername/timezone-toolkit.git

# 进入项目目录
cd timezone-toolkit

# 安装依赖项
npm install

# 启动 MCP 服务器
node dist/index.js

💻 使用示例

基础用法

# 获取当前时间，默认使用 UTC 时区
npm start -- --timeZone=UTC

# 转换为纽约时间
npm start -- --convertTo=America/New_York

📚 详细文档

功能模块

1. 时间显示

获取当前时间

{
  "currentTime": "2024年3月25日，晚上9:54",
  "timezone": "美洲/纽约",
  "utcOffset": "-04:00"
}

示例命令

• getCurrentTime：获取指定时区的当前时间
• listTimezones：列出所有可用时区

2. 日出日落计算

方法调用示例

{
  "latitude": 37.7749,
  "longitude": -122.4194,
  "date": "2024-03-25",
  "time": "06:00"
}

返回结果

{
  "sunrise": "早上6:05",
  "sunset": "晚上7:15",
  "moonPhase": "渐亏 gibbous"
}

3. 时区转换

支持的操作包括：

• 时间加减小时/分钟
• 转换为 UTC 时间
• 显示时区偏移量（如 +08:00）

🔧 技术细节

核心组件

• 核心服务：处理时区转换、天文计算和日期格式化
• MCP 服务器：接收来自 Claude Desktop 的 JSON RPC 请求
• 工具函数：提供日期时间操作的辅助功能
• 测试框架：全面测试 MCP 服务器的功能

技术依赖

• Luxon - 处理所有日期/时间操作和时区管理
• SunCalc - 用于日出、日落等天文计算
• @modelcontextprotocol/sdk - 用于 MCP 服务器实现

🤝 贡献指南

欢迎贡献！请按照以下步骤提交代码：

1. 叉取仓库
2. 创建功能分支（例如 feature/amazing-feature）
3. 提交更改（例如 git commit -m '添加精彩功能'）
4. 推送到分支（例如 git push origin feature/amazing-feature）
5. 提交拉取请求

🧪 测试方法

基本测试命令

# 执行单元测试
npm test

# 运行端到端测试
npm run e2e

详细说明

• 测试覆盖率：确保达到要求的覆盖范围
• 集成测试：验证各模块协同工作
• 性能测试：评估处理速度和稳定性

⚠️ 故障排除

常见问题及解决方案：

1. 安装依赖失败

• 检查网络连接
• 确认 Node.js 版本符合要求
• 重新运行 npm install

2. 启动服务器报错

• 查看错误日志
• 确保所有依赖已正确安装

3. 无法与 Claude 集成

• 检查 MCP 协议版本
• 确认端口配置正确

🔒 隐私安全

• 数据保护：遵循 GDPR 和 CCPA 规定
• 代码审计：定期进行安全审查
• 用户隐私：严格保护用户数据不被滥用

📄 许可证

Apache 2.0 许可证

...

📞 联系方式

如有任何问题或建议，请联系：

• 邮箱: support@timezone-toolkit.com
• GitHub: https://github.com/timezone-toolkit