kite-mcp-server-time

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

# Clone the repository
git clone <repository-url>
cd mcp-time-server

# Install dependencies
npm install

Running the Server

Using stdio transport (default)

# Build the project
npm run build

# Start with stdio transport
npm start

Using HTTP transport

# 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

npm run dev

Docker Deployment

Build and run with Docker

# 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

# 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:

{
  "timezone": "IANA timezone name (e.g., 'America/New_York', 'Europe/London')"
}

Result:

{
  "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:

{
  "source_timezone": "IANA timezone name (e.g., 'America/New_York')",
  "time": "14:30", 
  "target_timezone": "IANA timezone name (e.g., 'Asia/Tokyo')"
}

Result:

{
  "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