@strix-ai/currentdt

CurrentDT - MCP DateTime Tool

strix-ai 🦉
Wisdom in Every Line of Code
Engineered by AI, Empowering AI

A simple Model Context Protocol (MCP) tool that automatically provides current date and time context to AI assistants in supported IDEs.

🎯 What is CurrentDT?

CurrentDT is an MCP server that seamlessly integrates with AI-powered IDEs (Cursor, VSCode, Claude, Windsurf, etc.) to provide real-time date and time context. When active, it automatically informs the AI assistant about the current date and time, enabling more accurate and time-aware responses.

🏗️ Architecture Overview

┌─────────────────────────────────────────────────────────────────┐
│                    AI-Powered IDEs                              │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│  │   Cursor    │ │   VSCode    │ │   Claude    │ │  Windsurf   │ │
│  │     IDE     │ │ + MCP Ext   │ │  Desktop    │ │     IDE     │ │
│  └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │
└─────────────────────────────────────────────────────────────────┘
                                │
                    ┌───────────▼────────────┐
                    │   JSON-RPC 2.0 / MCP  │
                    │      Protocol Layer    │
                    └───────────┬────────────┘
                                │
        ┌───────────────────────▼────────────────────────┐
        │              CurrentDT MCP Server              │
        │                                                │
        │  ┌─────────────────┐  ┌─────────────────────┐  │
        │  │   MCP Server    │  │  DateTime Resource  │  │
        │  │      Core       │◄─┤     Provider       │  │
        │  └─────────────────┘  └─────────────────────┘  │
        │                                                │
        │  ┌─────────────────┐  ┌─────────────────────┐  │
        │  │  Time Sync      │  │   Edge Case         │  │
        │  │   Service       │  │    Handler          │  │
        │  └─────────────────┘  └─────────────────────┘  │
        │                                                │
        │  ┌─────────────────┐  ┌─────────────────────┐  │
        │  │ Configuration   │  │    Logger &         │  │
        │  │   Manager       │  │   Validator         │  │
        │  └─────────────────┘  └─────────────────────┘  │
        └────────────────────────────────────────────────┘
                                │
        ┌───────────────────────▼────────────────────────┐
        │                Data Sources                    │
        │                                                │
        │ ┌──────────────┐ ┌──────────────┐ ┌──────────┐ │
        │ │ System Clock │ │ Network Time │ │ Timezone │ │
        │ │   & Local    │ │   Servers    │ │ Database │ │
        │ │   Timezone   │ │   (NTP/HTTP) │ │ (Intl)   │ │
        │ └──────────────┘ └──────────────┘ └──────────┘ │
        └─────────────────────────────────────────────────┘

📊 Auto-Injection Flow:
1️⃣  IDE sends any MCP request → 2️⃣  Server auto-updates datetime
3️⃣  Fresh context generated → 4️⃣  AI gets current datetime automatically

✨ Key Features

• 🕒 Real-time DateTime: Provides current local and UTC timestamps
• 🌍 Timezone Aware: Supports both local system timezone and UTC
• 🔄 Auto-refresh: Updates datetime context automatically
• ⚡ Zero Config: Works out of the box with sensible defaults
• 🛡️ Privacy Conscious: Optional privacy modes and clear data usage
• 🎛️ Configurable: Flexible formatting and update intervals
• 🚀 Lightweight: Minimal performance impact
• 🔌 IDE Agnostic: Works with any MCP-supported IDE

🚀 Quick Start

Installation

# Install globally via npm
npm install -g @strix-ai/currentdt

# Or install locally in your project
npm install @strix-ai/currentdt

Basic Usage

# Start the MCP server (default configuration)
currentdt start

# Start with custom configuration
currentdt start --config ./my-config.json

# Check server status
currentdt status

# Stop the server
currentdt stop

IDE Integration

Once installed, CurrentDT automatically integrates with supported IDEs. The AI assistant will have access to current datetime context in every conversation.

