@fangcuntai/fangcuntai-mcp 1.6.7 → 1.6.8
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 +69 -127
- package/README.md +69 -127
- package/package.json +22 -4
package/README.en.md
CHANGED
|
@@ -1,19 +1,59 @@
|
|
|
1
1
|
# @fangcuntai/fangcuntai-mcp
|
|
2
2
|
|
|
3
|
-
Fangcuntai
|
|
3
|
+
Fangcuntai is a family AI assistant that brings the family ledger, member collaboration, and Xiaojiaoshi together. Its in-app assistant, Xiaojiaoshi, helps with household bookkeeping, notes, and everyday family matters. This MCP server connects the same family data to Claude Desktop, Cursor, Lobster, and other desktop AI clients. Ledger entries, notes, and deletions show a summary before saving, and deleted items can be restored.
|
|
4
4
|
|
|
5
5
|
[简体中文](https://unpkg.com/@fangcuntai/fangcuntai-mcp/README.md)
|
|
6
6
|
|
|
7
|
-
##
|
|
7
|
+
## Fangcuntai and Xiaojiaoshi
|
|
8
8
|
|
|
9
|
-
|
|
10
|
-
|
|
9
|
+
Xiaojiaoshi is the family AI assistant inside the app. By default it acts as the household's daily steward: checking spending, analyzing expenses, adding ledger entries, writing notes, and organizing family agreements and to-dos. When you ask it to record something, it writes directly to the official ledger or notes; AI changes can be reviewed in **Me → AI settings → Change history**.
|
|
10
|
+
|
|
11
|
+
It can also:
|
|
12
|
+
|
|
13
|
+
- Query by month, year, or quarter and answer questions like "How much did we spend this month?", "Was this reasonable?", and "How much more will we need?"
|
|
14
|
+
- Fill in a note's title, body, visibility, tags, and folder in one go when possible; when organizing existing notes, it only changes folders and tags.
|
|
15
|
+
- Link a note to the corresponding ledger entry.
|
|
16
|
+
- Give practical suggestions based on family data. For deeper relationship or emotional questions, you can `@` a specialized assistant.
|
|
17
|
+
- Let each family member choose which ledgers and notes Xiaojiaoshi can access.
|
|
18
|
+
|
|
19
|
+
Xiaojiaoshi is not a therapist and does not do fortune-telling or make decisions for parents. For medical, legal, or serious mental health issues, it suggests professional help.
|
|
20
|
+
|
|
21
|
+
The desktop MCP is the desktop extension of Xiaojiaoshi: the same ledger and notes, connected to Claude Desktop / Cursor / Lobster. Xiaojiaoshi writes directly in the app; the desktop MCP keeps a write confirmation step. The MCP does not replace in-app chat and does not include specialized assistants or private skills.
|
|
22
|
+
|
|
23
|
+
## Why use the desktop MCP
|
|
24
|
+
|
|
25
|
+
- **Official MCP server, not a community wrapper**: it calls the Fangcuntai API directly and works on the same ledger and notes as the app.
|
|
26
|
+
- **Built for families**: switch between families and ledger books you have joined; the server still enforces Fangcuntai family permissions.
|
|
27
|
+
- **Confirmation before writes**: creating entries, writing notes, deleting, and emptying the recycle bin show a summary first and save only after you confirm.
|
|
28
|
+
- **Deleted items can be restored**: deleted ledger entries and notes go to the recycle bin. Only emptying it is permanent.
|
|
29
|
+
- **Traceable writes**: ledger entries written by the desktop assistant carry a source marker visible in the app.
|
|
30
|
+
|
|
31
|
+
## Who it is for
|
|
32
|
+
|
|
33
|
+
- People already using Fangcuntai for family bookkeeping and notes who want to work from their desktop.
|
|
34
|
+
- Families sharing ledger books who need to switch between families and books.
|
|
35
|
+
- People who want AI to help organize bills and notes but want to review writes before they happen.
|
|
36
|
+
|
|
37
|
+
## What the desktop MCP can do
|
|
38
|
+
|
|
39
|
+
- **Query the ledger**: view summaries, entries, trends, and categories.
|
|
40
|
+
- **Write ledger entries**: create, update, delete, restore, or empty the recycle bin.
|
|
11
41
|
- **Notes**: browse, search, create, and move notes, and organize two-level folders. Write to-dos as `- [ ]` / `- [x]`; reference another note with `[[title]]`.
|
|
12
42
|
- **Links**: attach a note to a ledger entry, or unlink them.
|
|
13
43
|
- **Account**: check subscription status and AI credit balance.
|
|
14
|
-
- **Traceable**: writes carry a source marker and can be traced in the Fangcuntai app.
|
|
15
44
|
|
|
16
|
-
|
|
45
|
+
## Things you can ask
|
|
46
|
+
|
|
47
|
+
- "How much did our family spend this month?"
|
|
48
|
+
- "Add an expense: groceries, 58 yuan today."
|
|
49
|
+
- "Link last week's renovation note to this bill."
|
|
50
|
+
- "Organize travel notes into the 2026 travel folder."
|
|
51
|
+
|
|
52
|
+
## Desktop MCP boundaries
|
|
53
|
+
|
|
54
|
+
- It only handles families and ledger books the current account can access.
|
|
55
|
+
- It does not change ledger settings, members, subscriptions, or credits; subscriptions and credits are read-only.
|
|
56
|
+
- Reminders are no longer available.
|
|
17
57
|
|
|
18
58
|
## Quick start
|
|
19
59
|
|
|
@@ -23,7 +63,7 @@ The MCP server accesses the Fangcuntai API only. It does not connect directly to
|
|
|
23
63
|
- A Fangcuntai account.
|
|
24
64
|
- A desktop assistant token created in the Fangcuntai app: **Me → AI settings → Connect Desktop Assistant**.
|
|
25
65
|
|
|
26
|
-
|
|
66
|
+
The token is shown only once. Existing tokens cannot be changed, so revoke and create a new one if needed.
|
|
27
67
|
|
|
28
68
|
### 2. Configure
|
|
29
69
|
|
|
@@ -42,98 +82,29 @@ Add this server to your MCP-compatible desktop client:
|
|
|
42
82
|
|
|
43
83
|
You can also copy the complete configuration from the **Connect Desktop Assistant** page in the Fangcuntai app.
|
|
44
84
|
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
| Variable | Required | Description |
|
|
48
|
-
|----------|----------|-------------|
|
|
49
|
-
| `FANGCUNTAI_TOKEN` | Yes | Assistant token created in the app, starting with `hm_at_` |
|
|
50
|
-
| `FANGCUNTAI_API` | No | API base URL. Defaults to `http://127.0.0.1:9080` |
|
|
51
|
-
|
|
52
|
-
Production API: `https://api-service.fangcuntai.com`
|
|
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
|
-
|
|
71
|
-
## Security model
|
|
72
|
-
|
|
73
|
-
Write access is locked by default.
|
|
74
|
-
|
|
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.
|
|
78
|
-
|
|
79
|
-
Other safeguards:
|
|
80
|
-
|
|
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.
|
|
83
|
-
- A token is bound to a default family and can only switch to families the user has joined.
|
|
84
|
-
- Deleted ledger entries and notes are moved to the recycle bin and can be restored. Emptying the recycle bin is permanent.
|
|
85
|
-
- Ledger writes are marked with the `desktop_mcp` source.
|
|
86
|
-
- Requests include `X-App-ID: 60000` and `X-MCP-Tool` for auditing.
|
|
87
|
-
|
|
88
|
-
## Common flows
|
|
89
|
-
|
|
90
|
-
### Query the ledger
|
|
91
|
-
|
|
92
|
-
`list_my_families` → `select_family` → `list_ledger_books` → `select_ledger_book` → `get_ledger_summary`
|
|
85
|
+
The outer field differs by client (for example, Claude Desktop uses `mcpServers`). The JSON above is the server entry; the configuration copied from the app includes the correct outer structure.
|
|
93
86
|
|
|
94
|
-
|
|
87
|
+
### 3. Choose permissions
|
|
95
88
|
|
|
96
|
-
|
|
89
|
+
Select permissions when creating the token:
|
|
97
90
|
|
|
98
|
-
|
|
91
|
+
- Read-only ledger access: select **View transactions** and **View stats**.
|
|
92
|
+
- To create, update, or delete ledger entries: also select **Add / delete entries**.
|
|
93
|
+
- To write notes or organize folders: also select **Write notes**.
|
|
94
|
+
- To link notes and ledger entries: both write permissions are required.
|
|
99
95
|
|
|
100
|
-
|
|
96
|
+
### 4. Restart the client
|
|
101
97
|
|
|
102
|
-
|
|
98
|
+
Restart the desktop client after saving the configuration so it reloads the MCP server. To verify the connection, ask: "How much did our family spend this month?"
|
|
103
99
|
|
|
104
|
-
|
|
100
|
+
## Security and privacy
|
|
105
101
|
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
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.
|
|
123
|
-
|
|
124
|
-
### Organize note folders
|
|
125
|
-
|
|
126
|
-
`list_note_folders` → `unlock_writes` → `create_note_folder` / `rename_note_folder` / `move_note_folder`
|
|
127
|
-
|
|
128
|
-
Folders can be at most two levels deep. Deleting an empty folder requires `prepare_delete_note_folder` → `confirm_delete_note_folder`.
|
|
129
|
-
|
|
130
|
-
### Restore deleted items
|
|
131
|
-
|
|
132
|
-
Ledger entries: `list_ledger_trash` → `restore_ledger_entry`
|
|
133
|
-
|
|
134
|
-
Notes: `list_notes_trash` → `restore_note`
|
|
135
|
-
|
|
136
|
-
Emptying the recycle bin is permanent and requires `prepare_*` → `confirm_*`.
|
|
102
|
+
- A token only works within the permissions you selected, and the server checks them again.
|
|
103
|
+
- Creating entries, writing notes, deleting, and emptying the recycle bin show a summary first and save only after you confirm.
|
|
104
|
+
- Deleted ledger entries and notes go to the recycle bin and can be restored. Emptying the recycle bin is permanent.
|
|
105
|
+
- Ledger entries written by the desktop assistant carry a source marker visible in the app.
|
|
106
|
+
- The MCP server does not connect to the database or cache ledgers and notes; pending confirmations live only in the current process memory.
|
|
107
|
+
- Revoking the token in the app immediately disables the desktop assistant.
|
|
137
108
|
|
|
138
109
|
## Updates
|
|
139
110
|
|
|
@@ -149,47 +120,18 @@ Pin a specific version:
|
|
|
149
120
|
|
|
150
121
|
```json
|
|
151
122
|
{
|
|
152
|
-
"args": ["-y", "@fangcuntai/fangcuntai-mcp@1.6.
|
|
123
|
+
"args": ["-y", "@fangcuntai/fangcuntai-mcp@1.6.8"]
|
|
153
124
|
}
|
|
154
125
|
```
|
|
155
126
|
|
|
156
127
|
## Troubleshooting
|
|
157
128
|
|
|
158
|
-
- **
|
|
159
|
-
-
|
|
160
|
-
- **
|
|
129
|
+
- **No fangcuntai tools in the client**: restart the client after saving the configuration; confirm Node.js 18+ and that the config is under the correct `mcpServers` field.
|
|
130
|
+
- **Missing `FANGCUNTAI_TOKEN`**: make sure the client configuration includes the `hm_at_` token created in the app.
|
|
131
|
+
- **Missing-permission error**: create a new token in the app with the required permissions. Existing tokens cannot be expanded.
|
|
161
132
|
- **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
|
|
163
|
-
|
|
164
|
-
## Local development
|
|
165
|
-
|
|
166
|
-
```bash
|
|
167
|
-
cd fangcuntai-mcp
|
|
168
|
-
npm install
|
|
169
|
-
npm test
|
|
170
|
-
npm run build
|
|
171
|
-
|
|
172
|
-
FANGCUNTAI_TOKEN=hm_at_xxx \
|
|
173
|
-
FANGCUNTAI_API=http://127.0.0.1:9080 \
|
|
174
|
-
node dist/index.js
|
|
175
|
-
```
|
|
176
|
-
|
|
177
|
-
Local test data:
|
|
178
|
-
|
|
179
|
-
```bash
|
|
180
|
-
cd ../home-admin
|
|
181
|
-
go run cmd/seed-mcp-test-data/main.go -config config/config.yaml
|
|
182
|
-
```
|
|
183
|
-
|
|
184
|
-
The command only writes to the local development database and can be run repeatedly.
|
|
185
|
-
|
|
186
|
-
## Publishing
|
|
187
|
-
|
|
188
|
-
```bash
|
|
189
|
-
npm publish --access public
|
|
190
|
-
```
|
|
191
|
-
|
|
192
|
-
Use `npm publish --dry-run --access public` to inspect the package before publishing.
|
|
133
|
+
- **Cannot reach the API**: the local default is `http://127.0.0.1:9080`; for normal use, copy the production configuration from the app.
|
|
134
|
+
- **Token lost or leaked**: revoke it in the app and create a new one.
|
|
193
135
|
|
|
194
136
|
## Links
|
|
195
137
|
|
package/README.md
CHANGED
|
@@ -1,19 +1,59 @@
|
|
|
1
1
|
# @fangcuntai/fangcuntai-mcp
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
方寸台是一个面向家庭的 AI 助手:把家庭账本、成员协作和小家师放在一起。App 里的小家师帮你查账、记账、写记事;桌面 MCP 把同一份家庭数据接进 Claude Desktop、Cursor、龙虾等桌面 AI。记账、写记事和删除前先给你看摘要,账单和记事删了还能恢复。
|
|
4
4
|
|
|
5
5
|
[English](https://unpkg.com/@fangcuntai/fangcuntai-mcp/README.en.md)
|
|
6
6
|
|
|
7
|
-
##
|
|
7
|
+
## 方寸台和小家师
|
|
8
8
|
|
|
9
|
-
|
|
10
|
-
|
|
9
|
+
小家师是 App 里的家庭 AI 助手,默认做家里的日常管家:查账、分析开销、记账、写记事、整理家庭约定和待办。你说要记,它直接写进正式账本和记事;改过的内容可以在「我的 → AI 配置 → 修改记录」查看。
|
|
10
|
+
|
|
11
|
+
它还能:
|
|
12
|
+
|
|
13
|
+
- 按月份、年份或季度查账,回答「这个月花了多少」「花得合理吗」「接下来还要花多少」。
|
|
14
|
+
- 会尽量一次写全记事的标题、正文、可见范围、标签和文件夹;整理已有记事时只改文件夹和标签。
|
|
15
|
+
- 把一篇记事和对应账单挂在一起。
|
|
16
|
+
- 结合家庭数据给建议;相处、情绪等想深入聊,可以在输入框上方 `@` 专业小师。
|
|
17
|
+
- 每个家人可以自己选择小家师能看哪些账本和记事。
|
|
18
|
+
|
|
19
|
+
小家师不是心理医生,也不做算命或替代家长做决定;遇到医疗、法律、严重心理问题,会建议找专业人士。
|
|
20
|
+
|
|
21
|
+
桌面 MCP 是小家师在电脑上的延伸:同一本账、同一份记事,接进 Claude Desktop / Cursor / 龙虾。App 里的小家师直接写入;桌面 MCP 仍保留写入确认。MCP 不替代 App 内聊天,也不包含专业小师和私有技能。
|
|
22
|
+
|
|
23
|
+
## 为什么用桌面 MCP
|
|
24
|
+
|
|
25
|
+
- **官方 MCP,不是社区包装**:直接走方寸台 API,和 App 是同一本账、同一份记事。
|
|
26
|
+
- **家庭场景**:可以切换已加入的家庭和账本,权限仍由方寸台家庭权限校验。
|
|
27
|
+
- **写入有确认**:记账、写记事、删除和清空回收站前,先展示摘要,你确认后才保存。
|
|
28
|
+
- **误删可恢复**:账单和记事删除后进入回收站,可以恢复;清空回收站才永久删除。
|
|
29
|
+
- **来源可追踪**:桌面助手写入的账单带来源标记,App 里能查到。
|
|
30
|
+
|
|
31
|
+
## 适合谁
|
|
32
|
+
|
|
33
|
+
- 已经在方寸台记账、记事,想在电脑上顺手处理。
|
|
34
|
+
- 家里多人共用账本,需要在不同家庭和账本之间切换。
|
|
35
|
+
- 想让 AI 帮忙整理账单和记事,但写入前要能看一眼。
|
|
36
|
+
|
|
37
|
+
## 桌面 MCP 能做什么
|
|
38
|
+
|
|
39
|
+
- **查账**:查看收支摘要、流水、趋势和分类。
|
|
40
|
+
- **记账**:记一笔、改一笔、删除,以及恢复或清空回收站。
|
|
11
41
|
- **记事**:查看、搜索、新建、移动记事,整理两层文件夹。待办写成 `- [ ]` / `- [x]`,可用 `[[标题]]` 引用其他记事。
|
|
12
42
|
- **挂接**:把一篇记事和一笔账挂在一起,或拆开。
|
|
13
43
|
- **账号**:查询订阅状态和 AI 积分。
|
|
14
|
-
- **可追踪**:写入带来源标记,可在方寸台 App 中看到是桌面助手写的。
|
|
15
44
|
|
|
16
|
-
|
|
45
|
+
## 可以这样问
|
|
46
|
+
|
|
47
|
+
- 「这个月家里花了多少?」
|
|
48
|
+
- 「记一笔:今天买菜 58 元,算餐饮。」
|
|
49
|
+
- 「把上周那篇装修记事挂到这笔账上。」
|
|
50
|
+
- 「把出行相关的记事整理到「2026出行」文件夹。」
|
|
51
|
+
|
|
52
|
+
## 桌面 MCP 的边界
|
|
53
|
+
|
|
54
|
+
- 只处理当前账号有权限查看的家庭和账本。
|
|
55
|
+
- 不改账本设置、成员权限、订阅或积分;订阅和积分只能查询。
|
|
56
|
+
- 事情提醒已下线,不提供提醒功能。
|
|
17
57
|
|
|
18
58
|
## 快速开始
|
|
19
59
|
|
|
@@ -23,7 +63,7 @@ MCP 只访问方寸台 API,不直连数据库。
|
|
|
23
63
|
- 一个方寸台账号。
|
|
24
64
|
- 在方寸台 App 生成桌面助手令牌:**我的 → AI 配置 → 连接桌面助手**。
|
|
25
65
|
|
|
26
|
-
|
|
66
|
+
令牌明文只显示一次。已有令牌不能改权限,需要撤销后重新生成。
|
|
27
67
|
|
|
28
68
|
### 2. 配置
|
|
29
69
|
|
|
@@ -42,98 +82,29 @@ MCP 只访问方寸台 API,不直连数据库。
|
|
|
42
82
|
|
|
43
83
|
也可以从方寸台 App 的「连接桌面助手」页面复制完整配置。
|
|
44
84
|
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
| 变量 | 必填 | 说明 |
|
|
48
|
-
|------|------|------|
|
|
49
|
-
| `FANGCUNTAI_TOKEN` | 是 | App 生成的助手令牌,以 `hm_at_` 开头 |
|
|
50
|
-
| `FANGCUNTAI_API` | 否 | API 地址,默认 `http://127.0.0.1:9080` |
|
|
51
|
-
|
|
52
|
-
生产 API:`https://api-service.fangcuntai.com`
|
|
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
|
-
|
|
71
|
-
## 安全模型
|
|
72
|
-
|
|
73
|
-
桌面助手默认处于写锁状态。
|
|
74
|
-
|
|
75
|
-
1. 你明确同意后,调用 `unlock_writes`(`user_acknowledged=true`)解锁。
|
|
76
|
-
2. 写操作先调用 `prepare_*`,返回待确认摘要和一次性 `confirm_token`。
|
|
77
|
-
3. 你确认后,再调用对应的 `confirm_*` 写入正式数据。
|
|
78
|
-
|
|
79
|
-
此外:
|
|
80
|
-
|
|
81
|
-
- 解锁后约 15 分钟会过期,每次 `prepare_*` 会续期;确认码约 2 分钟过期。
|
|
82
|
-
- 令牌权限由 App 生成时决定,服务端会再次校验。
|
|
83
|
-
- 令牌绑定默认家庭,会话中只能切换到用户已经加入的其他家庭。
|
|
84
|
-
- 删除的账单和记事进入回收站,可以恢复;清空回收站不可恢复。
|
|
85
|
-
- 写入账单的来源标记为 `desktop_mcp`。
|
|
86
|
-
- 请求使用 `X-App-ID: 60000` 和 `X-MCP-Tool`,便于审计。
|
|
87
|
-
|
|
88
|
-
## 常用流程
|
|
89
|
-
|
|
90
|
-
### 查账
|
|
91
|
-
|
|
92
|
-
`list_my_families` → `select_family` → `list_ledger_books` → `select_ledger_book` → `get_ledger_summary`
|
|
85
|
+
不同客户端的外层字段不同(例如 Claude Desktop 用 `mcpServers`)。上面是服务器条目;从 App 复制的配置会带好外层结构。
|
|
93
86
|
|
|
94
|
-
|
|
87
|
+
### 3. 勾选权限
|
|
95
88
|
|
|
96
|
-
|
|
89
|
+
生成令牌时按需要勾选:
|
|
97
90
|
|
|
98
|
-
|
|
91
|
+
- 只想查账:勾「查询账单」和「查看统计」。
|
|
92
|
+
- 要记账、改账或删除流水:再勾「记一笔 / 删除」。
|
|
93
|
+
- 要写记事、整理文件夹:再勾「写记事」。
|
|
94
|
+
- 要挂接记事和账单:两个写权限都要勾。
|
|
99
95
|
|
|
100
|
-
|
|
96
|
+
### 4. 重启客户端
|
|
101
97
|
|
|
102
|
-
|
|
98
|
+
保存配置后重启桌面客户端,让 MCP 重新加载。第一次可以先问一句「这个月家里花了多少?」确认连接正常。
|
|
103
99
|
|
|
104
|
-
|
|
100
|
+
## 安全与隐私
|
|
105
101
|
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
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`
|
|
121
|
-
|
|
122
|
-
挂接本身不占每月记账条数。
|
|
123
|
-
|
|
124
|
-
### 整理记事文件夹
|
|
125
|
-
|
|
126
|
-
`list_note_folders` → `unlock_writes` → `create_note_folder` / `rename_note_folder` / `move_note_folder`
|
|
127
|
-
|
|
128
|
-
文件夹最多两层;删除空文件夹须 `prepare_delete_note_folder` → `confirm_delete_note_folder`。
|
|
129
|
-
|
|
130
|
-
### 恢复误删
|
|
131
|
-
|
|
132
|
-
账单:`list_ledger_trash` → `restore_ledger_entry`
|
|
133
|
-
|
|
134
|
-
记事:`list_notes_trash` → `restore_note`
|
|
135
|
-
|
|
136
|
-
清空回收站会永久删除,须先 `prepare_*` 再 `confirm_*`。
|
|
102
|
+
- 令牌只在你勾选的范围内工作,服务端还会再校验一次。
|
|
103
|
+
- 记账、写记事、删除和清空回收站前都会先展示摘要,确认后才写入正式数据。
|
|
104
|
+
- 账单和记事删除后进入回收站,可以恢复;清空回收站不可恢复。
|
|
105
|
+
- 桌面助手写入的账单带来源标记,App 里能看到是它写的。
|
|
106
|
+
- MCP 不直连数据库,也不缓存账本和记事;待确认内容只存在当前进程内存里。
|
|
107
|
+
- 在 App 里撤销令牌后,桌面助手会立刻失效。
|
|
137
108
|
|
|
138
109
|
## 更新
|
|
139
110
|
|
|
@@ -149,47 +120,18 @@ npm view @fangcuntai/fangcuntai-mcp version
|
|
|
149
120
|
|
|
150
121
|
```json
|
|
151
122
|
{
|
|
152
|
-
"args": ["-y", "@fangcuntai/fangcuntai-mcp@1.6.
|
|
123
|
+
"args": ["-y", "@fangcuntai/fangcuntai-mcp@1.6.8"]
|
|
153
124
|
}
|
|
154
125
|
```
|
|
155
126
|
|
|
156
127
|
## 常见问题
|
|
157
128
|
|
|
158
|
-
-
|
|
159
|
-
-
|
|
160
|
-
-
|
|
129
|
+
- **客户端里看不到 fangcuntai 工具**:保存配置后重启客户端;确认 Node.js 18+,并检查配置是否放在正确的 `mcpServers` 外层。
|
|
130
|
+
- **提示缺少 `FANGCUNTAI_TOKEN`**:确认客户端配置里填了 App 生成的 `hm_at_` 令牌。
|
|
131
|
+
- **提示未勾选权限**:在 App 里重新生成令牌,勾选对应权限;已有令牌不能追加权限。
|
|
161
132
|
- **提示只能改最近 1 个月**:更早的流水请在 App 里改,或让小家师直接更新。
|
|
162
|
-
- **连不上 API**:本地默认是 `http://127.0.0.1:9080
|
|
163
|
-
|
|
164
|
-
## 本地开发
|
|
165
|
-
|
|
166
|
-
```bash
|
|
167
|
-
cd fangcuntai-mcp
|
|
168
|
-
npm install
|
|
169
|
-
npm test
|
|
170
|
-
npm run build
|
|
171
|
-
|
|
172
|
-
FANGCUNTAI_TOKEN=hm_at_xxx \
|
|
173
|
-
FANGCUNTAI_API=http://127.0.0.1:9080 \
|
|
174
|
-
node dist/index.js
|
|
175
|
-
```
|
|
176
|
-
|
|
177
|
-
本地功能测试数据:
|
|
178
|
-
|
|
179
|
-
```bash
|
|
180
|
-
cd ../home-admin
|
|
181
|
-
go run cmd/seed-mcp-test-data/main.go -config config/config.yaml
|
|
182
|
-
```
|
|
183
|
-
|
|
184
|
-
命令只允许写入本机开发库,可重复执行。
|
|
185
|
-
|
|
186
|
-
## 发布
|
|
187
|
-
|
|
188
|
-
```bash
|
|
189
|
-
npm publish --access public
|
|
190
|
-
```
|
|
191
|
-
|
|
192
|
-
发布前可用 `npm publish --dry-run --access public` 检查包内容。
|
|
133
|
+
- **连不上 API**:本地默认是 `http://127.0.0.1:9080`;正常使用时从 App 复制配置,使用生产地址。
|
|
134
|
+
- **令牌丢失或泄露**:在 App 里撤销旧令牌,重新生成一个。
|
|
193
135
|
|
|
194
136
|
## 链接
|
|
195
137
|
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@fangcuntai/fangcuntai-mcp",
|
|
3
|
-
"version": "1.6.
|
|
4
|
-
"description": "
|
|
3
|
+
"version": "1.6.8",
|
|
4
|
+
"description": "方寸台家庭 AI 助手(小家师)的桌面 MCP:在 Claude Desktop、Cursor、龙虾里查家庭账本、记账、写记事;关键写入先确认,删除可恢复。",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"type": "module",
|
|
7
7
|
"bin": {
|
|
@@ -19,7 +19,8 @@
|
|
|
19
19
|
"dev": "tsc && node dist/index.js",
|
|
20
20
|
"organize-notes": "node scripts/organize-notes.mjs",
|
|
21
21
|
"test": "tsx --test \"src/**/*.test.ts\"",
|
|
22
|
-
"prepare": "npm run build"
|
|
22
|
+
"prepare": "npm run build",
|
|
23
|
+
"prepublishOnly": "npm test"
|
|
23
24
|
},
|
|
24
25
|
"publishConfig": {
|
|
25
26
|
"access": "public"
|
|
@@ -29,11 +30,28 @@
|
|
|
29
30
|
},
|
|
30
31
|
"keywords": [
|
|
31
32
|
"mcp",
|
|
33
|
+
"model-context-protocol",
|
|
34
|
+
"mcp-server",
|
|
32
35
|
"fangcuntai",
|
|
33
36
|
"方寸台",
|
|
37
|
+
"xiaojiaoshi",
|
|
38
|
+
"family-assistant",
|
|
39
|
+
"ai-assistant",
|
|
34
40
|
"family",
|
|
41
|
+
"family-finance",
|
|
42
|
+
"family-ledger",
|
|
35
43
|
"ledger",
|
|
36
|
-
"
|
|
44
|
+
"bookkeeping",
|
|
45
|
+
"personal-finance",
|
|
46
|
+
"expense-tracker",
|
|
47
|
+
"notes",
|
|
48
|
+
"claude-desktop",
|
|
49
|
+
"cursor",
|
|
50
|
+
"openclaw",
|
|
51
|
+
"lobster",
|
|
52
|
+
"desktop-assistant",
|
|
53
|
+
"家庭账本",
|
|
54
|
+
"记账"
|
|
37
55
|
],
|
|
38
56
|
"homepage": "https://www.fangcuntai.com",
|
|
39
57
|
"dependencies": {
|