# @notsuhas/moneylover-kit 中文文档

规范地址：https://npmcn.com/package/%40notsuhas/moneylover-kit/

版本：0\.5\.4
npm 元数据更新时间：2026-11-02T00:08:47.579Z
中文译文更新时间：2026-11-02T01:14:18.345Z
软件包许可：MIT

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40notsuhas/moneylover-kit
原文对照：https://npmcn.com/package/%40notsuhas/moneylover-kit/?lang=original
项目主页：https://github.com/notsuhas/moneylover-kit#readme
源码仓库：https://github.com/notsuhas/moneylover-kit

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：593 kB，161 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.13
- 运行依赖：2 个
- 首次发布：2026-09-11T07:41:18.613Z
- 最新版本发布：2026-11-02T00:08:47.286Z
- 已发布版本数：22（近 12 个月 22 个）

## 中文简介

非官方的钱情人客户端，CLI和MCP服务器。完整事务CRUD。

## 安装

```sh
npm install @notsuhas/moneylover-kit
```

也可以使用：`pnpm add @notsuhas/moneylover-kit`、`yarn add @notsuhas/moneylover-kit`、`bun add @notsuhas/moneylover-kit`

## README

# moneylover-kit

[![npm](https://img.shields.io/npm/v/@notsuhas/moneylover-kit)](https://www.npmjs.com/package/@notsuhas/moneylover-kit)

非官方的 [钱的情人](https://moneylover.me/) 客户端、CLI和MCP服务器。全 交易CRUD，贷款和文档化API -从您的电子邮件和密码， 没有别的东西可以设置。

与Money Lover或Finsify无关。Money Lover没有公共API；这 与自己的应用程序使用的相同端点进行通信。

## 为什么存在这个

其他Money Lover客户端可以创建和读取交易。他们都不能 **更新** 或者 **删除** 一，因为连线格式是一个完全替换- a 天真编辑默默地擦除人物、事件、排除报告标志 并且提醒贴在行上。这将重建实时的每个写入 行，因此编辑只更改您要求它更改的内容。

它还记录了花费实时时间来解决的部分：为什么是错误的 类别id挂起两分钟而不是错误，为什么空结果没有 一个空的账户，以及为什么登录两次会让你退出自己的手机。 看到 [文档/ traps.md](https://npmcn.com/package/%40notsuhas/moneylover-kit/docs/traps.md).

## 安装

```bash
npm install -g @notsuhas/moneylover-kit    # or npx @notsuhas/moneylover-kit
```

要从源代码运行它，请克隆并构建 `npm install -g github:notsuhas/moneylover-kit` 做 _不_ 工作，因为NPM 在准备git依赖时跳过devDependencies，并且没有编译器 构建:

```bash
git clone https://github.com/notsuhas/moneylover-kit && cd moneylover-kit
npm ci && npm run build && npm install -g .
```

然后设置你的证书：

```bash
export MONEYLOVER_EMAIL="you@example.com"
export MONEYLOVER_PASSWORD="…"
```

## 命令行界面

```bash
moneylover login                 # once — mints and caches a token
moneylover wallets               # names and balances
moneylover categories            # what you can write to
moneylover list --note coffee --from 2026-01-01 --limit 10

moneylover add  --wallet Cash --category Groceries --amount -480 --note "DMart"
moneylover edit <id> --note "DMart, cleaning supplies"
moneylover rm   <id>
```

钱包和类别：

```bash
moneylover add-wallet   --name Travel --currency 11
moneylover add-category --name Supplements --all-wallets --parent "Health"
moneylover edit-category --category Supplements --name Vitamins
moneylover rm-category  --category Vitamins
```

`--all-wallets` 和 `--parent` 需要 `--backend mobile`：一个跨越的类别 每个钱包，或者在另一个钱包下面，都生活在一个web API没有的层中 模型。

数量是 **签署**： `-480` 是花, `4500` 是获得。金钱爱好者商店 类别的方向而不是数量，所以这是一个不一致的标志 这一分类被拒绝，而不是悄然纠正。

`--json` 在任何命令上给出机器可读的输出。

### 贷款

Money Lover用自己的四种系统分类来追踪人们之间的金钱往来。 这样一来，应用程序的债务视图就能看到你记录的内容：

```bash
moneylover lend    --person Sam --amount 5000 --wallet Savings
moneylover collect --person Sam --amount 3000 --wallet Current --parent-id ORIGINAL_LOAN_ID
moneylover lending
```

```
person                          lent   collected   outstanding     you owe
Sam                          5000.00     3000.00       2000.00        0.00
Jordan                        800.00      800.00          0.00      450.00
```

钱包是一条腿，所以从一个账户贷款，然后还到另一个账户 不同的一个是正常的-余额被跟踪到 **人**，而不是。 帐户。 `borrow` 和 `repay` 是你所欠钱的镜子。集合和 需要还款 `--parent-id` 指向最初的贷款或债务。分裂一个 必要时跨原件付款；独立偏移量被拒绝，因为 他们打开应用程序的原始记录。

## MCP服务器

两个传输。两者都暴露了相同的工具： `list_wallets`， `list_categories`， `list_events`， `search_transactions`， `add_transaction`， `edit_transaction`， `delete_transaction`， `record_lending`， `lending_summary`.

管理钱包、分类和活动是可选的，在两个标志后面： `MONEYLOVER_MCP_ALLOW_STRUCTURE=1` 用于创建和编辑它们，以及 `MONEYLOVER_MCP_ALLOW_DELETE=1` 用于 `delete_wallet` 和 `delete_category`． 一个 Rename可以输入；删除钱包会获取其中的每笔交易 这两个API都没有撤消，这就是为什么它是自己的开关。

**本地，用于克劳德桌面/光标** -添加到您的MCP配置：

```json
{
  "mcpServers": {
    "moneylover": {
      "command": "npx",
      "args": ["-y", "-p", "@notsuhas/moneylover-kit", "moneylover-mcp"],
      "env": {
        "MONEYLOVER_EMAIL": "you@example.com",
        "MONEYLOVER_PASSWORD": "…"
      }
    }
  }
}
```

**远程，通过HTTP** -在某个地方运行它并指向一个客户端

```bash
MCP_TOKEN=$(openssl rand -hex 32) moneylover-mcp-http   # POST /mcp, GET /health
```

它拒绝在没有的情况下启动 `MCP_TOKEN`． 这个端点可以创建和删除 真实账户的交易；未经身份验证的端口永远不是正确的 违约。

**在码头工人** ——一个 `Dockerfile` 和 `compose.yaml` 都在回购中：

```bash
cp .env.example .env      # email, password, and an MCP_TOKEN
docker compose up -d      # POST localhost:8790/mcp
```

在…上装某事 `/config`，与撰写文件一样。这就是 令牌缓存存在，如果没有它，每次重新启动都会花费一个帐户的时间 设备槽。

完整的设置说明，包括如何阻止代理执行某些操作 不可逆转的: [文档/ mcp.md](https://npmcn.com/package/%40notsuhas/moneylover-kit/docs/mcp.md).

## 图书馆

```ts
import { createClient } from "@notsuhas/moneylover-kit";

const ml = createClient();

await ml.wallets();
await ml.transactions({ note: "coffee", from: "2026-01-01" });
await ml.addTransaction({
  wallet: "Cash",
  category: "Groceries",
  amount: -480,
});
await ml.lending("Sam");
```

CLI和MCP服务器都是薄薄的一层，所以它们不能这样做 图书馆做不到的任何事。

## 一次移动会话

当配置Android OAuth客户端时，每个正常的读取和事务 或类别编写使用移动API。钱包余额的推导完全为 应用程序派生它们：将同步的行以整数小单位求和并排除 future-dated事务。结果匹配了每个钱包的web API Live 11,239行帐户。

钱包过滤新鲜搜索和普通收据重复检查/读回 获取受影响钱包的最新完整快照，使用Android 应用程序的 `account_id` 请求过滤器。收据余额重复使用经过验证的钱包 快照。此快速路径不使用交叉调用TTL或增量游标，因此 外部编辑和删除在下一次操作中仍然可见。

全账户审计和关联贷款/债务验证保留完整的 和解。中断拉重新开始；部分页面 永远不要成为一个完整的快照。钱包范围内的读取不能取代其他读取 钱包。

启用移动：

```bash
export MONEYLOVER_MOBILE_CLIENT="…"
export MONEYLOVER_MOBILE_SECRET="…"
```

这些是Android应用程序自己的凭证，硬编码在它的每个副本中。他们 不是你的秘密，但它们不在这里公布——一个可搜索的公众 复制是让他们轮换的原因，这会破坏每个非官方客户 一次。 [文档/ api.md](https://npmcn.com/package/%40notsuhas/moneylover-kit/docs/api.md) 解释如何获得它们。

没有这两个价值，客户端显然是失败的；它永远不会落在网上 登录。 `--backend web` 仍然是一个明确的诊断逃生舱口。钱包 创建、重命名和删除也使用移动同步协议。

使用 `MONEYLOVER_MOBILE_TOKEN` 如果您直接提供令牌。通常情况下, 缓存的旋转刷新令牌更安全，因为它可以自我更新。

## 在你开始之前要知道一件事

**Money Lover账户只允许少量设备同时持有代币 目前是五个，而且每次登录都会注册另一个。** 没有东西被踢 当你达到极限时关闭；相反, _下一个_ 登录被拒绝，提示“Maximum。 已达到设备限制。请退出以继续。”所以你不会丢失数据 完全失去登录的能力，包括在更换的手机上，直到你 从您仍然拥有的设备注销。

这就缓存了你的令牌 `~/.config/moneylover-kit/` 并更新它 不需要注册另一个设备，所以服务维护自己没有 进一步的登录。移动路由是非标准的：Android应用程序发送一个空路由 身体 `oauth.moneylover.me/refresh-token` 使用刷新令牌为Bearer 身份验证。

集 `MONEYLOVER_ACCESS_TOKEN` 直接提供令牌而不登录。

## 环境

|  |  |
| --- | --- |
| `MONEYLOVER_EMAIL` · `MONEYLOVER_PASSWORD` | 凭证 |
| `MONEYLOVER_ACCESS_TOKEN` | 使用此令牌，永远不要登录 |
| `MONEYLOVER_BACKEND` | 力 `web` 或者 `mobile` |
| `MONEYLOVER_MOBILE_CLIENT` · `MONEYLOVER_MOBILE_SECRET` | 移动后端需要 |
| `MONEYLOVER_CONFIG_DIR` | 令牌缓存在哪里 |
| `MCP_TOKEN` · `MCP_PORT` · `MCP_HOST` | HTTP MCP传输 |
| `MONEYLOVER_MCP_ALLOW_STRUCTURE` | MCP：钱包/类别/事件写入 |
| `MONEYLOVER_MCP_ALLOW_DELETE` | MCP：删除钱包/类别 |

## 文档

-   [文档/ api.md](https://npmcn.com/package/%40notsuhas/moneylover-kit/docs/api.md) -两个api：验证，端点，项目形状
-   [文档/ traps.md](https://npmcn.com/package/%40notsuhas/moneylover-kit/docs/traps.md) ——所有需要花一天时间才能完成的事情
-   [文档/ mcp.md](https://npmcn.com/package/%40notsuhas/moneylover-kit/docs/mcp.md) -将MCP服务器连接到客户端
-   [规范/](https://npmcn.com/package/%40notsuhas/moneylover-kit/spec/) - OpenAPI规范的web API，加上观察到的模式

## 贡献

看到 [CONTRIBUTING.md](https://npmcn.com/package/%40notsuhas/moneylover-kit/CONTRIBUTING.md). `npm run verify` 运行类型检查，lint， 格式化和代码库健康门。

## 执照

麻省理工学院。用在你自己的账户上。

## 交易时间

编写工具接受可选 `dateTime` 而不是 `date`例如： `"2026-10-19T11:10:00+09:00"` 日本时间11:10打印的收据使用一个 完整的ISO时间戳，带秒和任选其一 `Z` 或显式的UTC偏移量。不 发送两个字段。只有日期的调用保持它们现有的行为；省略字段 在编辑保存节省的时间。对应的CLI是 `--date-time '2026-10-19T11:10:00+09:00'`． MCP事务结果包括 `dateTime` 当时间戳可用时。

### NPM可信发布设置

发布工作流使用GitHub OIDC而不是 `NPM_TOKEN`． 配置一个 在这个GitHub库的npm包上安装可信的发布者 `release.yml`，允许直接发布，不受环境限制。 保持 `repository.url` 与存储库保持一致。新配置的发布者 必须在两天内完成成功发布，否则NPM将过期。

如果在包读取工作时发布返回E404，请检查包是否受信任 替换令牌之前的发布服务器配置和存储库元数据。通过 CI没有验证npm发布授权；验证发布作业本身。

## 持久的MCP读取

MCP读取工具现在返回本地SQLite快照与显式 `sync` 元数据。 通过 `fresh: true` 查看审计或最新的上游状态。一个陈旧的阅读开始了。 背景和解;收据写入和验证总是使用新的API 读取。这减少了提供者的重复调用，而不会带来网络延迟。 要求节点为22.13+。看到 [MCP缓存](https://npmcn.com/package/%40notsuhas/moneylover-kit/docs/mcp.md) 对于迁移，响应 形状变化、恢复和私有体积要求。

## 常见问题

### @notsuhas/moneylover-kit 是什么？

非官方的钱情人客户端，CLI和MCP服务器。完整事务CRUD。

### 如何安装 @notsuhas/moneylover-kit？

在项目目录运行 npm install @notsuhas/moneylover-kit，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 moneylover、moneylover-mcp、moneylover-mcp-http，可以用 npx moneylover 直接运行。

### @notsuhas/moneylover-kit 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @notsuhas/moneylover-kit 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @notsuhas/moneylover-kit 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.13。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @notsuhas/moneylover-kit 可以商用吗？

@notsuhas/moneylover-kit 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @notsuhas/moneylover-kit 还在维护吗？

最新版本 0\.5\.4 发布于 2026/11/02（1 天前）；至今共发布 22 个版本，其中过去 12 个月发布了 22 个；首次发布于 2026/09/11。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。