Content
# MCP Time Server in TypeScript
A TypeScript implementation of an MCP (Model Context Protocol) server that provides time-related tools.
## Features
- **Get Current Time**: Get the current time in a specified timezone
- **Convert Time**: Convert a time between different timezones with time difference calculation
- **Modular Architecture**: Separated server creation and transport binding for flexibility
- **Multiple Transport Options**: Supports both stdio and HTTP transports
- **Docker Support**: Easy containerized deployment
## Requirements
- Node.js 18+
- npm or yarn
- Docker (optional, for containerized deployment)
## Installation
```bash
# Clone the repository
git clone <repository-url>
cd mcp-time-server
# Install dependencies
npm install
```
## Running the Server
### Using stdio transport (default)
```bash
# Build the project
npm run build
# Start with stdio transport
npm start
```
### Using HTTP transport
```bash
# Build the project
npm run build
# Start with HTTP transport on default port 3000
node dist/index.js --transport=http
# Start with HTTP transport on custom port
node dist/index.js --transport=http --port=8080
```
### Development Mode
```bash
npm run dev
```
## Docker Deployment
### Build and run with Docker
```bash
# Build the Docker image
docker build -t mcp-time-server .
# Run with stdio transport (default)
docker run --name mcp-time-stdio mcp-time-server
# Run with HTTP transport
docker run --name mcp-time-http -p 3000:3000 mcp-time-server node dist/index.js --transport=http
```
### Using Docker Compose
```bash
# Start the HTTP version
docker-compose up mcp-time-http
# Start the stdio version
docker-compose up mcp-time-stdio
# Start both services
docker-compose up
```
## HTTP Transport Endpoints
When using the HTTP transport, the following endpoints are available:
- **POST /mcp**: Main MCP protocol endpoint
- **GET /status**: Returns server status information
To test the HTTP transport:
1. Start the server with `--transport=http`
2. Use an MCP client configured to connect to `http://localhost:3000/mcp`
## Project Structure
The project follows a modular architecture with clear separation of concerns:
```
src/
├── index.ts # Entry point and command-line handling
├── server.ts # MCP server creation and configuration
├── timeService.ts # Time-related utilities and calculations
├── types.ts # Shared types and interfaces
└── transports/
├── index.ts # Transport exports and utilities
├── stdio.ts # Standard I/O transport implementation
└── http.ts # HTTP transport implementation
```
### Modules
1. **timeService.ts**: Core business logic for time operations
2. **server.ts**: Creates and configures the MCP server with tools
3. **transports/**: Contains different transport implementations
4. **types.ts**: Shared type definitions
5. **index.ts**: Main application entry point
This modular design makes the codebase more maintainable and facilitates:
- Adding new transport types
- Unit testing individual components
- Extending functionality with new time-related tools
## Tools
### 1. `get_current_time`
Get the current time in a specified timezone.
**Input Schema:**
```json
{
"timezone": "IANA timezone name (e.g., 'America/New_York', 'Europe/London')"
}
```
**Result:**
```json
{
"timezone": "America/New_York",
"datetime": "2023-06-01T12:34:56-04:00",
"is_dst": true
}
```
### 2. `convert_time`
Convert a time between different timezones.
**Input Schema:**
```json
{
"source_timezone": "IANA timezone name (e.g., 'America/New_York')",
"time": "14:30",
"target_timezone": "IANA timezone name (e.g., 'Asia/Tokyo')"
}
```
**Result:**
```json
{
"source": {
"timezone": "America/New_York",
"datetime": "2023-06-01T14:30:00-04:00",
"is_dst": true
},
"target": {
"timezone": "Asia/Tokyo",
"datetime": "2023-06-02T03:30:00+09:00",
"is_dst": false
},
"time_difference": "+13.0h"
}
```
## Implementation Details
This server is built using:
- TypeScript
- MCP TypeScript SDK
- Express for HTTP transport
- Luxon for timezone handling
- Zod for schema validation
## License
ISC
MCP Store
