qiyuey/time-service

Time Service

|

🌍 The most comprehensive time handling MCP server - Beyond simple timezone conversion

Time Service is a powerful Model Context Protocol (MCP) server that brings enterprise-grade time manipulation capabilities to your AI assistant. With 8 specialized tools, it goes far beyond basic timezone queries to solve real-world scheduling, calculation, and business time challenges.

Quick Links: 📦 npm Package • 🐙 GitHub • 📝 Changelog • 📖 MCP Docs

✨ Why Time Service?

🎯 Complete Solution

Time Service provides 8 comprehensive tools covering every time-handling scenario:

• ✅ Time queries - Current time, timestamps, multiple timezones
• ✅ Time calculations - Add/subtract time, calculate differences
• ✅ Timezone operations - Convert between any timezones
• ✅ Business scenarios - Calculate business days, find next occurrences

🚀 Killer Features

🔄 Batch Operations Query multiple timezones in one call - reduce API requests and get instant global time overview:

One call → All timezones with UTC offsets

📅 Business Day Intelligence Automatically skip weekends when calculating deadlines - perfect for project management:

"Add 5 business days to today" → Automatically excludes weekends

⏰ Smart Scheduling Find next occurrence with flexible conditions:

"Next Monday at 2pm" ✓
"Next 15th of the month" ✓
"Next Friday at 14:00" ✓

🎨 Flexible Formatting 4 built-in formats plus custom configurations:

• ISO 8601: 2024-01-15T10:30:00Z
• Unix timestamp: 1705315800
• Human-readable: Monday, January 15, 2024 at 10:30:00 AM
• Custom: Any format you need

💪 Production Ready

• ✅ 100% Test Coverage - 115 comprehensive test cases
• ✅ Fully Typed - Complete TypeScript type system
• ✅ Well Documented - Clear examples and guides
• ✅ Zero Installation - Use directly with npx/bunx

🛠️ Available Tools

📦 Installation

Add to your MCP client configuration:

{
  "mcpServers": {
    "time-service": {
      "command": "npx",
      "args": ["-y", "@qiyuey/time-service"]
    }
  }
}

Supported runtimes: npm (Node.js), bun

🎯 Usage Examples

Real-World Scenarios

Scenario 1: Global Team Coordination

User: "What time is it in our offices in New York, London, and Tokyo?"

Time Service: Uses get_multiple_timezones
→ Returns all three times with UTC offsets in one response

Scenario 2: Project Deadline Calculation

User: "If we start today, what's the date 10 business days from now?"

Time Service: Uses get_business_days
→ Automatically skips weekends, returns exact date

Scenario 3: Meeting Scheduling

User: "Convert 2pm EST to Tokyo time"

Time Service: Uses convert_timezone
→ Handles daylight saving automatically

Scenario 4: Recurring Event Planning

User: "When's the next Monday at 9am?"

Time Service: Uses next_occurrence
→ Finds exact date and time

API Examples

Get time in multiple timezones:

{
  "name": "get_multiple_timezones",
  "arguments": {
    "timezones": ["America/New_York", "Europe/London", "Asia/Tokyo"],
    "format": "readable"
  }
}

Calculate business days:

{
  "name": "get_business_days",
  "arguments": {
    "startDate": "2024-01-15T00:00:00Z",
    "days": 5,
    "excludeWeekends": true
  }
}

Find next occurrence:

{
  "name": "next_occurrence",
  "arguments": {
    "dayOfWeek": 1,
    "time": "14:00"
  }
}

🗺️ Roadmap

P0 - Core Improvements ✅

• ✅ Code Optimization (v0.3.1) - Extracted shared utilities, achieved 100% function coverage
• ✅ Comprehensive Testing - 115 test cases covering all scenarios

P1 - High Priority (Coming Soon)

• 📚 Enhanced Documentation - Detailed guides and tutorials
• 🐳 Docker Support - Container deployment ready
• 🔌 Platform Integration Guides - Claude Desktop, Zed, VS Code
• ⚡ Performance Boost - Caching and optimization

P2 - Medium Priority (Future)

• 🌍 Internationalization - Multi-language support
• 📊 Advanced Calculations - Holiday support, working hours
• 📈 Analytics - Usage statistics and monitoring
• 🐍 Python Version - Expand to Python ecosystem

P3 - Long-term Vision

• 🔄 Auto-updating Timezone Database - Always current
• 🌐 Web API Service - HTTP API version
• 🎨 Custom Holiday Calendars - Region-specific holidays
• 🔗 Third-party Integrations - Calendar systems, project management tools

🤝 Contributing

We welcome contributions! Here's how you can help:

Priority Areas:

• 🐳 Docker deployment configurations
• 📖 Documentation and integration guides
• ✨ New time calculation features
• 🚀 Performance optimizations

How to Contribute:

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📚 Resources

• 📦 npm Package
• 🐙 GitHub Repository
• 📝 Release Notes
• 🐛 Issue Tracker
• 📖 MCP Protocol
• 🤖 Claude AI

🙋 FAQ

Q: What makes Time Service special?
A: We provide 8 comprehensive tools including business day calculations, batch timezone queries, smart occurrence finding, and flexible formatting options - a complete solution for all your time-handling needs.

Q: Do I need to install anything?
A: No! Use npx -y @qiyuey/time-service directly in your MCP configuration.

Q: What timezones are supported?
A: All IANA timezone names (e.g., America/New_York, Asia/Tokyo, Europe/London).

Q: Can I use custom date formats?
A: Yes! Supports ISO, Unix, human-readable, and custom Intl.DateTimeFormat configurations.

Q: Is it production-ready?
A: Absolutely! 100% function coverage, 115 test cases, fully typed, and actively maintained.

📄 License

This project is licensed under the MIT License - see the file for details.

This project also supports the Anti-996 License. By using this software, you agree to comply with labor laws and regulations, and not to force employees to work overtime without reasonable compensation.

Additional Terms:

• This software is for learning, research, and legitimate business use only
• Users must comply with local labor laws and regulations
• Prohibited from using this software to exploit workers or violate labor rights

MIT © qiyuey