Example of what the AI sees:

Current DateTime Context:
- Local: 2024-01-15T14:30:25-05:00 (EST)
- UTC: 2024-01-15T19:30:25Z
- Day: Monday

📋 Prerequisites

• Node.js: Version 18.0.0 or higher
• npm: Version 8.0.0 or higher
• Supported IDEs: Cursor, VSCode with MCP extension, Claude Desktop, Windsurf, or any MCP-compatible IDE

🛠️ Configuration

CurrentDT works with zero configuration but supports extensive customization.

Default Configuration

{
  "server": {
    "host": "localhost",
    "port": 3000,
    "logLevel": "info",
    "maxConnections": 10,
    "timeoutMs": 5000
  },
  "datetime": {
    "format": "iso",
    "customFormat": null,
    "timezones": ["local", "utc"],
    "updateIntervalMs": 60000,
    "includeMilliseconds": false
  },
  "privacy": {
    "enabled": false,
    "shareDate": true,
    "anonymizeData": false,
    "logTimestamps": true,
    "logRetentionDays": 7
  },
  "timeSync": {
    "enabled": false,
    "servers": ["time.nist.gov", "worldtimeapi.org"],
    "timeout": 5000,
    "retryAttempts": 3,
    "userConsent": true,
    "fallbackToSystem": true
  }
}

Configuration Options Reference

Section	Option	Type	Default	Description
Server	host	string	"localhost"	MCP server bind address
	port	number	3000	MCP server port
	logLevel	string	"info"	Logging level (debug, info, warn, error, silent)
	maxConnections	number	10	Maximum concurrent connections
	timeoutMs	number	5000	Request timeout in milliseconds
DateTime	format	string	"iso"	DateTime format (iso, readable, custom)
	customFormat	string	null	Custom format string (when format="custom")
	timezones	array	["local", "utc"]	Timezones to include in context
	updateIntervalMs	number	60000	Auto-update interval in milliseconds
	includeMilliseconds	boolean	false	Include milliseconds in timestamps
Privacy	enabled	boolean	false	Enable privacy mode (date-only sharing)
	shareDate	boolean	true	Share date information
	anonymizeData	boolean	false	Anonymize timezone/location data
	logTimestamps	boolean	true	Include timestamps in logs
	logRetentionDays	number	7	Days to retain log files
TimeSync	enabled	boolean	false	Enable network time synchronization
	servers	array	["time.nist.gov", ...]	NTP/HTTP time servers
	timeout	number	5000	Network timeout in milliseconds
	retryAttempts	number	3	Number of retry attempts per server
	userConsent	boolean	true	Require user consent for network access
	fallbackToSystem	boolean	true	Fallback to system time if sync fails

Creating a Configuration File

# Generate default configuration
currentdt config --init

# Edit configuration
currentdt config --edit

# Validate configuration
currentdt config --validate

Environment Variables

# Override configuration with environment variables
CURRENTDT_ENABLED=true
CURRENTDT_FORMAT=readable
CURRENTDT_UPDATE_INTERVAL=30
CURRENTDT_PRIVACY_MODE=true
CURRENTDT_LOG_LEVEL=debug

🔧 Advanced Usage

Custom DateTime Formats

{
  "format": "custom",
  "customFormat": "dddd, MMMM Do YYYY, h:mm:ss a"
}

Privacy Mode

When privacy mode is enabled, only the date (not time) is shared:

{
  "privacyMode": true
}

Output in privacy mode:

Current Date Context:
- Local: 2024-01-15 (EST)
- UTC: 2024-01-15

Multiple Timezone Support

{
  "timezones": ["local", "utc", "America/New_York", "Europe/London", "Asia/Tokyo"]
}

🔌 IDE-Specific Setup

Cursor IDE (Recommended)

Setup:

