feishu-mcp 0.2.2 → 0.2.7

package/dist/mcp/tools/feishuBlockTools.js

@@ -2,17 +2,7 @@ import { z } from 'zod';
 import { formatErrorMessage } from '../../utils/error.js';
 import { Logger } from '../../utils/logger.js';
 import { detectMimeType } from '../../utils/document.js';
-import { DocumentIdSchema, ParentBlockIdSchema, BlockIdSchema, IndexSchema, StartIndexSchema, EndIndexSchema, 
-// AlignSchema,
-// AlignSchemaWithValidation,
-TextElementsArraySchema, 
-// CodeLanguageSchema,
-// CodeWrapSchema,
-BlockConfigSchema, MediaIdSchema, MediaExtraSchema, ImagesArraySchema, 
-// MermaidCodeSchema,
-// ImageWidthSchema,
-// ImageHeightSchema
-TableCreateSchema, WhiteboardFillArraySchema } from '../../types/feishuSchema.js';
+import { DocumentIdSchema, ParentBlockIdSchema, BlockIdSchema, IndexSchema, StartIndexSchema, EndIndexSchema, TextElementsArraySchema, BlockConfigSchema, MediaIdSchema, MediaExtraSchema, ImagesArraySchema, TableCreateSchema, WhiteboardFillArraySchema } from '../../types/feishuSchema.js';
 /**
  * 注册飞书块相关的MCP工具
  * @param server MCP服务器实例
@@ -264,233 +254,6 @@ export function registerFeishuBlockTools(server, feishuService) {
             };
         }
     });
-    // 添加创建飞书文本块工具
-    // server.tool(
-    //   "create_feishu_text_block",
-    //   "Creates a new text block with precise style control. Unlike markdown-based formatting, this tool lets you explicitly set text styles for each text segment. Ideal for formatted documents where exact styling control is needed. NOTE: If creating multiple blocks at once, use batch_create_feishu_blocks tool instead for better efficiency. Note: For Feishu wiki links (https://xxx.feishu.cn/wiki/xxx) you must first use convert_feishu_wiki_to_document_id tool to obtain a compatible document ID.",
-    //   {
-    //     documentId: DocumentIdSchema,
-    //     parentBlockId: ParentBlockIdSchema,
-    //     textContents: TextElementsArraySchema,
-    //     align: AlignSchema,
-    //     index: IndexSchema
-    //   },
-    //   async ({ documentId, parentBlockId, textContents, align = 1, index }) => {
-    //     try {
-    //       if (!feishuService) {
-    //         return {
-    //           content: [{ type: "text", text: "Feishu service is not initialized. Please check the configuration" }],
-    //         };
-    //       }
-    //
-    //       Logger.info(`开始创建飞书文本块，文档ID: ${documentId}，父块ID: ${parentBlockId}，对齐方式: ${align}，插入位置: ${index}`);
-    //       const result = await feishuService.createTextBlock(documentId, parentBlockId, textContents, align, index);
-    //       Logger.info(`飞书文本块创建成功`);
-    //
-    //       return {
-    //         content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
-    //       };
-    //     } catch (error) {
-    //       Logger.error(`创建飞书文本块失败:`, error);
-    //       const errorMessage = formatErrorMessage(error);
-    //       return {
-    //         content: [{ type: "text", text: `创建飞书文本块失败: ${errorMessage}` }],
-    //       };
-    //     }
-    //   },
-    // );
-    //
-    // // 添加创建飞书代码块工具
-    // server.tool(
-    //   "create_feishu_code_block",
-    //   "Creates a new code block with syntax highlighting and formatting options. Ideal for technical documentation, tutorials, or displaying code examples with proper formatting and language-specific highlighting. NOTE: If creating multiple blocks at once, use batch_create_feishu_blocks tool instead for better efficiency. Note: For Feishu wiki links (https://xxx.feishu.cn/wiki/xxx) you must first use convert_feishu_wiki_to_document_id tool to obtain a compatible document ID.",
-    //   {
-    //     documentId: DocumentIdSchema,
-    //     parentBlockId: ParentBlockIdSchema,
-    //     code: z.string().describe("Code content (required). The complete code text to display."),
-    //     language: CodeLanguageSchema,
-    //     wrap: CodeWrapSchema,
-    //     index: IndexSchema
-    //   },
-    //   async ({ documentId, parentBlockId, code, language = 1, wrap = false, index = 0 }) => {
-    //     try {
-    //       if (!feishuService) {
-    //         return {
-    //           content: [{ type: "text", text: "Feishu service is not initialized. Please check the configuration" }],
-    //         };
-    //       }
-    //
-    //       Logger.info(`开始创建飞书代码块，文档ID: ${documentId}，父块ID: ${parentBlockId}，语言: ${language}，自动换行: ${wrap}，插入位置: ${index}`);
-    //       const result = await feishuService.createCodeBlock(documentId, parentBlockId, code, language, wrap, index);
-    //       Logger.info(`飞书代码块创建成功`);
-    //
-    //       return {
-    //         content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
-    //       };
-    //     } catch (error) {
-    //       Logger.error(`创建飞书代码块失败:`, error);
-    //       const errorMessage = formatErrorMessage(error);
-    //       return {
-    //         content: [{ type: "text", text: `创建飞书代码块失败: ${errorMessage}` }],
-    //       };
-    //     }
-    //   },
-    // );
-    //
-    // // 添加创建飞书标题块工具
-    // server.tool(
-    //   "create_feishu_heading_block",
-    //   "Creates a heading block with customizable level and alignment. Use this tool to add section titles, chapter headings, or any hierarchical structure elements to your document. Supports nine heading levels for different emphasis needs. NOTE: If creating multiple blocks at once, use batch_create_feishu_blocks tool instead for better efficiency. Note: For Feishu wiki links (https://xxx.feishu.cn/wiki/xxx) you must first use convert_feishu_wiki_to_document_id tool to obtain a compatible document ID.",
-    //   {
-    //     documentId: DocumentIdSchema,
-    //     parentBlockId: ParentBlockIdSchema,
-    //     level: z.number().min(1).max(9).describe("Heading level (required). Integer between 1 and 9, where 1 is the largest heading (h1) and 9 is the smallest (h9)."),
-    //     content: z.string().describe("Heading text content (required). The actual text of the heading."),
-    //     align: AlignSchemaWithValidation,
-    //     index: IndexSchema
-    //   },
-    //   async ({ documentId, parentBlockId, level, content, align = 1, index = 0 }) => {
-    //     try {
-    //       if (!feishuService) {
-    //         return {
-    //           content: [{ type: "text", text: "Feishu service is not initialized. Please check the configuration" }],
-    //         };
-    //       }
-    //
-    //       // 确保align值在合法范围内（1-3）
-    //       if (align !== 1 && align !== 2 && align !== 3) {
-    //         return {
-    //           content: [{ type: "text", text: "错误: 对齐方式(align)参数必须是1(居左)、2(居中)或3(居右)中的一个值。" }],
-    //         };
-    //       }
-    //
-    //       Logger.info(`开始创建飞书标题块，文档ID: ${documentId}，父块ID: ${parentBlockId}，标题级别: ${level}，对齐方式: ${align}，插入位置: ${index}`);
-    //       const result = await feishuService.createHeadingBlock(documentId, parentBlockId, content, level, index, align);
-    //       Logger.info(`飞书标题块创建成功`);
-    //
-    //       return {
-    //         content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
-    //       };
-    //     } catch (error) {
-    //       Logger.error(`创建飞书标题块失败:`, error);
-    //       const errorMessage = formatErrorMessage(error);
-    //       return {
-    //         content: [{ type: "text", text: `创建飞书标题块失败: ${errorMessage}` }],
-    //       };
-    //     }
-    //   },
-    // );
-    //
-    // // 添加创建飞书列表块工具
-    // server.tool(
-    //   "create_feishu_list_block",
-    //   "Creates a list item block (either ordered or unordered). Perfect for creating hierarchical and structured content with bullet points or numbered lists. NOTE: If creating multiple blocks at once, use batch_create_feishu_blocks tool instead for better efficiency. Note: For Feishu wiki links (https://xxx.feishu.cn/wiki/xxx) you must first use convert_feishu_wiki_to_document_id tool to obtain a compatible document ID.",
-    //   {
-    //     documentId: DocumentIdSchema,
-    //     parentBlockId: ParentBlockIdSchema,
-    //     content: z.string().describe("List item content (required). The actual text of the list item."),
-    //     isOrdered: z.boolean().optional().default(false).describe("Whether this is an ordered (numbered) list item. Default is false (bullet point/unordered)."),
-    //     align: AlignSchemaWithValidation,
-    //     index: IndexSchema
-    //   },
-    //   async ({ documentId, parentBlockId, content, isOrdered = false, align = 1, index = 0 }) => {
-    //     try {
-    //       if (!feishuService) {
-    //         return {
-    //           content: [{ type: "text", text: "Feishu service is not initialized. Please check the configuration" }],
-    //         };
-    //       }
-    //
-    //       // 确保align值在合法范围内（1-3）
-    //       if (align !== 1 && align !== 2 && align !== 3) {
-    //         return {
-    //           content: [{ type: "text", text: "错误: 对齐方式(align)参数必须是1(居左)、2(居中)或3(居右)中的一个值。" }],
-    //         };
-    //       }
-    //
-    //       const listType = isOrdered ? "有序" : "无序";
-    //       Logger.info(`开始创建飞书${listType}列表块，文档ID: ${documentId}，父块ID: ${parentBlockId}，对齐方式: ${align}，插入位置: ${index}`);
-    //       const result = await feishuService.createListBlock(documentId, parentBlockId, content, isOrdered, index, align);
-    //       Logger.info(`飞书${listType}列表块创建成功`);
-    //
-    //       return {
-    //         content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
-    //       };
-    //     } catch (error) {
-    //       Logger.error(`创建飞书列表块失败:`, error);
-    //       const errorMessage = formatErrorMessage(error);
-    //       return {
-    //         content: [{ type: "text", text: `创建飞书列表块失败: ${errorMessage}` }],
-    //       };
-    //     }
-    //   },
-    // );
-    // 添加创建飞书Mermaid块工具
-    // server.tool(
-    //   "create_feishu_mermaid_block",
-    //   "Creates a new Mermaid block in a Feishu document. This tool allows you to insert a Mermaid diagram by specifying the Mermaid code.  Note: For Feishu wiki links (https://xxx.feishu.cn/wiki/xxx) you must first use convert_feishu_wiki_to_document_id tool to obtain a compatible document ID.",
-    //   {
-    //     documentId: DocumentIdSchema,
-    //     parentBlockId: ParentBlockIdSchema,
-    //     mermaidCode: MermaidCodeSchema,
-    //     index: IndexSchema
-    //   },
-    //   async ({ documentId, parentBlockId, mermaidCode, index }) => {
-    //     try {
-    //       if (!feishuService) {
-    //         return {
-    //           content: [{ type: "text", text: "Feishu service is not initialized. Please check the configuration" }],
-    //         };
-    //       }
-    //       Logger.info(`开始创建飞书Mermaid块，文档ID: ${documentId}，父块ID: ${parentBlockId}，插入位置: ${index}`);
-    //       const result = await (feishuService as any).createMermaidBlock(documentId, parentBlockId, mermaidCode, index);
-    //       Logger.info(`飞书Mermaid块创建成功`);
-    //       return {
-    //         content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
-    //       };
-    //     } catch (error) {
-    //       Logger.error(`创建飞书Mermaid块失败:`, error);
-    //       const errorMessage = formatErrorMessage(error);
-    //       return {
-    //         content: [{ type: "text", text: `创建飞书Mermaid块失败: ${errorMessage}` }],
-    //       };
-    //     }
-    //   },
-    // );
-    // 添加飞书Wiki文档ID转换工具
-    // server.tool(
-    //   'convert_feishu_wiki_to_document_id',
-    //   'Converts a Feishu Wiki document link to a compatible document ID. This conversion is required before using wiki links with any other Feishu document tools.',
-    //   {
-    //     wikiUrl: z.string().describe('Wiki URL or Token (required). Supports complete URL formats like https://xxx.feishu.cn/wiki/xxxxx or direct use of the Token portion'),
-    //   },
-    //   async ({ wikiUrl }) => {
-    //     try {
-    //       if (!feishuService) {
-    //         return {
-    //           content: [{ type: 'text', text: '飞书服务未初始化，请检查配置' }],
-    //         };
-    //       }
-    //
-    //       Logger.info(`开始转换Wiki文档链接，输入: ${wikiUrl}`);
-    //       const documentId = await feishuService.convertWikiToDocumentId(wikiUrl);
-    //
-    //       Logger.info(`Wiki文档转换成功，可用的文档ID为: ${documentId}`);
-    //
-    //       return {
-    //         content: [
-    //           { type: 'text', text: `Converted Wiki link to Document ID: ${documentId}\n\nUse this Document ID with other Feishu document tools.` }
-    //         ],
-    //       };
-    //     } catch (error) {
-    //       Logger.error(`转换Wiki文档链接失败:`, error);
-    //       const errorMessage = formatErrorMessage(error);
-    //       return {
-    //         content: [{ type: 'text', text: `转换Wiki文档链接失败: ${errorMessage}` }],
-    //       };
-    //     }
-    //   },
-    // );
     // 添加删除文档块工具
     server.tool('delete_feishu_document_blocks', 'Deletes one or more consecutive blocks from a Feishu document. Use this tool to remove unwanted content, clean up document structure, or clear space before inserting new content. Supports batch deletion for efficiency. Note: For Feishu wiki links (https://xxx.feishu.cn/wiki/xxx), use get_feishu_document_info to get document information, then use the returned documentId for editing operations.', {
         documentId: DocumentIdSchema,
@@ -552,53 +315,6 @@ export function registerFeishuBlockTools(server, feishuService) {
             };
         }
     });
-    // 添加创建飞书图片块工具
-    // server.tool(
-    //   'create_feishu_image_block',
-    //   'Creates a complete image block in a Feishu document by uploading an image from a local path or URL and setting it to the block. This tool handles the entire 3-step process: (1) Creates an empty image block, (2) Downloads/reads the image and uploads it as media resource, (3) Sets the image content to the block. Supports local file paths and HTTP/HTTPS URLs. Use this when you want to insert images into Feishu documents. Note: For Feishu wiki links (https://xxx.feishu.cn/wiki/xxx) you must first use convert_feishu_wiki_to_document_id tool to obtain a compatible document ID.',
-    //   {
-    //     documentId: DocumentIdSchema,
-    //     parentBlockId: ParentBlockIdSchema,
-    //     imagePathOrUrl: ImagePathOrUrlSchema,
-    //     fileName: ImageFileNameSchema,
-    //     width: ImageWidthSchema,
-    //     height: ImageHeightSchema,
-    //     index: IndexSchema
-    //   },
-    //   async ({ documentId, parentBlockId, imagePathOrUrl, fileName, width, height, index = 0 }) => {
-    //     try {
-    //       if (!feishuService) {
-    //         return {
-    //           content: [{ type: 'text', text: 'Feishu service is not initialized. Please check the configuration' }],
-    //         };
-    //       }
-    //
-    //       Logger.info(`开始创建飞书图片块，文档ID: ${documentId}，父块ID: ${parentBlockId}，图片源: ${imagePathOrUrl}，插入位置: ${index}`);
-    //
-    //       const result = await feishuService.createImageBlock(documentId, parentBlockId, imagePathOrUrl, {
-    //         fileName,
-    //         width,
-    //         height,
-    //         index
-    //       });
-    //
-    //       Logger.info(`飞书图片块创建成功，块ID: ${result.imageBlockId}`);
-    //
-    //       return {
-    //         content: [{
-    //           type: 'text',
-    //           text: `图片块创建成功！\n\n块ID: ${result.imageBlockId}\n文件Token: ${result.fileToken}\n文档修订ID: ${result.documentRevisionId}\n\n完整结果:\n${JSON.stringify(result, null, 2)}`
-    //         }],
-    //       };
-    //     } catch (error) {
-    //       Logger.error(`创建飞书图片块失败:`, error);
-    //       const errorMessage = formatErrorMessage(error);
-    //       return {
-    //         content: [{ type: 'text', text: `创建飞书图片块失败: ${errorMessage}` }],
-    //       };
-    //     }
-    //   },
-    // );
     // 添加图片上传绑定工具
     server.tool('upload_and_bind_image_to_block', 'Uploads images from local paths or URLs and binds them to existing empty image blocks. This tool is used after creating image blocks with batch_create_feishu_blocks tool. It handles uploading the image media and setting the image content to the specified block IDs. Supports local file paths and HTTP/HTTPS URLs. Each image upload and binding is processed independently, and all results are returned in order.', {
         documentId: DocumentIdSchema,

package/dist/mcp/tools/feishuTools.js

@@ -1,8 +1,6 @@
 import { formatErrorMessage } from '../../utils/error.js';
 import { Logger } from '../../utils/logger.js';
-import { DocumentIdSchema, DocumentIdOrWikiIdSchema, DocumentTypeSchema, 
-// BlockIdSchema,
-SearchKeySchema, SearchTypeSchema, PageTokenSchema, OffsetSchema, WhiteboardIdSchema, DocumentTitleSchema, FolderTokenOptionalSchema, WikiSpaceNodeContextSchema, } from '../../types/feishuSchema.js';
+import { DocumentIdSchema, DocumentIdOrWikiIdSchema, DocumentTypeSchema, SearchKeySchema, SearchTypeSchema, PageTokenSchema, OffsetSchema, WhiteboardIdSchema, DocumentTitleSchema, FolderTokenOptionalSchema, WikiSpaceNodeContextSchema, } from '../../types/feishuSchema.js';
 /**
  * 注册飞书相关的MCP工具
  * @param server MCP服务器实例
@@ -110,38 +108,6 @@ export function registerFeishuTools(server, feishuService) {
             };
         }
     });
-    // 添加获取飞书文档内容工具
-    // server.tool(
-    //   'get_feishu_document_content',
-    //   'Retrieves the plain text content of a Feishu document. Ideal for content analysis, processing, or when you need to extract text without formatting. The content maintains the document structure but without styling. Note: For Feishu wiki links (https://xxx.feishu.cn/wiki/xxx) you must first use convert_feishu_wiki_to_document_id tool to obtain a compatible document ID.',
-    //   {
-    //     documentId: DocumentIdSchema,
-    //     lang: z.number().optional().default(0).describe('Language code (optional). Default is 0 (Chinese). Use 1 for English if available.'),
-    //   },
-    //   async ({ documentId, lang }) => {
-    //     try {
-    //       if (!feishuService) {
-    //         return {
-    //           content: [{ type: 'text', text: 'Feishu service is not initialized. Please check the configuration' }],
-    //         };
-    //       }
-    //
-    //       Logger.info(`开始获取飞书文档内容，文档ID: ${documentId}，语言: ${lang}`);
-    //       const content = await feishuService.getDocumentContent(documentId, lang);
-    //       Logger.info(`飞书文档内容获取成功，内容长度: ${content.length}字符`);
-    //
-    //       return {
-    //         content: [{ type: 'text', text: content }],
-    //       };
-    //     } catch (error) {
-    //       Logger.error(`获取飞书文档内容失败:`, error);
-    //       const errorMessage = formatErrorMessage(error);
-    //       return {
-    //         content: [{ type: 'text', text: `获取飞书文档内容失败: ${errorMessage}` }],
-    //       };
-    //     }
-    //   },
-    // );
     // 添加获取飞书文档块工具
     server.tool('get_feishu_document_blocks', 'Retrieves the block structure information of a Feishu document. Essential to use before inserting content to understand document structure and determine correct insertion positions. Returns a detailed hierarchy of blocks with their IDs, types, and content. Note: For Feishu wiki links (https://xxx.feishu.cn/wiki/xxx), use get_feishu_document_info to get document information, then use the returned documentId for editing operations.', {
         documentId: DocumentIdSchema,
@@ -202,38 +168,6 @@ export function registerFeishuTools(server, feishuService) {
             };
         }
     });
-    // 添加获取块内容工具
-    // server.tool(
-    //   'get_feishu_block_content',
-    //   'Retrieves the detailed content and structure of a specific block in a Feishu document. Useful for inspecting block properties, formatting, and content, especially before making updates or for debugging purposes. Note: For Feishu wiki links (https://xxx.feishu.cn/wiki/xxx) you must first use convert_feishu_wiki_to_document_id tool to obtain a compatible document ID.',
-    //   {
-    //     documentId: DocumentIdSchema,
-    //     blockId: BlockIdSchema,
-    //   },
-    //   async ({ documentId, blockId }) => {
-    //     try {
-    //       if (!feishuService) {
-    //         return {
-    //           content: [{ type: 'text', text: '飞书服务未初始化，请检查配置' }],
-    //         };
-    //       }
-    //
-    //       Logger.info(`开始获取飞书块内容，文档ID: ${documentId}，块ID: ${blockId}`);
-    //       const blockContent = await feishuService.getBlockContent(documentId, blockId);
-    //       Logger.info(`飞书块内容获取成功，块类型: ${blockContent.block_type}`);
-    //
-    //       return {
-    //         content: [{ type: 'text', text: JSON.stringify(blockContent, null, 2) }],
-    //       };
-    //     } catch (error) {
-    //       Logger.error(`获取飞书块内容失败:`, error);
-    //       const errorMessage = formatErrorMessage(error);
-    //       return {
-    //         content: [{ type: 'text', text: `获取飞书块内容失败: ${errorMessage}` }],
-    //       };
-    //     }
-    //   },
-    // );
     // 添加搜索文档工具（支持文档和知识库搜索）
     server.tool('search_feishu_documents', 'Searches for documents and/or Wiki knowledge base nodes in Feishu. Supports keyword-based search with type filtering (document, wiki, or both). Returns document and wiki information including title, type, and owner. Supports pagination: use offset for document search pagination and pageToken for wiki search pagination. Each type (document or wiki) can return up to 100 results maximum per search. Default page size is 20 items.', {
         searchKey: SearchKeySchema,

package/dist/mcp/tools/folderTools.js

@@ -0,0 +1,99 @@
+import { formatErrorMessage } from '../../utils/error.js';
+import { Logger } from '../../utils/logger.js';
+import { FolderTokenSchema, FolderTokenOptionalSchema, FolderNameSchema, WikiSpaceNodeContextSchema, } from '../../types/feishuSchema.js';
+import { errorResponse, validateFolderOrWikiContext } from './toolHelpers.js';
+/**
+ * 注册飞书文件夹相关的MCP工具
+ */
+export function registerFolderTools(server, feishuService) {
+    server.tool('get_feishu_root_folder_info', 'Retrieves the root folder in Feishu Drive, wiki spaces list, and "My Library". Use this when you need to browse folders or wiki spaces from the root. If you know the wiki node name, you can also use search_feishu_documents to directly locate specific wiki nodes instead of traversing from root. Returns root folder token, all wiki spaces, and personal library information.', {}, async () => {
+        try {
+            Logger.info(`开始获取飞书根文件夹信息、知识空间列表和我的知识库`);
+            const result = {
+                root_folder: null,
+                wiki_spaces: [],
+                my_library: null,
+            };
+            try {
+                const folderInfo = await feishuService.getRootFolderInfo();
+                result.root_folder = folderInfo?.data ?? folderInfo;
+                Logger.info(`飞书根文件夹信息获取成功，token: ${result.root_folder?.token}`);
+            }
+            catch (error) {
+                Logger.error(`获取飞书根文件夹信息失败:`, error);
+                result.root_folder = { error: formatErrorMessage(error, '获取根文件夹信息失败') };
+            }
+            try {
+                result.wiki_spaces = (await feishuService.getAllWikiSpacesList(20)) ?? [];
+                Logger.info(`知识空间列表获取成功，共 ${result.wiki_spaces.length} 个空间`);
+            }
+            catch (error) {
+                Logger.error(`获取知识空间列表失败:`, error);
+                result.wiki_spaces = [];
+            }
+            try {
+                const myLibrary = await feishuService.getWikiSpaceInfo('my_library', 'en');
+                const libraryData = myLibrary?.data ?? myLibrary;
+                result.my_library = libraryData?.space ?? libraryData;
+                Logger.info(`我的知识库获取成功，space_id: ${result.my_library?.space_id}`);
+            }
+            catch (error) {
+                Logger.error(`获取我的知识库失败:`, error);
+                result.my_library = { error: formatErrorMessage(error, '获取我的知识库失败') };
+            }
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (error) {
+            Logger.error(`获取飞书信息失败:`, error);
+            return errorResponse(formatErrorMessage(error, '获取飞书信息失败'));
+        }
+    });
+    server.tool('get_feishu_folder_files', 'Retrieves a list of files and subfolders in a specified folder or wiki space node. Supports two modes: (1) Feishu Drive folder mode: use folderToken to get files in a Feishu Drive folder. (2) Wiki space node mode: use wikiContext with spaceId (and optional parentNodeToken) to get documents under a wiki space node. If parentNodeToken is not provided, retrieves nodes from the root of the wiki space. Only one mode can be used at a time - provide either folderToken OR wikiContext.', {
+        folderToken: FolderTokenOptionalSchema,
+        wikiContext: WikiSpaceNodeContextSchema,
+    }, async ({ folderToken, wikiContext }) => {
+        try {
+            const validationError = validateFolderOrWikiContext(folderToken, wikiContext);
+            if (validationError)
+                return validationError;
+            // 模式一：飞书文档目录模式
+            if (folderToken) {
+                Logger.info(`开始获取飞书文件夹中的文件清单，文件夹Token: ${folderToken}`);
+                const fileList = await feishuService.getFolderFileList(folderToken);
+                Logger.info(`飞书文件夹中的文件清单获取成功，共 ${fileList.files?.length ?? 0} 个文件`);
+                return { content: [{ type: 'text', text: JSON.stringify(fileList, null, 2) }] };
+            }
+            // 模式二：知识库节点模式
+            if (!wikiContext)
+                return errorResponse('错误：内部参数状态异常。');
+            const { spaceId, parentNodeToken } = wikiContext;
+            if (!spaceId) {
+                return errorResponse('错误：使用 wikiContext 模式时，必须提供 spaceId。');
+            }
+            Logger.info(`开始获取知识空间子节点列表，知识空间ID: ${spaceId}, 父节点Token: ${parentNodeToken ?? 'null（根节点）'}`);
+            const nodeList = await feishuService.getAllWikiSpaceNodes(spaceId, parentNodeToken);
+            Logger.info(`知识空间子节点列表获取成功，共 ${Array.isArray(nodeList) ? nodeList.length : 0} 个节点`);
+            return { content: [{ type: 'text', text: JSON.stringify({ nodes: nodeList ?? [] }, null, 2) }] };
+        }
+        catch (error) {
+            Logger.error(`获取文件列表失败:`, error);
+            return errorResponse(`获取文件列表失败: ${formatErrorMessage(error)}`);
+        }
+    });
+    // 添加创建文件夹工具
+    server.tool('create_feishu_folder', 'Creates a new folder in a specified parent folder. Use this to organize documents and files within your Feishu Drive structure. Returns the token and URL of the newly created folder.', {
+        folderToken: FolderTokenSchema,
+        folderName: FolderNameSchema,
+    }, async ({ folderToken, folderName }) => {
+        try {
+            Logger.info(`开始创建飞书文件夹，父文件夹Token: ${folderToken}，文件夹名称: ${folderName}`);
+            const result = await feishuService.createFolder(folderToken, folderName);
+            Logger.info(`飞书文件夹创建成功，token: ${result.token}，URL: ${result.url}`);
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (error) {
+            Logger.error(`创建飞书文件夹失败:`, error);
+            return errorResponse(`创建飞书文件夹失败: ${formatErrorMessage(error)}`);
+        }
+    });
+}

package/dist/mcp/tools/toolHelpers.js

@@ -0,0 +1,155 @@
+import { formatErrorMessage } from '../../utils/error.js';
+import { Logger } from '../../utils/logger.js';
+export const WHITEBOARD_NODE_THUMBNAIL_THRESHOLD = 200;
+export const BATCH_SIZE = 50;
+/** wiki 链接转换提示，在所有需要 documentId 的编辑类工具中复用 */
+export const WIKI_NOTE = 'For Feishu wiki links (https://xxx.feishu.cn/wiki/xxx), ' +
+    'use get_feishu_document_info first to obtain the documentId, then use that ID for editing operations.';
+const BLOCK_TYPE_IMAGE = 27;
+const BLOCK_TYPE_WHITEBOARD = 43;
+export function errorResponse(text) {
+    return { content: [{ type: 'text', text }] };
+}
+// ---------------------------------------------------------------------------
+// 参数校验
+// ---------------------------------------------------------------------------
+/**
+ * 校验 folderToken 与 wikiContext 的互斥关系（文件夹模式 vs 知识库模式）。
+ * 返回 null 表示校验通过，否则返回可直接 return 的错误响应。
+ */
+export function validateFolderOrWikiContext(folderToken, wikiContext) {
+    if (folderToken && wikiContext) {
+        return errorResponse('错误：不能同时提供 folderToken 和 wikiContext 参数，请选择其中一种模式。\n' +
+            '- 使用 folderToken 在飞书文档目录中操作\n' +
+            '- 使用 wikiContext 在知识库中操作');
+    }
+    if (!folderToken && !wikiContext) {
+        return errorResponse('错误：必须提供 folderToken（飞书文档目录模式）或 wikiContext（知识库节点模式）参数之一。');
+    }
+    return null;
+}
+/**
+ * 将 BlockConfig 数组转换为飞书 API 所需的块内容数组。
+ * 遇到单个块处理失败时立即终止。
+ *
+ * 注：contents 类型为 any[] 以匹配 FeishuApiService.createDocumentBlocks 的参数类型。
+ */
+export function prepareBlockContents(configs, feishuService) {
+    const contents = [];
+    for (const { blockType, options = {} } of configs) {
+        try {
+            const blockContent = feishuService.createBlockContent(blockType, options);
+            if (blockContent) {
+                contents.push(blockContent);
+                Logger.info(`已准备 ${blockType} 块，内容: ${JSON.stringify(blockContent).substring(0, 100)}...`);
+            }
+            else {
+                Logger.warn(`创建 ${blockType} 块失败，跳过此块`);
+            }
+        }
+        catch (err) {
+            Logger.error(`处理块类型 ${blockType} 时出错: ${err}`);
+            return {
+                ok: false,
+                error: errorResponse(`处理块类型"${blockType}"时出错: ${err}\n请检查该块类型的配置是否正确。`),
+            };
+        }
+    }
+    return { ok: true, contents };
+}
+// ---------------------------------------------------------------------------
+// 特殊块提取与提示
+// ---------------------------------------------------------------------------
+/**
+ * 从块列表中提取图片块（block_type=27）和画板块（block_type=43）。
+ */
+export function extractSpecialBlocks(blocks) {
+    return {
+        imageBlocks: blocks.filter(b => b.block_type === BLOCK_TYPE_IMAGE),
+        whiteboardBlocks: blocks.filter(b => b.block_type === BLOCK_TYPE_WHITEBOARD),
+    };
+}
+/**
+ * 构建特殊块的 JSON 提示对象，用于展开合并到 JSON 响应中。
+ */
+export function buildSpecialBlockHints(imageBlocks, whiteboardBlocks) {
+    const hints = {};
+    if (imageBlocks.length > 0) {
+        hints.imageBlocksInfo = {
+            count: imageBlocks.length,
+            blockIds: imageBlocks.map(b => b.block_id),
+            reminder: '检测到图片块已创建！请使用 upload_and_bind_image_to_block 工具上传图片并绑定到对应的块ID。',
+        };
+    }
+    if (whiteboardBlocks.length > 0) {
+        hints.whiteboardBlocksInfo = {
+            count: whiteboardBlocks.length,
+            blocks: whiteboardBlocks.map(b => ({
+                blockId: b.block_id,
+                token: b.board?.token,
+                align: b.board?.align,
+            })),
+            reminder: '检测到画板块已创建！请使用 fill_whiteboard_with_plantuml 工具填充画板内容，使用返回的 token 作为 whiteboardId 参数。支持 PlantUML (syntax_type: "plantuml") 和 Mermaid (syntax_type: "mermaid") 两种格式。',
+        };
+    }
+    return hints;
+}
+/**
+ * 构建文本形式的特殊块提示，追加到现有响应文本后。
+ */
+export function appendSpecialBlockTextHints(base, imageBlocks, whiteboardBlocks) {
+    const sections = [base];
+    if (imageBlocks.length > 0) {
+        const lines = [
+            `\n\n🖼️ 检测到 ${imageBlocks.length} 个图片块 (block_type: 27)！`,
+            '💡 提示：如需查看图片内容，可使用 get_feishu_image_resource 工具下载图片。',
+            '图片信息:',
+            ...imageBlocks.map((b, idx) => {
+                const parts = [`  ${idx + 1}. 块ID: ${b.block_id}`];
+                if (b.image?.token)
+                    parts.push(`媒体ID: ${b.image.token}`);
+                return parts.join('，');
+            }),
+            '📝 注意：只有在需要查看图片内容时才调用上述工具，仅了解文档结构时无需获取。',
+        ];
+        sections.push(lines.join('\n'));
+    }
+    if (whiteboardBlocks.length > 0) {
+        const lines = [
+            `\n\n⚠️ 检测到 ${whiteboardBlocks.length} 个画板块 (block_type: 43)！`,
+            '💡 提示：如需获取画板具体内容，可使用 get_feishu_whiteboard_content 工具。',
+            '画板信息:',
+            ...whiteboardBlocks.map((b, idx) => {
+                const parts = [`  ${idx + 1}. 块ID: ${b.block_id}`];
+                if (b.board?.token)
+                    parts.push(`画板ID: ${b.board.token}`);
+                return parts.join('，');
+            }),
+            '📝 注意：只有在需要分析画板内容时才调用上述工具，仅了解文档结构时无需获取。',
+        ];
+        sections.push(lines.join('\n'));
+    }
+    return sections.join('');
+}
+/**
+ * 从飞书 API 抛出的错误对象中提取结构化错误信息。
+ * 飞书 API 错误可能包含 apiError.code / apiError.msg / apiError.log_id 等字段。
+ */
+export function extractFeishuApiError(err) {
+    if (err && typeof err === 'object') {
+        const e = err;
+        const apiError = e.apiError;
+        if (apiError && apiError.code !== undefined && apiError.msg) {
+            return {
+                message: String(apiError.msg),
+                code: Number(apiError.code),
+                logId: apiError.log_id != null ? String(apiError.log_id) : undefined,
+            };
+        }
+        if (typeof e.err === 'string')
+            return { message: e.err };
+        if (typeof e.message === 'string')
+            return { message: e.message };
+    }
+    return { message: formatErrorMessage(err) };
+}

package/dist/modules/FeatureModule.js

@@ -0,0 +1 @@
+export {};