内容
# ATimeLogger MCP 服务器
一个独立的 MCP（模型上下文协议）服务器，通过 stdio 向 Claude Desktop / Claude Code 公开 ATimeLogger REST API。范围：活动（开始/停止/暂停/记录）、报告/历史记录和活动类型。
## 设置
需要 Node 20+。
1. 在 ATimeLogger 网页应用中生成 **个人访问令牌**：**设置 → API 令牌 → 生成令牌**。该值（以 `atl_pat_` 开头）仅显示 **一次** — 立即复制。你可以随时在同一页面撤销该令牌。
2. 构建服务器并注册它：
```bash
npm install
npm run build
npm run setup # 粘贴令牌，验证它，打印注册命令
```
设置脚本为两个客户端打印即用注册代码段：
**Claude Code** — 一行命令：
```bash
claude mcp add atimelogger \
-e ATL_TOKEN=atl_pat_... \
-- node /绝对路径/to/atimelogger-mcp/dist/index.js
```
**Claude Desktop** — 一个 JSON 块，合并到 `~/Library/Application Support/Claude/claude_desktop_config.json`（macOS）或 `%APPDATA%\Claude\claude_desktop_config.json`（Windows），然后重启 Claude Desktop：
```json
{
"mcpServers": {
"atimelogger": {
"command": "node",
"args": ["/绝对路径/to/atimelogger-mcp/dist/index.js"],
"env": {
"ATL_TOKEN": "atl_pat_..."
}
}
}
}
```
服务器默认面向生产环境（`https://app.atimelogger.pro`）— 无需配置 URL。要针对不同的后端工作，请显式设置 `ATL_BASE_URL`：将 `--url <base-url>` 传递给设置脚本（或设置环境变量），它将在打印的代码段中包含 `ATL_BASE_URL`。在指向 MCP 的相同服务器的网页 UI 中生成令牌。
故障排除：来自任何工具的 401 表示令牌无效、已过期或已被撤销 — 在 **设置 → API 令牌** 中生成新的令牌，并更新 MCP 配置中的 `ATL_TOKEN`。
## 远程服务器（用于 Notion 自定义代理和其他远程 MCP 客户端）
相同的工具可以通过 **可流式 HTTP** MCP 传输在网络上提供服务，这样托管的客户端（如 **Notion 自定义代理**）可以通过 URL 连接，而不是启动本地进程。
```bash
npm install
npm run build
ATL_TOKEN=atl_pat_... MCP_AUTH_TOKEN=some-long-secret npm start
# → 流式 HTTP MCP 端点位于 http://0.0.0.0:3000/mcp （健康检查：/health）
```
环境变量（参见 `.env.example`）：
| 变量 | 必需 | 目的 |
|---|---|---|
| `ATL_TOKEN` | 是 | ATimeLogger 个人访问令牌，服务器作为其代理 |
| `MCP_AUTH_TOKEN` | 推荐 | 调用 `/mcp` 所需的共享密钥（作为 `Authorization: Bearer …`、`x-mcp-token` 或 `?token=` 发送）。如果未设置，则端点是开放的 |
| `ATL_BASE_URL` | 否 | 非生产后端（默认为 `https://app.atimelogger.pro`） |
| `PORT` | 否 | 监听端口（默认为 `3000`；大多数主机都会注入它） |
| `MCP_PATH` | 否 | 端点路径（默认为 `/mcp`） |
> 一个部署 = 一个 ATimeLogger 账户（服务器作为单个 `ATL_TOKEN` 代理）。由于 URL 是面向互联网的，请设置 `MCP_AUTH_TOKEN` 并通过 HTTPS 提供服务。
### 获取公共 URL
**一键部署（Render）** — 在此仓库在 GitHub 上后，点击按钮（或用你的复刻替换 URL）：
[](https://render.com/deploy?repo=https://github.com/YOUR_GITHUB_USERNAME/atimelogger-mcp)
Render 读取捆绑的 `render.yaml`，然后提示你输入两个密钥 `ATL_TOKEN` 和 `MCP_AUTH_TOKEN`。当完成后，你的端点是 `https://<service>.onrender.com/mcp`。
其他选项：
- **Docker / VPS** — `docker compose up -d --build`（先填充 `.env`），然后将 HTTPS 放在前面（Caddy/Nginx/Cloudflare Tunnel）。
- 任何 Node 20+ 主机都有效：`npm ci && npm run build && npm start`.
详细的分步部署 + 配置（中文）：[`DEPLOY.zh-CN.md`](./DEPLOY.zh-CN.md).
### 连接到 Notion
打开你的 Notion **自定义代理 → 工具和访问 → 添加 MCP 服务器**，粘贴 `…/mcp` URL，并提供 `MCP_AUTH_TOKEN` 作为 bearer/access 令牌。完整分步指南（中文）：[`NOTION_MCP_GUIDE.zh-CN.md`](./NOTION_MCP_GUIDE.zh-CN.md). 设计/原理：[`docs/REMOTE_MCP_DESIGN.zh-CN.md`](./docs/REMOTE_MCP_DESIGN.zh-CN.md).
## 工具
| 工具 | 目的 |
|---|---|
| `get_current_status` | 运行/暂停活动及已用时间 |
| `list_activity_types` | 作为组树（其他工具名称的来源）活动类型名称 |
| `start_activity` | 按类型名称启动；可选回溯（`at` 壁钟时间或 `started_minutes_ago`） |
| `stop_activity` | 停止活动（如果只有一个活动，则名称可选）；相同的回溯选项 |
| `pause_resume_activity` | 暂停或恢复 |
| `log_interval` | 回溯记录已完成的条目（壁钟时间，可选注释/标签） |
| `time_report` | 按类型聚合统计数据，适用于某个时间段（`today`、`this_week`、`last_month`，… 或明确的日期） |
| `list_intervals` | 按天分组的原始历史记录，分页，最大 100 天范围 |
工具接受人类可读的类型名称（模糊匹配）；内部 ID 也通过工具输出和参数进行精确目标定位，但从不显示给用户。持续时间以 `"2h 15m"` 字符串形式返回；除非提供 `timezone` 参数，否则时间均显示为用户的 ATimeLogger 时区。
## 使用示例
服务器注册后，你可以向助手发出以下命令：
**计时器**
> "开始跟踪工作" · "停止计时器" · "暂停阅读，我 10 分钟后回来" · "我现在正在跟踪什么？"
**回溯** — 忘记按开始或停止：
> "开始开发 — 我实际上在 11:30 开始的" · "停止工作，我 20 分钟前完成了" · "我从 14:00 开始开会，记录它"
**记录过去的活动**
> "记录昨晚 9 点到 11 点的 2 小时阅读时间" · "为上周六早上添加一个健身房会话，90 分钟，标记为 '腿'" · "我从 23:30 睡到 7:15，记录它"
**报告和历史记录**
> "我的一周去哪了？" · "我在 6 月工作了多少时间，按周分解？" · "比较这个月和上个月的睡眠时间" · "显示我今天跟踪的所有内容" · "上周哪一天的开发时间最多？"
**组合** — 助手自动链接工具：
> "停止正在运行的活动并开始工作" · "从上一个条目结束的地方继续 — 从那个时间开始开发" · "用阅读内容填充昨天的午餐和会议之间的空隙"
活动名称与你自己的类型列表进行模糊匹配，因此 "start dev" 可以找到 "Development"；当名称不明确时，助手会询问。
## 限制
- `start_activity` 无法附加注释（底层启动端点仅接受类型和时间）；使用 `log_interval` 记录带有注释/标签的条目。
- 现有条目无法编辑（服务器端更新 API 不完整）。
- 历史记录请求受后端限制，最大范围为 100 天。
