@fangcuntai/fangcuntai-mcp 1.6.1 → 1.6.3
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 +125 -0
- package/README.md +60 -119
- package/dist/index.js +1 -1
- package/package.json +4 -7
package/README.en.md
ADDED
|
@@ -0,0 +1,125 @@
|
|
|
1
|
+
# @fangcuntai/fangcuntai-mcp
|
|
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.
|
|
4
|
+
|
|
5
|
+
[简体中文](https://unpkg.com/@fangcuntai/fangcuntai-mcp/README.md)
|
|
6
|
+
|
|
7
|
+
## Features
|
|
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.
|
|
13
|
+
- Review and confirm AI drafts.
|
|
14
|
+
- Check subscription status and AI credit balance.
|
|
15
|
+
- Track writes created by the desktop assistant.
|
|
16
|
+
|
|
17
|
+
The MCP server accesses the Fangcuntai API only. It does not connect directly to the database.
|
|
18
|
+
|
|
19
|
+
## Requirements
|
|
20
|
+
|
|
21
|
+
- Node.js 18 or later.
|
|
22
|
+
- A Fangcuntai account.
|
|
23
|
+
- A desktop assistant token created in the Fangcuntai app:
|
|
24
|
+
**Me > Settings > Connect Desktop Assistant**.
|
|
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.
|
|
27
|
+
|
|
28
|
+
## Configuration
|
|
29
|
+
|
|
30
|
+
Add this server to your MCP-compatible desktop client:
|
|
31
|
+
|
|
32
|
+
```json
|
|
33
|
+
{
|
|
34
|
+
"command": "npx",
|
|
35
|
+
"args": ["-y", "@fangcuntai/fangcuntai-mcp"],
|
|
36
|
+
"env": {
|
|
37
|
+
"FANGCUNTAI_API": "https://api-service.fangcuntai.com",
|
|
38
|
+
"FANGCUNTAI_TOKEN": "hm_at_your_token"
|
|
39
|
+
}
|
|
40
|
+
}
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
You can also copy the complete configuration from the **Connect Desktop Assistant** page in the Fangcuntai app.
|
|
44
|
+
|
|
45
|
+
### Environment variables
|
|
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
|
+
## Security model
|
|
55
|
+
|
|
56
|
+
Write access is locked by default.
|
|
57
|
+
|
|
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.
|
|
61
|
+
|
|
62
|
+
Other safeguards:
|
|
63
|
+
|
|
64
|
+
- The server validates the token permissions selected in the app.
|
|
65
|
+
- 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.
|
|
67
|
+
- Ledger writes are marked with the `desktop_mcp` source.
|
|
68
|
+
- Requests include `X-App-ID: 60000` and `X-MCP-Tool` for auditing.
|
|
69
|
+
|
|
70
|
+
## Common flows
|
|
71
|
+
|
|
72
|
+
### Query the ledger
|
|
73
|
+
|
|
74
|
+
`list_my_families` -> `select_family` -> `list_ledger_books` -> `select_ledger_book` -> `get_ledger_summary`
|
|
75
|
+
|
|
76
|
+
### Create a ledger entry
|
|
77
|
+
|
|
78
|
+
`unlock_writes` -> `prepare_create_ledger_entry` -> user confirmation -> `confirm_create_ledger_entry`
|
|
79
|
+
|
|
80
|
+
### Organize notes
|
|
81
|
+
|
|
82
|
+
`list_note_folders` -> `unlock_writes` -> `create_note_folder` / `rename_note_folder` / `move_note_folder`
|
|
83
|
+
|
|
84
|
+
### Restore deleted items
|
|
85
|
+
|
|
86
|
+
Ledger entries: `list_ledger_trash` -> `restore_ledger_entry`
|
|
87
|
+
|
|
88
|
+
Notes: `list_notes_trash` -> `restore_note`
|
|
89
|
+
|
|
90
|
+
## Local development
|
|
91
|
+
|
|
92
|
+
```bash
|
|
93
|
+
cd fangcuntai-mcp
|
|
94
|
+
npm install
|
|
95
|
+
npm test
|
|
96
|
+
npm run build
|
|
97
|
+
|
|
98
|
+
FANGCUNTAI_TOKEN=hm_at_xxx \
|
|
99
|
+
FANGCUNTAI_API=http://127.0.0.1:9080 \
|
|
100
|
+
node dist/index.js
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
Local test data:
|
|
104
|
+
|
|
105
|
+
```bash
|
|
106
|
+
cd ../home-admin
|
|
107
|
+
go run cmd/seed-mcp-test-data/main.go -config config/config.yaml
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
The command only writes to the local development database and can be run repeatedly.
|
|
111
|
+
|
|
112
|
+
## Publishing
|
|
113
|
+
|
|
114
|
+
```bash
|
|
115
|
+
npm publish --access public
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
## Links
|
|
119
|
+
|
|
120
|
+
- Website: https://www.fangcuntai.com
|
|
121
|
+
- npm: https://www.npmjs.com/package/@fangcuntai/fangcuntai-mcp
|
|
122
|
+
|
|
123
|
+
## License
|
|
124
|
+
|
|
125
|
+
MIT
|
package/README.md
CHANGED
|
@@ -1,44 +1,31 @@
|
|
|
1
1
|
# @fangcuntai/fangcuntai-mcp
|
|
2
2
|
|
|
3
|
-
方寸台桌面助手 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
|
-
|
|
14
|
-
4. 确保主 API 可访问(App 生产:`https://api-service.fangcuntai.com`;本地默认 `http://127.0.0.1:9080`)
|
|
15
|
-
|
|
16
|
-
## 环境变量
|
|
17
|
-
|
|
18
|
-
| 变量 | 必填 | 说明 |
|
|
19
|
-
|------|------|------|
|
|
20
|
-
| `FANGCUNTAI_TOKEN` | 是 | App 生成的助手令牌(`hm_at_...`) |
|
|
21
|
-
| `FANGCUNTAI_API` | 否 | API 根地址,默认 `http://127.0.0.1:9080` |
|
|
9
|
+
- 切换家庭和账本,查询收支摘要、账单、趋势与分类。
|
|
10
|
+
- 在确认锁保护下记账、删除、恢复回收站和清空回收站。
|
|
11
|
+
- 查看和搜索记事,整理两层记事文件夹,创建记事草稿。
|
|
12
|
+
- 查看并批量确认 AI 草稿,查询订阅和 AI 积分。
|
|
13
|
+
- 写入数据带来源标记,可在方寸台 App 中追踪。
|
|
22
14
|
|
|
23
|
-
|
|
15
|
+
MCP 只访问方寸台 API,不直连数据库。
|
|
24
16
|
|
|
25
|
-
##
|
|
26
|
-
|
|
27
|
-
防的是:**AI 误调写接口改正式数据**(MCP 不直连数据库)。
|
|
17
|
+
## 前置条件
|
|
28
18
|
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
| **令牌权限** | App 生成时勾选查询/统计/草稿/记一笔;缺权限时工具拒绝并提示重新生成。已有令牌不能改权限 |
|
|
34
|
-
| **来源标记(追溯)** | 入账 `source=desktop_mcp`,App 可区分桌面助手写入 |
|
|
35
|
-
| **回收站(后门)** | 删除软删;`list_ledger_trash` / `restore_ledger_entry`、`list_notes_trash` / `restore_note` 可恢复。清空回收站为永久删除,须确认锁 |
|
|
19
|
+
- Node.js 18 或更高版本。
|
|
20
|
+
- 一个方寸台账号。
|
|
21
|
+
- 在方寸台 App 中生成桌面助手令牌:
|
|
22
|
+
**我的 → 设置 → 连接桌面助手**。
|
|
36
23
|
|
|
37
|
-
|
|
24
|
+
生成令牌时可选择默认家庭和权限。令牌明文只显示一次,可在 App 中随时撤销。
|
|
38
25
|
|
|
39
|
-
|
|
26
|
+
## 配置
|
|
40
27
|
|
|
41
|
-
|
|
28
|
+
把以下配置添加到支持 MCP 的桌面客户端:
|
|
42
29
|
|
|
43
30
|
```json
|
|
44
31
|
{
|
|
@@ -51,106 +38,52 @@
|
|
|
51
38
|
}
|
|
52
39
|
```
|
|
53
40
|
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
### 查账(无需解锁)
|
|
57
|
-
|
|
58
|
-
`list_my_families` → `select_family` → `list_ledger_books` → `select_ledger_book` → `get_ledger_summary` / `list_ledger_entries`
|
|
59
|
-
|
|
60
|
-
### 记一笔(须确认)
|
|
41
|
+
也可以从方寸台 App 的「连接桌面助手」页面复制完整配置。
|
|
61
42
|
|
|
62
|
-
|
|
63
|
-
2. `prepare_create_ledger_entry` → 向用户展示 summary
|
|
64
|
-
3. 用户说确认 → `confirm_create_ledger_entry(confirm_token)`
|
|
43
|
+
### 环境变量
|
|
65
44
|
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
`
|
|
69
|
-
|
|
70
|
-
清空:`prepare_empty_ledger_trash` → 确认 → `confirm_empty_ledger_trash`(永久删除)
|
|
71
|
-
|
|
72
|
-
### 删一篇记事(进回收站)
|
|
73
|
-
|
|
74
|
-
`unlock_writes` → `prepare_delete_note` → 确认 → `confirm_delete_note`
|
|
75
|
-
误删:`list_notes_trash` → `restore_note`
|
|
76
|
-
清空:`prepare_empty_notes_trash` → 确认 → `confirm_empty_notes_trash`(永久删除)
|
|
45
|
+
| 变量 | 必填 | 说明 |
|
|
46
|
+
|------|------|------|
|
|
47
|
+
| `FANGCUNTAI_TOKEN` | 是 | App 生成的助手令牌,以 `hm_at_` 开头 |
|
|
48
|
+
| `FANGCUNTAI_API` | 否 | API 地址,默认 `http://127.0.0.1:9080` |
|
|
77
49
|
|
|
78
|
-
|
|
50
|
+
生产 API:`https://api-service.fangcuntai.com`
|
|
79
51
|
|
|
80
|
-
|
|
52
|
+
## 安全模型
|
|
81
53
|
|
|
82
|
-
|
|
83
|
-
|------|------|
|
|
84
|
-
| `get_write_lock_status` | 是否解锁、剩余秒数 |
|
|
85
|
-
| `unlock_writes` | 解锁(须 `user_acknowledged=true`) |
|
|
86
|
-
| `lock_writes` | 立即上锁 |
|
|
54
|
+
桌面助手默认处于写锁状态。
|
|
87
55
|
|
|
88
|
-
|
|
56
|
+
1. 用户明确同意后,调用 `unlock_writes` 解锁。
|
|
57
|
+
2. 写操作先生成待确认内容并展示摘要。
|
|
58
|
+
3. 用户确认后,才使用一次性确认令牌完成写入。
|
|
89
59
|
|
|
90
|
-
|
|
91
|
-
|------|------|
|
|
92
|
-
| `get_assistant_context` | 令牌默认家庭 / 公开 scopes + workspace |
|
|
93
|
-
| `get_active_workspace` | 当前会话家庭与账本 |
|
|
94
|
-
| `list_my_families` / `select_family` | 家庭列表与切换 |
|
|
95
|
-
| `get_bound_family` / `get_family_entitlements` / `list_family_members` | 家庭信息与权限 |
|
|
60
|
+
此外:
|
|
96
61
|
|
|
97
|
-
|
|
62
|
+
- 令牌权限由 App 生成时决定,服务端会再次校验。
|
|
63
|
+
- 令牌绑定默认家庭,会话中只能切换到用户已加入的其他家庭。
|
|
64
|
+
- 删除的账单和记事进入回收站,可以恢复。
|
|
65
|
+
- 写入账单的来源标记为 `desktop_mcp`。
|
|
66
|
+
- 请求使用 `X-App-ID: 60000` 和 `X-MCP-Tool` 便于审计。
|
|
98
67
|
|
|
99
|
-
|
|
100
|
-
|------|------|
|
|
101
|
-
| `list_ledger_books` / `select_ledger_book` | 账本;列表含用法、状态、说明(最多 50 字) |
|
|
102
|
-
| `get_ledger_summary` / `list_ledger_entries` / `get_ledger_trends` | 查账;时期账本不传 `month` 时 `get_ledger_summary` 返回整件事;`list_ledger_entries` 可按 `external_order_id` 精确查找 |
|
|
103
|
-
| `list_ledger_categories` | 分类 |
|
|
104
|
-
| `prepare_create_ledger_entry` / `confirm_create_ledger_entry` | 确认后入账;可传 `external_order_id`,已存在则 `already_exists` |
|
|
105
|
-
| `prepare_delete_ledger_entry` / `confirm_delete_ledger_entry` | 确认后进回收站 |
|
|
106
|
-
| `list_ledger_trash` / `restore_ledger_entry` | 回收站 |
|
|
107
|
-
| `prepare_empty_ledger_trash` / `confirm_empty_ledger_trash` | 清空回收站(永久删除) |
|
|
108
|
-
| `create_ledger_draft` | 仅草稿 |
|
|
68
|
+
## 常用流程
|
|
109
69
|
|
|
110
|
-
###
|
|
70
|
+
### 查账
|
|
111
71
|
|
|
112
|
-
|
|
113
|
-
|------|------|
|
|
114
|
-
| `list_note_folders` | 文件夹扁平列表(最多两层;按 `parent_id` 组树) |
|
|
115
|
-
| `create_note_folder` / `rename_note_folder` / `move_note_folder` | 建/改名/移动文件夹(须 `unlock_writes`) |
|
|
116
|
-
| `prepare_delete_note_folder` / `confirm_delete_note_folder` | 删空文件夹(须解锁 + confirm_token;非空拒绝) |
|
|
117
|
-
| `list_notes` / `search_notes` | 记事;`list_notes` 可传 `folder_id`(`0`=未分类;有关键词时忽略) |
|
|
118
|
-
| `create_note_draft` | 记事草稿;可传 `folder_id` |
|
|
119
|
-
| `prepare_move_note` / `confirm_move_note` | 已有记事改所属文件夹(须解锁 + confirm_token) |
|
|
120
|
-
| `prepare_delete_note` / `confirm_delete_note` | 确认后进回收站 |
|
|
121
|
-
| `list_notes_trash` / `restore_note` | 记事回收站 |
|
|
122
|
-
| `prepare_empty_notes_trash` / `confirm_empty_notes_trash` | 清空记事回收站(永久删除) |
|
|
123
|
-
| `list_ai_drafts` | 待确认列表(**仅当前账号自己创建的**;家长也不能看全家);可传 `session_id=mcp` |
|
|
124
|
-
| `get_ai_draft` | 单条详情(仅创建者;他人 404) |
|
|
125
|
-
| `prepare_confirm_ai_draft` / `confirm_ai_draft` | 单条确认(须解锁 + confirm_token;仅创建者) |
|
|
126
|
-
| `discard_ai_draft` | 单条丢弃(仅创建者) |
|
|
127
|
-
| `prepare_batch_confirm_ai_drafts` / `batch_confirm_ai_drafts` | 批量确认自己的草稿(须解锁 + confirm_token) |
|
|
128
|
-
| `batch_discard_ai_drafts` | 批量丢弃自己的草稿(不改正式数据,无需解锁) |
|
|
72
|
+
`list_my_families` → `select_family` → `list_ledger_books` → `select_ledger_book` → `get_ledger_summary`
|
|
129
73
|
|
|
130
|
-
|
|
74
|
+
### 记一笔
|
|
131
75
|
|
|
132
|
-
|
|
76
|
+
`unlock_writes` → `prepare_create_ledger_entry` → 用户确认 → `confirm_create_ledger_entry`
|
|
133
77
|
|
|
134
|
-
|
|
135
|
-
2. 征得同意 → `unlock_writes`
|
|
136
|
-
3. `create_note_folder` / `rename_note_folder` / `move_note_folder`
|
|
137
|
-
4. `list_notes(folder_id=…)` 浏览本层;`create_note_draft(folder_id=…)` 写入
|
|
138
|
-
5. 移动已有记事:`prepare_move_note` → 确认 → `confirm_move_note`
|
|
139
|
-
6. 删空文件夹:`prepare_delete_note_folder` → 确认 → `confirm_delete_note_folder`
|
|
78
|
+
### 整理记事
|
|
140
79
|
|
|
141
|
-
|
|
80
|
+
`list_note_folders` → `unlock_writes` → `create_note_folder` / `rename_note_folder` / `move_note_folder`
|
|
142
81
|
|
|
143
|
-
|
|
144
|
-
|------|------|
|
|
145
|
-
| `get_subscription_info` | 订阅状态 |
|
|
146
|
-
| `get_credit_balance` | AI 积分余额 |
|
|
82
|
+
### 恢复误删
|
|
147
83
|
|
|
148
|
-
|
|
84
|
+
账单:`list_ledger_trash` → `restore_ledger_entry`
|
|
149
85
|
|
|
150
|
-
|
|
151
|
-
- 助手令牌仅开放白名单 API;写操作前检查家庭 `entitlements`
|
|
152
|
-
- App 内可随时撤销令牌
|
|
153
|
-
- 请求带 `X-App-ID: 60000` 与 `X-MCP-Tool`
|
|
86
|
+
记事:`list_notes_trash` → `restore_note`
|
|
154
87
|
|
|
155
88
|
## 本地开发
|
|
156
89
|
|
|
@@ -159,24 +92,32 @@ cd fangcuntai-mcp
|
|
|
159
92
|
npm install
|
|
160
93
|
npm test
|
|
161
94
|
npm run build
|
|
162
|
-
FANGCUNTAI_TOKEN=hm_at_xxx FANGCUNTAI_API=http://127.0.0.1:9080 node dist/index.js
|
|
163
|
-
```
|
|
164
95
|
|
|
165
|
-
|
|
96
|
+
FANGCUNTAI_TOKEN=hm_at_xxx \
|
|
97
|
+
FANGCUNTAI_API=http://127.0.0.1:9080 \
|
|
98
|
+
node dist/index.js
|
|
99
|
+
```
|
|
166
100
|
|
|
167
|
-
|
|
101
|
+
本地功能测试数据:
|
|
168
102
|
|
|
169
103
|
```bash
|
|
170
104
|
cd ../home-admin
|
|
171
105
|
go run cmd/seed-mcp-test-data/main.go -config config/config.yaml
|
|
172
106
|
```
|
|
173
107
|
|
|
174
|
-
|
|
175
|
-
近 3 个月账单、回收站条目、两层记事文件夹、不同可见范围的记事、MCP / 小家师草稿、
|
|
176
|
-
积分和固定测试令牌。输出中的 `FANGCUNTAI_TOKEN` 可直接用于本地 MCP 配置。
|
|
108
|
+
命令只允许写入本机开发库,可重复执行。
|
|
177
109
|
|
|
178
110
|
## 发布
|
|
179
111
|
|
|
180
112
|
```bash
|
|
181
113
|
npm publish --access public
|
|
182
114
|
```
|
|
115
|
+
|
|
116
|
+
## 链接
|
|
117
|
+
|
|
118
|
+
- 官网:https://www.fangcuntai.com
|
|
119
|
+
- npm:https://www.npmjs.com/package/@fangcuntai/fangcuntai-mcp
|
|
120
|
+
|
|
121
|
+
## License
|
|
122
|
+
|
|
123
|
+
MIT
|
package/dist/index.js
CHANGED
|
@@ -9,7 +9,7 @@ async function main() {
|
|
|
9
9
|
const client = new FangcuntaiApiClient(config.apiBase, config.token);
|
|
10
10
|
const server = new McpServer({
|
|
11
11
|
name: "fangcuntai",
|
|
12
|
-
version: "1.
|
|
12
|
+
version: "1.6.2",
|
|
13
13
|
});
|
|
14
14
|
registerTools(server, client);
|
|
15
15
|
const transport = new StdioServerTransport();
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@fangcuntai/fangcuntai-mcp",
|
|
3
|
-
"version": "1.6.
|
|
3
|
+
"version": "1.6.3",
|
|
4
4
|
"description": "方寸台桌面助手 MCP — 确认锁 + 来源标记 + 回收站 + 记事文件夹整理,安全地用自然语言管理家庭账本与记事",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"type": "module",
|
|
@@ -9,7 +9,8 @@
|
|
|
9
9
|
},
|
|
10
10
|
"files": [
|
|
11
11
|
"dist",
|
|
12
|
-
"README.md"
|
|
12
|
+
"README.md",
|
|
13
|
+
"README.en.md"
|
|
13
14
|
],
|
|
14
15
|
"scripts": {
|
|
15
16
|
"build": "tsc",
|
|
@@ -33,11 +34,7 @@
|
|
|
33
34
|
"ledger",
|
|
34
35
|
"desktop-assistant"
|
|
35
36
|
],
|
|
36
|
-
"
|
|
37
|
-
"type": "git",
|
|
38
|
-
"url": "https://github.com/rhinogo/home-man.git",
|
|
39
|
-
"directory": "fangcuntai-mcp"
|
|
40
|
-
},
|
|
37
|
+
"homepage": "https://www.fangcuntai.com",
|
|
41
38
|
"dependencies": {
|
|
42
39
|
"@modelcontextprotocol/sdk": "^1.12.1",
|
|
43
40
|
"zod": "^3.24.2"
|