@fangcuntai/fangcuntai-mcp 1.6.5 → 1.6.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.en.md CHANGED
@@ -1,31 +1,31 @@
1
1
  # @fangcuntai/fangcuntai-mcp
2
2
 
3
- Fangcuntai Desktop Assistant MCP server. Connect it to Lobster / OpenClaw, Claude Desktop, Cursor, or another MCP-compatible client to query family ledgers and notes, organize notes, and safely write data after user confirmation.
3
+ Fangcuntai Desktop Assistant MCP server. Connect it to Lobster / OpenClaw, Claude Desktop, Cursor, or another MCP-compatible client to query family ledgers and notes, organize notes, and write official data after you confirm.
4
4
 
5
5
  [简体中文](https://unpkg.com/@fangcuntai/fangcuntai-mcp/README.md)
6
6
 
7
- ## Features
7
+ ## What it can do
8
8
 
9
- - Switch between families and ledger books.
10
- - Query summaries, entries, trends, and categories.
11
- - Create, delete, and restore ledger entries behind a write confirmation lock.
12
- - Browse and search notes, organize two-level note folders, and create note drafts. Write to-dos as `- [ ]` / `- [x]`; link another note with `[[title]]`.
13
- - Review and confirm AI drafts.
14
- - Check subscription status and AI credit balance.
15
- - Track writes created by the desktop assistant.
9
+ - **Query the ledger**: switch families and ledger books, and view summaries, entries, trends, and categories.
10
+ - **Write ledger entries**: create, update, delete, restore, or empty the recycle bin behind the write confirmation lock.
11
+ - **Notes**: browse, search, create, and move notes, and organize two-level folders. Write to-dos as `- [ ]` / `- [x]`; reference another note with `[[title]]`.
12
+ - **Links**: attach a note to a ledger entry, or unlink them.
13
+ - **Account**: check subscription status and AI credit balance.
14
+ - **Traceable**: writes carry a source marker and can be traced in the Fangcuntai app.
16
15
 
17
16
  The MCP server accesses the Fangcuntai API only. It does not connect directly to the database.
18
17
 
19
- ## Requirements
18
+ ## Quick start
19
+
20
+ ### 1. Prepare
20
21
 
21
22
  - Node.js 18 or later.
22
23
  - A Fangcuntai account.
23
- - A desktop assistant token created in the Fangcuntai app:
24
- **Me > Settings > Connect Desktop Assistant**.
24
+ - A desktop assistant token created in the Fangcuntai app: **Me → AI settings → Connect Desktop Assistant**.
25
25
 
26
- You can choose the default family and permissions when creating the token. The token is shown only once and can be revoked in the app at any time.
26
+ Choose the default family and permissions when creating the token. The token is shown only once; existing tokens cannot be changed, so revoke and create a new one if needed.
27
27
 
28
- ## Configuration
28
+ ### 2. Configure
29
29
 
30
30
  Add this server to your MCP-compatible desktop client:
31
31
 
@@ -42,7 +42,7 @@ Add this server to your MCP-compatible desktop client:
42
42
 
43
43
  You can also copy the complete configuration from the **Connect Desktop Assistant** page in the Fangcuntai app.
44
44
 
45
- ### Environment variables
45
+ ### 3. Environment variables
46
46
 
47
47
  | Variable | Required | Description |
48
48
  |----------|----------|-------------|
@@ -51,19 +51,37 @@ You can also copy the complete configuration from the **Connect Desktop Assistan
51
51
 
52
52
  Production API: `https://api-service.fangcuntai.com`
53
53
 
54
+ Local development API: `http://127.0.0.1:9080`
55
+
56
+ ## Token permissions
57
+
58
+ Select permissions when creating the token. `read:family` is added automatically by the server.
59
+
60
+ | Permission | Used for |
61
+ |------------|----------|
62
+ | `read:ledger` | Reading ledger entries, single entries, and categories |
63
+ | `read:stats` | Reading summaries and trends |
64
+ | `write:notes` | Creating, moving, and deleting notes; folders; notes recycle bin |
65
+ | `write:ledger` | Creating, updating, and deleting ledger entries; ledger recycle bin |
66
+
67
+ Linking a note and a ledger entry requires both `write:notes` and `write:ledger`.
68
+
69
+ Old tokens with `write:draft` are treated as `write:notes` during authentication. To use newer capabilities, create a new token in the app.
70
+
54
71
  ## Security model
55
72
 
56
73
  Write access is locked by default.
57
74
 
58
- 1. After the user explicitly agrees, call `unlock_writes`.
59
- 2. Prepare the write and show its summary to the user.
60
- 3. Complete the write with a one-time confirmation token only after the user confirms.
75
+ 1. After you explicitly agree, call `unlock_writes` with `user_acknowledged=true`.
76
+ 2. Prepare the write with `prepare_*`; it returns a summary and a one-time `confirm_token`.
77
+ 3. After you confirm, call the matching `confirm_*` tool to write official data.
61
78
 
62
79
  Other safeguards:
63
80
 
64
- - The server validates the token permissions selected in the app.
81
+ - Unlock expires after about 15 minutes and is extended by each `prepare_*` call; confirmation tokens expire after about 2 minutes.
82
+ - Token permissions are chosen in the app and checked again by the server.
65
83
  - A token is bound to a default family and can only switch to families the user has joined.
66
- - Deleted ledger entries and notes are moved to the recycle bin.
84
+ - Deleted ledger entries and notes are moved to the recycle bin and can be restored. Emptying the recycle bin is permanent.
67
85
  - Ledger writes are marked with the `desktop_mcp` source.
68
86
  - Requests include `X-App-ID: 60000` and `X-MCP-Tool` for auditing.
69
87
 
@@ -71,33 +89,77 @@ Other safeguards:
71
89
 
72
90
  ### Query the ledger
73
91
 
74
- `list_my_families` -> `select_family` -> `list_ledger_books` -> `select_ledger_book` -> `get_ledger_summary`
92
+ `list_my_families` → `select_family` → `list_ledger_books` → `select_ledger_book` → `get_ledger_summary`
93
+
94
+ For a period ledger, omitting the month returns the lifetime total for that event, not a monthly total.
75
95
 
76
96
  ### Create a ledger entry
77
97
 
78
- `unlock_writes` -> `prepare_create_ledger_entry` -> user confirmation -> `confirm_create_ledger_entry`
98
+ `unlock_writes` → `prepare_create_ledger_entry` → user confirmation → `confirm_create_ledger_entry`
79
99
 
80
- ### Link a note to a bill
100
+ You can pass `external_order_id` (Alipay / WeChat / bank transaction ID). If the same ID already exists in the ledger book, the entry is not duplicated.
81
101
 
82
- Entry lists only include `has_visible_related_note`, never note titles. `get_ledger_entry` returns titles the member can see. `get_note` returns related amounts only when the token can read the ledger.
102
+ ### Update a ledger entry
83
103
 
84
- Link or unlink existing records: `unlock_writes` -> `prepare_link_ledger_note` / `prepare_unlink_ledger_note` -> show the title, date, category, and amount -> `confirm_link_ledger_note` / `confirm_unlink_ledger_note`. Both write scopes are required.
104
+ `unlock_writes` → `prepare_update_ledger_entry` → user confirmation → `confirm_update_ledger_entry`
85
105
 
86
- When a new bill and a new note are created in the same turn, pass the same `link_group`. The link is written only after both saves succeed.
106
+ Only entries added in the last month can be updated. Income and expense cannot be switched.
87
107
 
88
- ### Update a ledger entry
108
+ ### Create a note
109
+
110
+ `unlock_writes` → `prepare_create_note` → user confirmation → `confirm_create_note`
111
+
112
+ `folder_id` 0 or omitted means uncategorized. To link the new note to existing ledger entries, pass `related_entry_ids`. When creating a new ledger entry and a new note in the same turn, pass the same `link_group` to both.
113
+
114
+ ### Link a note to a ledger entry
115
+
116
+ Ledger entry lists only include `has_visible_related_note`, never note titles. Use `get_ledger_entry` to read an entry; use `get_note` to read a note. Related amounts are omitted when the token cannot read the ledger.
117
+
118
+ Link or unlink existing records:
119
+
120
+ `unlock_writes` → `prepare_link_ledger_note` / `prepare_unlink_ledger_note` → show the title, date, category, and amount to the user → `confirm_link_ledger_note` / `confirm_unlink_ledger_note`
121
+
122
+ Linking itself does not count against the monthly ledger entry limit.
89
123
 
90
- `unlock_writes` -> `prepare_update_ledger_entry` -> user confirmation -> `confirm_update_ledger_entry` (only entries added in the last month)
124
+ ### Organize note folders
91
125
 
92
- ### Organize notes
126
+ `list_note_folders` → `unlock_writes` → `create_note_folder` / `rename_note_folder` / `move_note_folder`
93
127
 
94
- `list_note_folders` -> `unlock_writes` -> `create_note_folder` / `rename_note_folder` / `move_note_folder`
128
+ Folders can be at most two levels deep. Deleting an empty folder requires `prepare_delete_note_folder` → `confirm_delete_note_folder`.
95
129
 
96
130
  ### Restore deleted items
97
131
 
98
- Ledger entries: `list_ledger_trash` -> `restore_ledger_entry`
132
+ Ledger entries: `list_ledger_trash` → `restore_ledger_entry`
99
133
 
100
- Notes: `list_notes_trash` -> `restore_note`
134
+ Notes: `list_notes_trash` → `restore_note`
135
+
136
+ Emptying the recycle bin is permanent and requires `prepare_*` → `confirm_*`.
137
+
138
+ ## Updates
139
+
140
+ When a desktop client starts the server with `npx -y @fangcuntai/fangcuntai-mcp`, it uses npm's `latest` tag. Restart the client after a new release; no configuration change is needed.
141
+
142
+ Check the latest version:
143
+
144
+ ```bash
145
+ npm view @fangcuntai/fangcuntai-mcp version
146
+ ```
147
+
148
+ Pin a specific version:
149
+
150
+ ```json
151
+ {
152
+ "args": ["-y", "@fangcuntai/fangcuntai-mcp@1.6.7"]
153
+ }
154
+ ```
155
+
156
+ ## Troubleshooting
157
+
158
+ - **Missing `FANGCUNTAI_TOKEN`**: make sure the client's `env` contains the `hm_at_` token created in the app.
159
+ - **`40305` or a missing-permission error**: create a new token in the app with the required permissions. Existing tokens cannot be expanded.
160
+ - **Write operation is locked**: explain the risk to the user, call `unlock_writes`, then use `prepare_*` → `confirm_*`.
161
+ - **Only entries from the last month can be updated**: edit older entries in the app, or ask Xiaojiaoshi to update them.
162
+ - **Cannot reach the API**: the local default is `http://127.0.0.1:9080`; for production set `FANGCUNTAI_API` to `https://api-service.fangcuntai.com`.
101
163
 
102
164
  ## Local development
103
165
 
@@ -127,6 +189,8 @@ The command only writes to the local development database and can be run repeate
127
189
  npm publish --access public
128
190
  ```
129
191
 
192
+ Use `npm publish --dry-run --access public` to inspect the package before publishing.
193
+
130
194
  ## Links
131
195
 
132
196
  - Website: https://www.fangcuntai.com
package/README.md CHANGED
@@ -1,29 +1,31 @@
1
1
  # @fangcuntai/fangcuntai-mcp
2
2
 
3
- 方寸台桌面助手 MCP 服务。连接后可在有道龙虾 / OpenClaw、Claude Desktop、Cursor 等支持 MCP 的桌面客户端中,用自然语言查询家庭账本、整理记事,并在确认后安全地写入数据。
3
+ 方寸台桌面助手 MCP 服务。连接后可在有道龙虾 / OpenClaw、Claude Desktop、Cursor 等支持 MCP 的桌面客户端中,用自然语言查询家庭账本、整理记事,并在你确认后写入正式数据。
4
4
 
5
5
  [English](https://unpkg.com/@fangcuntai/fangcuntai-mcp/README.en.md)
6
6
 
7
- ## 功能
7
+ ## 能做什么
8
8
 
9
- - 切换家庭和账本,查询收支摘要、账单、趋势与分类。
10
- - 在确认锁保护下记账、删除、恢复回收站和清空回收站。
11
- - 查看和搜索记事,整理两层记事文件夹,创建记事草稿。待办写成 `- [ ]` / `- [x]`,一篇可用 `[[标题]]` 连到另一篇。
12
- - 查看并批量确认 AI 草稿,查询订阅和 AI 积分。
13
- - 写入数据带来源标记,可在方寸台 App 中追踪。
9
+ - **查账**:切换家庭和账本,查看收支摘要、流水、趋势和分类。
10
+ - **记账**:在确认锁保护下记一笔、改一笔、删除,以及恢复或清空回收站。
11
+ - **记事**:查看、搜索、新建、移动记事,整理两层文件夹。待办写成 `- [ ]` / `- [x]`,可用 `[[标题]]` 引用其他记事。
12
+ - **挂接**:把一篇记事和一笔账挂在一起,或拆开。
13
+ - **账号**:查询订阅状态和 AI 积分。
14
+ - **可追踪**:写入带来源标记,可在方寸台 App 中看到是桌面助手写的。
14
15
 
15
16
  MCP 只访问方寸台 API,不直连数据库。
16
17
 
17
- ## 前置条件
18
+ ## 快速开始
19
+
20
+ ### 1. 准备
18
21
 
19
22
  - Node.js 18 或更高版本。
20
23
  - 一个方寸台账号。
21
- - 在方寸台 App 中生成桌面助手令牌:
22
- **我的 → 设置 → 连接桌面助手**。
24
+ - 在方寸台 App 生成桌面助手令牌:**我的 → AI 配置 → 连接桌面助手**。
23
25
 
24
- 生成令牌时可选择默认家庭和权限。令牌明文只显示一次,可在 App 中随时撤销。
26
+ 生成令牌时选择默认家庭和权限。令牌明文只显示一次;已有令牌不能改权限,需要撤销后重新生成。
25
27
 
26
- ## 配置
28
+ ### 2. 配置
27
29
 
28
30
  把以下配置添加到支持 MCP 的桌面客户端:
29
31
 
@@ -40,7 +42,7 @@ MCP 只访问方寸台 API,不直连数据库。
40
42
 
41
43
  也可以从方寸台 App 的「连接桌面助手」页面复制完整配置。
42
44
 
43
- ### 环境变量
45
+ ### 3. 环境变量
44
46
 
45
47
  | 变量 | 必填 | 说明 |
46
48
  |------|------|------|
@@ -49,21 +51,39 @@ MCP 只访问方寸台 API,不直连数据库。
49
51
 
50
52
  生产 API:`https://api-service.fangcuntai.com`
51
53
 
54
+ 本地开发 API:`http://127.0.0.1:9080`
55
+
56
+ ## 令牌权限
57
+
58
+ 生成令牌时按需勾选。`read:family` 由服务端自动带上,不需要手动选择。
59
+
60
+ | 权限 | 用途 |
61
+ |------|------|
62
+ | `read:ledger` | 查账单、单笔明细、分类 |
63
+ | `read:stats` | 查收支摘要、趋势 |
64
+ | `write:notes` | 新建 / 移动 / 删除记事,整理文件夹,记事回收站 |
65
+ | `write:ledger` | 记账、改账、删除,账单回收站 |
66
+
67
+ 挂接记事和账单需要同时勾选 `write:notes` 和 `write:ledger`。
68
+
69
+ 旧令牌里的 `write:draft` 会在鉴权时自动按 `write:notes` 处理;想使用新能力,建议在 App 里重新生成令牌。
70
+
52
71
  ## 安全模型
53
72
 
54
73
  桌面助手默认处于写锁状态。
55
74
 
56
- 1. 用户明确同意后,调用 `unlock_writes` 解锁。
57
- 2. 写操作先生成待确认内容并展示摘要。
58
- 3. 用户确认后,才使用一次性确认令牌完成写入。
75
+ 1. 你明确同意后,调用 `unlock_writes`(`user_acknowledged=true`)解锁。
76
+ 2. 写操作先调用 `prepare_*`,返回待确认摘要和一次性 `confirm_token`。
77
+ 3. 你确认后,再调用对应的 `confirm_*` 写入正式数据。
59
78
 
60
79
  此外:
61
80
 
81
+ - 解锁后约 15 分钟会过期,每次 `prepare_*` 会续期;确认码约 2 分钟过期。
62
82
  - 令牌权限由 App 生成时决定,服务端会再次校验。
63
- - 令牌绑定默认家庭,会话中只能切换到用户已加入的其他家庭。
64
- - 删除的账单和记事进入回收站,可以恢复。
83
+ - 令牌绑定默认家庭,会话中只能切换到用户已经加入的其他家庭。
84
+ - 删除的账单和记事进入回收站,可以恢复;清空回收站不可恢复。
65
85
  - 写入账单的来源标记为 `desktop_mcp`。
66
- - 请求使用 `X-App-ID: 60000` 和 `X-MCP-Tool` 便于审计。
86
+ - 请求使用 `X-App-ID: 60000` 和 `X-MCP-Tool`,便于审计。
67
87
 
68
88
  ## 常用流程
69
89
 
@@ -71,32 +91,76 @@ MCP 只访问方寸台 API,不直连数据库。
71
91
 
72
92
  `list_my_families` → `select_family` → `list_ledger_books` → `select_ledger_book` → `get_ledger_summary`
73
93
 
94
+ 一件大事账本不传月份时,返回整件事的累计,不是某一个月。
95
+
74
96
  ### 记一笔
75
97
 
76
98
  `unlock_writes` → `prepare_create_ledger_entry` → 用户确认 → `confirm_create_ledger_entry`
77
99
 
78
- ### 记事和账单挂在一起
100
+ 可传 `external_order_id`(支付宝 / 微信 / 银行流水号)。同一账本已有相同订单号时,不会重复入账。
79
101
 
80
- 流水列表只有 `has_visible_related_note`,不带篇名。看一篇用 `get_ledger_entry`(要能看见那篇记事)。看一笔相关账单用 `get_note`,没有记账读取权限时不返回金额。
102
+ ### 改一笔
81
103
 
82
- 挂上或拆开已经存在的记录:`unlock_writes` → `prepare_link_ledger_note` / `prepare_unlink_ledger_note` → 向用户展示篇名、日期、分类和金额 → `confirm_link_ledger_note` / `confirm_unlink_ledger_note`。需要同时勾选写入账单和写入草稿。
104
+ `unlock_writes` → `prepare_update_ledger_entry` → 用户确认 → `confirm_update_ledger_entry`
83
105
 
84
- 同一回合新建账单和记事时,两边传同一个 `link_group`。只有两边都保存成功才挂上;丢掉一边就不会挂。挂接本身不占每月记账条数。
106
+ 只支持修改最近 1 个月内添加的流水;收入和支出不能互改。
85
107
 
86
- ### 改一笔
108
+ ### 新建记事
109
+
110
+ `unlock_writes` → `prepare_create_note` → 用户确认 → `confirm_create_note`
111
+
112
+ `folder_id` 为 0 或省略表示未分类。要挂到已经存在的账单时传 `related_entry_ids`;同一回合新建账单和记事时,两边传同一个 `link_group`。
113
+
114
+ ### 记事和账单挂在一起
115
+
116
+ 流水列表只有 `has_visible_related_note`,不带篇名。看一笔账用 `get_ledger_entry`;看一篇记事用 `get_note`,没有记账读取权限时不返回金额。
117
+
118
+ 挂上或拆开已经存在的记录:
119
+
120
+ `unlock_writes` → `prepare_link_ledger_note` / `prepare_unlink_ledger_note` → 向用户展示篇名、日期、分类和金额 → `confirm_link_ledger_note` / `confirm_unlink_ledger_note`
87
121
 
88
- `unlock_writes` → `prepare_update_ledger_entry` → 用户确认 → `confirm_update_ledger_entry`(只支持最近 1 个月内添加的流水)
122
+ 挂接本身不占每月记账条数。
89
123
 
90
- ### 整理记事
124
+ ### 整理记事文件夹
91
125
 
92
126
  `list_note_folders` → `unlock_writes` → `create_note_folder` / `rename_note_folder` / `move_note_folder`
93
127
 
128
+ 文件夹最多两层;删除空文件夹须 `prepare_delete_note_folder` → `confirm_delete_note_folder`。
129
+
94
130
  ### 恢复误删
95
131
 
96
132
  账单:`list_ledger_trash` → `restore_ledger_entry`
97
133
 
98
134
  记事:`list_notes_trash` → `restore_note`
99
135
 
136
+ 清空回收站会永久删除,须先 `prepare_*` 再 `confirm_*`。
137
+
138
+ ## 更新
139
+
140
+ 桌面客户端通过 `npx -y @fangcuntai/fangcuntai-mcp` 启动时,会自动使用 npm 的 `latest`。升级后重启客户端即可,配置不用改。
141
+
142
+ 查看当前最新版:
143
+
144
+ ```bash
145
+ npm view @fangcuntai/fangcuntai-mcp version
146
+ ```
147
+
148
+ 固定到某个版本:
149
+
150
+ ```json
151
+ {
152
+ "args": ["-y", "@fangcuntai/fangcuntai-mcp@1.6.7"]
153
+ }
154
+ ```
155
+
156
+ ## 常见问题
157
+
158
+ - **提示缺少 `FANGCUNTAI_TOKEN`**:确认客户端配置的 `env` 里有 App 生成的 `hm_at_` 令牌。
159
+ - **返回 `40305` 或提示未勾选权限**:在 App 里重新生成令牌,勾选对应权限;已有令牌不能追加权限。
160
+ - **写操作提示已上锁**:先向用户说明风险,再调用 `unlock_writes`,然后走 `prepare_*` → `confirm_*`。
161
+ - **提示只能改最近 1 个月**:更早的流水请在 App 里改,或让小家师直接更新。
162
+ - **连不上 API**:本地默认是 `http://127.0.0.1:9080`;用生产环境时把 `FANGCUNTAI_API` 设为 `https://api-service.fangcuntai.com`。
163
+
100
164
  ## 本地开发
101
165
 
102
166
  ```bash
@@ -125,6 +189,8 @@ go run cmd/seed-mcp-test-data/main.go -config config/config.yaml
125
189
  npm publish --access public
126
190
  ```
127
191
 
192
+ 发布前可用 `npm publish --dry-run --access public` 检查包内容。
193
+
128
194
  ## 链接
129
195
 
130
196
  - 官网:https://www.fangcuntai.com
@@ -1,7 +1,7 @@
1
1
  import type { FangcuntaiApiClient } from "../client/api-client.js";
2
2
  export declare const TOKEN_SCOPE_READ_LEDGER = "read:ledger";
3
3
  export declare const TOKEN_SCOPE_READ_STATS = "read:stats";
4
- export declare const TOKEN_SCOPE_WRITE_DRAFT = "write:draft";
4
+ export declare const TOKEN_SCOPE_WRITE_NOTES = "write:notes";
5
5
  export declare const TOKEN_SCOPE_WRITE_LEDGER = "write:ledger";
6
6
  export declare const TOKEN_SCOPE_DENIED = "\u5F53\u524D\u4EE4\u724C\u672A\u52FE\u9009\u6B64\u9879\u6743\u9650\u3002\u8BF7\u5728\u65B9\u5BF8\u53F0 App\u300C\u8FDE\u63A5\u684C\u9762\u52A9\u624B\u300D\u751F\u6210\u65B0\u4EE4\u724C\u5E76\u52FE\u9009\u5BF9\u5E94\u6743\u9650\uFF1B\u5DF2\u6709\u4EE4\u724C\u4E0D\u80FD\u6539\u6743\u9650\u3002";
7
7
  export type AssistantContext = {
@@ -8,7 +8,7 @@ let activeLedgerBookId = null;
8
8
  let cachedTokenScopes = null;
9
9
  export const TOKEN_SCOPE_READ_LEDGER = "read:ledger";
10
10
  export const TOKEN_SCOPE_READ_STATS = "read:stats";
11
- export const TOKEN_SCOPE_WRITE_DRAFT = "write:draft";
11
+ export const TOKEN_SCOPE_WRITE_NOTES = "write:notes";
12
12
  export const TOKEN_SCOPE_WRITE_LEDGER = "write:ledger";
13
13
  export const TOKEN_SCOPE_DENIED = "当前令牌未勾选此项权限。请在方寸台 App「连接桌面助手」生成新令牌并勾选对应权限;已有令牌不能改权限。";
14
14
  export function setBoundFamilyId(id) {
@@ -1,4 +1,4 @@
1
- export type PendingKind = "create_ledger" | "update_ledger" | "delete_ledger" | "empty_ledger_trash" | "confirm_draft" | "batch_confirm_draft" | "delete_note" | "empty_notes_trash" | "delete_note_folder" | "move_note" | "link_ledger_note" | "unlink_ledger_note";
1
+ export type PendingKind = "create_ledger" | "create_note" | "update_ledger" | "delete_ledger" | "empty_ledger_trash" | "delete_note" | "empty_notes_trash" | "delete_note_folder" | "move_note" | "link_ledger_note" | "unlink_ledger_note";
2
2
  export type PendingWrite = {
3
3
  kind: PendingKind;
4
4
  token: string;
@@ -17,7 +17,7 @@ export function unlockWrites(ttlMs = UNLOCK_TTL_MS) {
17
17
  return {
18
18
  unlocked: true,
19
19
  expires_in_seconds: Math.floor(ttlMs / 1000),
20
- hint: "已解锁写操作。入账/改账/删除/清空回收站/确认草稿仍须 prepare → 向用户展示摘要 → confirm。",
20
+ hint: "已解锁写操作。入账/写记事/改账/删除/清空回收站仍须 prepare → 向用户展示摘要 → confirm。",
21
21
  };
22
22
  }
23
23
  export function lockWrites() {
@@ -42,7 +42,7 @@ export function getWriteLockStatus() {
42
42
  /** 写操作前门:未解锁则抛错。 */
43
43
  export function requireWritesUnlocked() {
44
44
  if (!isWritesUnlocked()) {
45
- throw new Error("写操作已上锁。请先向用户确认后调用 unlock_writes,再 prepare → confirm。查账与建草稿不受影响。");
45
+ throw new Error("写操作已上锁。请先向用户确认后调用 unlock_writes,再 prepare → confirm。查账不受影响。");
46
46
  }
47
47
  }
48
48
  export function createPending(kind, familyId, summary, exec) {
@@ -1,6 +1,5 @@
1
1
  import { registerAccountTools } from "./account.js";
2
2
  import { registerContextTools } from "./context.js";
3
- import { registerDraftTools } from "./drafts.js";
4
3
  import { registerLedgerTools } from "./ledger.js";
5
4
  import { registerLedgerNoteLinkTools } from "./ledger-note-link.js";
6
5
  import { registerNoteTools } from "./notes.js";
@@ -11,6 +10,5 @@ export function registerTools(server, client) {
11
10
  registerLedgerTools(server, client);
12
11
  registerLedgerNoteLinkTools(server, client);
13
12
  registerNoteTools(server, client);
14
- registerDraftTools(server, client);
15
13
  registerAccountTools(server, client);
16
14
  }
@@ -1,5 +1,5 @@
1
1
  import { z } from "zod";
2
- import { ensureFamilyId, familyPath, requireEntitlement, requireTokenScope, tokenHasAnyScope, TOKEN_SCOPE_READ_LEDGER, TOKEN_SCOPE_WRITE_DRAFT, TOKEN_SCOPE_WRITE_LEDGER, } from "../context/family-context.js";
2
+ import { ensureFamilyId, familyPath, requireEntitlement, requireTokenScope, tokenHasAnyScope, TOKEN_SCOPE_READ_LEDGER, TOKEN_SCOPE_WRITE_NOTES, TOKEN_SCOPE_WRITE_LEDGER, } from "../context/family-context.js";
3
3
  import { createPending, pendingPublicView, takePending, } from "../context/write-lock.js";
4
4
  import { fenToYuan } from "../utils/money.js";
5
5
  import { okJson, runTool } from "../utils/response.js";
@@ -52,7 +52,7 @@ export async function linkRememberedPair(client, familyId, group, side, id) {
52
52
  }
53
53
  async function requireLinkWriteScopes(client) {
54
54
  await requireTokenScope(client, [TOKEN_SCOPE_WRITE_LEDGER]);
55
- await requireTokenScope(client, [TOKEN_SCOPE_WRITE_DRAFT]);
55
+ await requireTokenScope(client, [TOKEN_SCOPE_WRITE_NOTES]);
56
56
  }
57
57
  function entrySummary(entry, bookName) {
58
58
  const amount = Number(entry.amount ?? 0);
@@ -1,5 +1,5 @@
1
1
  import { z } from "zod";
2
- import { currentLedgerBookId, ensureFamilyId, familyPath, getWorkspaceContext, ledgerBookQuery, requireEntitlement, requireTokenScope, selectLedgerBook, TOKEN_SCOPE_READ_LEDGER, TOKEN_SCOPE_READ_STATS, TOKEN_SCOPE_WRITE_DRAFT, TOKEN_SCOPE_WRITE_LEDGER, } from "../context/family-context.js";
2
+ import { currentLedgerBookId, ensureFamilyId, familyPath, getWorkspaceContext, ledgerBookQuery, requireEntitlement, requireTokenScope, selectLedgerBook, TOKEN_SCOPE_READ_LEDGER, TOKEN_SCOPE_READ_STATS, TOKEN_SCOPE_WRITE_NOTES, TOKEN_SCOPE_WRITE_LEDGER, } from "../context/family-context.js";
3
3
  import { createPending, pendingPublicView, takePending, } from "../context/write-lock.js";
4
4
  import { linkRememberedPair } from "./ledger-note-link.js";
5
5
  import { fenToYuan, mapItemsWithYuan, stripLedgerListNoteDetails, yuanToFen } from "../utils/money.js";
@@ -87,8 +87,7 @@ export function ledgerCreatedWithinLastMonth(createdAtSec, nowMs = Date.now()) {
87
87
  }
88
88
  function buildLedgerUpdatePatch(input) {
89
89
  const patch = {};
90
- if (input.type)
91
- patch.type = input.type;
90
+ // 收入和支出不能互改。相同类型不写入,避免整单保存时把类型再传一遍。
92
91
  if (input.amount_yuan !== undefined)
93
92
  patch.amount = yuanToFen(input.amount_yuan);
94
93
  if (input.category !== undefined)
@@ -132,7 +131,13 @@ export async function prepareUpdateLedgerEntry(client, input) {
132
131
  const entry = await client.get(familyPath(familyId, `/ledger/${input.entry_id}`), bookQuery);
133
132
  const createdAt = Number(entry.created_at ?? 0);
134
133
  if (!ledgerCreatedWithinLastMonth(createdAt)) {
135
- throw new Error("桌面助手只能改最近 1 个月内添加的记账。更早的请在 App 里改,或让小家师出更新草稿。");
134
+ throw new Error("桌面助手只能改最近 1 个月内添加的记账。更早的请在 App 里改,或让小家师直接更新。");
135
+ }
136
+ if (input.type) {
137
+ const current = String(entry.type ?? "").trim().toLowerCase();
138
+ if (current !== input.type) {
139
+ throw new Error("已记下的账单,收入和支出不能互改。金额和备注还可以改。");
140
+ }
136
141
  }
137
142
  const patch = buildLedgerUpdatePatch(input);
138
143
  if (input.add_tags?.length) {
@@ -340,7 +345,7 @@ export function registerLedgerTools(server, client) {
340
345
  await requireTokenScope(client, [
341
346
  TOKEN_SCOPE_READ_LEDGER,
342
347
  TOKEN_SCOPE_READ_STATS,
343
- TOKEN_SCOPE_WRITE_DRAFT,
348
+ TOKEN_SCOPE_WRITE_NOTES,
344
349
  TOKEN_SCOPE_WRITE_LEDGER,
345
350
  ]);
346
351
  const familyId = await ensureFamilyId(client);
@@ -376,10 +381,13 @@ export function registerLedgerTools(server, client) {
376
381
  client.setToolName("confirm_create_ledger_entry");
377
382
  return okJson(await confirmCreateLedgerEntry(client, confirm_token));
378
383
  }));
379
- server.tool("prepare_update_ledger_entry", "准备修改已入账的一笔流水(不直接写入)。须先 unlock_writes。只支持修改最近 1 个月内添加的内容。返回 summary + confirm_token,向用户确认后再 confirm_update_ledger_entry。不会另记一笔新账。", {
384
+ server.tool("prepare_update_ledger_entry", "准备修改已入账的一笔流水(不直接写入)。须先 unlock_writes。只支持修改最近 1 个月内添加的内容。收入和支出不能互改。返回 summary + confirm_token,向用户确认后再 confirm_update_ledger_entry。不会另记一笔新账。", {
380
385
  entry_id: z.number().int().positive().describe("记账条目 ID"),
381
386
  ledger_book_id: optionalBookId,
382
- type: z.enum(["expense", "income"]).optional(),
387
+ type: z
388
+ .enum(["expense", "income"])
389
+ .optional()
390
+ .describe("不能改。和原来不同会失败;记错了类型请删掉重记"),
383
391
  amount_yuan: z.number().positive().optional().describe("金额(元)"),
384
392
  category: z.string().optional(),
385
393
  description: z.string().optional(),
@@ -388,7 +396,7 @@ export function registerLedgerTools(server, client) {
388
396
  currency: z.string().optional(),
389
397
  fund_account_type: z.string().optional().describe("cash / wechat / alipay / bank_card 等"),
390
398
  fund_account_detail: z.string().optional(),
391
- payer: z.string().optional().describe("对方"),
399
+ payer: z.string().optional().describe("商家(支出)或来源(收入),外面的店、公司或平台"),
392
400
  billing_month: z.string().optional().describe("YYYY-MM"),
393
401
  tags: z.array(z.string()).optional().describe("整笔替换标签"),
394
402
  add_tags: z.array(z.string()).optional().describe("追加标签,不覆盖已有"),
@@ -521,48 +529,4 @@ export function registerLedgerTools(server, client) {
521
529
  workspace: await getWorkspaceContext(client),
522
530
  });
523
531
  }));
524
- server.tool("create_ledger_draft", "创建记账草稿(不会直接入账,无需解锁)。正式入账请 unlock_writes → prepare_confirm_ai_draft → confirm_ai_draft。", {
525
- type: z.enum(["expense", "income"]).default("expense"),
526
- amount_yuan: z.number().positive().describe("金额(元)"),
527
- category: z.string().optional().describe("分类 key,如 food / education"),
528
- description: z.string().optional(),
529
- date: z.string().optional().describe("YYYY-MM-DD,默认今天"),
530
- currency: z.string().optional().describe("默认 CNY"),
531
- ledger_book_id: optionalBookId,
532
- external_order_id: z
533
- .string()
534
- .optional()
535
- .describe("外部订单号,非必填。确认入账时同一账本内不可重复"),
536
- }, async (input) => runTool(async () => {
537
- client.setToolName("create_ledger_draft");
538
- const familyId = await ensureFamilyId(client);
539
- await requireTokenScope(client, [TOKEN_SCOPE_WRITE_DRAFT]);
540
- await requireEntitlement(client, familyId, "can_use_ledger", "当前角色没有记账权限,无法创建记账草稿");
541
- const recordDate = parseRecordDate(input.date);
542
- const bookId = currentLedgerBookId(input.ledger_book_id);
543
- const payload = {
544
- type: input.type,
545
- amount: yuanToFen(input.amount_yuan),
546
- category: input.category ?? "other",
547
- description: input.description ?? "",
548
- record_date: recordDate,
549
- currency: input.currency ?? "CNY",
550
- source: "desktop_mcp",
551
- };
552
- if (bookId > 0)
553
- payload.ledger_book_id = bookId;
554
- if (input.external_order_id?.trim()) {
555
- payload.external_order_id = input.external_order_id.trim();
556
- }
557
- const data = await client.post(familyPath(familyId, "/ai-drafts"), {
558
- draft_type: "ledger",
559
- payload,
560
- session_id: "mcp",
561
- });
562
- return okJson({
563
- ...data,
564
- hint: "草稿已创建。确认入账:unlock_writes → prepare_confirm_ai_draft → confirm_ai_draft;或 discard_ai_draft 丢弃。",
565
- workspace: await getWorkspaceContext(client),
566
- });
567
- }));
568
532
  }
@@ -1,6 +1,6 @@
1
1
  import { z } from "zod";
2
- import { ensureFamilyId, familyPath, requireEntitlement, requireTokenScope, TOKEN_SCOPE_WRITE_DRAFT } from "../context/family-context.js";
3
- import { tokenCanSeeLedgerAmounts } from "./ledger-note-link.js";
2
+ import { ensureFamilyId, familyPath, requireEntitlement, requireTokenScope, TOKEN_SCOPE_WRITE_LEDGER, TOKEN_SCOPE_WRITE_NOTES, } from "../context/family-context.js";
3
+ import { linkRememberedPair, tokenCanSeeLedgerAmounts } from "./ledger-note-link.js";
4
4
  import { fenToYuan, stripNoteListLedgerDetails } from "../utils/money.js";
5
5
  import { createPending, pendingPublicView, requireWritesUnlocked, takePending, } from "../context/write-lock.js";
6
6
  import { okJson, runTool } from "../utils/response.js";
@@ -43,7 +43,7 @@ export function registerNoteTools(server, client) {
43
43
  const data = await client.post(familyPath(familyId, "/notes/folders"), body);
44
44
  return okJson({
45
45
  ...data,
46
- hint: "文件夹已创建。可用 list_notes(folder_id) 浏览本层,create_note_draft(folder_id) 写入该位置。",
46
+ hint: "文件夹已创建。可用 list_notes(folder_id) 浏览本层,prepare_create_note(folder_id) 写入该位置。",
47
47
  });
48
48
  }));
49
49
  server.tool("rename_note_folder", "重命名记事文件夹(须先 unlock_writes)。同父下不可与已有名称冲突。", {
@@ -179,18 +179,23 @@ export function registerNoteTools(server, client) {
179
179
  const seeLedger = await tokenCanSeeLedgerAmounts(client);
180
180
  return okJson(stripNoteListLedgerDetails(data, seeLedger));
181
181
  }));
182
- server.tool("create_note_draft", "创建记事草稿(不会直接保存)。visibility 可选 family / personal / selected / owner_only。folder_id 可选:0/省略=未分类,正整数=指定文件夹。待办写成 - [ ] / - [x];引用其他记事用 [[标题]] 或 [说明](note:id)。", {
182
+ server.tool("prepare_create_note", "准备新建一篇记事(先不保存)。须先 unlock_writes。返回摘要 + confirm_token,向用户确认后再 confirm_create_note。visibility 可选 family / personal / selected / owner_only。folder_id 可选:0/省略=未分类,正整数=指定文件夹。待办写成 - [ ] / - [x];引用其他记事用 [[标题]] 或 [说明](note:id)。", {
183
183
  title: z.string().min(1),
184
184
  content: z.string().optional(),
185
185
  visibility: z.enum(["family", "personal", "selected", "owner_only"]).optional(),
186
+ visible_user_ids: z.array(z.number().int().positive()).optional(),
186
187
  folder_id: folderIdParam.describe("所属文件夹;0/省略=未分类"),
188
+ tags: z.array(z.string()).optional(),
187
189
  link_group: z.string().optional().describe("和同一回合新建的账单使用同一个名字,两边都成功后才挂上"),
188
190
  related_entry_ids: z.array(z.number().int().positive()).optional().describe("挂到已经存在的账单;用户没明确要求就不要传"),
189
191
  }, async (input) => runTool(async () => {
190
- client.setToolName("create_note_draft");
192
+ client.setToolName("prepare_create_note");
191
193
  const familyId = await ensureFamilyId(client);
192
- await requireTokenScope(client, [TOKEN_SCOPE_WRITE_DRAFT]);
193
- await requireEntitlement(client, familyId, "can_view_notes", "当前角色没有记事权限,无法创建记事草稿");
194
+ await requireTokenScope(client, [TOKEN_SCOPE_WRITE_NOTES]);
195
+ if (input.related_entry_ids?.length) {
196
+ await requireTokenScope(client, [TOKEN_SCOPE_WRITE_LEDGER]);
197
+ }
198
+ await requireEntitlement(client, familyId, "can_view_notes", "当前角色没有记事权限,无法创建记事");
194
199
  const payload = {
195
200
  title: input.title,
196
201
  content: input.content ?? "",
@@ -199,22 +204,75 @@ export function registerNoteTools(server, client) {
199
204
  if (input.folder_id !== undefined) {
200
205
  payload.folder_id = input.folder_id;
201
206
  }
202
- if (input.link_group?.trim()) {
203
- payload.link_group = input.link_group.trim();
204
- payload.link_after_save = true;
207
+ if (input.visible_user_ids?.length) {
208
+ payload.visible_user_ids = input.visible_user_ids;
205
209
  }
206
- if (input.related_entry_ids?.length) {
207
- payload.related_entry_ids = input.related_entry_ids;
208
- payload.link_after_save = true;
210
+ if (input.tags?.length) {
211
+ payload.tags = input.tags;
209
212
  }
210
- const data = await client.post(familyPath(familyId, "/ai-drafts"), {
211
- draft_type: "note",
212
- session_id: "mcp",
213
+ let folderName = input.folder_id && input.folder_id > 0 ? "" : "未分类";
214
+ if (input.folder_id && input.folder_id > 0) {
215
+ const folders = await client.get(familyPath(familyId, "/notes/folders"));
216
+ const folder = (Array.isArray(folders.items) ? folders.items : []).find((item) => Number(item.id) === input.folder_id);
217
+ folderName = folder ? String(folder.name ?? "") : "";
218
+ }
219
+ const pending = createPending("create_note", familyId, {
220
+ action: "create_note",
221
+ title: input.title,
222
+ content_preview: (input.content ?? "").slice(0, 200),
223
+ visibility: payload.visibility,
224
+ folder_id: input.folder_id ?? 0,
225
+ folder_name: folderName || null,
226
+ tags: input.tags ?? [],
227
+ link_group: input.link_group?.trim() || null,
228
+ }, {
213
229
  payload,
230
+ link_group: input.link_group?.trim() || "",
231
+ related_entry_ids: (input.related_entry_ids ?? []).filter((id) => Number.isInteger(id) && id > 0),
214
232
  });
233
+ return okJson(pendingPublicView(pending));
234
+ }));
235
+ server.tool("confirm_create_note", "确认新建记事并保存到记事本。必须传入 prepare_create_note 返回的 confirm_token。", {
236
+ confirm_token: z.string().min(1).describe("来自 prepare_create_note"),
237
+ }, async ({ confirm_token }) => runTool(async () => {
238
+ client.setToolName("confirm_create_note");
239
+ await requireTokenScope(client, [TOKEN_SCOPE_WRITE_NOTES]);
240
+ const pending = takePending(confirm_token, "create_note");
241
+ const payload = pending.exec.payload && typeof pending.exec.payload === "object"
242
+ ? pending.exec.payload
243
+ : {};
244
+ const data = await client.post(familyPath(pending.familyId, "/notes"), payload);
245
+ const noteId = Number(data.id ?? data.note_id ?? 0);
246
+ const link = await linkRememberedPair(client, pending.familyId, String(pending.exec.link_group ?? ""), "note", noteId);
247
+ const relatedEntryIds = Array.isArray(pending.exec.related_entry_ids)
248
+ ? pending.exec.related_entry_ids.map(Number).filter((id) => Number.isInteger(id) && id > 0)
249
+ : [];
250
+ const relatedEntryLinks = [];
251
+ for (const entryId of relatedEntryIds) {
252
+ try {
253
+ await client.post(familyPath(pending.familyId, "/ledger-note-links"), {
254
+ entry_id: entryId,
255
+ note_id: noteId,
256
+ });
257
+ relatedEntryLinks.push({ entry_id: entryId, linked: true });
258
+ }
259
+ catch (err) {
260
+ relatedEntryLinks.push({
261
+ entry_id: entryId,
262
+ linked: false,
263
+ link_error: err instanceof Error ? err.message : String(err),
264
+ });
265
+ }
266
+ }
267
+ const linkedToExisting = relatedEntryLinks.some((item) => item.linked === true);
215
268
  return okJson({
216
269
  ...data,
217
- hint: "草稿已创建。确认保存:unlock_writes → prepare_confirm_ai_draft → confirm_ai_draft;或 discard_ai_draft 丢弃。",
270
+ note_id: noteId || data.note_id,
271
+ link,
272
+ related_entry_links: relatedEntryLinks,
273
+ hint: link?.linked || linkedToExisting
274
+ ? "记事已保存,并和对应账单挂在一起。"
275
+ : "记事已保存到记事本。",
218
276
  });
219
277
  }));
220
278
  server.tool("prepare_move_note", "准备将已有记事移到指定文件夹(须先 unlock_writes)。folder_id=0 表示未分类。返回 summary + confirm_token。", {
@@ -269,7 +327,7 @@ export function registerNoteTools(server, client) {
269
327
  }, async ({ note_id }) => runTool(async () => {
270
328
  client.setToolName("prepare_delete_note");
271
329
  const familyId = await ensureFamilyId(client);
272
- await requireTokenScope(client, [TOKEN_SCOPE_WRITE_DRAFT]);
330
+ await requireTokenScope(client, [TOKEN_SCOPE_WRITE_NOTES]);
273
331
  await requireEntitlement(client, familyId, "can_view_notes", "当前角色没有记事权限,无法删除记事");
274
332
  const note = await client.get(familyPath(familyId, `/notes/${note_id}`));
275
333
  const pending = createPending("delete_note", familyId, {
@@ -284,7 +342,7 @@ export function registerNoteTools(server, client) {
284
342
  confirm_token: z.string().min(1),
285
343
  }, async ({ confirm_token }) => runTool(async () => {
286
344
  client.setToolName("confirm_delete_note");
287
- await requireTokenScope(client, [TOKEN_SCOPE_WRITE_DRAFT]);
345
+ await requireTokenScope(client, [TOKEN_SCOPE_WRITE_NOTES]);
288
346
  const pending = takePending(confirm_token, "delete_note");
289
347
  const noteId = Number(pending.exec.note_id);
290
348
  await client.delete(familyPath(pending.familyId, `/notes/${noteId}`));
@@ -300,7 +358,7 @@ export function registerNoteTools(server, client) {
300
358
  page_size: z.number().int().min(1).max(100).optional(),
301
359
  }, async ({ page, page_size }) => runTool(async () => {
302
360
  client.setToolName("list_notes_trash");
303
- await requireTokenScope(client, [TOKEN_SCOPE_WRITE_DRAFT]);
361
+ await requireTokenScope(client, [TOKEN_SCOPE_WRITE_NOTES]);
304
362
  const familyId = await ensureFamilyId(client);
305
363
  const data = await client.get(familyPath(familyId, "/notes/trash"), { page, page_size });
306
364
  return okJson({
@@ -313,7 +371,7 @@ export function registerNoteTools(server, client) {
313
371
  }, async ({ note_id }) => runTool(async () => {
314
372
  client.setToolName("restore_note");
315
373
  const familyId = await ensureFamilyId(client);
316
- await requireTokenScope(client, [TOKEN_SCOPE_WRITE_DRAFT]);
374
+ await requireTokenScope(client, [TOKEN_SCOPE_WRITE_NOTES]);
317
375
  await requireEntitlement(client, familyId, "can_view_notes", "当前角色没有记事权限,无法恢复记事");
318
376
  const data = await client.post(familyPath(familyId, `/notes/${note_id}/restore`));
319
377
  return okJson({
@@ -324,7 +382,7 @@ export function registerNoteTools(server, client) {
324
382
  server.tool("prepare_empty_notes_trash", "准备清空记事回收站(永久删除,不可恢复)。须先 unlock_writes。会返回将删除的条数供用户确认。", {}, async () => runTool(async () => {
325
383
  client.setToolName("prepare_empty_notes_trash");
326
384
  const familyId = await ensureFamilyId(client);
327
- await requireTokenScope(client, [TOKEN_SCOPE_WRITE_DRAFT]);
385
+ await requireTokenScope(client, [TOKEN_SCOPE_WRITE_NOTES]);
328
386
  await requireEntitlement(client, familyId, "can_view_notes", "当前角色没有记事权限,无法清空回收站");
329
387
  const trash = await client.get(familyPath(familyId, "/notes/trash"), { page: 1, page_size: 1 });
330
388
  const count = Number(trash.total ?? 0);
@@ -339,7 +397,7 @@ export function registerNoteTools(server, client) {
339
397
  confirm_token: z.string().min(1),
340
398
  }, async ({ confirm_token }) => runTool(async () => {
341
399
  client.setToolName("confirm_empty_notes_trash");
342
- await requireTokenScope(client, [TOKEN_SCOPE_WRITE_DRAFT]);
400
+ await requireTokenScope(client, [TOKEN_SCOPE_WRITE_NOTES]);
343
401
  const pending = takePending(confirm_token, "empty_notes_trash");
344
402
  const data = await client.delete(familyPath(pending.familyId, "/notes/trash"));
345
403
  return okJson({
@@ -5,10 +5,10 @@ export function registerSafetyTools(server) {
5
5
  server.tool("get_write_lock_status", "查看 MCP 写操作安全锁状态(是否已解锁、剩余秒数、待确认数)。", {}, async () => runTool(async () => {
6
6
  return okJson({
7
7
  ...getWriteLockStatus(),
8
- policy: "默认上锁。查账/列文件夹/建草稿可用;入账、改账、删除记账/记事、清空回收站、确认草稿、删除文件夹、移动记事所属文件夹须 unlock_writes → prepare_* → 用户确认 → confirm_*。新建/改名/移动文件夹须先 unlock_writes。删除进入回收站,可恢复;清空回收站不可恢复。改账只支持最近 1 个月内添加的流水。",
8
+ policy: "默认上锁。查账/列文件夹可用;记账、写记事、改账、删除记账/记事、清空回收站、删除文件夹、移动记事所属文件夹须 unlock_writes → prepare_* → 用户确认 → confirm_*。新建/改名/移动文件夹须先 unlock_writes。删除进入回收站,可恢复;清空回收站不可恢复。改账只支持最近 1 个月内添加的流水。",
9
9
  });
10
10
  }));
11
- server.tool("unlock_writes", "解锁写操作(须先征得用户同意)。解锁后仍须对入账/改账/删除/确认草稿(含批量)走 prepare→confirm,不能一步写库。约 15 分钟无操作会过期。", {
11
+ server.tool("unlock_writes", "解锁写操作(须先征得用户同意)。解锁后仍须对入账/改账/写记事/删除走 prepare→confirm,确认后直接写正式数据。约 15 分钟无操作会过期。", {
12
12
  user_acknowledged: z
13
13
  .boolean()
14
14
  .describe("必须为 true,表示已向用户说明风险并获得同意"),
package/package.json CHANGED
@@ -1,11 +1,11 @@
1
1
  {
2
2
  "name": "@fangcuntai/fangcuntai-mcp",
3
- "version": "1.6.5",
3
+ "version": "1.6.7",
4
4
  "description": "方寸台桌面助手 MCP — 确认锁 + 来源标记 + 回收站 + 记事文件夹整理,安全地用自然语言管理家庭账本与记事",
5
5
  "license": "MIT",
6
6
  "type": "module",
7
7
  "bin": {
8
- "fangcuntai-mcp": "./dist/index.js"
8
+ "fangcuntai-mcp": "dist/index.js"
9
9
  },
10
10
  "files": [
11
11
  "dist",
@@ -13,7 +13,8 @@
13
13
  "README.en.md"
14
14
  ],
15
15
  "scripts": {
16
- "build": "tsc",
16
+ "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
17
+ "build": "npm run clean && tsc",
17
18
  "start": "node dist/index.js",
18
19
  "dev": "tsc && node dist/index.js",
19
20
  "organize-notes": "node scripts/organize-notes.mjs",
@@ -1,3 +0,0 @@
1
- import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
2
- import type { FangcuntaiApiClient } from "../client/api-client.js";
3
- export declare function registerDraftTools(server: McpServer, client: FangcuntaiApiClient): void;
@@ -1,163 +0,0 @@
1
- import { z } from "zod";
2
- import { ensureFamilyId, familyPath, requireTokenScope, TOKEN_SCOPE_WRITE_DRAFT, TOKEN_SCOPE_WRITE_LEDGER, } from "../context/family-context.js";
3
- import { createPending, pendingPublicView, takePending, } from "../context/write-lock.js";
4
- import { linkRememberedPair } from "./ledger-note-link.js";
5
- import { fenToYuan } from "../utils/money.js";
6
- import { okJson, runTool } from "../utils/response.js";
7
- export function registerDraftTools(server, client) {
8
- server.tool("list_ai_drafts", "列出当前账号自己创建的待确认 AI 草稿(记账/记事)。家长也不能看家人的。可用 session_id=mcp 只看桌面助手草稿。", {
9
- status: z.string().optional().describe("草稿状态筛选,如 pending"),
10
- session_id: z.string().optional().describe("可选:mcp 或小家师会话 id"),
11
- }, async ({ status, session_id }) => runTool(async () => {
12
- client.setToolName("list_ai_drafts");
13
- await requireTokenScope(client, [TOKEN_SCOPE_WRITE_DRAFT, TOKEN_SCOPE_WRITE_LEDGER]);
14
- const familyId = await ensureFamilyId(client);
15
- const data = await client.get(familyPath(familyId, "/ai-drafts"), {
16
- status,
17
- session_id,
18
- });
19
- return okJson(data);
20
- }));
21
- server.tool("get_ai_draft", "获取单个 AI 草稿详情。", { draft_id: z.string().min(1) }, async ({ draft_id }) => runTool(async () => {
22
- client.setToolName("get_ai_draft");
23
- await requireTokenScope(client, [TOKEN_SCOPE_WRITE_DRAFT, TOKEN_SCOPE_WRITE_LEDGER]);
24
- const familyId = await ensureFamilyId(client);
25
- const data = await client.get(familyPath(familyId, `/ai-drafts/${draft_id}`));
26
- return okJson(data);
27
- }));
28
- server.tool("prepare_confirm_ai_draft", "准备确认草稿(不写入)。须先 unlock_writes。返回摘要 + confirm_token,用户同意后再 confirm_ai_draft。", { draft_id: z.string().min(1) }, async ({ draft_id }) => runTool(async () => {
29
- client.setToolName("prepare_confirm_ai_draft");
30
- await requireTokenScope(client, [TOKEN_SCOPE_WRITE_DRAFT, TOKEN_SCOPE_WRITE_LEDGER]);
31
- const familyId = await ensureFamilyId(client);
32
- const draft = await client.get(familyPath(familyId, `/ai-drafts/${draft_id}`));
33
- if (draft?.draft_type === "reminder") {
34
- throw new Error("事情提醒功能已下线,无法确认提醒草稿,请丢弃该草稿");
35
- }
36
- const payload = draft.payload && typeof draft.payload === "object"
37
- ? draft.payload
38
- : {};
39
- const amount = Number(payload.amount ?? 0);
40
- const summary = {
41
- action: "confirm_ai_draft",
42
- draft_id,
43
- draft_type: draft.draft_type,
44
- payload_preview: payload,
45
- };
46
- if (draft.draft_type === "ledger" && amount > 0) {
47
- summary.amount_yuan = fenToYuan(amount);
48
- }
49
- const pending = createPending("confirm_draft", familyId, summary, {
50
- draft_id,
51
- draft_type: draft.draft_type,
52
- link_group: typeof payload.link_group === "string" ? payload.link_group : "",
53
- });
54
- return okJson(pendingPublicView(pending));
55
- }));
56
- server.tool("confirm_ai_draft", "确认 AI 草稿并写入正式数据。必须传入 prepare_confirm_ai_draft 返回的 confirm_token(不再接受仅 draft_id)。", {
57
- confirm_token: z.string().min(1).describe("来自 prepare_confirm_ai_draft"),
58
- }, async ({ confirm_token }) => runTool(async () => {
59
- client.setToolName("confirm_ai_draft");
60
- await requireTokenScope(client, [TOKEN_SCOPE_WRITE_DRAFT, TOKEN_SCOPE_WRITE_LEDGER]);
61
- const pending = takePending(confirm_token, "confirm_draft");
62
- const draftId = String(pending.exec.draft_id ?? "");
63
- if (!draftId)
64
- throw new Error("确认码缺少 draft_id");
65
- const data = await client.post(familyPath(pending.familyId, `/ai-drafts/${draftId}/confirm`));
66
- const result = data.result && typeof data.result === "object" ? data.result : {};
67
- const createdId = Number(result.id ?? 0);
68
- const draftType = String(pending.exec.draft_type ?? "");
69
- const side = draftType === "ledger" ? "entry" : draftType === "note" ? "note" : "";
70
- const link = side
71
- ? await linkRememberedPair(client, pending.familyId, String(pending.exec.link_group ?? ""), side, createdId)
72
- : null;
73
- return okJson({
74
- ...data,
75
- link,
76
- hint: link?.linked ? "草稿已确认,并和另一边挂在一起。" : "草稿已确认并写入正式数据。",
77
- });
78
- }));
79
- server.tool("discard_ai_draft", "丢弃 AI 草稿(不可恢复)。丢弃草稿不改正式账本,无需解锁。", { draft_id: z.string().min(1) }, async ({ draft_id }) => runTool(async () => {
80
- client.setToolName("discard_ai_draft");
81
- await requireTokenScope(client, [TOKEN_SCOPE_WRITE_DRAFT, TOKEN_SCOPE_WRITE_LEDGER]);
82
- const familyId = await ensureFamilyId(client);
83
- await client.post(familyPath(familyId, `/ai-drafts/${draft_id}/discard`));
84
- return okJson({ ok: true, draft_id });
85
- }));
86
- server.tool("prepare_batch_confirm_ai_drafts", "准备批量确认草稿(不写入)。须先 unlock_writes。返回摘要 + confirm_token,用户同意后再 batch_confirm_ai_drafts。", {
87
- draft_ids: z.array(z.string().min(1)).min(1).max(50).describe("待确认的草稿 ID 列表"),
88
- }, async ({ draft_ids }) => runTool(async () => {
89
- client.setToolName("prepare_batch_confirm_ai_drafts");
90
- await requireTokenScope(client, [TOKEN_SCOPE_WRITE_DRAFT, TOKEN_SCOPE_WRITE_LEDGER]);
91
- const familyId = await ensureFamilyId(client);
92
- const drafts = [];
93
- for (const draft_id of draft_ids) {
94
- try {
95
- const draft = await client.get(familyPath(familyId, `/ai-drafts/${draft_id}`));
96
- if (draft?.draft_type === "reminder") {
97
- drafts.push({
98
- draft_id,
99
- draft_type: "reminder",
100
- error: "事情提醒已下线,无法确认,请丢弃",
101
- });
102
- continue;
103
- }
104
- const payload = draft.payload && typeof draft.payload === "object"
105
- ? draft.payload
106
- : {};
107
- const item = {
108
- draft_id,
109
- draft_type: draft.draft_type,
110
- payload_preview: payload,
111
- };
112
- const amount = Number(payload.amount ?? 0);
113
- if (draft.draft_type === "ledger" && amount > 0) {
114
- item.amount_yuan = fenToYuan(amount);
115
- }
116
- drafts.push(item);
117
- }
118
- catch {
119
- drafts.push({ draft_id, error: "not_found_or_inaccessible" });
120
- }
121
- }
122
- const confirmableIds = drafts
123
- .filter((d) => !d.error)
124
- .map((d) => String(d.draft_id));
125
- if (confirmableIds.length === 0) {
126
- throw new Error("没有可确认的草稿(均不可访问或为已下线类型)");
127
- }
128
- const summary = {
129
- action: "batch_confirm_ai_drafts",
130
- requested_count: draft_ids.length,
131
- confirmable_count: confirmableIds.length,
132
- drafts,
133
- };
134
- const pending = createPending("batch_confirm_draft", familyId, summary, {
135
- draft_ids: confirmableIds,
136
- });
137
- return okJson(pendingPublicView(pending));
138
- }));
139
- server.tool("batch_confirm_ai_drafts", "批量确认 AI 草稿并写入正式记账/记事。必须传入 prepare_batch_confirm_ai_drafts 返回的 confirm_token(不再接受仅 draft_ids)。", {
140
- confirm_token: z.string().min(1).describe("来自 prepare_batch_confirm_ai_drafts"),
141
- }, async ({ confirm_token }) => runTool(async () => {
142
- client.setToolName("batch_confirm_ai_drafts");
143
- await requireTokenScope(client, [TOKEN_SCOPE_WRITE_DRAFT, TOKEN_SCOPE_WRITE_LEDGER]);
144
- const pending = takePending(confirm_token, "batch_confirm_draft");
145
- const draftIds = pending.exec.draft_ids;
146
- if (!Array.isArray(draftIds) || draftIds.length === 0) {
147
- throw new Error("确认码缺少 draft_ids");
148
- }
149
- const data = await client.post(familyPath(pending.familyId, "/ai-drafts/batch-confirm"), { draft_ids: draftIds });
150
- return okJson({ ...data, hint: "批量确认已完成;请查看 succeeded/failed。" });
151
- }));
152
- server.tool("batch_discard_ai_drafts", "批量丢弃 AI 草稿(不可恢复)。", {
153
- draft_ids: z.array(z.string().min(1)).min(1).max(50).describe("待丢弃的草稿 ID 列表"),
154
- }, async ({ draft_ids }) => runTool(async () => {
155
- client.setToolName("batch_discard_ai_drafts");
156
- await requireTokenScope(client, [TOKEN_SCOPE_WRITE_DRAFT, TOKEN_SCOPE_WRITE_LEDGER]);
157
- const familyId = await ensureFamilyId(client);
158
- const data = await client.post(familyPath(familyId, "/ai-drafts/batch-discard"), {
159
- draft_ids,
160
- });
161
- return okJson(data);
162
- }));
163
- }