@fangcuntai/fangcuntai-mcp 1.6.2 → 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 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 服务,供有道龙虾 / OpenClaw / Claude Desktop / Cursor 等客户端连接。
3
+ 方寸台桌面助手 MCP 服务。连接后可在有道龙虾 / OpenClaw、Claude Desktop、Cursor 等支持 MCP 的桌面客户端中,用自然语言查询家庭账本、整理记事,并在确认后安全地写入数据。
4
4
 
5
- 用自然语言完成:**切换家庭/账本 → 查账 →(解锁并确认后)记一笔/删一笔**;删除进回收站可恢复;**整理记事两层文件夹**(浏览本层、建文件夹、移动记事)。
5
+ [English](https://unpkg.com/@fangcuntai/fangcuntai-mcp/README.en.md)
6
6
 
7
- > **事情提醒已下线**:不再提供 `list_reminders` / `create_reminder_draft` / `mark_reminder_done`。
7
+ ## 功能
8
8
 
9
- ## 前置条件
10
-
11
- 1. 在方寸台 App:**我的 → 设置 → 连接桌面助手**
12
- 2. 选择**默认家庭**,勾选权限后生成令牌(查询账单 / 查看统计 / 创建草稿 / 记一笔·删除;已有令牌不能改权限);可一键复制完整 MCP 配置
13
- 3. 按页面内「如何安装到桌面 AI」把配置粘贴到龙虾 / Claude Desktop / Cursor
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
- > 兼容旧变量名:`HOME_MAN_TOKEN` / `HOME_MAN_API`(仍可使用,优先读 `FANGCUNTAI_*`)。
15
+ MCP 只访问方寸台 API,不直连数据库。
24
16
 
25
- ## 安全模型(v1.5)
26
-
27
- 防的是:**AI 误调写接口改正式数据**(MCP 不直连数据库)。
17
+ ## 前置条件
28
18
 
29
- | 层 | 机制 |
30
- |----|------|
31
- | **确认锁(前门)** | 默认上锁。入账/删除记账或记事/清空回收站/确认草稿(含批量)/删除文件夹/移动记事所属:`unlock_writes` → `prepare_*` → 展示摘要 → `confirm_*` |
32
- | **结构写(轻门)** | 新建/改名/移动文件夹:须 `unlock_writes` 后直接调用(非空文件夹不可删,服务端兜底) |
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
- > 亦可先 `create_ledger_draft` / `create_note_draft`,再确认草稿入账。当前账号开启个人 `auto_confirm_ai_drafts`(App「设置 → 草稿自动保存」)后,创建草稿会自动确认;失败则仍为 `pending`,可在 App「我的 → AI 草稿箱」批量保存。家长打开开关不会替家人自动保存。
26
+ ## 配置
40
27
 
41
- ## 有道龙虾 / OpenClaw 配置示例
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
- 1. 征得用户同意 → `unlock_writes`(`user_acknowledged=true`)
63
- 2. `prepare_create_ledger_entry` → 向用户展示 summary
64
- 3. 用户说确认 → `confirm_create_ledger_entry(confirm_token)`
43
+ ### 环境变量
65
44
 
66
- ### 删一笔(进回收站)
67
-
68
- `unlock_writes` → `prepare_delete_ledger_entry` → 确认 → `confirm_delete_ledger_entry`
69
- 误删:`list_ledger_trash` → `restore_ledger_entry`
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
- ## 工具列表(v1.5)
50
+ 生产 API:`https://api-service.fangcuntai.com`
79
51
 
80
- ### 安全锁
52
+ ## 安全模型
81
53
 
82
- | Tool | 说明 |
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
- | Tool | 说明 |
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
- | Tool | 说明 |
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
- | Tool | 说明 |
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
- > App 侧也可在 **我的 → AI 草稿箱** 勾选后批量保存。文件夹规则与 App 一致:全家共用、最多两层、非空不可删。
74
+ ### 记一笔
131
75
 
132
- ### 推荐:整理记事文件夹
76
+ `unlock_writes` → `prepare_create_ledger_entry` → 用户确认 → `confirm_create_ledger_entry`
133
77
 
134
- 1. `list_note_folders` → 了解树
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
- | Tool | 说明 |
144
- |------|------|
145
- | `get_subscription_info` | 订阅状态 |
146
- | `get_credit_balance` | AI 积分余额 |
82
+ ### 恢复误删
147
83
 
148
- ## 安全说明
84
+ 账单:`list_ledger_trash` → `restore_ledger_entry`
149
85
 
150
- - 令牌生成时**绑定默认家庭**;MCP 会话可切换到**你已加入**的其他家庭,不能访问无关家庭
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
- 先确保本地 PostgreSQL(`127.0.0.1:5433`)和 Redis(`127.0.0.1:6379`)可用,再执行:
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
- 命令仅允许写本机开发库,可重复执行且不会重复插入。它会创建 2 个家庭、2 个账本、
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.6.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.2",
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",