@fangcuntai/fangcuntai-mcp 1.6.0

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.
@@ -0,0 +1,307 @@
1
+ import { z } from "zod";
2
+ import { ensureFamilyId, familyPath, requireEntitlement, requireTokenScope, TOKEN_SCOPE_WRITE_DRAFT } from "../context/family-context.js";
3
+ import { createPending, pendingPublicView, requireWritesUnlocked, takePending, } from "../context/write-lock.js";
4
+ import { okJson, runTool } from "../utils/response.js";
5
+ /** folder_id:省略=不过滤/不改;0=未分类;正整数=指定文件夹。 */
6
+ const folderIdParam = z
7
+ .number()
8
+ .int()
9
+ .min(0)
10
+ .optional()
11
+ .describe("文件夹 ID;0 表示未分类;浏览列表时省略表示不过滤");
12
+ const parentIdParam = z
13
+ .number()
14
+ .int()
15
+ .positive()
16
+ .nullable()
17
+ .optional()
18
+ .describe("父文件夹 ID;null/省略表示一级文件夹");
19
+ export function registerNoteTools(server, client) {
20
+ server.tool("list_note_folders", "列出家庭记事文件夹(扁平列表,含 id/parent_id/name/sort_order)。客户端可按 parent_id 组两层树;未分类不在列表中(浏览用 folder_id=0)。", {}, async () => runTool(async () => {
21
+ client.setToolName("list_note_folders");
22
+ const familyId = await ensureFamilyId(client);
23
+ await requireEntitlement(client, familyId, "can_view_notes", "当前角色没有记事权限,无法查看文件夹");
24
+ const data = await client.get(familyPath(familyId, "/notes/folders"));
25
+ return okJson({
26
+ ...data,
27
+ hint: "最多两层:parent_id 为空为一级,非空为二级。整理:create/rename/move_note_folder;删空文件夹须 prepare→confirm。",
28
+ });
29
+ }));
30
+ server.tool("create_note_folder", "新建记事文件夹(须先 unlock_writes)。parent_id 省略/null 为一级;传入一级文件夹 ID 则建二级。同父不可重名;每家最多 50 个。", {
31
+ name: z.string().min(1).max(30).describe("文件夹名称,最多 30 字"),
32
+ parent_id: parentIdParam,
33
+ }, async ({ name, parent_id }) => runTool(async () => {
34
+ client.setToolName("create_note_folder");
35
+ requireWritesUnlocked();
36
+ const familyId = await ensureFamilyId(client);
37
+ await requireEntitlement(client, familyId, "can_view_notes", "当前角色没有记事权限,无法创建文件夹");
38
+ const body = { name };
39
+ if (parent_id != null)
40
+ body.parent_id = parent_id;
41
+ const data = await client.post(familyPath(familyId, "/notes/folders"), body);
42
+ return okJson({
43
+ ...data,
44
+ hint: "文件夹已创建。可用 list_notes(folder_id) 浏览本层,create_note_draft(folder_id) 写入该位置。",
45
+ });
46
+ }));
47
+ server.tool("rename_note_folder", "重命名记事文件夹(须先 unlock_writes)。同父下不可与已有名称冲突。", {
48
+ folder_id: z.number().int().positive(),
49
+ name: z.string().min(1).max(30),
50
+ }, async ({ folder_id, name }) => runTool(async () => {
51
+ client.setToolName("rename_note_folder");
52
+ requireWritesUnlocked();
53
+ const familyId = await ensureFamilyId(client);
54
+ await requireEntitlement(client, familyId, "can_view_notes", "当前角色没有记事权限,无法重命名文件夹");
55
+ const data = await client.put(familyPath(familyId, `/notes/folders/${folder_id}`), {
56
+ name,
57
+ });
58
+ return okJson(data);
59
+ }));
60
+ server.tool("move_note_folder", "移动/重排记事文件夹(须先 unlock_writes)。将 folder_id 放到 parent_id 下的 index 位置(0-based)。parent_id=null 表示升到/保持一级。仍最多两层:有子级的一级不能降为二级;不可挂到二级之下。", {
61
+ folder_id: z.number().int().positive(),
62
+ parent_id: z
63
+ .number()
64
+ .int()
65
+ .positive()
66
+ .nullable()
67
+ .describe("目标父级;null 表示一级(根级)"),
68
+ index: z.number().int().min(0).describe("目标兄弟列表中的位置,从 0 开始"),
69
+ }, async ({ folder_id, parent_id, index }) => runTool(async () => {
70
+ client.setToolName("move_note_folder");
71
+ requireWritesUnlocked();
72
+ const familyId = await ensureFamilyId(client);
73
+ await requireEntitlement(client, familyId, "can_view_notes", "当前角色没有记事权限,无法移动文件夹");
74
+ const data = await client.post(familyPath(familyId, "/notes/folders/move"), {
75
+ folder_id,
76
+ parent_id,
77
+ index,
78
+ });
79
+ return okJson(data);
80
+ }));
81
+ server.tool("prepare_delete_note_folder", "准备删除记事文件夹(须先 unlock_writes)。仅空文件夹可删(无子文件夹且无本层笔记)。返回 summary + confirm_token。", {
82
+ folder_id: z.number().int().positive(),
83
+ }, async ({ folder_id }) => runTool(async () => {
84
+ client.setToolName("prepare_delete_note_folder");
85
+ const familyId = await ensureFamilyId(client);
86
+ await requireEntitlement(client, familyId, "can_view_notes", "当前角色没有记事权限,无法删除文件夹");
87
+ const folders = await client.get(familyPath(familyId, "/notes/folders"));
88
+ const items = Array.isArray(folders.items) ? folders.items : [];
89
+ const folder = items.find((f) => Number(f.id) === folder_id);
90
+ if (!folder) {
91
+ throw new Error("未找到该文件夹,请先 list_note_folders 核对 folder_id");
92
+ }
93
+ const childCount = items.filter((f) => Number(f.parent_id) === folder_id).length;
94
+ const pending = createPending("delete_note_folder", familyId, {
95
+ action: "delete_note_folder",
96
+ folder_id,
97
+ name: folder.name,
98
+ parent_id: folder.parent_id ?? null,
99
+ child_folder_count: childCount,
100
+ note: childCount > 0
101
+ ? "该文件夹仍有子文件夹,确认时会被拒绝;请先移走或删除子级"
102
+ : "仅当本层无笔记且无子文件夹时才能删除;非空会失败且不丢笔记",
103
+ }, { folder_id });
104
+ return okJson(pendingPublicView(pending));
105
+ }));
106
+ server.tool("confirm_delete_note_folder", "确认删除空记事文件夹。必须传入 prepare_delete_note_folder 返回的 confirm_token。", {
107
+ confirm_token: z.string().min(1),
108
+ }, async ({ confirm_token }) => runTool(async () => {
109
+ client.setToolName("confirm_delete_note_folder");
110
+ const pending = takePending(confirm_token, "delete_note_folder");
111
+ const folderId = Number(pending.exec.folder_id);
112
+ await client.delete(familyPath(pending.familyId, `/notes/folders/${folderId}`));
113
+ return okJson({
114
+ ok: true,
115
+ folder_id: folderId,
116
+ hint: "文件夹已删除(若非空会失败,笔记不会被级联删除)。",
117
+ });
118
+ }));
119
+ server.tool("list_notes", "列出家庭记事。无 keyword 时可按 folder_id 浏览本层(0=未分类);有 keyword 时搜索全部可见笔记并忽略 folder_id。", {
120
+ page: z.number().int().min(1).optional(),
121
+ page_size: z.number().int().min(1).max(100).optional(),
122
+ keyword: z.string().optional(),
123
+ folder_id: folderIdParam,
124
+ }, async ({ page, page_size, keyword, folder_id }) => runTool(async () => {
125
+ client.setToolName("list_notes");
126
+ const familyId = await ensureFamilyId(client);
127
+ const query = {
128
+ page,
129
+ page_size,
130
+ keyword,
131
+ };
132
+ // 有关键词时服务端会忽略 folder_id;无关键词时再传,避免误导。
133
+ if (!keyword && folder_id !== undefined) {
134
+ query.folder_id = folder_id;
135
+ }
136
+ const data = await client.get(familyPath(familyId, "/notes"), query);
137
+ return okJson(data);
138
+ }));
139
+ server.tool("search_notes", "按关键词搜索家庭记事(全部可见笔记,不受当前文件夹限制)。", { keyword: z.string().min(1) }, async ({ keyword }) => runTool(async () => {
140
+ client.setToolName("search_notes");
141
+ const familyId = await ensureFamilyId(client);
142
+ const data = await client.get(familyPath(familyId, "/notes"), {
143
+ keyword,
144
+ page: 1,
145
+ page_size: 20,
146
+ });
147
+ return okJson(data);
148
+ }));
149
+ server.tool("create_note_draft", "创建记事草稿(不会直接保存)。visibility 可选 family / personal / selected / owner_only。folder_id 可选:0/省略=未分类,正整数=指定文件夹。", {
150
+ title: z.string().min(1),
151
+ content: z.string().optional(),
152
+ visibility: z.enum(["family", "personal", "selected", "owner_only"]).optional(),
153
+ folder_id: folderIdParam.describe("所属文件夹;0/省略=未分类"),
154
+ }, async (input) => runTool(async () => {
155
+ client.setToolName("create_note_draft");
156
+ const familyId = await ensureFamilyId(client);
157
+ await requireTokenScope(client, [TOKEN_SCOPE_WRITE_DRAFT]);
158
+ await requireEntitlement(client, familyId, "can_view_notes", "当前角色没有记事权限,无法创建记事草稿");
159
+ const payload = {
160
+ title: input.title,
161
+ content: input.content ?? "",
162
+ visibility: input.visibility ?? "family",
163
+ };
164
+ if (input.folder_id !== undefined) {
165
+ payload.folder_id = input.folder_id;
166
+ }
167
+ const data = await client.post(familyPath(familyId, "/ai-drafts"), {
168
+ draft_type: "note",
169
+ session_id: "mcp",
170
+ payload,
171
+ });
172
+ return okJson({
173
+ ...data,
174
+ hint: "草稿已创建。确认保存:unlock_writes → prepare_confirm_ai_draft → confirm_ai_draft;或 discard_ai_draft 丢弃。",
175
+ });
176
+ }));
177
+ server.tool("prepare_move_note", "准备将已有记事移到指定文件夹(须先 unlock_writes)。folder_id=0 表示未分类。返回 summary + confirm_token。", {
178
+ note_id: z.number().int().positive(),
179
+ folder_id: z
180
+ .number()
181
+ .int()
182
+ .min(0)
183
+ .describe("目标文件夹 ID;0=未分类"),
184
+ }, async ({ note_id, folder_id }) => runTool(async () => {
185
+ client.setToolName("prepare_move_note");
186
+ const familyId = await ensureFamilyId(client);
187
+ await requireEntitlement(client, familyId, "can_view_notes", "当前角色没有记事权限,无法移动记事");
188
+ const note = await client.get(familyPath(familyId, `/notes/${note_id}`));
189
+ let folderName = folder_id === 0 ? "未分类" : null;
190
+ if (folder_id > 0) {
191
+ const folders = await client.get(familyPath(familyId, "/notes/folders"));
192
+ const items = Array.isArray(folders.items) ? folders.items : [];
193
+ const folder = items.find((f) => Number(f.id) === folder_id);
194
+ if (!folder) {
195
+ throw new Error("目标文件夹不存在,请先 list_note_folders");
196
+ }
197
+ folderName = String(folder.name ?? "");
198
+ }
199
+ const pending = createPending("move_note", familyId, {
200
+ action: "move_note",
201
+ note_id,
202
+ title: note.title,
203
+ from_folder_id: note.folder_id ?? null,
204
+ to_folder_id: folder_id === 0 ? null : folder_id,
205
+ to_folder_name: folderName,
206
+ }, { note_id, folder_id });
207
+ return okJson(pendingPublicView(pending));
208
+ }));
209
+ server.tool("confirm_move_note", "确认移动记事所属文件夹。必须传入 prepare_move_note 返回的 confirm_token。", {
210
+ confirm_token: z.string().min(1),
211
+ }, async ({ confirm_token }) => runTool(async () => {
212
+ client.setToolName("confirm_move_note");
213
+ const pending = takePending(confirm_token, "move_note");
214
+ const noteId = Number(pending.exec.note_id);
215
+ const folderId = Number(pending.exec.folder_id);
216
+ const data = await client.put(familyPath(pending.familyId, `/notes/${noteId}`), {
217
+ folder_id: folderId,
218
+ });
219
+ return okJson({
220
+ ...data,
221
+ hint: "记事所属文件夹已更新。",
222
+ });
223
+ }));
224
+ server.tool("prepare_delete_note", "准备删除记事(移入回收站,可恢复)。须先 unlock_writes。会拉取标题供用户确认。", {
225
+ note_id: z.number().int().positive(),
226
+ }, async ({ note_id }) => runTool(async () => {
227
+ client.setToolName("prepare_delete_note");
228
+ const familyId = await ensureFamilyId(client);
229
+ await requireTokenScope(client, [TOKEN_SCOPE_WRITE_DRAFT]);
230
+ await requireEntitlement(client, familyId, "can_view_notes", "当前角色没有记事权限,无法删除记事");
231
+ const note = await client.get(familyPath(familyId, `/notes/${note_id}`));
232
+ const pending = createPending("delete_note", familyId, {
233
+ action: "delete_note",
234
+ note_id,
235
+ title: note.title,
236
+ note: "删除后进入回收站,可用 list_notes_trash / restore_note 恢复",
237
+ }, { note_id });
238
+ return okJson(pendingPublicView(pending));
239
+ }));
240
+ server.tool("confirm_delete_note", "确认删除记事:移入回收站(非永久删除)。须传入 prepare_delete_note 的 confirm_token。", {
241
+ confirm_token: z.string().min(1),
242
+ }, async ({ confirm_token }) => runTool(async () => {
243
+ client.setToolName("confirm_delete_note");
244
+ await requireTokenScope(client, [TOKEN_SCOPE_WRITE_DRAFT]);
245
+ const pending = takePending(confirm_token, "delete_note");
246
+ const noteId = Number(pending.exec.note_id);
247
+ await client.delete(familyPath(pending.familyId, `/notes/${noteId}`));
248
+ return okJson({
249
+ ok: true,
250
+ note_id: noteId,
251
+ trashed: true,
252
+ hint: "已移入回收站。可用 list_notes_trash 查看,restore_note 恢复。",
253
+ });
254
+ }));
255
+ server.tool("list_notes_trash", "查看记事回收站(已删除、可恢复的记事)。", {
256
+ page: z.number().int().min(1).optional(),
257
+ page_size: z.number().int().min(1).max(100).optional(),
258
+ }, async ({ page, page_size }) => runTool(async () => {
259
+ client.setToolName("list_notes_trash");
260
+ await requireTokenScope(client, [TOKEN_SCOPE_WRITE_DRAFT]);
261
+ const familyId = await ensureFamilyId(client);
262
+ const data = await client.get(familyPath(familyId, "/notes/trash"), { page, page_size });
263
+ return okJson({
264
+ ...data,
265
+ hint: "可用 restore_note 恢复;清空须 prepare_empty_notes_trash → confirm。",
266
+ });
267
+ }));
268
+ server.tool("restore_note", "从回收站恢复一篇记事。恢复属于补救操作,无需 unlock_writes。原文件夹已删则回到未分类。", {
269
+ note_id: z.number().int().positive(),
270
+ }, async ({ note_id }) => runTool(async () => {
271
+ client.setToolName("restore_note");
272
+ const familyId = await ensureFamilyId(client);
273
+ await requireTokenScope(client, [TOKEN_SCOPE_WRITE_DRAFT]);
274
+ await requireEntitlement(client, familyId, "can_view_notes", "当前角色没有记事权限,无法恢复记事");
275
+ const data = await client.post(familyPath(familyId, `/notes/${note_id}/restore`));
276
+ return okJson({
277
+ ...data,
278
+ hint: "已从回收站恢复。",
279
+ });
280
+ }));
281
+ server.tool("prepare_empty_notes_trash", "准备清空记事回收站(永久删除,不可恢复)。须先 unlock_writes。会返回将删除的条数供用户确认。", {}, async () => runTool(async () => {
282
+ client.setToolName("prepare_empty_notes_trash");
283
+ const familyId = await ensureFamilyId(client);
284
+ await requireTokenScope(client, [TOKEN_SCOPE_WRITE_DRAFT]);
285
+ await requireEntitlement(client, familyId, "can_view_notes", "当前角色没有记事权限,无法清空回收站");
286
+ const trash = await client.get(familyPath(familyId, "/notes/trash"), { page: 1, page_size: 1 });
287
+ const count = Number(trash.total ?? 0);
288
+ const pending = createPending("empty_notes_trash", familyId, {
289
+ action: "empty_notes_trash",
290
+ count,
291
+ note: "将永久删除这些记事,无法恢复",
292
+ }, {});
293
+ return okJson(pendingPublicView(pending));
294
+ }));
295
+ server.tool("confirm_empty_notes_trash", "确认清空记事回收站(永久删除)。须传入 prepare_empty_notes_trash 的 confirm_token。", {
296
+ confirm_token: z.string().min(1),
297
+ }, async ({ confirm_token }) => runTool(async () => {
298
+ client.setToolName("confirm_empty_notes_trash");
299
+ await requireTokenScope(client, [TOKEN_SCOPE_WRITE_DRAFT]);
300
+ const pending = takePending(confirm_token, "empty_notes_trash");
301
+ const data = await client.delete(familyPath(pending.familyId, "/notes/trash"));
302
+ return okJson({
303
+ ...data,
304
+ hint: "记事回收站已清空,无法恢复。",
305
+ });
306
+ }));
307
+ }
@@ -0,0 +1,2 @@
1
+ import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
2
+ export declare function registerSafetyTools(server: McpServer): void;
@@ -0,0 +1,24 @@
1
+ import { z } from "zod";
2
+ import { getWriteLockStatus, lockWrites, unlockWrites, } from "../context/write-lock.js";
3
+ import { okJson, runTool } from "../utils/response.js";
4
+ export function registerSafetyTools(server) {
5
+ server.tool("get_write_lock_status", "查看 MCP 写操作安全锁状态(是否已解锁、剩余秒数、待确认数)。", {}, async () => runTool(async () => {
6
+ return okJson({
7
+ ...getWriteLockStatus(),
8
+ policy: "默认上锁。查账/列文件夹/建草稿可用;入账、删除记账/记事、清空回收站、确认草稿、删除文件夹、移动记事所属文件夹须 unlock_writes → prepare_* → 用户确认 → confirm_*。新建/改名/移动文件夹须先 unlock_writes。删除进入回收站,可恢复;清空回收站不可恢复。",
9
+ });
10
+ }));
11
+ server.tool("unlock_writes", "解锁写操作(须先征得用户同意)。解锁后仍须对入账/删除/确认草稿(含批量)走 prepare→confirm,不能一步写库。约 15 分钟无操作会过期。", {
12
+ user_acknowledged: z
13
+ .boolean()
14
+ .describe("必须为 true,表示已向用户说明风险并获得同意"),
15
+ }, async ({ user_acknowledged }) => runTool(async () => {
16
+ if (!user_acknowledged) {
17
+ throw new Error("须将 user_acknowledged=true,并先征得用户同意后再解锁");
18
+ }
19
+ return okJson(unlockWrites());
20
+ }));
21
+ server.tool("lock_writes", "立即重新上锁,并清空未确认的 prepare 令牌。", {}, async () => runTool(async () => {
22
+ return okJson(lockWrites());
23
+ }));
24
+ }
@@ -0,0 +1,10 @@
1
+ /** 元 → 分(API 整数) */
2
+ export declare function yuanToFen(yuan: number): number;
3
+ /** 分 → 元 */
4
+ export declare function fenToYuan(fen: number): number;
5
+ /** 为记账条目补充 amount_yuan 字段,方便 Agent 展示。 */
6
+ export declare function withYuanAmount<T extends Record<string, unknown>>(entry: T): T & {
7
+ amount_yuan: number;
8
+ };
9
+ /** 列表结果中的 items 批量补元。 */
10
+ export declare function mapItemsWithYuan(data: Record<string, unknown>): Record<string, unknown>;
@@ -0,0 +1,28 @@
1
+ /** 元 → 分(API 整数) */
2
+ export function yuanToFen(yuan) {
3
+ if (!Number.isFinite(yuan)) {
4
+ throw new Error("金额无效");
5
+ }
6
+ return Math.round(yuan * 100);
7
+ }
8
+ /** 分 → 元 */
9
+ export function fenToYuan(fen) {
10
+ if (!Number.isFinite(fen))
11
+ return 0;
12
+ return fen / 100;
13
+ }
14
+ /** 为记账条目补充 amount_yuan 字段,方便 Agent 展示。 */
15
+ export function withYuanAmount(entry) {
16
+ const amount = Number(entry.amount ?? 0);
17
+ return { ...entry, amount_yuan: fenToYuan(amount) };
18
+ }
19
+ /** 列表结果中的 items 批量补元。 */
20
+ export function mapItemsWithYuan(data) {
21
+ const items = data.items;
22
+ if (!Array.isArray(items))
23
+ return data;
24
+ return {
25
+ ...data,
26
+ items: items.map((item) => item && typeof item === "object" ? withYuanAmount(item) : item),
27
+ };
28
+ }
@@ -0,0 +1,5 @@
1
+ import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
2
+ export declare function okJson(data: unknown): CallToolResult;
3
+ export declare function failText(message: string): CallToolResult;
4
+ /** 包装 tool 逻辑:捕获异常并返回 isError,避免 MCP 客户端裸崩。 */
5
+ export declare function runTool(fn: () => Promise<CallToolResult>): Promise<CallToolResult>;
@@ -0,0 +1,21 @@
1
+ export function okJson(data) {
2
+ return {
3
+ content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
4
+ };
5
+ }
6
+ export function failText(message) {
7
+ return {
8
+ content: [{ type: "text", text: message }],
9
+ isError: true,
10
+ };
11
+ }
12
+ /** 包装 tool 逻辑:捕获异常并返回 isError,避免 MCP 客户端裸崩。 */
13
+ export async function runTool(fn) {
14
+ try {
15
+ return await fn();
16
+ }
17
+ catch (err) {
18
+ const message = err instanceof Error ? err.message : String(err);
19
+ return failText(message);
20
+ }
21
+ }
package/package.json ADDED
@@ -0,0 +1,50 @@
1
+ {
2
+ "name": "@fangcuntai/fangcuntai-mcp",
3
+ "version": "1.6.0",
4
+ "description": "方寸台桌面助手 MCP — 确认锁 + 来源标记 + 回收站 + 记事文件夹整理,安全地用自然语言管理家庭账本与记事",
5
+ "license": "MIT",
6
+ "type": "module",
7
+ "bin": {
8
+ "fangcuntai-mcp": "./dist/index.js"
9
+ },
10
+ "files": [
11
+ "dist",
12
+ "README.md"
13
+ ],
14
+ "scripts": {
15
+ "build": "tsc",
16
+ "start": "node dist/index.js",
17
+ "dev": "tsc && node dist/index.js",
18
+ "organize-notes": "node scripts/organize-notes.mjs",
19
+ "test": "tsx --test \"src/**/*.test.ts\"",
20
+ "prepare": "npm run build"
21
+ },
22
+ "publishConfig": {
23
+ "access": "public"
24
+ },
25
+ "engines": {
26
+ "node": ">=18"
27
+ },
28
+ "keywords": [
29
+ "mcp",
30
+ "fangcuntai",
31
+ "方寸台",
32
+ "family",
33
+ "ledger",
34
+ "desktop-assistant"
35
+ ],
36
+ "repository": {
37
+ "type": "git",
38
+ "url": "https://github.com/rhinogo/home-man.git",
39
+ "directory": "fangcuntai-mcp"
40
+ },
41
+ "dependencies": {
42
+ "@modelcontextprotocol/sdk": "^1.12.1",
43
+ "zod": "^3.24.2"
44
+ },
45
+ "devDependencies": {
46
+ "@types/node": "^22.13.10",
47
+ "tsx": "^4.19.3",
48
+ "typescript": "^5.8.2"
49
+ }
50
+ }