内容
# 时间感知 MCP 服务器
一个模型上下文协议 (MCP) 服务器，为 AI 代理提供全面的时间感知和时间计算能力。
## 功能
- **当前时间**：获取任何时区的当前日期和时间
- **时间计算**：计算时间戳之间的差异
- **时间调整**：从时间戳中添加或减去持续时间
- **上下文分析**：获取关于时间戳的人类可读上下文
- **多种传输方式**：支持 stdio（本地）和 HTTP（远程）连接
- **Docker 支持**：准备好进行云部署
## 快速开始
### 本地开发（Claude Desktop, Cursor）
1. **安装依赖**：
```bash
git clone https://github.com/pmbstyle/temporal-awareness-mcp.git
cd temporal-awareness-mcp
poetry install
```
2. **使用 stdio 传输运行**：
```bash
poetry run python -m temporal_awareness_mcp.stdio_main
```
### 云部署
1. **使用 Docker 运行**:
```bash
docker-compose up -d --build
```
2. **或直接使用 HTTP 传输运行**:
```bash
poetry run python -m temporal_awareness_mcp.http_main --host 0.0.0.0 --port 8000
```
## 集成指南
### Claude Desktop
将以下内容添加到您的 Claude Desktop 配置文件中：
**对于 Windows：**
```json
{
"mcpServers": {
"temporal-awareness": {
"command": "cmd",
"args": ["/c", "cd /d \"C:\\path\\to\\temporal-awareness-mcp\" && poetry run python -m temporal_awareness_mcp.stdio_main"],
"env": {}
}
}
}
```
**对于 macOS/Linux：**
```json
{
"mcpServers": {
"temporal-awareness": {
"command": "sh",
"args": ["-c", "cd '/path/to/temporal-awareness-mcp' && poetry run python -m temporal_awareness_mcp.stdio_main"],
"env": {}
}
}
}
```
> **重要**：将 `/path/to/temporal-awareness-mcp` 替换为您的实际项目目录。
**替代方案：使用 Python 和 PYTHONPATH**
如果您不想使用 Poetry：
```json
{
"mcpServers": {
"temporal-awareness": {
"command": "python",
"args": ["-m", "temporal_awareness_mcp.stdio_main"],
"env": {
"PYTHONPATH": "/path/to/temporal-awareness-mcp/src"
}
}
}
}
```
### Cursor IDE
在 Cursor 设置 > 扩展 > MCP 中进行配置：
```json
{
"servers": {
"temporal-awareness": {
"command": "poetry",
"args": ["run", "python", "-m", "temporal_awareness_mcp.stdio_main"],
"cwd": "/path/to/temporal-awareness-mcp"
}
}
}
```
### OpenAI 和云客户端
对于基于云的 AI 服务，部署服务器并使用 HTTP 传输：
1. **使用 ngrok 部署（开发环境）**：
```bash
# 终端 1：启动服务器
docker-compose up -d --build
# 终端 2：使用 ngrok 进行暴露
ngrok http 8000
```
2. **在你的 MCP 客户端中使用公共 URL**：
```json
{
"type": "mcp",
"server_label": "temporal-awareness",
"server_url": "https://your-ngrok-url.ngrok.app/sse",
"require_approval": "never"
}
```
3. **生产环境部署**：部署到 Railway、Heroku、Google Cloud Run 等。
## 可用工具
### `get_current_time`
获取指定时区的当前日期和时间。
**参数:**
- `timezone` (字符串，可选): 时区名称（默认: "UTC"）
- `format` (字符串，可选): 输出格式 - "iso"、"human" 或 "timestamp"（默认: "iso"）
**示例:**
```
东京现在几点了？
```
### `calculate_difference`
计算两个时间戳之间的持续时间。
**参数:**
- `start_time` (string): 开始时间戳（ISO格式或人类可读格式）
- `end_time` (string): 结束时间戳（ISO格式或人类可读格式）
- `unit` (string, 可选): 结果单位 - "seconds"（秒）、"minutes"（分钟）、"hours"（小时）或 "days"（天）（默认: "seconds"）
**示例:**
```
从上午9:00到下午5:30有多长时间？
```
### `get_timestamp_context`
提供关于时间戳的人类可读上下文。
**参数:**
- `timestamp` (string): 要分析的时间戳
- `timezone` (string, optional): 上下文的时区 (默认: "UTC")
**示例:**
```
2024年3月15日下午2:30是工作日吗？
```
### `adjust_timestamp`
从时间戳中添加或减去一个持续时间。
**参数:**
- `timestamp` (string): 基础时间戳
- `adjustment` (string): 要应用的调整（例如，“+1 day”，“ -2 hours”）
- `timezone` (string, 可选): 计算时使用的时区（默认: "UTC"）
**示例:**
```
2024年3月1日之后的30天是哪个日期？
```
## 测试服务器
尝试使用以下示例提示与您的 AI 代理进行交互：
### 基本操作
- "现在几点了？"
- "东京现在几点？"
- "将东部标准时间（EST）下午3:30转换为太平洋时间"
### 日期计算
- "距离圣诞节还有多少天？"
- "2000年1月1日是星期几？"
- "在2024年3月15日上加45天"
### 复杂场景
- "我有一班航班于周五晚上11:30从洛杉矶出发。如果航班时长为14小时，我将在东京当地时间几点到达？"
- "计算2024年2月的工作小时，假设周一至周五为8小时工作日"
## 开发
### 先决条件
- Python 3.12+
- 使用 Poetry 进行依赖管理
- Docker（可选，用于容器化部署）
### 设置
```bash
```
# 克隆并安装
git clone <repository-url>
cd temporal-awareness-mcp
poetry install
# 运行测试
```
poetry run pytest
```
## 部署
### Docker
```bash
```
# 构建和运行
docker-compose up -d --build
# 检查日志
docker-compose logs temporal-awareness-mcp-server
# 停止
docker-compose down
```
### 环境变量
对于生产环境部署，您可以配置：
- `HOST`: 服务器主机（默认: "0.0.0.0"）
- `PORT`: 服务器端口（默认: 8000）
## 许可证
MIT 许可证
MCP 市场
