Time MCP Server

# Time MCP Server A Model Context Protocol (MCP) server that provides time and date information for AI assistants like Claude in VSCode. ## Features - **Current Time**: Get the current time in various formats - **Timezone Support**: Query time in different timezones - **Detailed Info**: Get comprehensive time information including day of week, timestamp, etc. - **Multiple Formats**: Support for 12-hour, 24-hour, and ISO formats ## Available Tools ### `get_current_time` Get the current date and time with formatting options. **Parameters:** - `timezone` (optional): Timezone identifier (e.g., "America/New_York", "Europe/London", "Asia/Tokyo") - `format` (optional): Time format - "12hour" (default), "24hour", or "iso" **Examples:** - "What time is it?" - "Get current time in Tokyo" - "Show me the time in 24-hour format" ### `get_time_info` Get detailed time information including timezone data, day of week, and timestamps. **Parameters:** - `timezone` (optional): Timezone identifier **Examples:** - "Give me detailed time information" - "Show time info for London timezone" ## Prerequisites - **Node.js** (v18 or higher) - **npm** - **Docker Desktop** (for Docker builds) - Install via: `brew install --cask docker` - Or download from https://www.docker.com/products/docker-desktop/ - **Important**: You need Docker Desktop (full app), not just Docker CLI ## Installation ### Local Development 1. **Clone or create the project:** ```bash mkdir time-mcp-server cd time-mcp-server ``` 2. **Install dependencies:** ```bash npm install ``` 3. **Build the project:** ```bash npm run build ``` ### Docker Deployment **Prerequisites**: Ensure Docker Desktop is running ```bash # Check Docker is running docker ps # If not running, start Docker Desktop open -a Docker # or open -a "Docker Desktop" ``` 1. **Build and run with Docker Compose:** ```bash docker-compose up -d ``` 2. **Or build manually:** ```bash docker build -t time-mcp-server . docker run -d --name time-mcp-server time-mcp-server ``` 3. **View logs:** ```bash docker-compose logs -f time-mcp-server ``` ## Configuration ## Configuration ### Local Development - Claude in VSCode For local Node.js execution: ```json { "servers": { "time-server": { "command": "node", "args": ["dist/index.js"], "env": {}, "cwd": "." } } } ``` ### Docker Deployment - Claude in VSCode #### Option 1: Docker Exec (Recommended) For a running Docker container: ```json { "servers": { "time-server": { "command": "docker", "args": ["exec", "-i", "time-mcp-server", "node", "dist/index.js"], "env": {} } } } ``` #### Option 2: Docker Run (Creates new container each time) ```json { "servers": { "time-server": { "command": "docker", "args": ["run", "--rm", "-i", "time-mcp-server"], "env": {} } } } ``` ### Combined Configuration (Both Docker and Local) Use this configuration to have both options available simultaneously: ```json { "servers": { "time-server-docker": { "command": "docker", "args": ["exec", "-i", "time-mcp-server", "node", "dist/index.js"], "env": {} }, "time-server-local": { "command": "node", "args": ["dist/index.js"], "env": {}, "cwd": "." } } } ``` **Benefits of combined configuration:** - ✅ **Fallback options** - If Docker is down, local still works - ✅ **Performance testing** - Compare Docker vs local performance - ✅ **Development flexibility** - Switch between deployment methods - ✅ **Redundancy** - Multiple servers provide the same functionality **Note:** Place your `mcp.json` file in the project root directory (same level as `package.json`) for relative paths to work correctly. ### Configuration Steps #### For Docker Setup: 1. **Start your Docker container:** ```bash docker-compose up -d ``` 2. **Verify container is running:** ```bash docker ps | grep time-mcp-server ``` 3. **Update mcp.json** with Docker configuration #### For Local Setup: 1. **Build the project:** ```bash npm run build # or ./ci.sh ``` 2. **Place mcp.json in project root** (same directory as package.json) 3. **Test it works:** ```bash npm test ``` #### For Combined Setup: 1. **Ensure both are working** (Docker container running + local build exists) 2. **Place the mcp.json in your project root directory** 3. **Use the combined mcp.json** configuration above ### Testing Your Configuration **Test Docker version:** ```bash echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | docker exec -i time-mcp-server node dist/index.js ``` **Test local version:** ```bash echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | node dist/index.js ``` **Check logs:** ```bash # Docker logs docker-compose logs -f time-mcp-server # Local logs appear in terminal when running ``` ## Quick Start Guide 1. **Build everything with CI script:** ```bash chmod +x ci.sh ./ci.sh ``` 2. **For Docker deployment:** ```bash # Ensure Docker Desktop is running docker ps # Build with Docker BUILD_TYPE=docker ./ci.sh # Start the container docker-compose up -d ``` 3. **Configure Claude in VSCode** with appropriate `mcp.json` ## Usage Examples Once configured with Claude in VSCode, you can ask natural language questions: - **"What time is it?"** → Returns current time - **"What time is it in New York?"** → Returns time in EST/EDT - **"Show me the time in 24-hour format"** → Returns time in 24-hour format - **"Get detailed time information"** → Returns comprehensive time data - **"What day is today?"** → Uses detailed info to show current day ## Development ### Project Structure ``` time-mcp-server/ ├── src/ │ └── index.ts # Main server code ├── dist/ # Built JavaScript (generated) ├── ci.sh # CI/CD build script ├── Dockerfile # Docker image definition ├── docker-compose.yml # Docker orchestration ├── .dockerignore # Docker build exclusions ├── package.json ├── tsconfig.json ├── .gitignore └── README.md ``` ### Local Development Scripts - `npm run build` - Build TypeScript to JavaScript - `npm run dev` - Build and run the server (for MCP clients) - `npm start` - Run the built server (for MCP clients) - `npm test` - Quick test to verify server is working ### CI/CD Build Script Use the included `ci.sh` script for automated building and testing: ```bash # Make executable (first time only) chmod +x ci.sh # Basic build and test ./ci.sh # Docker build only BUILD_TYPE=docker ./ci.sh # Full build (local + Docker) BUILD_TYPE=all ./ci.sh # Skip tests RUN_TESTS=false ./ci.sh # Custom Docker tag BUILD_TYPE=docker DOCKER_TAG=v1.0.0 ./ci.sh # CI environment CI=true ./ci.sh ``` **CI Script Features:** - ✅ Prerequisite checking (Node.js, Docker) - ✅ Automated building (TypeScript + Docker) - ✅ Comprehensive testing (tool listing, function calls) - ✅ Cross-platform compatibility (macOS/Linux) - ✅ Color-coded output and error handling - ✅ Build artifact generation ### Testing **Quick Test:** ```bash npm test ``` **Manual Testing:** ```bash # Test tool listing echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | node dist/index.js # Test getting current time echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "get_current_time", "arguments": {}}}' | node dist/index.js ``` **Note:** `npm start` and `npm run dev` will appear to "hang" - this is normal! The server is waiting for MCP protocol messages on stdin. Use the test commands above or configure with Claude to interact with it. ## Supported Timezones The server supports any valid IANA timezone identifier, including: - `America/New_York` - `Europe/London` - `Asia/Tokyo` - `Australia/Sydney` - `UTC` ## Dependencies - `@modelcontextprotocol/sdk` - Official MCP SDK - `typescript` - TypeScript compiler - `@types/node` - Node.js type definitions ## License MIT ## Contributing 1. Fork the repository 2. Create a feature branch 3. Make your changes 4. Build and test: `npm run build` 5. Submit a pull request ## Troubleshooting ### Common Issues **"No inputs were found" error:** - Ensure the `src/index.ts` file exists - Run `npm run build` after creating the file **Docker not working:** - Ensure Docker Desktop is installed and running: `brew install --cask docker` - Start Docker Desktop: `open -a Docker` (wait for whale icon in menu bar) - Verify with: `docker ps` (should not show connection errors) - Docker Desktop takes 30-60 seconds to fully start after launching **Server appears to hang:** - This is normal behavior! The server waits for MCP protocol messages on stdin - Use `npm test` for quick verification, or configure with Claude for actual usage - The server only responds when it receives proper JSON-RPC messages **TypeScript errors:** - Make sure all dependencies are installed: `npm install` - Check TypeScript version compatibility ### Debug Mode Add console logging by setting environment variables: ```json { "servers": { "time-server": { "command": "node", "args": ["/path/to/dist/index.js"], "env": { "DEBUG": "true" } } } } ``` ## Version History - **0.1.0** - Initial release with basic time functionality