Timezone Toolkit

🚀 TimezoneToolkit

TimezoneToolkit is a time and timezone toolkit developed using the Model Context Protocol (MCP). It offers a range of powerful tools and services to assist users in handling tasks such as date, time, timezone conversion, and astronomical calculations.

🚀 Quick Start

TimezoneToolkit provides a variety of functions for handling time and timezone-related tasks. You can quickly start using it by following the installation and usage steps below.

✨ Features

• Multi-timezone Support: Built-in information on major timezones worldwide.
• Date and Time Operations: Functions including time addition/subtraction and formatting.
• Astronomical Calculations: Calculations for natural phenomena such as sunrise, sunset, and tides.
• JSON RPC Support: Integration with Claude Desktop via the MCP protocol.

📦 Installation

Prerequisites

• Node.js 18.x or higher.
• npm 9.x or higher.
• The latest version of Claude Desktop.

Installation Steps

# Download the project source code
git clone https://github.com/yourusername/timezone-toolkit.git

# Navigate to the project directory
cd timezone-toolkit

# Install dependencies
npm install

# Start the MCP server
node dist/index.js

💻 Usage Examples

Basic Usage

# Get the current time, defaulting to the UTC timezone
npm start -- --timeZone=UTC

# Convert to New York time
npm start -- --convertTo=America/New_York

📚 Documentation

1. Time Display

Get the Current Time

{
  "currentTime": "March 25, 2024, 9:54 PM",
  "timezone": "America/New_York",
  "utcOffset": "-04:00"
}

Example Commands

• getCurrentTime: Get the current time in a specified timezone.
• listTimezones: List all available timezones.

2. Sunrise and Sunset Calculation

Method Call Example

{
  "latitude": 37.7749,
  "longitude": -122.4194,
  "date": "2024-03-25",
  "time": "06:00"
}

Return Result

{
  "sunrise": "6:05 AM",
  "sunset": "7:15 PM",
  "moonPhase": "Waning gibbous"
}

3. Timezone Conversion

Supported Operations Include:

• Add/subtract hours/minutes from a time.
• Convert to UTC time.
• Display the timezone offset (e.g., +08:00).

🔧 Technical Details

Core Components

• Core Service: Handles timezone conversion, astronomical calculations, and date formatting.
• MCP Server: Receives JSON RPC requests from Claude Desktop.
• Utility Functions: Provides auxiliary functions for date and time operations.
• Testing Framework: Comprehensively tests the functionality of the MCP server.

Technical Dependencies

• Luxon - Handles all date/time operations and timezone management.
• SunCalc - Used for astronomical calculations such as sunrise and sunset.
• @modelcontextprotocol/sdk - Used for MCP server implementation.

🤝 Contribution Guidelines

Contributions are welcome! Please follow these steps to submit your code:

1. Fork the repository.
2. Create a feature branch (e.g., feature/amazing-feature).
3. Commit your changes (e.g., git commit -m 'Add amazing feature').
4. Push to the branch (e.g., git push origin feature/amazing-feature).
5. Submit a pull request.

🧪 Testing Methods

Basic Test Commands

# Run unit tests
npm test

# Run end-to-end tests
npm run e2e

Detailed Explanation

• Test Coverage: Ensure the required coverage is achieved.
• Integration Testing: Verify the collaborative work of each module.
• Performance Testing: Evaluate processing speed and stability.

🛠️ Troubleshooting

Common issues and solutions:

1. Failed to install dependencies
   • Check your network connection.
   • Ensure that the Node.js version meets the requirements.
   • Re-run npm install.
2. Error starting the server
   • Check the error log.
   • Ensure that all dependencies are correctly installed.
3. Unable to integrate with Claude
   • Check the MCP protocol version.
   • Ensure that the port configuration is correct.

🔒 Privacy and Security

• Data Protection: Comply with GDPR and CCPA regulations.
• Code Auditing: Conduct regular security reviews.
• User Privacy: Strictly protect user data from misuse.

📄 License

Apache 2.0 License

...

📞 Contact Information

If you have any questions or suggestions, please contact us:

• Email: support@timezone-toolkit.com
• GitHub: https://github.com/timezone-toolkit