# Time MCP

A Model Context Protocol (MCP) server that provides time-related tools for LLM applications.

## Features

- Get current UTC time in ISO 8601 format
- Get Unix timestamp
- Support for timezone queries (optional extension)

## Requirements

- Node.js 18+
- pnpm

## Docker Deployment

> 🐳 **Docker 部署**: 查看 [DOCKER.md](./DOCKER.md) 了解如何使用 Docker 和 Docker Compose 部署 Time MCP 服务器。

快速开始：
```bash
docker-compose up -d
```

## Installation

```bash
pnpm install
```

## Development

```bash
# Run in development mode (Stdio mode)
pnpm dev

# Run in HTTP mode (development)
pnpm dev:http

# Build for production
pnpm build

# Run production build (Stdio mode)
pnpm start

# Run production build (HTTP mode)
pnpm start:http
```

## Transport Modes

This server supports two transport modes:

### Stdio Mode (Default)

The server communicates via standard input/output streams. This is the default mode and is suitable for local process communication.

```bash
pnpm dev
# or
TRANSPORT=stdio pnpm start
```

### HTTP Mode

The server runs as an HTTP server and can be accessed remotely. Suitable for remote deployment and network communication.

```bash
# Development
pnpm dev:http

# Production
TRANSPORT=http PORT=3000 HOST=0.0.0.0 pnpm start
```

**Environment Variables for HTTP Mode:**
- `TRANSPORT`: Transport type (`stdio` | `http`), default: `stdio`
- `PORT`: HTTP port (HTTP mode), default: `3000`
- `HOST`: HTTP listen address (HTTP mode), default: `0.0.0.0`
- `MCP_PATH` or `API_PATH`: HTTP API path (HTTP mode), default: `/mcp`
- `LOG_LEVEL`: Log level (`DEBUG` | `INFO` | `WARN` | `ERROR`), default: `INFO`

## Logging

The server includes comprehensive logging for troubleshooting. Logs are output to `stderr` (following MCP protocol conventions).

**Log Levels:**
- `DEBUG`: Detailed debug information (most verbose)
- `INFO`: General informational messages (default)
- `WARN`: Warning messages
- `ERROR`: Error messages only (least verbose)

**Setting Log Level:**
```bash
# Set log level via environment variable
LOG_LEVEL=DEBUG pnpm dev
LOG_LEVEL=ERROR pnpm start:http
```

**What Gets Logged:**
- Server startup and shutdown
- Transport creation and connection
- HTTP request/response details (method, path, duration)
- Tool calls (name, arguments, results)
- Errors with stack traces

## Usage

> 📖 **详细使用文档**: 查看 [USAGE.md](./USAGE.md) 了解如何在其他 LLM 应用中集成和使用 time-mcp，包括在 OpenAI JS SDK Response API 中的完整示例。

This MCP server provides the following tools:

### getCurrentTime

Returns the current UTC time in ISO 8601 format along with Unix timestamp.

**Parameters**: None

**Returns**:
```json
{
  "timestamp": "2024-01-01T12:00:00.000Z",
  "iso": "2024-01-01T12:00:00.000Z",
  "unix": 1704110400000
}
```

## License

ISC