# Time Manager MCP（STDIO Server）

这是一个基于 SQLite 的 MCP STDIO Server：让 Codex/LLM 通过 MCP tools 读写任务、状态、计划与日志，并返回可口播的指标面板数据。

你通常不需要“手动运行”它；更推荐把它作为 MCP Server 配进 Codex CLI，由 Codex 自动拉起。

## 解决什么样的痛点
当我们想在一段时间里，学习某项技能，某些知识，同时又担心因为生活并不非如同计划表一样严格可控的时候，这个项目将帮助你协调时间。我曾经在假期里做了非常详尽的计划，但是总因为各种原因不能很好的执行，然后一步乱步步乱，最后离预设的目标很远。但是依赖于ai的灵活性，当我的原定计划被某些因素影响，我不得不调整我的规划的时候，ai就可以出来重新整理规划我的计划，让我在合适的时间里做正确的事，让我把我欠的“债”还好。

## 它怎么工作
### 任务与信息入库
在初次使用的时候，用户输入自然语言（当然最好是有规律的，比如：一个b站视频播放列表），然后ai替你把这些东西填到数据库里，变成一条条的结构化数据。
### 生成明日计划与存档
用户给自然语言告诉ai明日可用时段与精力，ai读取任务、截止日期、最近日志、债务、状态等上下文然后生成计划，给你看，并且写进日志里。
### 完成汇报与进度更新
每天晚上睡觉之前，跟ai汇报你干了什么，没干什么，它会更新你的状态，并且记录你的债务（没干完的），然后再问他明天该干什么了。

## 你能得到什么

把“时间规划/复盘/进度统计”变成一组可被 LLM 调用的本地工具：LLM 负责对话与规划，Server 负责把数据可靠地落到 SQLite 并计算面板指标。
- 一个本地 SQLite 数据库（默认在 `./data/app.db`），存任务/日志/计划/设置
- 一组 MCP tools（见下方）供 LLM 调用

# 安装
# 如果你图省事可以直接让ai替你装（毕竟这只是个无伤大雅的小玩具）

## 如果你执意自己安装
推荐用 `uv`，也支持 `pip`。

```powershell
# 方式 A：uv
pip install uv
uv pip install -e .

# 方式 B：pip
# pip install -e .
```

## 数据库位置（重要）

- 默认数据库：`./data/app.db`（相对于启动 MCP Server 时的 `cwd`）
- 想把数据放到仓库外（推荐）：设置环境变量 `TIME_MANAGER_MCP_DB_PATH`

例如（Windows，建议放 D 盘）：

```powershell
$env:TIME_MANAGER_MCP_DB_PATH = "D:\\time_manager_mcp\\data\\app.db"
```

## 配置到 Codex CLI（推荐用法）

### 方式 A：`codex mcp add`

```powershell
codex mcp add time_manager_mcp -- python -m time_manager_mcp
```

### 方式 B：编辑 `~/.codex/config.toml`

把 `cwd` 改成你本机的仓库绝对路径：

```toml
[mcp_servers.time_manager_mcp]
command = "python"
args = ["-m", "time_manager_mcp"]
cwd = "<ABS_PATH_TO_THIS_REPO>"
```

如果你需要固定数据库路径（推荐），请在启动 Codex 前设置 `TIME_MANAGER_MCP_DB_PATH`，或者把它写进系统环境变量里。

## 可用 Tools（给 LLM 调用）

- `tasks_upsert`
- `state_set_current`
- `plan_save_day`
- `tasklog_append`
- `debtlog_append`
- `settings_set`
- `context_get_snapshot`
- `dashboard_get_metrics`

## 最小调用示例（按顺序）

1) `tasks_upsert`

```json
{
  "tasks": [
    { "title": "线性代数刷题", "category": "math", "course_minutes": 240, "estimate_factor": 1.3 },
    { "title": "Python 刷题", "category": "python", "course_minutes": 180 },
    { "title": "Linux 基础", "category": "linux", "course_minutes": 120 }
  ]
}
```

2) `state_set_current`

```json
{
  "energy": "mid",
  "note": "1) 专注/执行状态：轻度疲劳但可持续\n2) 固定约束：01:30 后不学习\n3) 目标变化：优先 python\n4) 环境/资源限制：只有笔记本\n5) 风险与干扰源：消息打断"
}
```

3) `plan_save_day`

```json
{
  "date": "2026-01-24",
  "energy": "mid",
  "availability_slots": [{ "start": "19:30", "end": "22:30" }],
  "items": [
    {
      "start": "19:30",
      "end": "20:30",
      "task_id": "YOUR_TASK_ID",
      "minutes": 60,
      "video_from": "45",
      "video_to": "46",
      "note": "看视频 + 做随堂笔记"
    }
  ]
}
```

4) `dashboard_get_metrics`

```json
{ "week_start": "2026-01-20", "week_end": "2026-01-26" }
```

## 常见问题
我目前没遇到问题，我也不知道这个东西会有什么问题
，如果真遇到了，就提个issue吧，谢谢了