• Install CurrentDT: npm install -g @strix-ai/currentdt
• Start the server: currentdt start
• Cursor automatically detects the MCP server via auto-discovery
• DateTime context is now available in all AI conversations

Configuration File: Not required (auto-discovery)

Verification:

# Check if CurrentDT is running
currentdt status

# Test datetime context
# Open Cursor and ask: "What time is it right now?"

VSCode with MCP Extension

Setup:

• Install the MCP Extension for VSCode
• Install CurrentDT: npm install -g @strix-ai/currentdt
• Add CurrentDT to VSCode settings

Configuration File: settings.json

{
  "mcp.servers": {
    "currentdt": {
      "command": "currentdt",
      "args": ["start"],
      "env": {
        "CURRENTDT_LOG_LEVEL": "info"
      }
    }
  }
}

Alternative Configuration (with custom config):

{
  "mcp.servers": {
    "currentdt": {
      "command": "node",
      "args": [
        "path/to/currentdt/dist/cli/index.js",
        "--config", "path/to/your-config.json"
      ]
    }
  }
}

Claude Desktop

Setup:

• Install CurrentDT: npm install -g @strix-ai/currentdt
• Locate Claude Desktop config file:
  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
• Add CurrentDT configuration

Configuration File: claude_desktop_config.json

{
  "mcpServers": {
    "currentdt": {
      "command": "currentdt",
      "args": ["start"]
    }
  }
}

Advanced Configuration:

{
  "mcpServers": {
    "currentdt": {
      "command": "currentdt",
      "args": [
        "start",
        "--config", "~/.currentdt/config.json",
        "--log-level", "debug"
      ],
      "env": {
        "CURRENTDT_PRIVACY_MODE": "true",
        "CURRENTDT_UPDATE_INTERVAL": "30000"
      }
    }
  }
}

Windsurf IDE

Setup:

• Install CurrentDT: npm install -g @strix-ai/currentdt
• Configure MCP server in Windsurf settings
• Add CurrentDT to MCP servers list

Configuration File: Windsurf Settings → MCP Servers

{
  "mcp": {
    "servers": {
      "currentdt": {
        "command": "currentdt",
        "args": ["start"],
        "description": "Current DateTime Context Provider"
      }
    }
  }
}

Any MCP-Compatible IDE

Generic Configuration Template:

