mcp-timekeeper/DEVELOPMENT.md

MCP server for timezone conversion and time utilities

# Development Guide

This guide provides development setup, testing, and contribution instructions for MCP Timekeeper.

## Development Setup

### Prerequisites

- Node.js (ES modules enabled via `"type": "module"`)
- TypeScript for development
- MCP SDK for protocol implementation

### Installation

1. Clone the repository:
   ```bash
   git clone <repository-url>
   cd mcp-timekeeper
   ```

2. Install dependencies:
   ```bash
   npm install
   ```

## Development Commands

### Build
```bash
npm run build             # Compile TypeScript to dist/ using tsc
```

### Run

**Development mode with auto-restart:**
```bash
npx nodemon --exec "npx ts-node src/index.ts"
```

**Direct execution:**
```bash
npx ts-node src/index.ts
```

**Production mode:**
```bash
npm run build
npm start                 # Run compiled server (requires build first)
```

### Testing

**Interactive testing with MCP Inspector:**
```bash
mcp-inspector npx ts-node src/index.ts
```

This opens a web interface where you can test all the time conversion tools interactively.

## Project Structure

```
/
├── src/
│   └── index.ts          # Main MCP server implementation
├── package.json          # Dependencies and scripts
├── README.md             # User-facing documentation
├── DEVELOPMENT.md        # This file - development guide
├── CLAUDE.md             # Claude Code integration guide
└── node_modules/         # Dependencies
```

## Architecture Overview

### MCP Server Implementation

The server implements the Model Context Protocol using the `@modelcontextprotocol/sdk` and provides eight core tools:

- **Transport**: Uses STDIO transport for MCP communication
- **Validation**: Zod schemas validate all tool inputs with regex patterns for time formats
- **Error Handling**: All tools return structured error messages on failure
- **Timezone Handling**: Uses `Intl.DateTimeFormat` for timezone conversions and locale formatting
- **Time Parsing**: Supports both HH:MM and ISO datetime formats as input
- **Architecture**: Single-file implementation with helper functions for core time operations

### Core Helper Functions

- `convertTime()`: Main timezone conversion logic using Intl API
- `getTimezoneOffset()`: Calculates timezone offset in minutes
- `toUnixTimestamp()`: Converts ISO dates to Unix timestamps
- `getCurrentTime()`: Gets current time in specified timezone
- `getClientTime()`: Gets client system time with timezone and offset information
- `addTime()`: Adds/subtracts time periods using native Date methods
- `getTimeDifference()`: Calculates time differences in various units
- `formatTime()`: Custom and locale-aware date/time formatting
- `getTimezoneInfo()`: Comprehensive timezone information including DST detection

## Tool Implementation Details

### Input Validation

All tools use Zod schemas for input validation:

```typescript
const ConvertTimeSchema = z.object({
  source_timezone: z.string(),
  time: z.string().regex(/^(\d{1,2}:\d{2}|\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2})/, 
    "Time must be in HH:MM format or ISO datetime format"),
  target_timezone: z.string()
});
```

### Error Handling

All tools follow a consistent error handling pattern:

```typescript
try {
  // Tool implementation
  return { success: true, result: data };
} catch (error) {
  return { 
    success: false, 
    error: error instanceof Error ? error.message : String(error) 
  };
}
```

## Testing Guidelines

### Manual Testing with MCP Inspector

1. Start the MCP Inspector:
   ```bash
   mcp-inspector npx ts-node src/index.ts
   ```

2. Open the web interface (usually http://localhost:5173)

3. Test each tool with various inputs:
   - Valid timezone identifiers
   - Edge cases (DST transitions, leap years)
   - Invalid inputs (to test error handling)
   - Different time formats

### Test Cases to Verify

**convert_time:**
- Valid timezone conversions
- HH:MM vs ISO datetime formats
- DST boundary conditions
- Invalid timezone handling

**time_to_unix:**
- Various ISO formats
- With and without timezone specification
- Invalid date formats

**get_current_time:**
- Different timezones
- System timezone default
- Invalid timezone handling

**get_client_time:**
- System time retrieval
- Timezone detection
- UTC offset calculation

**add_time:**
- All time units (years, months, days, hours, minutes, seconds)
- Positive and negative amounts
- Month/year boundary handling
- Leap year considerations

**time_difference:**
- Various units
- Positive and negative differences
- Same date/time handling

**format_time:**
- Standard formats (full, long, medium, short, date, time, iso)
- Custom format patterns
- Different locales
- Timezone formatting

**timezone_info:**
- Various timezone identifiers
- DST status detection
- Current vs specific date queries

## Contributing

### Code Style

- Use TypeScript with strict mode
- Follow existing naming conventions
- Add JSDoc comments for public functions
- Use consistent error handling patterns

### Making Changes

1. Make changes to `src/index.ts`
2. Test using MCP Inspector: `mcp-inspector npx ts-node src/index.ts`
3. Build and test: `npm run build && npm start`
4. Update documentation if needed

### Publishing

1. Update version in package.json
2. Build the project: `npm run build`
3. Test the built version works
4. Publish: `npm publish`

### Pull Request Guidelines

- Test all changes thoroughly with MCP Inspector
- Update documentation for any API changes
- Ensure backwards compatibility
- Add appropriate error handling
- Follow existing code patterns

## Debugging

### Common Issues

**MCP Connection Issues:**
- Ensure STDIO transport is working correctly
- Check for proper JSON-RPC formatting
- Verify tool registration

**Timezone Issues:**
- Use IANA timezone identifiers
- Be aware of DST transitions
- Test with various locales

**Time Parsing Issues:**
- Validate input formats
- Handle edge cases (leap years, month boundaries)
- Test with different time representations

### Debug Output

Add debug logging to understand tool execution:

```typescript
console.error(`Debug: Converting ${time} from ${source_timezone} to ${target_timezone}`);
```

Note: Use `console.error` for debug output as `console.log` interferes with MCP STDIO communication.

## MCP Integration

The server runs as a standalone process communicating via STDIO. It registers with an MCP-compatible client that can invoke the timezone tools. The server uses the standard MCP protocol for tool registration and execution.

### MCP Protocol Flow

1. Client connects via STDIO
2. Server registers available tools
3. Client requests tool execution
4. Server validates input and executes tool
5. Server returns structured response
6. Client processes and displays result