# Time Node MCP Server

A Model Context Protocol (MCP) server that provides timezone-aware date and time operations. This server addresses the common issue where AI assistants provide incorrect date information due to timezone confusion.

## Features

- **Accurate timezone handling** - Get current time in any IANA timezone
- **Time conversion** - Convert time between different timezones
- **Multiple formats** - ISO 8601, localized, and human-readable formats
- **System timezone detection** - Automatically detect system timezone
- **DST awareness** - Correctly handles Daylight Saving Time transitions
- **Date utilities** - Get current date with day-of-week information

## Installation

### Prerequisites

- Node.js 18.0.0 or higher
- npm or yarn

### Install and Build

```bash
# Clone or download the project
cd time-node-mcp

# Install dependencies
npm install

# Build the TypeScript code
npm run build
```

## Usage with Claude Desktop

Add the following configuration to your Claude Desktop settings file:

### macOS
`~/Library/Application Support/Claude/claude_desktop_config.json`

### Windows
`%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "time-node-mcp": {
      "command": "node",
      "args": ["/path/to/time-node-mcp/dist/index.js"]
    }
  }
}
```

Replace `/path/to/time-node-mcp/` with the actual path to your installation directory.

## Available Tools

### 1. get_current_time
Get the current date and time in a specific timezone.

**Parameters:**
- `timezone` (required): IANA timezone identifier (e.g., "America/New_York", "Europe/London")
- `format` (optional): Output format - "iso", "local", or "full" (default: "iso")

**Example:**
```json
{
  "timezone": "America/New_York",
  "format": "full"
}
```

### 2. convert_time
Convert time from one timezone to another.

**Parameters:**
- `sourceTimezone` (required): Source IANA timezone identifier
- `targetTimezone` (required): Target IANA timezone identifier  
- `time` (required): Time in HH:MM or HH:MM:SS format (24-hour)
- `date` (optional): Date in YYYY-MM-DD format (uses current date if not provided)

**Example:**
```json
{
  "sourceTimezone": "America/New_York",
  "targetTimezone": "Europe/London",
  "time": "14:30",
  "date": "2024-08-12"
}
```

### 3. get_system_timezone
Get the system's current timezone with current time information.

**Parameters:** None

### 4. get_current_date
Get the current date in a specific timezone with day-of-week information.

**Parameters:**
- `timezone` (required): IANA timezone identifier
- `includeTime` (optional): Whether to include time information (default: false)

**Example:**
```json
{
  "timezone": "Asia/Tokyo",
  "includeTime": true
}
```

## Development

### Scripts

```bash
# Build the project
npm run build

# Build and watch for changes
npm run dev

# Run the server directly (after building)
npm start

# Lint the code
npm run lint

# Type check
npm run typecheck
```

### Project Structure

```
time-node-mcp/
├── src/
│   ├── index.ts           # Main MCP server implementation
│   ├── time-service.ts    # Core time/timezone functionality
│   └── interfaces.ts      # TypeScript interfaces
├── dist/                  # Compiled JavaScript (generated)
├── package.json
├── tsconfig.json
└── README.md
```

## Common Use Cases

1. **Correct current date/time**: When Claude needs to know "what day is today" in your timezone
2. **Meeting scheduling**: Convert meeting times between different timezones
3. **Travel planning**: Understand time differences when traveling
4. **International coordination**: Work with teams across multiple timezones

## Timezone Support

This server supports all IANA timezone identifiers, including:

- `America/New_York`
- `Europe/London`
- `Asia/Tokyo`
- `Australia/Sydney`
- `Pacific/Auckland`
- And many more...

You can find a complete list of supported timezones at: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones

## Error Handling

The server provides comprehensive error handling for:
- Invalid timezone identifiers
- Malformed time formats
- Invalid date formats
- System errors

All errors are returned in a structured JSON format with descriptive messages.

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests and linting
5. Submit a pull request

## License

MIT License - see LICENSE file for details.

## Troubleshooting

### Common Issues

**"Invalid timezone" error:**
- Ensure you're using valid IANA timezone identifiers
- Check spelling and capitalization (e.g., "America/New_York", not "america/new_york")

**MCP server not connecting:**
- Verify the path in your Claude Desktop configuration is correct
- Ensure the project is built (`npm run build`)
- Check that Node.js is installed and accessible

**Date/time seems incorrect:**
- The server uses your system's current date/time as the base
- Ensure your system clock is correct and timezone is properly set