{
  "mcpServers": {
    "currentdt": {
      "command": "currentdt",
      "args": ["start"],
      "description": "strix-ai CurrentDT MCP Server",
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

Custom Binary Path:

{
  "mcpServers": {
    "currentdt": {
      "command": "/usr/local/bin/node",
      "args": [
        "/usr/local/lib/node_modules/@strix-ai/currentdt/dist/cli/index.js",
        "start"
      ]
    }
  }
}

IDE Configuration Comparison

IDE	Setup Complexity	Auto-Discovery	Custom Config	Performance
Cursor	⭐ Very Easy	✅ Yes	✅ Optional	⭐⭐⭐⭐⭐ Excellent
VSCode + MCP	⭐⭐ Easy	❌ Manual	✅ Required	⭐⭐⭐⭐ Very Good
Claude Desktop	⭐⭐ Easy	❌ Manual	✅ Required	⭐⭐⭐⭐ Very Good
Windsurf	⭐⭐⭐ Medium	❌ Manual	✅ Required	⭐⭐⭐ Good
Generic MCP	⭐⭐⭐ Medium	❌ Manual	✅ Required	⭐⭐⭐ Good

Environment Variables for All IDEs

# Server Configuration
export CURRENTDT_SERVER_HOST="localhost"
export CURRENTDT_SERVER_PORT="3000"
export CURRENTDT_SERVER_LOG_LEVEL="info"

# DateTime Configuration
export CURRENTDT_DATETIME_FORMAT="iso"
export CURRENTDT_DATETIME_UPDATE_INTERVAL="60000"
export CURRENTDT_DATETIME_TIMEZONES="local,utc"

# Privacy Configuration
export CURRENTDT_PRIVACY_ENABLED="false"
export CURRENTDT_PRIVACY_SHARE_DATE="true"

# Time Sync Configuration
export CURRENTDT_TIME_SYNC_ENABLED="false"
export CURRENTDT_TIME_SYNC_USER_CONSENT="true"

📊 Monitoring & Debugging

Status Check

currentdt status

Output:

CurrentDT Status:
✅ Server: Running (PID: 12345)
🌍 Local Time: 2024-01-15T14:30:25-05:00
🌐 UTC Time: 2024-01-15T19:30:25Z
📡 Port: 3000
🔄 Update Interval: 60s
📊 Uptime: 2h 15m

Logs

# View logs
currentdt logs

# Follow logs in real-time
currentdt logs --follow

# Filter by log level
currentdt logs --level error

Health Check

# Basic health check
curl http://localhost:3000/health

# Detailed health information
curl http://localhost:3000/health/detailed

🔒 Privacy & Security

Data Collection

CurrentDT only collects and shares:

• Current system date and time
• System timezone information
• Server uptime and status

Privacy Considerations

⚠️ Important Privacy Notes:

• Timezone Exposure: Local timezone can reveal your geographical location
• Time Precision: Exact timestamps may be used for temporal analysis
• Always On: Datetime context is shared with every AI interaction

Privacy Protection

• Use privacyMode: true to share only dates, not precise times
• Consider using UTC-only mode: timezones: ["utc"]
• Review your IDE's data sharing policies
• Regularly audit MCP server logs

Security Best Practices

• Keep CurrentDT updated to the latest version
• Use firewall rules to restrict MCP server access
• Monitor logs for unusual activity
• Use strong system authentication

🧪 Testing

Test Current Installation

# Test basic functionality
currentdt test

# Test with specific IDE
currentdt test --ide cursor

# Performance test
currentdt test --performance

Manual Testing

• Start CurrentDT: currentdt start
• Open your IDE
• Ask the AI assistant: "What time is it?"
• Verify the AI has access to current datetime

🚨 Troubleshooting

Common Issues

Server Won't Start

# Check if port is in use
netstat -an | grep 3000

# Try different port
currentdt start --port 3001

IDE Not Detecting Server

# Verify server is running
currentdt status

# Check IDE MCP configuration
currentdt config --ide-check

Incorrect Timezone

# Check system timezone
currentdt timezone --check

# Force timezone refresh
currentdt timezone --refresh

Debug Mode

# Start in debug mode
currentdt start --debug

# Verbose logging
currentdt start --log-level debug

Getting Help

# Show help
currentdt --help

# Show version
currentdt --version

# Run diagnostics
currentdt diagnose

🔄 Updates & Maintenance

Updating CurrentDT

# Update to latest version
npm update -g @strix-ai/currentdt

# Check for updates
currentdt update --check

# Auto-update (if enabled)
currentdt update --auto

Maintenance Commands

# Clean temporary files
currentdt clean

# Reset configuration to defaults
currentdt reset

# Backup configuration
currentdt backup

# Restore configuration
currentdt restore

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

# Clone repository
git clone https://github.com/strix-ai/currentdt.git
cd currentdt

# Install dependencies
npm install

# Run tests
npm test

# Start development server
npm run dev

Project Structure

src/
├── core/           # Core MCP server implementation
├── datetime/       # DateTime handling logic
├── config/         # Configuration management
├── resources/      # MCP resource providers
├── cli/           # Command-line interface
├── utils/         # Utility functions
└── types/         # TypeScript type definitions

📄 License

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

🙏 Acknowledgments

• Model Context Protocol for the excellent protocol specification
• Anthropic for Claude and MCP support
• Cursor for IDE integration inspiration
• All contributors and beta testers

📞 Support

• 📧 Email: [e-mail]
• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 📖 Documentation: Wiki

Made with ❤️ for the AI development community