@fangcuntai/fangcuntai-mcp 1.6.6 → 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 +96 -31
- package/README.md +92 -26
- package/package.json +1 -1
package/README.en.md
CHANGED
|
@@ -1,30 +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
|
|
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
|
-
##
|
|
7
|
+
## What it can do
|
|
8
8
|
|
|
9
|
-
-
|
|
10
|
-
-
|
|
11
|
-
-
|
|
12
|
-
-
|
|
13
|
-
-
|
|
14
|
-
-
|
|
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.
|
|
15
15
|
|
|
16
16
|
The MCP server accesses the Fangcuntai API only. It does not connect directly to the database.
|
|
17
17
|
|
|
18
|
-
##
|
|
18
|
+
## Quick start
|
|
19
|
+
|
|
20
|
+
### 1. Prepare
|
|
19
21
|
|
|
20
22
|
- Node.js 18 or later.
|
|
21
23
|
- A Fangcuntai account.
|
|
22
|
-
- A desktop assistant token created in the Fangcuntai app:
|
|
23
|
-
**Me > Settings > Connect Desktop Assistant**.
|
|
24
|
+
- A desktop assistant token created in the Fangcuntai app: **Me → AI settings → Connect Desktop Assistant**.
|
|
24
25
|
|
|
25
|
-
|
|
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.
|
|
26
27
|
|
|
27
|
-
|
|
28
|
+
### 2. Configure
|
|
28
29
|
|
|
29
30
|
Add this server to your MCP-compatible desktop client:
|
|
30
31
|
|
|
@@ -41,7 +42,7 @@ Add this server to your MCP-compatible desktop client:
|
|
|
41
42
|
|
|
42
43
|
You can also copy the complete configuration from the **Connect Desktop Assistant** page in the Fangcuntai app.
|
|
43
44
|
|
|
44
|
-
### Environment variables
|
|
45
|
+
### 3. Environment variables
|
|
45
46
|
|
|
46
47
|
| Variable | Required | Description |
|
|
47
48
|
|----------|----------|-------------|
|
|
@@ -50,19 +51,37 @@ You can also copy the complete configuration from the **Connect Desktop Assistan
|
|
|
50
51
|
|
|
51
52
|
Production API: `https://api-service.fangcuntai.com`
|
|
52
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
|
+
|
|
53
71
|
## Security model
|
|
54
72
|
|
|
55
73
|
Write access is locked by default.
|
|
56
74
|
|
|
57
|
-
1. After
|
|
58
|
-
2. Prepare the write
|
|
59
|
-
3.
|
|
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.
|
|
60
78
|
|
|
61
79
|
Other safeguards:
|
|
62
80
|
|
|
63
|
-
-
|
|
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.
|
|
64
83
|
- A token is bound to a default family and can only switch to families the user has joined.
|
|
65
|
-
- 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.
|
|
66
85
|
- Ledger writes are marked with the `desktop_mcp` source.
|
|
67
86
|
- Requests include `X-App-ID: 60000` and `X-MCP-Tool` for auditing.
|
|
68
87
|
|
|
@@ -70,33 +89,77 @@ Other safeguards:
|
|
|
70
89
|
|
|
71
90
|
### Query the ledger
|
|
72
91
|
|
|
73
|
-
`list_my_families`
|
|
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.
|
|
74
95
|
|
|
75
96
|
### Create a ledger entry
|
|
76
97
|
|
|
77
|
-
`unlock_writes`
|
|
98
|
+
`unlock_writes` → `prepare_create_ledger_entry` → user confirmation → `confirm_create_ledger_entry`
|
|
78
99
|
|
|
79
|
-
|
|
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.
|
|
80
101
|
|
|
81
|
-
|
|
102
|
+
### Update a ledger entry
|
|
82
103
|
|
|
83
|
-
|
|
104
|
+
`unlock_writes` → `prepare_update_ledger_entry` → user confirmation → `confirm_update_ledger_entry`
|
|
84
105
|
|
|
85
|
-
|
|
106
|
+
Only entries added in the last month can be updated. Income and expense cannot be switched.
|
|
86
107
|
|
|
87
|
-
###
|
|
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.
|
|
88
123
|
|
|
89
|
-
|
|
124
|
+
### Organize note folders
|
|
90
125
|
|
|
91
|
-
|
|
126
|
+
`list_note_folders` → `unlock_writes` → `create_note_folder` / `rename_note_folder` / `move_note_folder`
|
|
92
127
|
|
|
93
|
-
|
|
128
|
+
Folders can be at most two levels deep. Deleting an empty folder requires `prepare_delete_note_folder` → `confirm_delete_note_folder`.
|
|
94
129
|
|
|
95
130
|
### Restore deleted items
|
|
96
131
|
|
|
97
|
-
Ledger entries: `list_ledger_trash`
|
|
132
|
+
Ledger entries: `list_ledger_trash` → `restore_ledger_entry`
|
|
98
133
|
|
|
99
|
-
Notes: `list_notes_trash`
|
|
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`.
|
|
100
163
|
|
|
101
164
|
## Local development
|
|
102
165
|
|
|
@@ -126,6 +189,8 @@ The command only writes to the local development database and can be run repeate
|
|
|
126
189
|
npm publish --access public
|
|
127
190
|
```
|
|
128
191
|
|
|
192
|
+
Use `npm publish --dry-run --access public` to inspect the package before publishing.
|
|
193
|
+
|
|
129
194
|
## Links
|
|
130
195
|
|
|
131
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
|
-
-
|
|
12
|
-
-
|
|
13
|
-
-
|
|
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
|
-
**我的 → AI 配置 → 连接桌面助手**。
|
|
24
|
+
- 在方寸台 App 生成桌面助手令牌:**我的 → AI 配置 → 连接桌面助手**。
|
|
23
25
|
|
|
24
|
-
|
|
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.
|
|
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
|
-
|
|
102
|
+
### 改一笔
|
|
81
103
|
|
|
82
|
-
|
|
104
|
+
`unlock_writes` → `prepare_update_ledger_entry` → 用户确认 → `confirm_update_ledger_entry`
|
|
83
105
|
|
|
84
|
-
|
|
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
|
-
|
|
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
|