内容
# Momentum
一款能回答 *"我现在应该专注于什么?"* 的 MCP 服务器，适用于多个工作流——客户、项目、计划——并提供 **可审计的评分**，而非猜测。
指向克劳德（或任何 MCP 客户端）并询问 "what now?"，它会返回一个排名列表，其中每个位置都有解释：*11 天未更新，逾期 2 天，有收入*。排名通过确定性的 Python 代码计算，不涉及语言模型。
---
## 为什么存在
大多数 "AI 生产力" 工具让模型来排名优先级。这不是模型应该做的事情。排名需要 **一致性**（相同的输入每次产生相同的顺序）和 **可解释性**（可以清楚地看到为什么某项排名第一）。语言模型天生不具备这些特性——它们不确定，其推理过程也无法检查。
因此，Momentum 将任务分开：
- **代码决定排名。** 四个加权因素，根据您的数据计算，完全可复制。
- **模型处理语言和判断。** 它决定 **何时** 调用工具，解释您的简写（"刚刚完成了 ACME 规格"），并以对话式呈现结果。
这是设计良好的代理系统背后的相同原理：保持确定性的热点路径在代码中，将模型保留在真正需要判断的部分。这更容易信任，更容易调试，也不会漂移。
---
## 评分机制
每个活跃的工作流都通过四个因素评分，范围从 0 到 100，结合您在配置文件中设置的权重：
| 因素 | 衡量内容 |
| --- | --- |
| **陈旧度** | 工作流距其审查周期有多远。未更新 11 天的每周工作流被视为陈旧；今天更新则重置为零。 |
| **截止日期压力** | 距离最近目标或任务截止日期的接近程度，截止日期临近时增加，一旦逾期则达到最大值。 |
| **收入权重** | 可配置的收入工作重点，具有可选的工作日/周末分割，以便在工作日将计费客户工作排在内部工作之上。 |
| **级联风险** | **陈旧的上游依赖** 传播的风险。如果工作流 A 以 `strong` 边提供给工作流 B，而 A 变为陈旧，则 B 的风险增加——因为 B 即将被阻塞。 |
**每日容量检查**（能量 1-5，可用专注小时）会在上面应用状态修饰器。在低能量日，引擎倾向于您标记为低努力兼容的工作流，因此在下午精力不足时，提案后续工作会被显示，而不是板上最艰难的构建。
所有内容——权重、分级阈值、节奏定义、每个工作流的收入和低容量值——都存储在 JSON 配置文件中，并且可以热加载。重新调整排名无需触及代码。
---
## 工具
| 工具 | 用途 |
| --- | --- |
| `get_now` | 头条信息：逾期任务、当日任务、排名前 5 的工作流，附带下一步行动和原因。 |
| `compute_priorities` | 强制重新排名。传递 `energy_override` 以预览容量水平将如何重新排列排名。 |
| `quick_update` | 记录工作流进度并设置下一步行动。重新排名并报告新位置。 |
| `write_checkin` | 记录每日容量/能量；当能量 ≤ 2 时触发低容量模式。 |
| `list_workstreams` | 工作流投资组合，可按状态筛选。 |
| `workstream_status` | 完整的工作流报告：状态、日志、目标、依赖、任务、优先级历史。 |
| `workstream_manage` | 创建/暂停/存档/重新调整工作流节奏。 |
| `sync_tasks` | 将外部任务（来自任务工具 MCP）上载到工作流缓存。 |
| `mark_task_disposition` | 记录任务结果并返回路由，以便克劳德将更改推送到上游。 |
| `reload_config` | 在不重启的情况下重新读取配置文件。 |
### 跨 MCP 代理模式
MCP 服务器不能直接调用另一个 MCP 服务器。Momentum 需要来自任务工具（TickTick、ClickUp）的实时任务数据，但通过 **克劳德作为代理** 保持依赖关系自由：
1. `sync_tasks` 获取克劳德已读取的任务工具 MCP 的行并在本地缓存，以便截止日期因素纳入评分。
2. `mark_task_disposition` 更新本地缓存 **并返回一个 `routing` 块**，指定确切的下游 MCP 工具和参数，克劳德然后执行该调用。
服务器从不跨边界到达；它向克劳德提供精确的指令，让模型桥接两个服务器。这样，Momentum 保持自包含和可移植，适用于任何工作流使用的任务工具。
---
## 快速入门
```bash
python -m venv .venv && source .venv/bin/activate
pip install fastmcp
# 创建并初始化演示数据库（小型咨询投资组合）
MOMENTUM_DB_PATH=./momentum.db python init_db.py
# 从示例创建配置文件
cp config.example.json config.json
# 运行服务器
MOMENTUM_DB_PATH=./momentum.db MOMENTUM_CONFIG_PATH=./config.json python server.py
```
然后使用您的 MCP 客户端注册它。克劳德桌面配置示例（`claude_desktop_config.json`）：
```json
{
"mcpServers": {
"momentum": {
"command": "/path/to/.venv/bin/python",
"args": ["/path/to/momentum-mcp/server.py"],
"env": {
"MOMENTUM_DB_PATH": "/path/to/momentum.db",
"MOMENTUM_CONFIG_PATH": "/path/to/config.json"
}
}
}
}
```
**将所有 `/path/to/` 替换为机器上的实际绝对路径**——解释器、`server.py`、数据库和您的配置文件。使用从 `/Users/...` 开始的完整路径；`~` 不可靠地扩展。留下的占位符是日志中 "Failed to spawn process" 错误的最常见原因。
重启您的 MCP 客户端，然后询问克劳德： *"我现在应该专注于什么?"* → 它调用 `get_now` 并带您浏览排名列表。
### 调整排名
`config.json` 是您自定义权重、分级阈值、收入规则和低容量拟合的地方——编辑它以匹配您自己的工作流。每个键都是可选的；您省略的任何内容都会回落到引擎默认值，因此最小化的配置文件也适用。`config.json` 被 gitignore，因此您的实际调整永远不会进入仓库。使用 `reload_config` 工具在不重启的情况下应用编辑。
---
## 设计笔记
- **配置优于代码。** 没有硬编码的用户或业务特定值。权重、阈值、节奏和每个工作流的规则都是外部的且可热加载的。默认配置在没有任何文件的情况下也能正常运行。
- **配置失败时快速报错。** 所需路径来自 MCP 客户端设置的环境变量。缺少的 `MOMENTUM_DB_PATH` 在导入时是硬错误，而不是静默的故障。
- **工具从不引发异常。** 每个工具返回 `{"status": "ok" | "error", ...}`。错误的输入表现为模型可以读取和转发的结构化错误，而不是杀死会话的堆栈跟踪。
- **SQLite 以 WAL 模式运行，启用外键。** 持久、可并发读取、零基础设施。
- **工具描述是为模型编写的。** 每个文档字符串清楚地说明何时调用工具并消除可能的混淆（例如，"workstreams" 是您跟踪的工作领域，而非 DNS 域）——因为模型无法可靠地选择的工具是无效的。
## 来源
Momentum 是一个开放的、通用的核心，源自作者为同时运行多个业务和研究项目而构建的私有个人操作系统 MCP 服务器。评分引擎、跨 MCP 代理模式和配置驱动的架构直接从该系统提取并为专业工作流投资组合重新构建。 同样的引擎可以配置为对任何一组争夺有限注意力和资源的项目或个人事项进行排名。
## 许可证
MIT.
