feishu-mcp 0.1.6 → 0.1.8

package/dist/types/feishuSchema.js

@@ -1,9 +1,12 @@
 import { z } from 'zod';
-// 文档ID或URL参数定义
+// 文档类型枚举（用于 get_feishu_document_info）
+export const DocumentTypeSchema = z.enum(['document', 'wiki']).optional().describe('Document type (optional). "document" for regular document, "wiki" for Wiki document.');
+// 文档ID或URL参数定义（仅支持普通文档）
 export const DocumentIdSchema = z.string().describe('Document ID or URL (required). Supports the following formats:\n' +
     '1. Standard document URL: https://xxx.feishu.cn/docs/xxx or https://xxx.feishu.cn/docx/xxx\n' +
-    '2. Direct document ID: e.g., JcKbdlokYoPIe0xDzJ1cduRXnRf\n' +
-    'Note: Wiki links require conversion with convert_feishu_wiki_to_document_id first.');
+    '2. Direct document ID: e.g., JcKbdlokYoPIe0xDzJ1cduRXnRf');
+// 文档ID或Wiki ID参数定义（用于 get_feishu_document_info，支持普通文档和Wiki文档）
+export const DocumentIdOrWikiIdSchema = z.string().describe('Document ID, URL, or Wiki ID/URL (required). Supports regular document formats (https://xxx.feishu.cn/docx/xxx or direct ID) and Wiki formats (https://xxx.feishu.cn/wiki/xxxxx or Wiki token).');
 // 父块ID参数定义
 export const ParentBlockIdSchema = z.string().describe('Parent block ID (required). Target block ID where content will be added, without any URL prefix. ' +
     'For page-level (root level) insertion, extract and use only the document ID portion (not the full URL) as parentBlockId. ' +
@@ -103,9 +106,10 @@ export const ListBlockSchema = z.object({
     align: AlignSchemaWithValidation,
 });
 // 块类型枚举 - 用于批量创建块工具
-export const BlockTypeEnum = z.string().describe("Block type (required). Supports: 'text', 'code', 'heading', 'list', 'image','mermaid',as well as 'heading1' through 'heading9'. " +
+export const BlockTypeEnum = z.string().describe("Block type (required). Supports: 'text', 'code', 'heading', 'list', 'image','mermaid','whiteboard',as well as 'heading1' through 'heading9'. " +
     "For headings, we recommend using 'heading' with level property, but 'heading1'-'heading9' are also supported. " +
     "For images, use 'image' to create empty image blocks that can be filled later. " +
+    "For whiteboards, use 'whiteboard' to create empty whiteboard blocks that return a token for filling content. " +
     "For text blocks, you can include both regular text and equation elements in the same block.");
 // 图片宽度参数定义
 export const ImageWidthSchema = z.number().optional().describe('Image width in pixels (optional). If not provided, the original image width will be used.');
@@ -124,6 +128,12 @@ export const MermaidCodeSchema = z.string().describe('Mermaid code (required). T
 export const MermaidBlockSchema = z.object({
     code: MermaidCodeSchema,
 });
+// 画板对齐方式参数定义
+export const WhiteboardAlignSchema = z.number().optional().default(2).describe('Whiteboard alignment: 1 for left, 2 for center (default), 3 for right.');
+// 画板块内容定义 - 用于批量创建块工具
+export const WhiteboardBlockSchema = z.object({
+    align: WhiteboardAlignSchema,
+});
 // 块配置定义 - 用于批量创建块工具
 export const BlockConfigSchema = z.object({
     blockType: BlockTypeEnum,
@@ -134,6 +144,7 @@ export const BlockConfigSchema = z.object({
         z.object({ list: ListBlockSchema }).describe("List block options. Used when blockType is 'list'."),
         z.object({ image: ImageBlockSchema }).describe("Image block options. Used when blockType is 'image'. Creates empty image blocks."),
         z.object({ mermaid: MermaidBlockSchema }).describe("Mermaid block options.  Used when blockType is 'mermaid'."),
+        z.object({ whiteboard: WhiteboardBlockSchema }).describe("Whiteboard block options. Used when blockType is 'whiteboard'. Creates empty whiteboard blocks that return a token for filling content."),
         z.record(z.any()).describe("Fallback for any other block options")
     ]).describe('Options for the specific block type. Provide the corresponding options object based on blockType.'),
 });
@@ -171,13 +182,36 @@ export const MediaIdSchema = z.string().describe('Media ID (required). The uniqu
 // 额外参数定义 - 用于媒体资源下载
 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参数定义
+// 文件夹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".');
+// 文件夹Token参数定义（可选，用于文档创建、获取文件列表等场景）
+export const FolderTokenOptionalSchema = z.string().optional().describe('Folder token (optional, for Feishu Drive folder mode). The unique identifier for a folder in Feishu Drive. ' +
+    '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.');
+// 知识空间ID参数定义
+export const SpaceIdSchema = z.string().describe('Space ID (optional, required for wiki space mode). The unique identifier for a wiki space in Feishu. ' +
+    'Can be obtained from get_feishu_root_folder_info (wiki_spaces array or my_library.space_id). ' +
+    'Format is typically like "74812***88644".');
+// 父节点Token参数定义
+export const ParentNodeTokenSchema = z.string().optional().describe('Parent node token (optional, used with spaceId). The token of the parent node in a wiki space. ' +
+    'If not provided or empty, will retrieve nodes from the root of the wiki space. ' +
+    'Format is typically like "PdDWwIHD6****MhcIOY7npg".');
+// 知识库节点上下文参数定义（包装 spaceId 和 parentNodeToken）
+export const WikiSpaceNodeContextSchema = z.object({
+    spaceId: SpaceIdSchema.optional(),
+    parentNodeToken: ParentNodeTokenSchema,
+}).optional().describe('Wiki space node context object. Contains spaceId (required when using this object) and optional parentNodeToken. ' +
+    'Used for wiki space operations instead of folderToken.');
 // 搜索关键字参数定义
 export const SearchKeySchema = z.string().describe('Search keyword (required). The keyword to search for in documents.');
+// 搜索类型枚举
+export const SearchTypeSchema = z.enum(['document', 'wiki', 'both']).optional().default('both').describe('Search type (optional, default: "both"). "document": only documents, "wiki": only wiki nodes, "both": both (default)');
+// 知识库分页token参数定义
+export const PageTokenSchema = z.string().optional().describe('Wiki page token (optional). Token from previous wiki search result for pagination. Only needed when fetching next page of wiki results.');
+// 文档分页偏移量参数定义
+export const OffsetSchema = z.number().optional().describe('Document offset (optional). Offset for document search pagination. Only needed when fetching next page of document results.');
 // 图片路径或URL参数定义
 export const ImagePathOrUrlSchema = z.string().describe('Image path or URL (required). Supports the following formats:\n' +
     '1. Local file absolute path: e.g., "C:\\path\\to\\image.jpg"\n' +
@@ -196,5 +230,26 @@ export const ImagesArraySchema = z.array(z.object({
 export const WhiteboardIdSchema = z.string().describe('Whiteboard ID (required). This is the token value from the board.token field when getting document blocks.\n' +
     'When you find a block with block_type: 43, the whiteboard ID is located in board.token field.\n' +
     'Example: "EPJKwvY5ghe3pVbKj9RcT2msnBX"');
+// 画板代码参数定义（支持 PlantUML 和 Mermaid）
+export const WhiteboardCodeSchema = z.string().describe('Diagram code (required). The complete diagram code to create in the whiteboard.\n' +
+    'Supports both PlantUML and Mermaid formats.\n' +
+    'PlantUML example: "@startuml\nAlice -> Bob: Hello\n@enduml"\n' +
+    'Mermaid example: "graph TD\nA[Start] --> B[End]"');
+// 语法类型参数定义
+export const SyntaxTypeSchema = z.number().describe('Syntax type (required). Specifies the diagram syntax format.\n' +
+    '1: PlantUML syntax\n' +
+    '2: Mermaid syntax');
+// 画板内容配置定义（包含画板ID和内容配置）
+export const WhiteboardContentSchema = z.object({
+    whiteboardId: WhiteboardIdSchema,
+    code: WhiteboardCodeSchema,
+    syntax_type: SyntaxTypeSchema,
+}).describe('Whiteboard content configuration. Contains the whiteboard ID, diagram code and syntax type.\n' +
+    'whiteboardId: The token value from board.token field when creating whiteboard block (required)\n' +
+    'code: The diagram code (PlantUML or Mermaid format) (required)\n' +
+    'syntax_type: 1 for PlantUML, 2 for Mermaid (required)');
+// 批量填充画板数组定义
+export const WhiteboardFillArraySchema = z.array(WhiteboardContentSchema).describe('Array of whiteboard fill items (required). Each item must include whiteboardId, code and syntax_type.\n' +
+    'Example: [{whiteboardId:"token1", code:"@startuml...", syntax_type:1}, {whiteboardId:"token2", code:"graph TD...", syntax_type:2}]');
 // 文档标题参数定义
 export const DocumentTitleSchema = z.string().describe('Document title (required). This will be displayed in the Feishu document list and document header.');

package/dist/utils/auth/tokenCacheManager.js

@@ -28,9 +28,16 @@ export class TokenCacheManager {
             writable: true,
             value: void 0
         });
+        Object.defineProperty(this, "scopeVersionCacheFile", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
         this.cache = new Map();
         this.userTokenCacheFile = path.resolve(process.cwd(), 'user_token_cache.json');
         this.tenantTokenCacheFile = path.resolve(process.cwd(), 'tenant_token_cache.json');
+        this.scopeVersionCacheFile = path.resolve(process.cwd(), 'scope_version_cache.json');
         this.loadTokenCaches();
         this.startCacheCleanupTimer();
     }
@@ -49,6 +56,7 @@ export class TokenCacheManager {
     loadTokenCaches() {
         this.loadUserTokenCache();
         this.loadTenantTokenCache();
+        this.loadScopeVersionCache();
     }
     /**
      * 加载用户token缓存
@@ -433,4 +441,108 @@ export class TokenCacheManager {
         Logger.debug(`获取到 ${keys.length} 个用户token keys`);
         return keys;
     }
+    /**
+     * 获取scope版本信息
+     * @param clientKey 客户端缓存键
+     * @returns scope版本信息，如果未找到则返回null
+     */
+    getScopeVersionInfo(clientKey) {
+        const cacheKey = `scope_version:${clientKey}`;
+        const cacheItem = this.cache.get(cacheKey);
+        if (!cacheItem) {
+            Logger.debug(`Scope版本信息未找到: ${clientKey}`);
+            return null;
+        }
+        Logger.debug(`获取Scope版本信息成功: ${clientKey}`);
+        return cacheItem.data;
+    }
+    /**
+     * 保存scope版本信息
+     * @param clientKey 客户端缓存键
+     * @param scopeVersionInfo scope版本信息
+     * @returns 是否成功保存
+     */
+    saveScopeVersionInfo(clientKey, scopeVersionInfo) {
+        try {
+            const cacheKey = `scope_version:${clientKey}`;
+            const now = Date.now();
+            // scope版本信息永久有效，不设置过期时间
+            const cacheItem = {
+                data: scopeVersionInfo,
+                timestamp: now,
+                expiresAt: Number.MAX_SAFE_INTEGER // 永久有效
+            };
+            this.cache.set(cacheKey, cacheItem);
+            this.saveScopeVersionCache();
+            Logger.debug(`Scope版本信息保存成功: ${clientKey}, 版本: ${scopeVersionInfo.scopeVersion}`);
+            return true;
+        }
+        catch (error) {
+            Logger.error(`保存Scope版本信息失败: ${clientKey}`, error);
+            return false;
+        }
+    }
+    /**
+     * 检查scope版本是否需要校验
+     * @param clientKey 客户端缓存键
+     * @param currentScopeVersion 当前scope版本号
+     * @returns 是否需要校验
+     */
+    shouldValidateScope(clientKey, currentScopeVersion) {
+        const scopeVersionInfo = this.getScopeVersionInfo(clientKey);
+        if (!scopeVersionInfo) {
+            Logger.debug(`Scope版本信息不存在，需要校验: ${clientKey}`);
+            return true;
+        }
+        // 如果版本号不同，需要重新校验
+        if (scopeVersionInfo.validatedVersion !== currentScopeVersion) {
+            Logger.debug(`Scope版本号已更新，需要重新校验: ${clientKey}, 旧版本: ${scopeVersionInfo.validatedVersion}, 新版本: ${currentScopeVersion}`);
+            return true;
+        }
+        Logger.debug(`Scope版本已校验过，无需重复校验: ${clientKey}, 版本: ${currentScopeVersion}`);
+        return false;
+    }
+    /**
+     * 加载scope版本缓存
+     */
+    loadScopeVersionCache() {
+        if (fs.existsSync(this.scopeVersionCacheFile)) {
+            try {
+                const raw = fs.readFileSync(this.scopeVersionCacheFile, 'utf-8');
+                const cacheData = JSON.parse(raw);
+                let loadedCount = 0;
+                for (const key in cacheData) {
+                    if (key.startsWith('scope_version:')) {
+                        this.cache.set(key, cacheData[key]);
+                        loadedCount++;
+                    }
+                }
+                Logger.info(`已加载Scope版本缓存，共 ${loadedCount} 条记录`);
+            }
+            catch (error) {
+                Logger.warn('加载Scope版本缓存失败:', error);
+            }
+        }
+        else {
+            Logger.info('Scope版本缓存文件不存在，将创建新的缓存');
+        }
+    }
+    /**
+     * 保存scope版本缓存到文件
+     */
+    saveScopeVersionCache() {
+        const cacheData = {};
+        for (const [key, value] of this.cache.entries()) {
+            if (key.startsWith('scope_version:')) {
+                cacheData[key] = value;
+            }
+        }
+        try {
+            fs.writeFileSync(this.scopeVersionCacheFile, JSON.stringify(cacheData, null, 2), 'utf-8');
+            Logger.debug('Scope版本缓存已保存到文件');
+        }
+        catch (error) {
+            Logger.warn('保存Scope版本缓存失败:', error);
+        }
+    }
 }

package/dist/utils/error.js

@@ -206,3 +206,27 @@ export class AuthRequiredError extends Error {
         this.message = message;
     }
 }
+/**
+ * 权限不足异常类
+ * 用于处理应用权限范围不足的情况
+ */
+export class ScopeInsufficientError extends Error {
+    constructor(missingScopes, message) {
+        super(message);
+        Object.defineProperty(this, "missingScopes", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "message", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.name = 'ScopeInsufficientError';
+        this.missingScopes = missingScopes;
+        this.message = message;
+    }
+}

package/package.json

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