timer-mcp

# timer-mcp

An MCP server that lets AI agents manage **multiple named countdown timers** in memory. Great for timeboxing tasks, Pomodoro sessions, or reminding you when something is due.

## Installation

```bash
git clone <repo-url> && cd timer-mcp
npm install
```

## Configuration

Add to your MCP client config:

### VS Code (`.vscode/mcp.json`)

```json
{
  "mcpServers": {
    "timer-mcp": {
      "command": "node",
      "args": ["c:/dev/timer-mcp/server.js"]
    }
  }
}
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "timer-mcp": {
      "command": "node",
      "args": ["/path/to/timer-mcp/server.js"]
    }
  }
}
```

## Tools

| Tool | Description |
|------|-------------|
| `timer_start` | Start a named timer. `name: string`, `duration: string` (e.g. `"5m"`, `"30s"`, `"1h"`). Returns timer ID + end time. |
| `timer_pause` | Pause a running timer by name. Freezes remaining time. |
| `timer_resume` | Resume a paused timer by name. Continues from where it left off. |
| `timer_stop` | Stop/cancel a timer by name. Removes it completely. |
| `timer_status` | Check remaining time on a timer. Returns `running` / `paused` / `done` state + time left. |
| `timer_list` | List all active timers with their name, state, and remaining time. |

## Duration Format

Accepts shorthand with `h`, `m`, `s` units. Composite formats are supported:

| Input | Meaning |
|-------|---------|
| `30s` | 30 seconds |
| `5m` | 5 minutes |
| `1h` | 1 hour |
| `90s` | 90 seconds (1.5 minutes) |
| `2m30s` | 2 minutes 30 seconds |
| `1h15m` | 1 hour 15 minutes |
| `1h5m10s` | 1 hour 5 minutes 10 seconds |

## Timer States

```
running → pause → paused → resume → running → ... → done (expired)
                                                → stopped (canceled)
```

| State | Meaning |
|-------|---------|
| `running` | Timer is actively counting down |
| `paused` | Timer is frozen, remaining time preserved |
| `done` | Timer expired — auto-cleaned on next `timer_status` or `timer_list` call |
| `stopped` | Timer was explicitly cancelled and removed |

## Edge Cases

- **Name collision** — `timer_start` rejects if a timer with the same name is already `running` or `paused`
- **Double pause/resume** — returns a friendly message; no error
- **Expired timers** — auto-removed from the store when queried via `timer_status` or `timer_list`
- **Non-existent names** — all tools return a clear `"No timer found"` error

## Tech Stack

- **Runtime**: Node.js (ESM)
- **Transport**: stdio
- **Dependencies**: `@modelcontextprotocol/sdk` only
- **Persistence**: In-memory only (stateless across restarts)

## License

MIT