# Time MCP 技术方案文档
## 1. 项目概述
本项目旨在开发一个基于 Model Context Protocol (MCP) 的时间服务服务器，为 LLM 应用提供获取当前时间的能力。通过标准化的 MCP 协议，LLM 应用可以方便地调用时间相关的功能。
## 2. 技术栈
- **编程语言**: TypeScript
- **运行环境**: Node.js (推荐版本 18+)
- **包管理器**: pnpm
- **核心依赖**:
- `@modelcontextprotocol/server`: MCP 服务器核心库
- **开发依赖**:
- `typescript`: TypeScript 编译器
- `@types/node`: Node.js 类型定义
- `tsx` 或 `ts-node`: TypeScript 运行时（可选）
## 3. 系统架构
### 3.1 架构设计
```
┌─────────────────┐
│ LLM 应用 │
└────────┬────────┘
│ MCP Protocol
│ (JSON-RPC)
▼
┌─────────────────┐
│ Time MCP │
│ Server │
└────────┬────────┘
│
├──────────────┬──────────────┐
│ │ │
▼ ▼ ▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Stdio │ │ HTTP │ │ 其他传输 │
│ Transport │ │ Transport │ │ 方式 │
└─────────────┘ └─────────────┘ └─────────────┘
│ │ │
└──────────────┴──────────────┘
│
▼
┌─────────────────────┐
│ Time Tools │
│ - getCurrentTime │
│ - getTimeInZone │
└─────────────────────┘
```
### 3.2 核心组件
1. **MCP 服务器**: 处理来自 LLM 应用的请求
2. **传输层 (Transport)**: 支持多种传输方式
- **Stdio Transport**: 标准输入/输出传输（适用于本地进程通信）
- **HTTP Transport**: HTTP 传输（适用于远程网络通信）
3. **工具 (Tools)**: 提供时间相关的功能接口
- `getCurrentTime`: 获取当前 UTC 时间
- `getTimeInZone`: 获取指定时区的当前时间（可选扩展）
### 3.3 传输方式
#### 3.3.1 Stdio Transport（标准输入/输出）
- **适用场景**: 本地进程通信，LLM 应用作为父进程启动 MCP 服务器
- **通信方式**: 通过标准输入/输出流进行 JSON-RPC 通信
- **优点**:
- 简单直接，无需网络配置
- 安全性高，进程间通信
- 延迟低
- **缺点**:
- 仅支持本地通信
- 需要进程管理
#### 3.3.2 HTTP Transport（HTTP 传输）
- **适用场景**: 远程网络通信，跨机器或跨容器部署
- **通信方式**: 通过 HTTP/HTTPS 协议进行 JSON-RPC 通信
- **配置参数**:
- `host`: 监听地址（默认: `0.0.0.0`）
- `port`: 监听端口（默认: `3000`）
- `path`: API 路径（默认: `/mcp`）
- **优点**:
- 支持远程访问
- 易于部署和扩展
- 支持负载均衡
- 便于监控和日志收集
- **缺点**:
- 需要网络配置和安全考虑
- 可能有网络延迟
## 4. 功能设计
### 4.1 核心功能
#### 4.1.1 getCurrentTime 工具
- **功能描述**: 获取当前 UTC 时间的 ISO 8601 格式字符串
- **输入参数**: 无
- **输出格式**:
```json
{
"timestamp": "2024-01-01T12:00:00.000Z",
"iso": "2024-01-01T12:00:00.000Z",
"unix": 1704110400000
}
```
#### 4.1.2 getTimeInZone 工具（可选扩展）
- **功能描述**: 获取指定时区的当前时间
- **输入参数**:
```json
{
"timezone": "Asia/Shanghai"
}
```
- **输出格式**:
```json
{
"timestamp": "2024-01-01T20:00:00+08:00",
"timezone": "Asia/Shanghai",
"iso": "2024-01-01T20:00:00+08:00"
}
```
### 4.2 错误处理
- 参数验证错误：返回标准的 MCP 错误响应
- 时区无效错误：返回友好的错误信息
- 系统错误：记录日志并返回通用错误信息
## 5. 项目结构
```
time-mcp/
├── src/
│ ├── index.ts # 服务器入口文件
│ ├── server.ts # MCP 服务器实现
│ ├── transport.ts # 传输层抽象和实现
│ └── tools/
│ ├── time.ts # 时间工具实现
│ └── types.ts # 类型定义
├── package.json
├── tsconfig.json
├── pnpm-lock.yaml
└── README.md
```
## 6. 实现方案
### 6.1 MCP 服务器初始化
使用 `@modelcontextprotocol/server` 创建服务器实例，配置服务器元信息（名称、版本等）。
### 6.2 工具注册
通过 `server.setRequestHandler` 或类似 API 注册工具，定义：
- 工具名称
- 工具描述
- 输入参数 schema
- 处理函数
### 6.3 时间处理
- 使用 JavaScript 原生 `Date` 对象获取时间
- 使用 `Intl.DateTimeFormat` 处理时区转换（如需要）
- 返回标准化的时间格式
### 6.4 传输层实现
#### 6.4.1 Stdio Transport 实现
- 使用 `StdioServerTransport` 创建标准输入/输出传输
- 服务器通过 `stdin/stdout` 与客户端通信
- 适用于本地进程通信场景
#### 6.4.2 HTTP Transport 实现
- 使用 `SSEServerTransport` 或自定义 HTTP 传输实现
- 创建 HTTP 服务器监听指定端口
- 支持 Server-Sent Events (SSE) 或 HTTP POST 请求
- 配置 CORS 和安全策略（如需要）
### 6.5 服务器启动
服务器支持两种启动方式：
1. **Stdio 模式**（默认）:
```bash
node dist/index.js
# 或通过环境变量指定
TRANSPORT=stdio node dist/index.js
```
2. **HTTP 模式**:
```bash
TRANSPORT=http PORT=3000 node dist/index.js
```
配置方式：
- 通过环境变量配置传输方式和参数
- 通过命令行参数配置（可选）
- 支持配置文件（可选扩展）
环境变量：
- `TRANSPORT`: 传输方式 (`stdio` | `http`)，默认 `stdio`
- `PORT`: HTTP 端口（HTTP 模式），默认 `3000`
- `HOST`: HTTP 监听地址（HTTP 模式），默认 `0.0.0.0`
- `PATH`: HTTP API 路径（HTTP 模式），默认 `/mcp`
## 7. 开发流程
1. **项目初始化**: 使用 pnpm 初始化项目
2. **依赖安装**: 安装必要的依赖包
3. **TypeScript 配置**: 配置 tsconfig.json
4. **代码实现**: 实现服务器和工具逻辑
5. **测试验证**: 使用 MCP 客户端工具测试
6. **文档完善**: 编写使用文档和 API 文档
## 8. 测试方案
### 8.1 单元测试
- 测试时间格式化函数
- 测试时区转换逻辑
- 测试错误处理
### 8.2 集成测试
- 使用 MCP Inspector 工具测试服务器
- 模拟 LLM 应用调用场景
- 验证 JSON-RPC 协议通信
## 9. 部署方案
### 9.1 本地开发
#### 9.1.1 Stdio 模式开发
- 直接运行 TypeScript 文件（使用 tsx）
- 或编译后运行 JavaScript 文件
- 通过标准输入/输出与客户端通信
#### 9.1.2 HTTP 模式开发
- 启动 HTTP 服务器监听端口
- 通过 HTTP 客户端工具测试（如 curl、Postman）
- 支持热重载和调试
### 9.2 生产部署
#### 9.2.1 Stdio 模式部署
- 编译 TypeScript 到 JavaScript
- 作为子进程由 LLM 应用启动
- 使用进程管理器（如 PM2）管理进程生命周期
#### 9.2.2 HTTP 模式部署
- 编译 TypeScript 到 JavaScript
- 使用进程管理器（如 PM2）运行 HTTP 服务器
- 配置反向代理（如 Nginx）进行负载均衡
- 配置 HTTPS 和安全策略
- 配置日志和监控
- 支持容器化部署（Docker）
## 10. 扩展性考虑
- 支持更多时间格式（相对时间、时间差等）
- 支持时间计算功能（日期加减等）
- 支持多语言时间格式化
- 支持历史时间查询（如需要）
## 11. 注意事项
### 11.1 时间处理
- 确保时间格式符合 ISO 8601 标准
- 正确处理时区转换
- 注意服务器时区和客户端时区的差异
- 考虑性能优化（避免频繁的系统调用）
### 11.2 传输方式选择
- **Stdio 模式**: 适用于本地部署，LLM 应用直接启动服务器进程
- **HTTP 模式**: 适用于远程部署，需要网络访问的场景
- 根据实际部署需求选择合适的传输方式
### 11.3 HTTP 模式安全考虑
- 配置适当的 CORS 策略
- 考虑添加身份验证机制（如 API Key）
- 使用 HTTPS 保护数据传输
- 配置请求限流防止滥用
- 记录访问日志便于审计
