lifeos

LifeOS MCP 服务

使用官方 MCP SDK、Node 22.9+（推荐 24）和 Zod 验证的本地 stdio 服务。所有工具都通过 HTTP 调用 LifeOS /api/v1。不提供 SQL、文件系统、任意状态键、配置或凭据管理工具。

安装和运行

cd mcp
npm ci
cp .env.example .env
npm start

设置被忽略的 .env：

LIFEOS_BASE_URL=https://lifeos.example.com
LIFEOS_API_TOKEN=replace-with-your-dedicated-random-token
LIFEOS_MCP_TIMEOUT_MS=10000

使用 PHP 中配置的同一个专用令牌（至少 32 个字符；生成 32 个随机字节）。请先安装 API。远程源站必须使用已验证的 HTTPS；仅在 localhost/127.0.0.1/::1 开发时允许 HTTP。URL 中的凭据、查询字符串和子路径都会被拒绝。为防止转发凭据，重定向会被拒绝。超时时间涵盖响应解析，且必须为 100–120000 ms。标准输出仅包含协议消息；启动和错误日志不会记录令牌或上游响应正文。

npm start 会从 mcp 加载 .env。直接启动 node src/index.js 的客户端必须提供环境变量。请勿提交真实的客户端配置或令牌。

客户端配置

此服务已发布到 npm，名称为 @edicodes/lifeos-mcp，并以 io.github.edrisranjbar/lifeos 列入 MCP Registry，因此客户端无需克隆仓库即可运行：

{
  "mcpServers": {
    "lifeos": {
      "command": "npx",
      "args": ["-y", "@edicodes/lifeos-mcp"],
      "env": {
        "LIFEOS_BASE_URL": "https://lifeos.example.com",
        "LIFEOS_API_TOKEN": "replace-with-your-dedicated-random-token"
      }
    }
  }
}

若要改为运行你自己的检出版本，请将客户端指向 src/index.js：

{
  "mcpServers": {
    "lifeos": {
      "command": "node",
      "args": ["/absolute/path/lifeos/mcp/src/index.js"],
      "env": {
        "LIFEOS_BASE_URL": "https://lifeos.example.com",
        "LIFEOS_API_TOKEN": "replace-with-your-dedicated-random-token"
      }
    }
  }
}

对于 Codex，请在其启动环境中设置令牌，并按照 OpenAI 官方文档在用户的 ~/.codex/config.toml 中传递该令牌：

[mcp_servers.lifeos]
command = "node"
args = ["/absolute/path/lifeos/mcp/src/index.js"]
env_vars = ["LIFEOS_API_TOKEN"]

[mcp_servers.lifeos.env]
LIFEOS_BASE_URL = "https://lifeos.example.com"
LIFEOS_MCP_TIMEOUT_MS = "10000"

请使用实际的绝对路径。不会自动安装任何客户端配置。此实现仅支持 stdio；需要远程 MCP URL 的客户端必须使用单独的、经过身份验证的传输桥接/服务。/api/v1 不是 MCP 传输 URL。

工具

领域	工具
读取任意内容	lifeos_query
目标	lifeos_create_goal, lifeos_update_goal, lifeos_delete_goal
任务	lifeos_create_task, lifeos_update_task, lifeos_complete_task, lifeos_delete_task
习惯	lifeos_complete_habit, lifeos_uncomplete_habit
财务	lifeos_log_expense, lifeos_set_income
笔记	lifeos_create_note, lifeos_update_note, lifeos_delete_note

所有读取操作都通过只读工具 lifeos_query 完成。其 type 参数决定读取内容：dashboard、goals、goal、tasks、task、habits、today_habits、finance_summary、expenses、incomes、notes 或 note。goal、task 和 note 需要提供 id。tasks 可选接受 source、goal_id、board_id 和 column_id 过滤条件；task 接受 source、goal_id 和 board_id，以便解析有歧义的 ID。finance_summary、expenses 和 incomes 可选接受 period。notes 和 note 可接受 include_secret。不适用于所选 type 的参数会在发出请求前被拒绝。写入操作仍由独立工具处理，因此每个工具都会单独请求批准，具有破坏性的操作也会明确标记。

从 1.x 升级： 2.0.0 版本用 lifeos_query 替代了 12 个读取工具（lifeos_dashboard、lifeos_list_goals、lifeos_get_goal、lifeos_list_tasks、lifeos_get_task、lifeos_list_habits、lifeos_get_today_habits、lifeos_finance_summary、lifeos_list_expenses、lifeos_list_incomes、lifeos_list_notes、lifeos_get_note）。例如，lifeos_get_goal 接受 { id }，现在对应 lifeos_query 接受 { type: "goal", id }。直接调用旧名称的客户端需要更新；启动时发现工具的客户端只需重启。

更新操作接受 id 和一个 patch 对象。patch 中提供的目标衡量指标和任务会替换原有列表；未提供的字段则保留。创建任务必须提供 source 和容器 ID。更新、完成或删除任务时，可选提供 source/容器过滤条件以解析有歧义的 ID；请先查询 tasks 以获取 ID。财务金额的单位为 Toman；period 默认为 active。完成/取消完成/设置收入操作均为幂等操作。删除操作会永久移除数据，并明确标记为具有破坏性；批准行为由客户端控制。

默认情况下会省略私密笔记，包括直接查找的结果。对 notes/note 查询或更新/删除显式设置 include_secret: true 需要服务端权限。Dashboard 始终不会包含私密内容。任何工具都不会返回令牌。成功时返回简洁的 JSON 文本和结构化的 {data: ...}；失败时返回 isError: true 以及安全的 code/message/status。

示例提示词：

• 显示我的 LifeOS 仪表板。
• 创建一个名为 Build dream home studio、三个月后到期的 SMART 目标。
• 将 Buy acoustic panels 添加为该目标的任务。
• 将今天的 Reading 标记为已完成。
• 记录一笔 450,000 Toman 的食品支出。
• 显示我当前的财务余额。
• 创建一条名为 Studio Ideas 的笔记。

外部编辑后请重新加载浏览器。过时的 UI 保存会返回冲突，而不是覆盖 API 更改。网络超时可能发生在写入提交之后；重试非幂等的创建/支出调用前，请先检查已保存的状态。

测试

npm test

默认运行模拟的错误/超时/格式错误响应、架构验证和真实的 stdio 握手。要对可丢弃的 MySQL/API 环境进行集成测试，请参阅根目录 README，并设置 LIFEOS_TEST_BASE_URL=http://localhost:8000。集成测试会拒绝远程主机，并要求提供 tests/mysql_fixture.php；它不会加载生产配置。