current-time-timezone-server/README.md

MCP服务器，提供NTP校准的当前时间和时区相关功能，支持stdio和HTTP/SSE，可配置host和protocol，支持.env文件，返回指定时区的本地时间

# Current Time Timezone Server

A Model Context Protocol (MCP) server that provides accurate time information with timezone support and NTP synchronization.

## Features

- **Accurate Time**: NTP-synchronized time from configurable NTP servers
- **Timezone Support**: Local time for any specified timezone
- **Unix Timestamp**: Unix timestamp in seconds
- **Dual Protocol**: Supports both Streamable HTTP and Server-Sent Events (SSE) protocols
- **Real-time Updates**: SSE endpoint provides real-time time updates via streaming
- **Docker Ready**: Complete Docker support with health checks

## Installation

### NPM
```bash
npm install -g current-time-timezone-server
```

### Docker
```bash
# 直接运行
docker run -p 3000:3000 current-time-timezone-server:latest

# 使用docker-compose
docker-compose up -d
```

## Usage

### MCP Server Configuration

#### Streamable HTTP方式 (推荐)
```json
{
  "mcpServers": {
    "current-time-http": {
      "protocol": "http",
      "url": "http://localhost:3000/mcp"
    }
  }
}
```

#### SSE方式
```json
{
  "mcpServers": {
    "current-time-sse": {
      "protocol": "sse",
      "url": "http://localhost:3000/sse"
    }
  }
}
```

### Docker方式
```json
{
  "mcpServers": {
    "current-time": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-p", "3000:3000", "current-time-timezone-server:latest"]
    }
  }
}
```

#### Stdio方式
```json
{
  "mcpServers": {
    "current-time": {
      "command": "npx",
      "args": ["current-time-timezone-server-stdio"],
      "env": {
        "NTP_SERVER": "pool.ntp.org"
      }
    }
  }
}
```

### 启动服务器
```bash
# 默认启动（同时支持Streamable HTTP和SSE）
npx current-time-timezone-server

# 自定义配置
HOST=0.0.0.0 PORT=8080 npx current-time-timezone-server
```

### 访问端点
服务器启动后，以下端点可用：
- **Streamable HTTP**: `POST http://localhost:3000/mcp`
- **SSE**: `GET http://localhost:3000/sse`
- **SSE消息**: `POST http://localhost:3000/messages`

### 测试SSE连接
```bash
# 访问SSE端点
curl -N http://localhost:3000/sse

# 注意：SSE端点用于MCP客户端连接，不支持直接带时区参数
```

### Stdio Server
```bash
npx current-time-timezone-server-stdio
```


## Environment Variables

- `HOST`: 服务器地址 (默认: localhost)
- `PORT`: 服务器端口 (默认: 3000)
- `NTP_SERVER`: NTP服务器地址 (默认: pool.ntp.org)

## Docker Usage

### 构建镜像
```bash
docker build -t current-time-timezone-server .
```

### 运行容器
```bash
docker run -d \
  --name time-server \
  -p 3000:3000 \
  -e NTP_SERVER=pool.ntp.org \
  current-time-timezone-server:latest
```

### 使用docker-compose
```bash
docker-compose up -d
```
## Development

```bash
# 安装依赖
npm install

# 开发模式
npm run dev

# 构建
npm run build
```

## 协议对比

| 协议 | 描述 | 使用场景 | 端点 |
|---|---|---|---|
| **Streamable HTTP** | MCP标准HTTP传输 | MCP客户端连接 | `POST /mcp` |
| **SSE** | 服务器推送实时数据流 | MCP客户端连接 | `GET /sse` |
| **Stdio** | 标准输入输出通信 | MCP客户端内部通信 | 无 |

### 端点说明
- **Streamable HTTP**: 支持完整的MCP协议，包括工具调用
- **SSE**: 提供实时连接，需要配合`/messages`端点使用
- **Stdio**: 独立的可执行文件，用于标准输入输出通信