time-converter-mcp

v1.0.0

Published

16 days ago

时间格式转换MCP服务器 - 支持字符串与时间戳的双向转换，默认使用北京时区

0High
0Medium
0Low

storv

mcp model-context-protocol time timestamp converter datetime beijing-time utc+8 time-format mcp-server

时间转换MCP服务器 (Time Converter MCP Server)

一个基于Node.js的MCP (Model Context Protocol) 服务器，专门用于时间格式转换功能。支持字符串格式(YYYY-MM-DD HH:mm:ss)与时间戳(毫秒)的双向转换，默认使用北京时区(UTC+8)。

✨ 主要特性

🕒 双向时间转换: 字符串格式 ⇄ 时间戳(毫秒)
🌏 北京时区支持: 默认使用UTC+8时区
🔒 双重校验机制: 确保转换准确性和数据完整性
🛡️ 完整错误处理: 详细的错误信息和输入验证
📦 即开即用: 支持npx直接安装和启动
🔌 MCP标准协议: 完全兼容Model Context Protocol

🚀 快速开始

安装和启动

# 直接使用npx启动(推荐)
npx time-converter-mcp

# 或者全局安装后使用
npm install -g time-converter-mcp
time-converter-mcp

查看帮助信息

npx time-converter-mcp --help

查看版本信息

npx time-converter-mcp --version

🛠️ 支持的工具

1. string_to_timestamp

将时间字符串转换为时间戳(毫秒)

输入参数:

timeString (string): 时间字符串，格式为 YYYY-MM-DD HH:mm:ss

输出:

timestamp (number): 对应的时间戳(毫秒)
timezone: 时区信息(Asia/Shanghai UTC+8)

示例:

{
  "name": "string_to_timestamp",
  "arguments": {
    "timeString": "2025-12-03 14:30:00"
  }
}

2. timestamp_to_string

将时间戳(毫秒)转换为时间字符串

输入参数:

timestamp (number): 时间戳(毫秒)

输出:

timeString (string): 格式化的时间字符串 YYYY-MM-DD HH:mm:ss
timezone: 时区信息(Asia/Shanghai UTC+8)

示例:

{
  "name": "timestamp_to_string",
  "arguments": {
    "timestamp": 1733205000000
  }
}

📋 系统要求

Node.js: >= 14.0.0
操作系统: macOS, Linux, Windows
架构: x64, arm64

🔧 MCP客户端配置

📋 完整安装和配置流程

第一步：在MCP客户端中配置服务器

根据你使用的MCP客户端，选择对应的配置方法：

Claude Desktop配置

macOS配置文件位置: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows配置文件位置: %APPDATA%\Claude\claude_desktop_config.json

Linux配置文件位置: ~/.config/Claude/claude_desktop_config.json

在配置文件中添加以下内容：

{
  "mcpServers": {
    "time-converter": {
      "command": "npx",
      "args": [
        "-y",
        "time-converter-mcp"
      ]
    }
  }
}

配置说明:

time-converter: 服务器名称，可以自定义
command: 使用npx命令启动
args: 参数数组
- -y: 自动确认安装，避免交互式提示
- time-converter-mcp: 我们的包名

其他MCP客户端配置

对于其他支持MCP协议的客户端，使用以下通用配置：

{
  "mcpServers": {
    "time-converter": {
      "command": "npx",
      "args": ["-y", "time-converter-mcp"]
    }
  }
}

或者直接使用启动命令：

npx -y time-converter-mcp

第二步：重启MCP客户端

配置完成后，需要重启客户端使配置生效：

Claude Desktop: 完全退出应用程序，然后重新启动
其他客户端: 按照对应客户端的重启方法操作

第三步：验证连接和使用

重启客户端后，你可以：

检查连接状态: 在客户端中查看MCP服务器连接状态
测试工具功能: 尝试使用时间转换工具
查看可用工具: 确认string_to_timestamp和timestamp_to_string工具可用

🔧 高级配置选项

使用本地安装版本

如果你已经全局安装了包，可以使用以下配置：

{
  "mcpServers": {
    "time-converter": {
      "command": "time-converter-mcp"
    }
  }
}

指定Node.js版本

如果需要使用特定的Node.js版本：

{
  "mcpServers": {
    "time-converter": {
      "command": "node",
      "args": [
        "--version", ">=14.0.0",
        "npx", "-y", "time-converter-mcp"
      ]
    }
  }
}

