feishu-mcp 0.1.6 → 0.1.8

package/dist/mcp/tools/feishuTools.js

@@ -1,9 +1,8 @@
-// import { z } from 'zod';
 import { formatErrorMessage } from '../../utils/error.js';
 import { Logger } from '../../utils/logger.js';
-import { DocumentIdSchema, 
+import { DocumentIdSchema, DocumentIdOrWikiIdSchema, DocumentTypeSchema, 
 // BlockIdSchema,
-SearchKeySchema, WhiteboardIdSchema, DocumentTitleSchema, FolderTokenSchema, } from '../../types/feishuSchema.js';
+SearchKeySchema, SearchTypeSchema, PageTokenSchema, OffsetSchema, WhiteboardIdSchema, DocumentTitleSchema, FolderTokenOptionalSchema, WikiSpaceNodeContextSchema, } from '../../types/feishuSchema.js';
 /**
  * 注册飞书相关的MCP工具
  * @param server MCP服务器实例
@@ -11,42 +10,94 @@ SearchKeySchema, WhiteboardIdSchema, DocumentTitleSchema, FolderTokenSchema, } f
  */
 export function registerFeishuTools(server, feishuService) {
     // 添加创建飞书文档工具
-    server.tool('create_feishu_document', 'Creates a new Feishu document and returns its information. Use this tool when you need to create a document from scratch with a specific title and folder location.', {
+    server.tool('create_feishu_document', 'Creates a new Feishu document and returns its information. Supports two modes: (1) Feishu Drive folder mode: use folderToken to create a document in a folder. (2) Wiki space node mode: use wikiContext with spaceId (and optional parentNodeToken) to create a node (document) in a wiki space. IMPORTANT: In wiki spaces, documents are nodes themselves - they can act as parent nodes containing child documents, and can also be edited as regular documents. The created node returns both node_token (node ID, can be used as parentNodeToken for creating child nodes) and obj_token (document ID, can be used for document editing operations like get_feishu_document_blocks, batch_create_feishu_blocks, etc.). Only one mode can be used at a time - provide either folderToken OR wikiContext, not both.', {
         title: DocumentTitleSchema,
-        folderToken: FolderTokenSchema,
-    }, async ({ title, folderToken }) => {
+        folderToken: FolderTokenOptionalSchema,
+        wikiContext: WikiSpaceNodeContextSchema,
+    }, async ({ title, folderToken, wikiContext }) => {
         try {
-            Logger.info(`开始创建飞书文档，标题: ${title}${folderToken ? `，文件夹Token: ${folderToken}` : '，使用默认文件夹'}`);
-            const newDoc = await feishuService?.createDocument(title, folderToken);
-            if (!newDoc) {
-                throw new Error('创建文档失败，未返回文档信息');
+            if (!feishuService) {
+                return {
+                    content: [{ type: 'text', text: '飞书服务未初始化，请检查配置' }],
+                };
+            }
+            // 参数验证：必须提供 folderToken 或 wikiContext 之一，但不能同时提供
+            if (folderToken && wikiContext) {
+                return {
+                    content: [{ type: 'text', text: '错误：不能同时提供 folderToken 和 wikiContext 参数，请选择其中一种模式。\n- 使用 folderToken 在飞书文档目录中创建文档\n- 使用 wikiContext 在知识库中创建节点（文档）' }],
+                };
             }
-            Logger.info(`飞书文档创建成功，文档ID: ${newDoc.objToken || newDoc.document_id}`);
+            if (!folderToken && !wikiContext) {
+                return {
+                    content: [{ type: 'text', text: '错误：必须提供 folderToken（飞书文档目录模式）或 wikiContext（知识库节点模式）参数之一。' }],
+                };
+            }
+            // 模式一：飞书文档目录模式
+            if (folderToken) {
+                Logger.info(`开始创建飞书文档（文件夹模式），标题: ${title}，文件夹Token: ${folderToken}`);
+                const newDoc = await feishuService.createDocument(title, folderToken);
+                if (!newDoc) {
+                    throw new Error('创建文档失败，未返回文档信息');
+                }
+                Logger.info(`飞书文档创建成功，文档ID: ${newDoc.objToken || newDoc.document_id}`);
+                return {
+                    content: [{ type: 'text', text: JSON.stringify(newDoc, null, 2) }],
+                };
+            }
+            // 模式二：知识库节点模式
+            if (wikiContext) {
+                const { spaceId, parentNodeToken } = wikiContext;
+                if (!spaceId) {
+                    return {
+                        content: [{ type: 'text', text: '错误：使用 wikiContext 模式时，必须提供 spaceId。' }],
+                    };
+                }
+                Logger.info(`开始创建知识库节点，标题: ${title}，知识空间ID: ${spaceId}，父节点Token: ${parentNodeToken || 'null（根节点）'}`);
+                const node = await feishuService.createWikiSpaceNode(spaceId, title, parentNodeToken);
+                if (!node) {
+                    throw new Error('创建知识库节点失败，未返回节点信息');
+                }
+                // 构建返回信息，说明知识库节点的特殊性质
+                const result = {
+                    ...node,
+                    _note: '知识库节点既是节点又是文档：node_token 可作为父节点使用，obj_token 可用于文档编辑操作'
+                };
+                Logger.info(`知识库节点创建成功，node_token: ${node.node_token}, obj_token: ${node.obj_token}`);
+                return {
+                    content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+                };
+            }
+            // 理论上不会到达这里
             return {
-                content: [{ type: 'text', text: JSON.stringify(newDoc, null, 2) }],
+                content: [{ type: 'text', text: '错误：未知错误' }],
             };
         }
         catch (error) {
-            Logger.error(`创建飞书文档失败:`, error);
+            Logger.error(`创建文档失败:`, error);
             const errorMessage = formatErrorMessage(error);
             return {
-                content: [{ type: 'text', text: `创建飞书文档失败: ${errorMessage}` }],
+                content: [{ type: 'text', text: `创建文档失败: ${errorMessage}` }],
             };
         }
     });
-    // 添加获取飞书文档信息工具
-    server.tool('get_feishu_document_info', 'Retrieves basic information about a Feishu document. Use this to verify a document exists, check access permissions, or get metadata like title, type, and creation information.', {
-        documentId: DocumentIdSchema,
-    }, async ({ documentId }) => {
+    // 添加获取飞书文档信息工具（支持普通文档和Wiki文档）
+    server.tool('get_feishu_document_info', 'Retrieves basic information about a Feishu document or Wiki node. Supports both regular documents (via document ID/URL) and Wiki documents (via Wiki URL/token). Use this to verify a document exists, check access permissions, or get metadata like title, type, and creation information. For Wiki documents, returns complete node information including documentId (obj_token) for document editing operations, and space_id and node_token for creating child nodes. ', {
+        documentId: DocumentIdOrWikiIdSchema,
+        documentType: DocumentTypeSchema,
+    }, async ({ documentId, documentType }) => {
         try {
             if (!feishuService) {
                 return {
                     content: [{ type: 'text', text: '飞书服务未初始化，请检查配置' }],
                 };
             }
-            Logger.info(`开始获取飞书文档信息，文档ID: ${documentId}`);
-            const docInfo = await feishuService.getDocumentInfo(documentId);
-            Logger.info(`飞书文档信息获取成功，标题: ${docInfo.title}`);
+            Logger.info(`开始获取飞书文档信息，文档ID: ${documentId}, 类型: ${documentType || 'auto'}`);
+            const docInfo = await feishuService.getDocumentInfo(documentId, documentType);
+            if (!docInfo) {
+                throw new Error('获取文档信息失败，未返回数据');
+            }
+            const title = docInfo.title || docInfo.document?.title || '未知标题';
+            Logger.info(`飞书文档信息获取成功，标题: ${title}, 类型: ${docInfo._type || 'document'}`);
             return {
                 content: [{ type: 'text', text: JSON.stringify(docInfo, null, 2) }],
             };
@@ -92,7 +143,7 @@ export function registerFeishuTools(server, feishuService) {
     //   },
     // );
     // 添加获取飞书文档块工具
-    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) you must first use convert_feishu_wiki_to_document_id tool to obtain a compatible document ID.', {
+    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,
     }, async ({ documentId }) => {
         try {
@@ -183,19 +234,22 @@ export function registerFeishuTools(server, feishuService) {
     //     }
     //   },
     // );
-    // 添加搜索文档工具
-    server.tool('search_feishu_documents', 'Searches for documents in Feishu. Supports keyword-based search and returns document information including title, type, and owner. Use this tool to find specific content or related documents in your document library.', {
+    // 添加搜索文档工具（支持文档和知识库搜索）
+    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,
-    }, async ({ searchKey }) => {
+        searchType: SearchTypeSchema,
+        offset: OffsetSchema,
+        pageToken: PageTokenSchema,
+    }, async ({ searchKey, searchType, offset, pageToken }) => {
         try {
             if (!feishuService) {
                 return {
                     content: [{ type: 'text', text: 'Feishu service is not initialized. Please check the configuration.' }],
                 };
             }
-            Logger.info(`开始搜索飞书文档，关键字: ${searchKey},`);
-            const searchResult = await feishuService.searchDocuments(searchKey);
-            Logger.info(`文档搜索完成，找到 ${searchResult.size} 个结果`);
+            Logger.info(`开始搜索，关键字: ${searchKey}, 类型: ${searchType || 'both'}, offset: ${offset || 0}, pageToken: ${pageToken || '无'}`);
+            const searchResult = await feishuService.search(searchKey, searchType || 'both', offset, pageToken);
+            Logger.info(`搜索完成，文档: ${searchResult.documents?.length || 0} 条，知识库: ${searchResult.wikis?.length || 0} 条`);
             return {
                 content: [
                     { type: 'text', text: JSON.stringify(searchResult, null, 2) },
@@ -203,11 +257,11 @@ export function registerFeishuTools(server, feishuService) {
             };
         }
         catch (error) {
-            Logger.error(`搜索飞书文档失败:`, error);
+            Logger.error(`搜索失败:`, error);
             const errorMessage = formatErrorMessage(error);
             return {
                 content: [
-                    { type: 'text', text: `搜索飞书文档失败: ${errorMessage}` },
+                    { type: 'text', text: `搜索失败: ${errorMessage}` },
                 ],
             };
         }

package/dist/services/baseService.js

@@ -1,7 +1,7 @@
 import axios, { AxiosError } from 'axios';
 import FormData from 'form-data';
 import { Logger } from '../utils/logger.js';
-import { formatErrorMessage, AuthRequiredError } from '../utils/error.js';
+import { formatErrorMessage, AuthRequiredError, ScopeInsufficientError } from '../utils/error.js';
 import { Config } from '../utils/config.js';
 import { TokenCacheManager, UserContextManager, AuthUtils } from '../utils/auth/index.js';
 /**
@@ -126,6 +126,10 @@ export class BaseApiService {
         }
         catch (error) {
             const config = Config.getInstance().feishu;
+            // 优先处理权限不足异常
+            if (error instanceof ScopeInsufficientError) {
+                return this.handleScopeInsufficientError(error);
+            }
             // 处理授权异常
             if (error instanceof AuthRequiredError) {
                 return this.handleAuthFailure(config.authType === "tenant", clientKey, baseUrl, userKey);
@@ -212,6 +216,13 @@ export class BaseApiService {
     async delete(endpoint, data, needsAuth = true) {
         return this.request(endpoint, 'DELETE', data, needsAuth);
     }
+    /**
+     * 处理权限不足异常
+     * @param error 权限不足错误
+     */
+    handleScopeInsufficientError(error) {
+        throw error;
+    }
     /**
      * 处理认证失败
      * @param tenant 是否是tenant
@@ -300,7 +311,7 @@ export class BaseApiService {
         const { appId, appSecret } = Config.getInstance().feishu;
         const clientKey = AuthUtils.generateClientKey(userKey);
         const redirect_uri = `${baseUrl}/callback`;
-        const scope = encodeURIComponent('base:app:read bitable:app bitable:app:readonly board:whiteboard:node:read contact:user.employee_id:readonly docs:document.content:read docx:document docx:document.block:convert docx:document:create docx:document:readonly drive:drive drive:drive:readonly drive:file drive:file:upload sheets:spreadsheet sheets:spreadsheet:readonly space:document:retrieve space:folder:create wiki:space:read wiki:space:retrieve wiki:wiki wiki:wiki:readonly offline_access');
+        const scope = encodeURIComponent('base:app:read bitable:app bitable:app:readonly board:whiteboard:node:read board:whiteboard:node:create contact:user.employee_id:readonly docs:document.content:read docx:document docx:document.block:convert docx:document:create docx:document:readonly drive:drive drive:drive:readonly drive:file drive:file:upload sheets:spreadsheet sheets:spreadsheet:readonly space:document:retrieve space:folder:create wiki:space:read wiki:space:retrieve wiki:wiki wiki:wiki:readonly offline_access');
         const state = AuthUtils.encodeState(appId, appSecret, clientKey, redirect_uri);
         return `https://accounts.feishu.cn/open-apis/authen/v1/authorize?client_id=${appId}&redirect_uri=${encodeURIComponent(redirect_uri)}&scope=${scope}&state=${state}`;
     }

package/dist/services/blockFactory.js

@@ -10,6 +10,7 @@ export var BlockType;
     BlockType["LIST"] = "list";
     BlockType["IMAGE"] = "image";
     BlockType["MERMAID"] = "mermaid";
+    BlockType["WHITEBOARD"] = "whiteboard";
 })(BlockType || (BlockType = {}));
 /**
  * 对齐方式枚举
@@ -78,6 +79,8 @@ export class BlockFactory {
                 return this.createImageBlock(options);
             case BlockType.MERMAID:
                 return this.createMermaidBlock(options);
+            case BlockType.WHITEBOARD:
+                return this.createWhiteboardBlock(options);
             default:
                 Logger.error(`不支持的块类型: ${type}`);
                 throw new Error(`不支持的块类型: ${type}`);
@@ -246,6 +249,20 @@ export class BlockFactory {
             },
         };
     }
+    /**
+     * 创建画板块内容（空画板块，需要后续填充内容）
+     * @param options 画板块选项
+     * @returns 画板块内容对象
+     */
+    createWhiteboardBlock(options = {}) {
+        const { align = AlignType.CENTER } = options;
+        return {
+            block_type: 43, // 43表示画板块
+            board: {
+                align: align // 1 居左，2 居中，3 居右
+            }
+        };
+    }
     /**
      * 创建表格块
      * @param options 表格块选项