feishu-mcp 0.0.7 → 0.0.8

package/dist/server.js

@@ -5,7 +5,8 @@ import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
 import { formatErrorMessage } from './utils/error.js';
 import { FeishuApiService } from './services/feishuApiService.js';
 import { Logger } from './utils/logger.js';
-import { DocumentIdSchema, ParentBlockIdSchema, BlockIdSchema, IndexSchema, StartIndexSchema, AlignSchema, AlignSchemaWithValidation, TextElementsArraySchema, CodeLanguageSchema, CodeWrapSchema, BlockConfigSchema } from './types/feishuSchema.js';
+import { detectMimeType } from './utils/document.js';
+import { DocumentIdSchema, ParentBlockIdSchema, BlockIdSchema, IndexSchema, StartIndexSchema, EndIndexSchema, AlignSchema, AlignSchemaWithValidation, TextElementsArraySchema, CodeLanguageSchema, CodeWrapSchema, BlockConfigSchema, MediaIdSchema, MediaExtraSchema, FolderTokenSchema, FolderNameSchema, OrderBySchema, DirectionSchema } from './types/feishuSchema.js';
 export class FeishuMcpServer {
     constructor() {
         Object.defineProperty(this, "server", {
@@ -202,11 +203,11 @@ export class FeishuMcpServer {
             }
         });
         // 添加通用飞书块创建工具（支持文本、代码、标题）
-        this.server.tool('batch_create_feishu_blocks', 'RECOMMENDED: Creates multiple blocks of different types (text, code, heading, list) in a single efficient API call. This tool should be PREFERRED OVER individual block creation tools when creating multiple consecutive blocks at the same position. Significantly improves performance and reduces API calls by up to 90% compared to creating blocks individually. AUTOMATICALLY handles batching for large number of blocks (>50) by splitting into multiple requests. For specific block positioning at different locations, use individual block creation tools instead. For error recovery, use get_feishu_document_blocks to check the document state. 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.', {
+        this.server.tool('batch_create_feishu_blocks', 'PREFERRED: Efficiently creates multiple blocks (text, code, heading, list) in a single API call. USE THIS TOOL when creating multiple consecutive blocks at the same position - reduces API calls by up to 90%. KEY FEATURES: (1) Handles any number of blocks by auto-batching large requests (>50 blocks), (2) Creates blocks at consecutive positions in a document. CORRECT FORMAT: mcp_feishu_batch_create_feishu_blocks({documentId:"doc123",parentBlockId:"para123",startIndex:0,blocks:[{blockType:"text",options:{...}},{blockType:"heading",options:{...}}]}). For separate positions, use individual block creation tools instead. For wiki links (https://xxx.feishu.cn/wiki/xxx), first convert with convert_feishu_wiki_to_document_id tool.', {
             documentId: DocumentIdSchema,
             parentBlockId: ParentBlockIdSchema,
             startIndex: StartIndexSchema,
-            blocks: z.array(BlockConfigSchema).describe('Array of block configurations (required). Each element contains blockType and options properties. Example: [{blockType:"text",options:{text:{textStyles:[{text:"Hello",style:{bold:true}}]}}},{blockType:"code",options:{code:{code:"console.log(\'Hello\')",language:30}}}]. Handles any number of blocks by automatically batching in groups of 50.'),
+            blocks: z.array(BlockConfigSchema).describe('Array of block configurations. CRITICAL: Must be a JSON array object, NOT a string. CORRECT: blocks:[{...}] - WITHOUT quotes around array. INCORRECT: blocks:"[{...}]". Example: [{blockType:"text",options:{text:{textStyles:[{text:"Hello",style:{bold:true}}]}}},{blockType:"code",options:{code:{code:"console.log()",language:30}}}]. Auto-batches requests when exceeding 50 blocks.'),
         }, async ({ documentId, parentBlockId, startIndex = 0, blocks }) => {
             try {
                 if (!this.feishuService) {
@@ -219,6 +220,17 @@ export class FeishuMcpServer {
                         ],
                     };
                 }
+                // 类型检查：确保blocks是数组而不是字符串
+                if (typeof blocks === 'string') {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: 'ERROR: The "blocks" parameter was passed as a string instead of an array. Please provide a proper JSON array without quotes. Example: {blocks:[{blockType:"text",options:{...}}]} instead of {blocks:"[{...}]"}',
+                            },
+                        ],
+                    };
+                }
                 // 如果块数量不超过50，直接调用一次API
                 if (blocks.length <= 50) {
                     Logger.info(`开始批量创建飞书块，文档ID: ${documentId}，父块ID: ${parentBlockId}，块数量: ${blocks.length}，起始插入位置: ${startIndex}`);
@@ -484,6 +496,143 @@ export class FeishuMcpServer {
                 };
             }
         });
+        // 添加删除文档块工具
+        this.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) you must first use convert_feishu_wiki_to_document_id tool to obtain a compatible document ID.', {
+            documentId: DocumentIdSchema,
+            parentBlockId: ParentBlockIdSchema,
+            startIndex: StartIndexSchema,
+            endIndex: EndIndexSchema,
+        }, async ({ documentId, parentBlockId, startIndex, endIndex }) => {
+            try {
+                if (!this.feishuService) {
+                    return {
+                        content: [{ type: 'text', text: 'Feishu service is not initialized. Please check the configuration' }],
+                    };
+                }
+                Logger.info(`开始删除飞书文档块，文档ID: ${documentId}，父块ID: ${parentBlockId}，索引范围: ${startIndex}-${endIndex}`);
+                const result = await this.feishuService.deleteDocumentBlocks(documentId, parentBlockId, startIndex, endIndex);
+                Logger.info(`飞书文档块删除成功，文档修订ID: ${result.document_revision_id}`);
+                return {
+                    content: [{ type: 'text', text: `Successfully deleted blocks from index ${startIndex} to ${endIndex - 1}` }],
+                };
+            }
+            catch (error) {
+                Logger.error(`删除飞书文档块失败:`, error);
+                const errorMessage = formatErrorMessage(error);
+                return {
+                    content: [{ type: 'text', text: `Failed to delete document blocks: ${errorMessage}` }],
+                };
+            }
+        });
+        // 添加获取图片资源工具
+        this.server.tool('get_feishu_image_resource', 'Downloads an image resource from Feishu by its media ID. Use this to retrieve images referenced in document blocks or other Feishu resources. Returns the binary image data that can be saved or processed further. For example, extract the media_id from an image block in a document, then use this tool to download the actual image.', {
+            mediaId: MediaIdSchema,
+            extra: MediaExtraSchema,
+        }, async ({ mediaId, extra = '' }) => {
+            try {
+                if (!this.feishuService) {
+                    return {
+                        content: [{ type: 'text', text: 'Feishu service is not initialized. Please check the configuration' }],
+                    };
+                }
+                Logger.info(`开始获取飞书图片资源，媒体ID: ${mediaId}`);
+                const imageBuffer = await this.feishuService.getImageResource(mediaId, extra);
+                Logger.info(`飞书图片资源获取成功，大小: ${imageBuffer.length} 字节`);
+                // 将图片数据转为Base64编码，以便在MCP协议中传输
+                const base64Image = imageBuffer.toString('base64');
+                const mimeType = detectMimeType(imageBuffer);
+                return {
+                    content: [{
+                            type: 'image',
+                            mimeType: mimeType,
+                            data: base64Image
+                        }],
+                };
+            }
+            catch (error) {
+                Logger.error(`获取飞书图片资源失败:`, error);
+                const errorMessage = formatErrorMessage(error);
+                return {
+                    content: [{ type: 'text', text: `Failed to get image resource: ${errorMessage}` }],
+                };
+            }
+        });
+        // 添加获取根文件夹信息工具
+        this.server.tool('get_feishu_root_folder_info', 'Retrieves basic information about the root folder in Feishu Drive. Returns the token, ID and user ID of the root folder, which can be used for subsequent folder operations.', {}, async () => {
+            try {
+                if (!this.feishuService) {
+                    return {
+                        content: [{ type: 'text', text: '飞书服务未初始化，请检查配置' }],
+                    };
+                }
+                Logger.info(`开始获取飞书根文件夹信息`);
+                const folderInfo = await this.feishuService.getRootFolderInfo();
+                Logger.info(`飞书根文件夹信息获取成功，token: ${folderInfo.token}`);
+                return {
+                    content: [{ type: 'text', text: JSON.stringify(folderInfo, null, 2) }],
+                };
+            }
+            catch (error) {
+                Logger.error(`获取飞书根文件夹信息失败:`, error);
+                const errorMessage = formatErrorMessage(error, '获取飞书根文件夹信息失败');
+                return {
+                    content: [{ type: 'text', text: errorMessage }],
+                };
+            }
+        });
+        // 添加获取文件夹中的文件清单工具
+        this.server.tool('get_feishu_folder_files', 'Retrieves a list of files and subfolders in a specified folder. Use this to explore folder contents, view file metadata, and get URLs and tokens for further operations.', {
+            folderToken: FolderTokenSchema,
+            orderBy: OrderBySchema,
+            direction: DirectionSchema
+        }, async ({ folderToken, orderBy = 'EditedTime', direction = 'DESC' }) => {
+            try {
+                if (!this.feishuService) {
+                    return {
+                        content: [{ type: 'text', text: '飞书服务未初始化，请检查配置' }],
+                    };
+                }
+                Logger.info(`开始获取飞书文件夹中的文件清单，文件夹Token: ${folderToken}，排序方式: ${orderBy}，排序方向: ${direction}`);
+                const fileList = await this.feishuService.getFolderFileList(folderToken, orderBy, direction);
+                Logger.info(`飞书文件夹中的文件清单获取成功，共 ${fileList.files?.length || 0} 个文件`);
+                return {
+                    content: [{ type: 'text', text: JSON.stringify(fileList, null, 2) }],
+                };
+            }
+            catch (error) {
+                Logger.error(`获取飞书文件夹中的文件清单失败:`, error);
+                const errorMessage = formatErrorMessage(error);
+                return {
+                    content: [{ type: 'text', text: `获取飞书文件夹中的文件清单失败: ${errorMessage}` }],
+                };
+            }
+        });
+        // 添加创建文件夹工具
+        this.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 {
+                if (!this.feishuService) {
+                    return {
+                        content: [{ type: 'text', text: '飞书服务未初始化，请检查配置' }],
+                    };
+                }
+                Logger.info(`开始创建飞书文件夹，父文件夹Token: ${folderToken}，文件夹名称: ${folderName}`);
+                const result = await this.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);
+                const errorMessage = formatErrorMessage(error);
+                return {
+                    content: [{ type: 'text', text: `创建飞书文件夹失败: ${errorMessage}` }],
+                };
+            }
+        });
     }
     async connect(transport) {
         await this.server.connect(transport);

package/dist/services/feishuApiService.js

@@ -377,9 +377,48 @@ export class FeishuApiService extends BaseApiService {
      * @returns 创建结果
      */
     async createMixedBlocks(documentId, parentBlockId, blocks, index = 0) {
-        const blockContents = this.blockFactory.createBatchBlocks(blocks);
+        const blockContents = blocks.map(block => this.blockFactory.createBlock(block.type, block.options));
         return this.createDocumentBlocks(documentId, parentBlockId, blockContents, index);
     }
+    /**
+     * 删除文档中的块，支持批量删除
+     * @param documentId 文档ID或URL
+     * @param parentBlockId 父块ID（通常是文档ID）
+     * @param startIndex 起始索引
+     * @param endIndex 结束索引
+     * @returns 操作结果
+     */
+    async deleteDocumentBlocks(documentId, parentBlockId, startIndex, endIndex) {
+        try {
+            const normalizedDocId = ParamUtils.processDocumentId(documentId);
+            const endpoint = `/docx/v1/documents/${normalizedDocId}/blocks/${parentBlockId}/children/batch_delete`;
+            // 确保索引有效
+            if (startIndex < 0 || endIndex < startIndex) {
+                throw new Error('无效的索引范围：起始索引必须大于等于0，结束索引必须大于等于起始索引');
+            }
+            const payload = {
+                start_index: startIndex,
+                end_index: endIndex
+            };
+            Logger.info(`开始删除文档块，文档ID: ${normalizedDocId}，父块ID: ${parentBlockId}，索引范围: ${startIndex}-${endIndex}`);
+            const response = await this.delete(endpoint, payload);
+            Logger.info('文档块删除成功');
+            return response;
+        }
+        catch (error) {
+            this.handleApiError(error, '删除文档块失败');
+        }
+    }
+    /**
+     * 删除单个文档块（通过创建起始和结束索引相同的批量删除请求）
+     * @param documentId 文档ID或URL
+     * @param parentBlockId 父块ID
+     * @param blockIndex 块索引
+     * @returns 操作结果
+     */
+    async deleteDocumentBlock(documentId, parentBlockId, blockIndex) {
+        return this.deleteDocumentBlocks(documentId, parentBlockId, blockIndex, blockIndex + 1);
+    }
     /**
      * 将飞书Wiki链接转换为文档ID
      * @param wikiUrl Wiki链接或Token
@@ -485,4 +524,107 @@ export class FeishuApiService extends BaseApiService {
             return null;
         }
     }
+    /**
+     * 获取飞书图片资源
+     * @param mediaId 图片媒体ID
+     * @param extra 额外参数，可选
+     * @returns 图片二进制数据
+     */
+    async getImageResource(mediaId, extra = '') {
+        try {
+            Logger.info(`开始获取图片资源，媒体ID: ${mediaId}`);
+            if (!mediaId) {
+                throw new Error('媒体ID不能为空');
+            }
+            const endpoint = `/drive/v1/medias/${mediaId}/download`;
+            const params = {};
+            if (extra) {
+                params.extra = extra;
+            }
+            // 这里需要特殊处理，因为返回的是二进制数据，不是JSON
+            const token = await this.getAccessToken();
+            const url = `${this.getBaseUrl()}${endpoint}`;
+            const headers = {
+                'Authorization': `Bearer ${token}`
+            };
+            Logger.debug(`请求图片资源URL: ${url}`);
+            // 使用axios直接获取二进制响应
+            const response = await axios.get(url, {
+                params,
+                headers,
+                responseType: 'arraybuffer'
+            });
+            // 检查响应状态
+            if (response.status !== 200) {
+                throw new Error(`获取图片资源失败，状态码: ${response.status}`);
+            }
+            const imageBuffer = Buffer.from(response.data);
+            Logger.info(`图片资源获取成功，大小: ${imageBuffer.length} 字节`);
+            return imageBuffer;
+        }
+        catch (error) {
+            this.handleApiError(error, '获取图片资源失败');
+            return Buffer.from([]); // 永远不会执行到这里
+        }
+    }
+    /**
+     * 获取飞书根文件夹信息
+     * 获取用户的根文件夹的元数据信息，包括token、id和用户id
+     * @returns 根文件夹信息
+     */
+    async getRootFolderInfo() {
+        try {
+            const endpoint = '/drive/explorer/v2/root_folder/meta';
+            const response = await this.get(endpoint);
+            Logger.debug('获取根文件夹信息成功:', response);
+            return response;
+        }
+        catch (error) {
+            this.handleApiError(error, '获取飞书根文件夹信息失败');
+        }
+    }
+    /**
+     * 获取文件夹中的文件清单
+     * @param folderToken 文件夹Token
+     * @param orderBy 排序方式，默认按修改时间排序
+     * @param direction 排序方向，默认降序
+     * @returns 文件清单信息
+     */
+    async getFolderFileList(folderToken, orderBy = 'EditedTime', direction = 'DESC') {
+        try {
+            const endpoint = '/drive/v1/files';
+            const params = {
+                folder_token: folderToken,
+                order_by: orderBy,
+                direction: direction
+            };
+            const response = await this.get(endpoint, params);
+            Logger.debug(`获取文件夹(${folderToken})中的文件清单成功，文件数量: ${response.files?.length || 0}`);
+            return response;
+        }
+        catch (error) {
+            this.handleApiError(error, '获取文件夹中的文件清单失败');
+        }
+    }
+    /**
+     * 创建文件夹
+     * @param folderToken 父文件夹Token
+     * @param name 文件夹名称
+     * @returns 创建的文件夹信息
+     */
+    async createFolder(folderToken, name) {
+        try {
+            const endpoint = '/drive/v1/files/create_folder';
+            const payload = {
+                folder_token: folderToken,
+                name: name
+            };
+            const response = await this.post(endpoint, payload);
+            Logger.debug(`文件夹创建成功, token: ${response.token}, url: ${response.url}`);
+            return response;
+        }
+        catch (error) {
+            this.handleApiError(error, '创建文件夹失败');
+        }
+    }
 }

package/dist/types/feishuSchema.js

@@ -17,6 +17,10 @@ export const IndexSchema = z.number().describe('Insertion position index (requir
 // 起始插入位置索引参数定义
 export const StartIndexSchema = z.number().describe('Starting insertion position index (required). Specifies where the first block should be inserted. Use 0 to insert at the beginning. ' +
     'Use get_feishu_document_blocks tool to understand document structure if unsure.');
+// 结束位置索引参数定义
+export const EndIndexSchema = z.number().describe('Ending position index (required). Specifies the end of the range for deletion (exclusive). ' +
+    'For example, to delete blocks 2, 3, and 4, use startIndex=2, endIndex=5. ' +
+    'To delete a single block at position 2, use startIndex=2, endIndex=3.');
 // 文本对齐方式参数定义
 export const AlignSchema = z.number().optional().default(1).describe('Text alignment: 1 for left (default), 2 for center, 3 for right.');
 // 文本对齐方式参数定义（带验证）
@@ -95,3 +99,21 @@ export const BlockConfigSchema = z.object({
         z.object({ list: ListBlockSchema }).describe("List block options. Only used when blockType is 'list'."),
     ]).describe('Options for the specific block type. Must provide the corresponding options object based on blockType.'),
 });