开发环境配置

对于开发和调试，可以使用本地路径：

{
  "mcpServers": {
    "time-converter-dev": {
      "command": "node",
      "args": ["/path/to/time-converter-mcp/index.js"],
      "cwd": "/path/to/time-converter-mcp"
    }
  }
}

🚨 故障排除

常见问题和解决方案

1. 服务器连接失败

问题: MCP客户端显示连接失败或服务器无响应

可能原因和解决方案:

网络问题: 检查网络连接，确保可以访问npm registry
Node.js版本: 确保Node.js版本 >= 14.0.0
```
node --version
```
npx权限: 确保npx有执行权限
```
npm config get prefix
npx --version
```

2. 包安装失败

问题: npx无法下载或安装time-converter-mcp包

解决方案:

# 清理npm缓存
npm cache clean --force

# 手动安装包
npm install -g time-converter-mcp

# 使用本地安装的版本
time-converter-mcp

3. 配置文件格式错误

问题: JSON配置文件格式不正确

解决方案:

使用JSON验证工具检查配置文件语法
确保所有字符串都用双引号包围
检查括号和逗号是否正确匹配

正确的配置示例:

{
  "mcpServers": {
    "time-converter": {
      "command": "npx",
      "args": ["-y", "time-converter-mcp"]
    }
  }
}

4. 工具无法使用

问题: 连接成功但无法调用时间转换工具

检查步骤:

确认服务器状态为"已连接"
检查工具列表中是否包含我们的工具
验证工具调用参数格式

测试命令:

{
  "name": "string_to_timestamp",
  "arguments": {
    "timeString": "2025-12-03 14:30:00"
  }
}

5. 权限问题

问题: 在某些系统上可能遇到权限问题

解决方案:

# macOS/Linux: 使用sudo安装全局包
sudo npm install -g time-converter-mcp

# Windows: 以管理员身份运行命令提示符
# 然后执行安装命令

验证安装

使用以下步骤验证MCP服务器是否正确安装和配置：

检查包是否可用:
```
npx time-converter-mcp --version
```
测试服务器启动:
```
npx time-converter-mcp --help
```
验证MCP协议:
- 启动MCP客户端
- 查看连接状态
- 测试工具调用

日志和调试

如果遇到问题，可以：

查看客户端日志: 大多数MCP客户端都有日志功能
手动测试服务器: 直接运行npx time-converter-mcp检查输出
检查网络连接: 确保可以访问npm registry

获取帮助

如果以上方法都无法解决问题：

查看项目的Issues页面
创建新的Issue，包含：
- 操作系统和版本
- Node.js版本
- MCP客户端类型和版本
- 完整的错误信息
- 配置文件内容

📱 客户端兼容性

| MCP客户端 | 支持状态 | 配置方式 | 备注 | |----------|----------|----------|------| | Claude Desktop | ✅ 完全支持 | JSON配置文件 | 推荐使用 | | Continue.dev | ✅ 支持 | 配置文件 | 需要MCP插件 | | 自定义MCP客户端 | ✅ 支持 | 标准MCP协议 | 遵循MCP规范 |

🔄 配置更新

当time-converter-mcp包更新时：

自动更新: npx会自动使用最新版本
手动更新:
```
npm update -g time-converter-mcp
```

版本锁定: 如需使用特定版本

{
  "mcpServers": {
    "time-converter": {
      "command": "npx",
      "args": ["-y", "[email protected]"]
    }
  }
}

📖 使用示例

示例1: 时间字符串转时间戳

输入:

{
  "method": "tools/call",
  "params": {
    "name": "string_to_timestamp",
    "arguments": {
      "timeString": "2025-12-03 14:30:00"
    }
  }
}

输出:

{
  "content": [
    {
      "type": "text",
      "text": "时间转换成功！\n输入时间: 2025-12-03 14:30:00\n转换结果: 1733205000000\n时区: 北京时间(UTC+8)"
    }
  ],
  "result": {
    "timeString": "2025-12-03 14:30:00",
    "timestamp": 1733205000000,
    "timezone": "Asia/Shanghai (UTC+8)"
  }
}

示例2: 时间戳转时间字符串

输入:

{
  "method": "tools/call",
  "params": {
    "name": "timestamp_to_string",
    "arguments": {
      "timestamp": 1733205000000
    }
  }
}

输出:

