# 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