# Life OKR MCP 官方说明

这是 Life OKR 的远程 MCP 服务说明文档。

## 文档语言

- 中文版：`https://life-okr.com/mcp.zh.md`
- English: `https://life-okr.com/mcp.en.md`

## 服务地址

- MCP endpoint: `https://life-okr.com/mcp`
- Web console: `https://life-okr.com/console/`
- 传输方式：Streamable HTTP
- 鉴权方式：`Authorization: Bearer <mcp_token>`

## OKR Skills

Life OKR 提供一组可选的 OKR skills，帮助 LLM 客户端按「星级 / 月级 / 日级」理清目标，并用 MCP 做复盘。

- 最新版本：`0.1.4`
- 下载地址：`https://life-okr.com/skills/okr-skills.zip`
- 当前版本固定地址：`https://life-okr.com/skills/okr-skills-0.1.4.zip`
- 包内包含：`okr-compose`（建立 OKR）和 `okr-review`（复盘与调整）

这个下载地址不需要登录。安装后，把 `okr-compose/` 和 `okr-review/` 放到你的客户端 skills 目录；连接本 MCP 后，skill 可以读取和写入同一个 Life OKR 账号的数据。

最新版本改进：
- Added startup version self-check guidance for okr-compose and okr-review.
- Added MCP-readable OKR skills version metadata for sandbox-limited clients.
- Documented latest-version comparison and update prompt behavior.

如果客户端无法直接访问公网文档或本地文件沙箱受限，可以通过 MCP 工具 `get_okr_skills_info` 查询最新版本、改进内容和下载地址。skill 启动时可把本地 `okr-skills/VERSION` 与该工具返回的 `latest_version` 对比；如果本地版本较旧，只提醒一次并询问用户是否下载更新，不要阻塞当前 OKR 流程。

## 必须先有 Token

连接这个 MCP 服务之前，你必须先有一枚 MCP token。

如果你还没有 token，流程很快：

1. 打开 Web 控制台。
2. 如果还没有账号，先用邮箱注册。
3. 登录后点击 MCP token 按钮，生成或复制 token。
4. 把 token 粘贴到你的 MCP 客户端里。

整个过程通常不到一分钟。

## 如何获取 Token

1. 打开 Web 控制台。
2. 如有需要，先用邮箱创建账号。
3. 使用你的 Life OKR 账号登录。
4. 从控制台复制 MCP token；如果需要，也可以重新生成。

## 支持的 MCP Tools

- `list_objectives`：返回当前账号下的全部 objectives。
- `get_objective`：返回单个 objective 及其 key results。
- `create_objective`：新建 objective。
- `update_objective`：更新标题、摘要、分类、profile、内置背景、开始时间、到期时间或占位进度。
- `delete_objective`：删除 objective。
- `set_objective_progress`：更新 objective 级别的占位进度。
- `get_objective_progress_history`：读取 objective 的进度更新时间线，可按时间范围过滤。
- `create_key_result`：给 objective 新增 key result，可附带当前值、目标值与单位。
- `update_key_result`：编辑 key result 的标题、标签、样式、到期时间、进度、当前值、目标值或单位。
- `delete_key_result`：删除 key result。
- `get_key_result_progress_history`：读取单个 key result 的进度更新时间线，可按时间范围过滤。
- `list_background_images`：列出当前账号上传过的自定义背景图。
- `upload_background_image`：上传 base64 图片并返回 `background_image_key`。
- `assign_background_image`：把已上传图片绑定到 objective，或者清除自定义图片。
- `replace_objective_background_from_base64`：上传新图片并立即绑定到 objective。
- `get_sync_snapshot`：返回原始同步快照和 revision 元数据。
- `get_okr_skills_info`：返回 OKR skills 最新版本、改进内容和公开下载地址，便于客户端做升级提示。

`create_objective` 和 `update_objective` 支持可选的 ISO-8601 `start_at` 与 `due_at` 字段。
`create_key_result` 和 `update_key_result` 支持可选的 ISO-8601 `due_at` 字段。

## 内置规则

- Objective progress 的取值范围是 `0.0` 到 `1.0`。
- 当 objective 下存在 key results 时，新增、更新或删除 KR 会把 objective progress 重算为当前 KR progress 的平均值；`set_objective_progress` 主要保留给没有 KR 的 objective 和旧客户端兼容。
- Objective 的 `start_at` 与 `due_at` 都是可选字段；`start_at` 表示目标开始时间，`due_at` 表示目标截止时间。
- Key result progress 的取值范围是 `0.0` 到 `1.0`。
- Key result 的 `current_value`、`target_value` 与 `unit` 是可选字段；旧客户端可以忽略。
- 自定义 objective 图片必须先上传到同一个用户账号下。
- 所有工具都只操作 bearer token 对应的账号数据。

## Objective 字段语义

这些说明是给 LLM 和其他 MCP 客户端直接消费的，请不要自行脑补字段含义。

- `category_raw_value`：objective 所属领域。当前线上支持 `work` 和 `life`。
- `category_raw_value=work`：偏工作、职业、学习、项目推进类目标。
- `category_raw_value=life`：偏个人生活、健康、家庭、关系、生活方式类目标。
- `profile_raw_value`：objective 所属时间周期层级，不是用户 profile，也不是权限 profile。
- `profile_raw_value` 当前线上支持 `sun`、`moon`、`star`，默认值是 `sun`。
- `profile_raw_value=sun`：日级或短周期目标，通常以 7、14、30 天为一个周期。
- `profile_raw_value=moon`：月级或中周期目标，通常以 3、6 个月为一个周期。
- `profile_raw_value=star`：年级或长周期目标，通常以 1-3 年为一个周期。
- 如果用户没有明确说明，一般优先使用已有 objective 上已经出现过的 `profile_raw_value`；新建 objective 时 `profile_raw_value=sun` 是安全的短周期默认值，但 `category_raw_value` 必须先确认 Work / Life，不能静默默认。

## 兼容性原则

- 当 Life OKR 主体功能改动影响到 MCP 行为、字段或能力时，这份对外文档必须同步更新。
- MCP 的线上变更应坚持增量兼容，不能删除、降级或悄悄改变现有正常可用的能力，避免影响已经接入的用户。

## 推荐给 LLM 的提示词

请把下面这段规则一并给到 LLM：

```md
You are connected to the Life OKR MCP server.

Always inspect existing objectives before making destructive changes.
Prefer `update_objective` and `update_key_result` over delete/recreate.
When changing an objective image:
1. Use `list_background_images` to discover existing images.
2. If you already have image bytes, use `upload_background_image` or `replace_objective_background_from_base64`.
3. Use `assign_background_image` to switch an objective to a known `background_image_key`.

Keep progress values within 0.0 and 1.0.
Preserve existing `start_at` values unless the user explicitly asks to change them.
Preserve existing `due_at` values unless the user explicitly asks to change them.
Preserve existing `key_results` unless the user explicitly asks to remove them.
Treat `profile_raw_value` as the planning horizon, not a user profile.
Current production values:
- `category_raw_value`: `work` | `life`
- `profile_raw_value`: `sun` | `moon` | `star`
```

## 远程 MCP 配置示例

```json
{
  "name": "life-okr",
  "type": "streamable-http",
  "url": "https://life-okr.com/mcp",
  "headers": {
    "Authorization": "Bearer YOUR_MCP_TOKEN"
  }
}
```

## 备注

- 当前服务使用项目签发的 bearer token，而不是完整的 OAuth discovery 流程。
- 这枚 bearer token 来自同一个 Life OKR 账号，但与 iOS App 的同步 token 分离。