{
  "content": [
    {
      "type": "text",
      "text": "时间转换成功！\n输入时间戳: 1733205000000\n转换结果: 2025-12-03 14:30:00\n时区: 北京时间(UTC+8)"
    }
  ],
  "result": {
    "timestamp": 1733205000000,
    "timeString": "2025-12-03 14:30:00",
    "timezone": "Asia/Shanghai (UTC+8)"
  }
}

🔍 错误处理

服务器提供详细的错误信息，帮助快速定位问题：

常见错误类型

格式错误: 时间字符串格式不正确

{
  "error": {
    "code": -32602,
    "message": "时间格式无效，请使用 YYYY-MM-DD HH:mm:ss 格式"
  }
}

数值错误: 时间戳不是有效数字

{
  "error": {
    "code": -32602,
    "message": "时间戳无效，必须是有效的数字"
  }
}

日期无效: 不存在的日期(如2月30日)

{
  "error": {
    "code": -32602,
    "message": "日期时间无效(可能是不存在的日期，如2月30日)"
  }
}

🏗️ 项目结构

time-converter-mcp/
├── package.json          # 项目配置文件
├── README.md             # 项目说明文档
├── index.js              # 主入口文件
└── src/
    ├── server.js         # MCP服务器实现
    └── timeUtils.js      # 时间转换工具函数

🔒 安全特性

输入验证: 严格验证所有输入参数
类型检查: 确保参数类型正确性
范围检查: 验证时间戳和日期的有效范围
双重校验: 转换后进行反向验证确保准确性
错误隔离: 完善的错误处理机制

🧪 测试

# 运行测试(如果有测试文件)
npm test

# 手动测试服务器启动
npm start

📝 开发

本地开发

# 克隆项目
git clone https://github.com/joycode/time-converter-mcp.git
cd time-converter-mcp

# 安装依赖(如果有)
npm install

# 启动开发服务器
npm run dev

代码结构

timeUtils.js: 核心时间转换逻辑，包含双重校验机制
server.js: MCP协议实现，处理客户端请求
index.js: 入口文件，命令行参数处理和服务器启动

🤝 贡献

欢迎提交Issue和Pull Request来改进这个项目！

贡献指南

Fork 这个仓库
创建你的特性分支 (git checkout -b feature/AmazingFeature)
提交你的更改 (git commit -m 'Add some AmazingFeature')
推送到分支 (git push origin feature/AmazingFeature)
打开一个 Pull Request

📄 许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。

🆘 支持

如果你遇到任何问题或有疑问，请：

查看本README文档
检查 Issues 页面
创建新的Issue描述你的问题

📦 npm发布指南

详细的npm发布流程请参考：npm发布指南

快速发布

# 1. 登录npm账户
npm login

# 2. 运行测试
npm test

# 3. 更新版本并发布
npm run publish-patch  # 发布修订版本
npm run publish-minor  # 发布次版本
npm run publish-major  # 发布主版本

发布前检查

✅ 所有测试通过
✅ 代码已提交到Git
✅ 版本号符合语义化版本规范
✅ README.md文档已更新

� 相关资源

注意: 所有时间转换都基于北京时区(UTC+8)，转换过程包含双重校验机制确保准确性。

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

时间转换MCP服务器 (Time Converter MCP Server)

✨ 主要特性

🚀 快速开始

安装和启动

查看帮助信息

查看版本信息

🛠️ 支持的工具

1. string_to_timestamp

2. timestamp_to_string

📋 系统要求

🔧 MCP客户端配置

📋 完整安装和配置流程

第一步：在MCP客户端中配置服务器

Claude Desktop配置

其他MCP客户端配置

第二步：重启MCP客户端

第三步：验证连接和使用

🔧 高级配置选项

使用本地安装版本

指定Node.js版本

开发环境配置

🚨 故障排除

常见问题和解决方案

1. 服务器连接失败

2. 包安装失败

3. 配置文件格式错误

4. 工具无法使用

5. 权限问题

验证安装

日志和调试

获取帮助

📱 客户端兼容性

🔄 配置更新

📖 使用示例

示例1: 时间字符串转时间戳

示例2: 时间戳转时间字符串

🔍 错误处理

常见错误类型

🏗️ 项目结构

🔒 安全特性

🧪 测试

📝 开发

本地开发

代码结构

🤝 贡献

贡献指南

📄 许可证

🆘 支持

📦 npm发布指南

快速发布

发布前检查

� 相关资源