moneypal-workspace

4. 配置宿主并首次查询

在 WorkBuddy 的用户级或项目级 mcp.json 中加入：

{
  "mcpServers": {
    "moneypal": {
      "command": "mcp-moneypal",
      "env": {
        "MONEYPAL_LEDGER_WORKSPACE": "/path/to/ledger-workspace"
      }
    }
  }
}

环境变量说明：

• MONEYPAL_LEDGER_WORKSPACE（必填）：账本工作区，须包含 default/main.beancount、default/accounts.beancount 和 default/transactions/。有多个账本时注册多个 mcpServers 条目，各自指向不同工作区。
• MONEYPAL_PYTHON（可选）：解释器的绝对路径；缺省使用共享托管运行时。
• MONEYPAL_BATCH_TTL_MS（可选）：写入预览批次的有效期（毫秒），默认 30 分钟；仅供测试调整。

配置后重启 WorkBuddy 即可。六个只读工具与 DSH 完全一致；每个成功的工具响应都带 serverToday（服务器本机时区当日），可与对话中的日期互相核对。工具描述要求所有日期参数使用绝对日期 YYYY-MM-DD；请直接给出绝对日期，避免“昨天”等相对表述被错误换算。余额以工具 JSON 输出呈现，余额抽屉保持 DSH Web 专属。

向助手发送：

账本里有哪些可用账户？然后检查账本是否有效。

能列出账户并通过校验，即表示宿主已连接账本。随后可按日常使用操作；需要助手遵循领域规则时，可安装可选领域技能。

日常使用

查询账户、流水与报表

直接描述需要的信息。以下明确日期的示例适用于两种宿主，请将日期、账户和金额替换为自己的实际情况。

想做什么	可以这样说
查账户	“账本里有哪些可用账户？”
查余额	“截至 2026-09-07，现金账户余额是多少？”
查流水	“列出 2026 年 8 月的餐饮支出。”
查损益	“生成 2026 年 8 月损益表。”
查资产负债	“查看截至 2026-08-31 的资产负债表。”
检查账本	“检查账本是否有效。”

DSH Web 支持按浏览器时区理解“今天”“昨天”；时间或时区不可用时会要求澄清。MCP 使用时请直接给出绝对日期，避免宿主错误换算相对日期。报表金额按币种或商品分别展示，不自动换汇。

记一笔交易

1. 提出需求：例如“记一笔 2026-09-07 的午餐 35 元，现金支付”。账户必须已在账本中声明；可先让助手列出账户。
2. 查看预览：核对日期、账户、金额、说明及重复提醒。此时账本尚未变化。
3. 确认或修改：DSH Web 会显示确认框，确认后才写入，取消或关闭则不写入；MCP 会在对话中展示预览，只有你明确确认后，助手才应提交。需要修改时，让助手重新生成预览再确认。
4. 核对结果：写入成功后，可以说“列出 2026-09-07 的午餐交易”，检查正式账本中的记录。

预览后账本发生变化或批次已过期，需要重新预览并确认。如果提示 write_outcome_uncertain，先查询正式账本确认是否已写入，再决定是否重试，不要直接重复提交。更多情况见常见问题。

运行时配置

默认使用 MoneyPal 的共享托管运行时。首次创建时，macOS/Linux 使用 python3，Windows 使用 py 作为引导解释器；需要指定其他 Python 3.11+ 时，可在对应的 setup-runtime 命令后追加 --python /absolute/path/to/python。

MONEYPAL_PYTHON 可指定外部解释器的绝对路径，须具备兼容版本的 Beancount 和 beanquery；确保宿主进程也能读取该变量。设置此变量后，setup-runtime 会拒绝修改外部环境：要使用托管环境，请先取消该变量；要使用外部环境，请自行准备依赖并通过 runtime-status 检查。

DSH CLI 提供预设安装、账本初始化、运行时安装和状态检查；MCP CLI 提供账本初始化、运行时安装和状态检查，无子命令时启动 stdio 服务器。两者均不提供直接查询或写入账本的 CLI 子命令，日常使用通过宿主内的财务工具完成。