+// 媒体ID参数定义
+export const MediaIdSchema = z.string().describe('Media ID (required). The unique identifier for a media resource (image, file, etc.) in Feishu. ' +
+    'Usually obtained from image blocks or file references in documents. ' +
+    'Format is typically like "boxcnrHpsg1QDqXAAAyachabcef".');
+// 额外参数定义 - 用于媒体资源下载
+export const MediaExtraSchema = z.string().optional().describe('Extra parameters for media download (optional). ' +
+    'These parameters are passed directly to the Feishu API and can modify how the media is returned.');
+// 文件夹Token参数定义
+export const FolderTokenSchema = z.string().describe('Folder token (required). The unique identifier for a folder in Feishu. ' +
+    'Format is an alphanumeric string like "FWK2fMleClICfodlHHWc4Mygnhb".');
+// 文件夹名称参数定义
+export const FolderNameSchema = z.string().describe('Folder name (required). The name for the new folder to be created.');
+// 排序方式参数定义
+export const OrderBySchema = z.string().optional().default('EditedTime').describe('Order by field (optional). Specifies how to sort the file list. Available values: ' +
+    '"EditedTime" (default), "CreatedTime", "Name". For user-friendly display, case insensitive.');
+// 排序方向参数定义
+export const DirectionSchema = z.string().optional().default('DESC').describe('Sort direction (optional). Specifies the sort order. Available values: ' +
+    '"DESC" (default) for descending order, "ASC" for ascending order. Case sensitive.');

