内容
# 计时器MCP ⏱ — 用于Claude的语音计时器
毫秒级精度的MCP计时器服务器。对Claude说“开始计时” — 时钟在服务器的单调纳秒时钟上开始，实时墙面显示在您的浏览器中亮起，当您说“停止”时，Claude会像赛道播音员一样宣布官方时间。
```
🏁 停止计时！ 'ship the landing page' 完成于 4:07.312！
🏆 新个人最佳成绩 — 比旧记录快 18.455 秒！
```
使用免费的云连接器（[timermcp.com](https://timermcp.com)），倒计时直接在聊天中显示为实时滴答卡 — 桌面和移动设备：
## 为什么毫秒是准确的（延迟数学）
您在 **t₀** 说“开始”；命令经过延迟 **d₁** （输入 + 模型 + 传输）到达服务器。服务器记录 **S₁ = t₀ + d₁**。您在 **t₁** 说“停止”，记录 **S₂ = t₁ + d₂**。
```
reported = S₂ − S₁ = (t₁ − t₀) + (d₂ − d₁)
```
两个时间戳都是在**服务器端**获取的，因此管道延迟的常数部分会**抵消**。只有启动侧和停止侧延迟之间的*差值*可能会泄漏 — 而对于对称调用，这个差值很小。所有数学运算都在 `process.hrtime.bigint()`（单调纳秒）上运行，不受 NTP 跳跃和 DST 的影响。
如果您认为您的管道是不对称的，可以通过 `timer_config` 进行偏差校正：`start_offset_ms` / `stop_offset_ms`，从每个结果中减去。`raw_elapsed_ms`（纯单调）始终与调整后的 `elapsed_ms` 一起返回。
## 设置
**前提条件：** Node.js ≥ 18（`node --version`）。
TimerMCP 已在 npm 上发布 — 无需克隆或构建。
**Claude 代码**（一条命令）：
```bash
claude mcp add timermcp -- npx -y timermcp
claude mcp list # 显示 timermcp ✓ 已连接
```
**Claude 桌面版** — 编辑 `claude_desktop_config.json`:
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- Linux: `~/.config/Claude/claude_desktop_config.json`
```json
{
"mcpServers": {
"timermcp": {
"command": "npx",
"args": ["-y", "timermcp"]
}
}
}
```
<details>
<summary>从克隆运行（用于开发）</summary>
```bash
git clone https://github.com/julanbasnet/timermcp.git
cd timermcp
npm install && npm run build
node dist/index.js --version # 打印横幅并退出
npm run smoke # 完整的 18 项断言套件
claude mcp add timermcp -- node /absolute/path/to/timermcp/dist/index.js
```
在 Windows 上，在配置路径中使用正斜杠或转义反斜杠：`"C:/tools/timermcp/dist/index.js"`。
</details>
添加后，完全退出并重新打开客户端（桌面版：从菜单/托盘退出，而不是简单地关闭窗口）。说 *"开始计时"* 并打开 **http://localhost:5717** — 墙面显示。
**检查器（可选）：** `npx @modelcontextprotocol/inspector npx -y timermcp`，用于交互式工具控制台。
## 与其交互
| 您说的话 | 工具 | 会发生什么 |
|---|---|---|
| "开始计时" | `timer_start` | 单调起始时间戳 + 播音员调用 |
| "开始一个 25 分钟的番茄工作" | `timer_start` (`target_ms`) | 倒计时模式；停止时报告超时/不足 |
| "与构建比赛：启动 alice 和 bob" | `timer_start` (`"alice,bob"`) | 两个计时器在**同一纳秒**开始 |
| "分段 — 英雄部分完成" | `timer_split` | 类似 LiveSplit 的圈数，delta 与 PB 节奏 🟢🔴 |
| "到现在为止多长时间了？" | `timer_status` | 服务器端实时读取 |
| "停止计时" | `timer_stop` | 官方毫秒数，PB 检查，SVG 结果卡 |
| "错误开始，取消它" | `timer_cancel` | 丢弃历史记录而不影响 |
| "我的记录是什么？" | `timer_history` | PB，近期运行，生命周期总数 |
| "将播音员切换到训练班长" | `timer_config` | hype · zen · sergeant · sports · minimal |
## 特点
- **实时墙面显示** — 电光青色计时控制台，位于 `localhost:5717`，每毫秒通过 SSE 流式传输。将其放在第二显示器或手机上；当 Claude 操作时，它会立即反应。按钮 + 键盘（空格 = 分段，enter = 开始/停止）也可在浏览器中使用，包括用于浏览器启动的番茄工作计时器目标字段。
- **倒计时提示音** — 在墙面显示上翻转 🔔 声音切换，倒计时在零点时大声提示。（默认关闭；浏览器需要一次点击才能播放音频。）
- **经验值，等级和成就** — 每次完成运行和跟踪的分钟数都能获得经验值。从 ROOKIE 到 TIME LORD 共 10 个等级，每天一个连胜计数器和 12 个奖章成就架（PHOTO FINISH，RECORD BREAKER，BULLSEYE，MIDNIGHT OIL，RACE DAY…），所有这些都源自您的本地历史记录。升级和解锁会触发祝贺 + 彩带。
- **个人最佳成绩和速度通关分段** — 每个命名计时器都保留一个 PB。分段与 PB 运行中的相同检查点进行比较，类似 LiveSplit： *"1.204 超过 PB 节奏 🟢"*. 新记录时的彩带。
- **比赛模式** — 逗号分隔的名称在一个共享的纳秒时间戳上启动（测试中测量的 Δ：0.003ms）。
- **结果卡** — 每次停止都会写入 1200×630 SVG 完成卡（`~/.timermcp/cards/`，也在 `/card/{id}` 处提供）。为 X/LinkedIn 截图准备就绪。
- **播音员个性** — 默认情况下为 hype 比赛播音员； zen，drill sergeant，broadcast 或 minimal。
- **崩溃安全** — 状态持续到 `~/.timermcp/state.json`；在时钟精度下重启后恢复运行的计时器（标记为 `recovered`）。
## 环境
| 变量 | 默认值 | |
|---|---|---|
| `TIMERMCP_PORT` | `5717` | 仪表盘端口 |
| `TIMERMCP_HOST` | `127.0.0.1` | 设置为 `0.0.0.0` 以从局域网中的其他设备查看（无身份验证 — 仅限受信任的网络） |
| `TIMERMCP_HOME` | `~/.timermcp` | 状态 + 卡目录 |
| `TIMERMCP_NO_DASHBOARD` | 未设置 | `1` 禁用 HTTP 服务器 |
## 故障排除
- **Claude 中未显示工具** → 配置路径必须是绝对的；完全退出并重新启动客户端。服务器日志（stderr）记录在客户端的 MCP 日志中 — macOS: `~/Library/Logs/Claude/mcp-server-timermcp.log`，Windows: `%APPDATA%\Claude\logs\`。
- **仪表盘无法加载 / 日志中“端口被占用”** → 另一个 TimerMCP 实例占用了 5717。Claude Desktop 和 Claude Code 都会启动**它们自己的**服务器进程；计时器在两者中仍然有效，但给第二个实例设置 `TIMERMCP_PORT=5718`（及其自己的 `TIMERMCP_HOME`，如果您想要单独的 PB — 否则 `state.json` 是最后写入的胜者）。
- **`node dist/index.js` 似乎挂起** → 正常；stdio 服务器等待客户端。使用 `--version` 进行健全性检查。
- **时间看起来几乎相同但相差一个常数** → 这是差异延迟；通过 `timer_config` 设置 `start_offset_ms` / `stop_offset_ms`（参见上面的延迟数学）。
## 测试
```bash
npm run smoke # 19 项断言：协议，计时精度，偏移量，比赛 Δ，仪表盘，卡片
```
MIT.