package/dist/utils/document.js

@@ -72,3 +72,41 @@ export function normalizeWikiToken(input) {
     }
     return token;
 }
+/**
+ * 根据图片二进制数据检测MIME类型
+ * @param buffer 图片二进制数据
+ * @returns MIME类型字符串
+ */
+export function detectMimeType(buffer) {
+    // 简单的图片格式检测，根据文件头进行判断
+    if (buffer.length < 4) {
+        return 'application/octet-stream';
+    }
+    // JPEG格式
+    if (buffer[0] === 0xFF && buffer[1] === 0xD8 && buffer[2] === 0xFF) {
+        return 'image/jpeg';
+    }
+    // PNG格式
+    else if (buffer[0] === 0x89 && buffer[1] === 0x50 && buffer[2] === 0x4E && buffer[3] === 0x47) {
+        return 'image/png';
+    }
+    // GIF格式
+    else if (buffer[0] === 0x47 && buffer[1] === 0x49 && buffer[2] === 0x46) {
+        return 'image/gif';
+    }
+    // SVG格式 - 检查字符串前缀
+    else if (buffer.length > 5 && buffer.toString('ascii', 0, 5).toLowerCase() === '<?xml' ||
+        buffer.toString('ascii', 0, 4).toLowerCase() === '<svg') {
+        return 'image/svg+xml';
+    }
+    // WebP格式
+    else if (buffer.length > 12 &&
+        buffer[0] === 0x52 && buffer[1] === 0x49 && buffer[2] === 0x46 && buffer[3] === 0x46 &&
+        buffer[8] === 0x57 && buffer[9] === 0x45 && buffer[10] === 0x42 && buffer[11] === 0x50) {
+        return 'image/webp';
+    }
+    // 默认二进制流
+    else {
+        return 'application/octet-stream';
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "feishu-mcp",
-  "version": "0.0.7",
+  "version": "0.0.8",
   "description": "Model Context Protocol server for Feishu integration",
   "type": "module",
   "main": "dist/index.js",