feishu-mcp 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 cso1z
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,86 @@
+# 飞书 MCP 服务器
+
+为 [Cursor](https://cursor.sh/)、[Windsurf](https://codeium.com/windsurf)、[Cline](https://cline.bot/) 和其他 AI 驱动的编码工具提供访问飞书文档的能力，基于 [Model Context Protocol](https://modelcontextprotocol.io/introduction) 服务器实现。
+
+当 Cursor 能够访问飞书文档数据时，它可以更准确地理解和处理文档内容，比其他方法（如复制粘贴文本）更加高效。
+
+## 核心功能
+
+### 文档管理
+- **创建飞书文档**：支持创建新的飞书文档
+
+### 文档内容操作
+- **获取文档信息**：能够获取文档中各个块的详细信息
+- **获取文档纯文本内容**：支持提取文档的纯文本内容
+- **修改文档内容**：
+  - 更新现有文档的内容
+  - 插入新的内容块
+
+### 计划中的功能
+- **高级内容插入**：
+  - 插入图表：支持各类数据可视化图表
+  - 插入流程图：支持流程图和思维导图
+  - 插入公式：支持数学公式和科学符号
+  - 图表、流程图的内容识别
+
+
+## 工作原理
+
+1. 在 Cursor 的 Agent 模式下打开编辑器。
+2. 粘贴飞书文档的链接。
+3. 要求 Cursor 基于飞书文档执行操作——例如，分析文档内容或创建相关代码。
+4. Cursor 将从飞书获取相关元数据并使用它来辅助编写代码。
+
+这个 MCP 服务器专为 Cursor 设计。在响应来自[飞书 API](https://open.feishu.cn/document/home/introduction-to-lark-open-platform/overview) 的内容之前，它会简化和转换响应，确保只向模型提供最相关的文档信息。
+
+### 从本地源代码运行服务器
+
+1. 克隆仓库
+2. 使用 `pnpm install` 安装依赖
+3. 复制 `.env.example` 到 `.env` 并填入你的[飞书应用凭证](https://open.feishu.cn/document/home/develop-a-bot-in-5-minutes/create-an-app)。
+4. 使用 `pnpm run dev` 运行服务器，可以使用[命令行参数](#命令行参数)部分的任何标志。
+
+## 配置
+
+服务器可以使用环境变量（通过 `.env` 文件）或命令行参数进行配置。命令行参数优先于环境变量。
+
+### 环境变量
+
+- `FEISHU_APP_ID`：你的[飞书应用 ID](https://open.feishu.cn/document/home/develop-a-bot-in-5-minutes/create-an-app)（必需）
+- `FEISHU_APP_SECRET`：你的[飞书应用密钥](https://open.feishu.cn/document/home/develop-a-bot-in-5-minutes/create-an-app)（必需）
+- `PORT`：运行服务器的端口（默认：3333）
+
+### 命令行参数
+
+- `--version`：显示版本号
+- `--feishu-app-id`：你的飞书应用 ID
+- `--feishu-app-secret`：你的飞书应用密钥
+- `--port`：运行服务器的端口
+- `--stdio`：在命令模式下运行服务器，而不是默认的 HTTP/SSE
+- `--help`：显示帮助菜单
+
+## 连接到 Cursor
+
+### 配置 Cursor
+
+1. 打开 Cursor 设置
+2. 导航到 `Settings > AI > MCP Servers`
+3. 添加新服务器，URL 为 `http://localhost:3333`（或你配置的端口）
+4. 点击 "Verify Connection" 确保连接成功
+
+## 使用方法
+
+1. 在 Cursor 中，打开 AI 面板（默认快捷键 `Cmd+K` 或 `Ctrl+K`）
+2. 如果需要新建一个飞书文档编辑信息，应该明确制定一个folderToken,可以打开一个飞书文档目录如：`https://vq5xxxxx7bc.feishu.cn/drive/folder/FPKvfjdxxxxx706RnOc查找`
+2. 如果需要修改飞书文档内容应该明确告知飞书文档链接，例如：`https://vq5ixxxx7bc.feishu.cn/docx/J6T0d6exxxxxxxDdc1zqwnph`
+3. 询问关于文档的问题或请求基于文档内容执行操作
+4. 创建编辑文档都需要权限，可以到飞书开放平台对账号进行测试`https://open.feishu.cn/api-explorer/cli_a75a8ca0ac79100c?apiName=tenant_access_token_internal&from=op_doc&project=auth&resource=auth&version=v3`
+
+## Cursor最佳实践
+
+添加Rules指导模型操作流程
+
+`在将文档上传至飞书时，请遵循以下操作指南：1. 若未特别指定 folderToken，默认为 FPKvf*********6RnOc。2. 在块创建失败的情况下，通过查询文档中所有的块信息，以确认是否确实发生了失败。3. 若需在现有文档中追加信息，请先获取该文档的所有块信息，并根据返回结果确定要插入的内容及其索引位置。4. 一旦文档内容全部修改完成，请提供文档链接,格式如下： https://vq5iay***bc.feishu.cn/docx/documentId。5.获取文档信息时应优先查询其纯文本内容，如果不满足则通过查询所有块来确定内容`
+## 许可证
+
+MIT

package/dist/cli.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+import { resolve } from "path";
+import { config } from "dotenv";
+import { startServer } from "./index";
+// Load .env from the current working directory
+config({ path: resolve(process.cwd(), ".env") });
+startServer().catch((error) => {
+    if (error instanceof Error) {
+        console.error("Failed to start server:", error.message);
+    }
+    else {
+        console.error("Failed to start server with unknown error:", error);
+    }
+    process.exit(1);
+});

package/dist/config.js

@@ -0,0 +1,104 @@
+import { config } from "dotenv";
+import yargs from "yargs";
+import { hideBin } from "yargs/helpers";
+// 确保在任何配置读取前加载.env文件
+config();
+function maskApiKey(key) {
+    if (key.length <= 4)
+        return "****";
+    return `****${key.slice(-4)}`;
+}
+export function getServerConfig(isStdioMode) {
+    // Parse command line arguments
+    const argv = yargs(hideBin(process.argv))
+        .options({
+        port: {
+            type: "number",
+            description: "Port to run the server on",
+        },
+        "feishu-app-id": {
+            type: "string",
+            description: "Feishu App ID",
+        },
+        "feishu-app-secret": {
+            type: "string",
+            description: "Feishu App Secret",
+        },
+    })
+        .help()
+        .parseSync();
+    const config = {
+        port: 3333,
+        configSources: {
+            port: "default",
+        },
+    };
+    // Handle PORT
+    if (argv.port) {
+        config.port = argv.port;
+        config.configSources.port = "cli";
+    }
+    else if (process.env.PORT) {
+        config.port = parseInt(process.env.PORT, 10);
+        config.configSources.port = "env";
+    }
+    // 在加载环境变量之前添加日志
+    console.log('开始加载环境变量配置...');
+    console.log('当前环境变量 FEISHU_APP_ID:', process.env.FEISHU_APP_ID);
+    console.log('当前环境变量 FEISHU_APP_SECRET:', process.env.FEISHU_APP_SECRET);
+    // Handle Feishu configuration
+    if (argv["feishu-app-id"]) {
+        config.feishuAppId = argv["feishu-app-id"];
+        config.configSources.feishuAppId = "cli";
+        console.log(`飞书应用 ID 来自命令行参数: ${maskApiKey(config.feishuAppId)}`);
+    }
+    else if (process.env.FEISHU_APP_ID) {
+        config.feishuAppId = process.env.FEISHU_APP_ID;
+        config.configSources.feishuAppId = "env";
+        console.log(`飞书应用 ID 来自环境变量: ${maskApiKey(config.feishuAppId)}`);
+    }
+    else {
+        console.log('未提供飞书应用 ID');
+    }
+    if (argv["feishu-app-secret"]) {
+        config.feishuAppSecret = argv["feishu-app-secret"];
+        config.configSources.feishuAppSecret = "cli";
+        console.log(`飞书应用密钥来自命令行参数: ${maskApiKey(config.feishuAppSecret)}`);
+    }
+    else if (process.env.FEISHU_APP_SECRET) {
+        config.feishuAppSecret = process.env.FEISHU_APP_SECRET;
+        config.configSources.feishuAppSecret = "env";
+        console.log(`飞书应用密钥来自环境变量: ${maskApiKey(config.feishuAppSecret)}`);
+    }
+    else {
+        console.log('未提供飞书应用密钥');
+    }
+    // 输出飞书配置状态总结
+    if (config.feishuAppId && config.feishuAppSecret) {
+        console.log('飞书配置已完整提供，服务将被初始化');
+    }
+    else if (config.feishuAppId || config.feishuAppSecret) {
+        console.log('飞书配置不完整，服务将不会初始化');
+    }
+    else {
+        console.log('未提供飞书配置，服务将不会初始化');
+    }
+    // 验证配置
+    if (!config.feishuAppId || !config.feishuAppSecret) {
+        console.error("FEISHU_APP_ID 和 FEISHU_APP_SECRET 是必需的（通过命令行参数 --feishu-app-id 和 --feishu-app-secret 或 .env 文件）");
+        process.exit(1);
+    }
+    // Log configuration sources
+    if (!isStdioMode) {
+        console.log("\n配置信息:");
+        console.log(`- PORT: ${config.port} (来源: ${config.configSources.port})`);
+        if (config.feishuAppId) {
+            console.log(`- FEISHU_APP_ID: ${maskApiKey(config.feishuAppId)} (来源: ${config.configSources.feishuAppId})`);
+        }
+        if (config.feishuAppSecret) {
+            console.log(`- FEISHU_APP_SECRET: ${maskApiKey(config.feishuAppSecret)} (来源: ${config.configSources.feishuAppSecret})`);
+        }
+        console.log(); // 空行，提高可读性
+    }
+    return config;
+}

package/dist/index.js

@@ -0,0 +1,32 @@
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { FeishuMcpServer } from "./server";
+import { getServerConfig } from "./config";
+export async function startServer() {
+    // Check if we're running in stdio mode (e.g., via CLI)
+    const isStdioMode = process.env.NODE_ENV === "cli" || process.argv.includes("--stdio");
+    const config = getServerConfig(isStdioMode);
+    // 创建飞书配置对象
+    const feishuConfig = {
+        appId: config.feishuAppId,
+        appSecret: config.feishuAppSecret
+    };
+    console.log("Feishu configuration status: Available");
+    console.log(`Feishu App ID: ${feishuConfig.appId.substring(0, 4)}...${feishuConfig.appId.substring(feishuConfig.appId.length - 4)}`);
+    console.log(`Feishu App Secret: ${feishuConfig.appSecret.substring(0, 4)}...${feishuConfig.appSecret.substring(feishuConfig.appSecret.length - 4)}`);
+    const server = new FeishuMcpServer(feishuConfig);
+    if (isStdioMode) {
+        const transport = new StdioServerTransport();
+        await server.connect(transport);
+    }
+    else {
+        console.log(`Initializing Feishu MCP Server in HTTP mode on port ${config.port}...`);
+        await server.startHttpServer(config.port);
+    }
+}
+// If this file is being run directly, start the server
+if (require.main === module) {
+    startServer().catch((error) => {
+        console.error("Failed to start server:", error);
+        process.exit(1);
+    });
+}

package/dist/server.js

@@ -0,0 +1,314 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { FeishuService } from "./services/feishu";
+import express from "express";
+import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
+export const Logger = {
+    log: (...args) => { console.log(...args); },
+    error: (...args) => { console.error(...args); },
+};
+export class FeishuMcpServer {
+    constructor(feishuConfig) {
+        Object.defineProperty(this, "server", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "sseTransport", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        Object.defineProperty(this, "feishuService", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        // 详细记录飞书配置状态
+        Logger.log(`飞书配置已提供 - AppID: ${feishuConfig.appId.substring(0, 4)}...${feishuConfig.appId.substring(feishuConfig.appId.length - 4)}, AppSecret: ${feishuConfig.appSecret.substring(0, 4)}...${feishuConfig.appSecret.substring(feishuConfig.appSecret.length - 4)}`);
+        try {
+            this.feishuService = new FeishuService(feishuConfig.appId, feishuConfig.appSecret);
+            Logger.log('飞书服务初始化成功');
+        }
+        catch (error) {
+            Logger.error('飞书服务初始化失败:', error);
+            throw new Error('飞书服务初始化失败');
+        }
+        this.server = new McpServer({
+            name: "Feishu MCP Server",
+            version: "0.0.1",
+        }, {
+            capabilities: {
+                logging: {},
+                tools: {},
+            },
+        });
+        this.registerTools();
+    }
+    registerTools() {
+        // 添加创建飞书文档工具
+        // 添加创建飞书文档工具
+        this.server.tool("create_feishu_doc", "Create a new Feishu document", {
+            title: z.string().describe("Document title"),
+            folderToken: z.string().optional().describe("Folder token where the document will be created. If not provided, the document will be created in the root directory"),
+        }, async ({ title, folderToken }) => {
+            try {
+                Logger.log(`开始创建飞书文档，标题: ${title}${folderToken ? `，文件夹Token: ${folderToken}` : ''}`);
+                // @ts-ignore
+                const newDoc = await this.feishuService.createDocument(title, folderToken);
+                Logger.log(`飞书文档创建成功，文档ID: ${newDoc?.objToken || newDoc?.document_id}`);
+                return {
+                    content: [{ type: "text", text: JSON.stringify(newDoc, null, 2) }],
+                };
+            }
+            catch (error) {
+                Logger.error(`创建飞书文档失败:`, error);
+                return {
+                    content: [{ type: "text", text: `创建飞书文档失败: ${error}` }],
+                };
+            }
+        });
+        // 添加获取飞书文档信息工具
+        // this.server.tool(
+        //   "get_feishu_doc_info",
+        //   "Get basic information about a Feishu document",
+        //   {
+        //     documentId: z.string().describe("Document ID or URL. Supported formats:\n1. Standard document URL: https://xxx.feishu.cn/docs/xxx or https://xxx.feishu.cn/docx/xxx\n2. API URL: https://open.feishu.cn/open-apis/doc/v2/documents/xxx\n3. Direct document ID (e.g., JcKbdlokYoPIe0xDzJ1cduRXnRf)"),
+        //   },
+        //   async ({ documentId }) => {
+        //     try {
+        //       if (!this.feishuService) {
+        //         return {
+        //           content: [{ type: "text", text: "Feishu service is not initialized. Please check the configuration" }],
+        //         };
+        //       }
+        //       Logger.log(`开始获取飞书文档信息，文档ID: ${documentId}`);
+        //       const docInfo = await this.feishuService.getDocumentInfo(documentId);
+        //       Logger.log(`飞书文档信息获取成功，标题: ${docInfo.title}`);
+        //       return {
+        //         content: [{ type: "text", text: JSON.stringify(docInfo, null, 2) }],
+        //       };
+        //     } catch (error) {
+        //       Logger.error(`获取飞书文档信息失败:`, error);
+        //       return {
+        //         content: [{ type: "text", text: `获取飞书文档信息失败: ${error}` }],
+        //       };
+        //     }
+        //   },
+        // );
+        // 添加获取飞书文档内容工具
+        this.server.tool("get_feishu_doc_content", "Get the plain text content of a Feishu document", {
+            documentId: z.string().describe("Document ID or URL. Supported formats:\n1. Standard document URL: https://xxx.feishu.cn/docs/xxx or https://xxx.feishu.cn/docx/xxx\n2. API URL: https://open.feishu.cn/open-apis/doc/v2/documents/xxx\n3. Direct document ID (e.g., JcKbdlokYoPIe0xDzJ1cduRXnRf)"),
+            lang: z.number().optional().default(0).describe("Language code. Default is 0 (Chinese)"),
+        }, async ({ documentId, lang }) => {
+            try {
+                if (!this.feishuService) {
+                    return {
+                        content: [{ type: "text", text: "Feishu service is not initialized. Please check the configuration" }],
+                    };
+                }
+                Logger.log(`开始获取飞书文档内容，文档ID: ${documentId}，语言: ${lang}`);
+                const content = await this.feishuService.getDocumentContent(documentId, lang);
+                Logger.log(`飞书文档内容获取成功，内容长度: ${content.length}字符`);
+                return {
+                    content: [{ type: "text", text: content }],
+                };
+            }
+            catch (error) {
+                Logger.error(`获取飞书文档内容失败:`, error);
+                return {
+                    content: [{ type: "text", text: `获取飞书文档内容失败: ${error}` }],
+                };
+            }
+        });
+        // 添加获取飞书文档块工具
+        this.server.tool("get_feishu_doc_blocks", "When document structure is needed, obtain the block information about the Feishu document for content analysis or block insertion", {
+            documentId: z.string().describe("Document ID or URL. Supported formats:\n1. Standard document URL: https://xxx.feishu.cn/docs/xxx or https://xxx.feishu.cn/docx/xxx\n2. API URL: https://open.feishu.cn/open-apis/doc/v2/documents/xxx\n3. Direct document ID (e.g., JcKbdlokYoPIe0xDzJ1cduRXnRf)"),
+            pageSize: z.number().optional().default(500).describe("Number of blocks per page. Default is 500"),
+        }, async ({ documentId, pageSize }) => {
+            try {
+                if (!this.feishuService) {
+                    return {
+                        content: [{ type: "text", text: "Feishu service is not initialized. Please check the configuration" }],
+                    };
+                }
+                Logger.log(`开始获取飞书文档块，文档ID: ${documentId}，页大小: ${pageSize}`);
+                const blocks = await this.feishuService.getDocumentBlocks(documentId, pageSize);
+                Logger.log(`飞书文档块获取成功，共 ${blocks.length} 个块`);
+                return {
+                    content: [{ type: "text", text: JSON.stringify(blocks, null, 2) }],
+                };
+            }
+            catch (error) {
+                Logger.error(`获取飞书文档块失败:`, error);
+                return {
+                    content: [{ type: "text", text: `获取飞书文档块失败: ${error}` }],
+                };
+            }
+        });
+        // 添加创建飞书文档块工具
+        this.server.tool("create_feishu_text_block", "Create a new text block in a Feishu document (AI will automatically convert Markdown syntax to corresponding style attributes: **bold** → bold:true, *italic* → italic:true, ~~strikethrough~~ → strikethrough:true, `code` → inline_code:true)", {
+            documentId: z.string().describe("Document ID or URL. Supported formats:\n1. Standard document URL: https://xxx.feishu.cn/docs/xxx or https://xxx.feishu.cn/docx/xxx\n2. API URL: https://open.feishu.cn/open-apis/doc/v2/documents/xxx\n3. Direct document ID (e.g., JcKbdlokYoPIe0xDzJ1cduRXnRf)"),
+            parentBlockId: z.string().describe("Parent block ID (NOT URL) where the new block will be added as a child. This should be the raw block ID without any URL prefix. When adding blocks at the page level (root level), use the extracted document ID from documentId parameter"),
+            textContents: z.array(z.object({
+                text: z.string().describe("Text content"),
+                style: z.object({
+                    bold: z.boolean().optional().describe("Whether to make text bold. Default is false"),
+                    italic: z.boolean().optional().describe("Whether to make text italic. Default is false"),
+                    underline: z.boolean().optional().describe("Whether to add underline. Default is false"),
+                    strikethrough: z.boolean().optional().describe("Whether to add strikethrough. Default is false"),
+                    inline_code: z.boolean().optional().describe("Whether to format as inline code. Default is false"),
+                    text_color: z.number().optional().describe("Text color as a number. Default is 0")
+                }).optional().describe("Text style settings")
+            })).describe("Array of text content objects. A block can contain multiple text segments with different styles"),
+            align: z.number().optional().default(1).describe("Text alignment: 1 for left, 2 for center, 3 for right. Default is 1"),
+            index: z.number().optional().default(0).describe("Insertion position index. Default is 0 (insert at the beginning). If unsure about the position, use the get_feishu_doc_blocks tool first to understand the document structure. For consecutive insertions, calculate the next position as previous_index + 1 to avoid querying document structure repeatedly")
+        }, async ({ documentId, parentBlockId, textContents, align = 1, index }) => {
+            try {
+                if (!this.feishuService) {
+                    return {
+                        content: [{ type: "text", text: "Feishu service is not initialized. Please check the configuration" }],
+                    };
+                }
+                // 处理Markdown语法转换
+                const processedTextContents = textContents.map(content => {
+                    let { text, style = {} } = content;
+                    // 创建一个新的style对象，避免修改原始对象
+                    const newStyle = { ...style };
+                    // 处理粗体 **text**
+                    if (text.match(/\*\*([^*]+)\*\*/g)) {
+                        text = text.replace(/\*\*([^*]+)\*\*/g, "$1");
+                        newStyle.bold = true;
+                    }
+                    // 处理斜体 *text*
+                    if (text.match(/(?<!\*)\*([^*]+)\*(?!\*)/g)) {
+                        text = text.replace(/(?<!\*)\*([^*]+)\*(?!\*)/g, "$1");
+                        newStyle.italic = true;
+                    }
+                    // 处理删除线 ~~text~~
+                    if (text.match(/~~([^~]+)~~/g)) {
+                        text = text.replace(/~~([^~]+)~~/g, "$1");
+                        newStyle.strikethrough = true;
+                    }
+                    // 处理行内代码 `code`
+                    if (text.match(/`([^`]+)`/g)) {
+                        text = text.replace(/`([^`]+)`/g, "$1");
+                        newStyle.inline_code = true;
+                    }
+                    return { text, style: newStyle };
+                });
+                Logger.log(`开始创建飞书文本块，文档ID: ${documentId}，父块ID: ${parentBlockId}，对齐方式: ${align}，插入位置: ${index}`);
+                const result = await this.feishuService.createTextBlock(documentId, parentBlockId, processedTextContents, align, index);
+                Logger.log(`飞书文本块创建成功`);
+                return {
+                    content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+                };
+            }
+            catch (error) {
+                Logger.error(`创建飞书文本块失败:`, error);
+                return {
+                    content: [{ type: "text", text: `创建飞书文本块失败: ${error}` }],
+                };
+            }
+        });
+        // 添加创建飞书代码块工具
+        this.server.tool("create_feishu_code_block", "Create a new code block in a Feishu document", {
+            documentId: z.string().describe("Document ID or URL. Supported formats:\n1. Standard document URL: https://xxx.feishu.cn/docs/xxx or https://xxx.feishu.cn/docx/xxx\n2. API URL: https://open.feishu.cn/open-apis/doc/v2/documents/xxx\n3. Direct document ID (e.g., JcKbdlokYoPIe0xDzJ1cduRXnRf)"),
+            parentBlockId: z.string().describe("Parent block ID (NOT URL) where the new block will be added as a child. This should be the raw block ID without any URL prefix. When adding blocks at the page level (root level), use the extracted document ID from documentId parameter"),
+            code: z.string().describe("Code content"),
+            language: z.number().optional().default(0).describe("Programming language code as a number. Examples: 1: PlainText; 7: Bash; 8: CSharp; 9: C++; 10: C; 12: CSS; 22: Go; 24: HTML; 29: Java; 30: JavaScript; 32: Kotlin; 43: PHP; 49: Python; 52: Ruby; 53: Rust; 56: SQL; 60: Shell; 61: Swift; 63: TypeScript. Default is 0"),
+            wrap: z.boolean().optional().default(false).describe("Whether to enable automatic line wrapping. Default is false"),
+            index: z.number().optional().default(0).describe("Insertion position index. Default is 0 (insert at the beginning). If unsure about the position, use the get_feishu_doc_blocks tool first to understand the document structure. For consecutive insertions, calculate the next position as previous_index + 1 to avoid querying document structure repeatedly")
+        }, async ({ documentId, parentBlockId, code, language = 0, wrap = false, index = 0 }) => {
+            try {
+                if (!this.feishuService) {
+                    return {
+                        content: [{ type: "text", text: "Feishu service is not initialized. Please check the configuration" }],
+                    };
+                }
+                Logger.log(`开始创建飞书代码块，文档ID: ${documentId}，父块ID: ${parentBlockId}，语言: ${language}，自动换行: ${wrap}，插入位置: ${index}`);
+                const result = await this.feishuService.createCodeBlock(documentId, parentBlockId, code, language, wrap, index);
+                Logger.log(`飞书代码块创建成功`);
+                return {
+                    content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+                };
+            }
+            catch (error) {
+                Logger.error(`创建飞书代码块失败:`, error);
+                return {
+                    content: [{ type: "text", text: `创建飞书代码块失败: ${error}` }],
+                };
+            }
+        });
+        // 添加创建飞书标题块工具
+        this.server.tool("create_feishu_heading_block", "Create a heading block in a Feishu document with specified level (1-9)", {
+            documentId: z.string().describe("Document ID or URL. Supported formats:\n1. Standard document URL: https://xxx.feishu.cn/docs/xxx or https://xxx.feishu.cn/docx/xxx\n2. API URL: https://open.feishu.cn/open-apis/doc/v2/documents/xxx\n3. Direct document ID (e.g., JcKbdlokYoPIe0xDzJ1cduRXnRf)"),
+            parentBlockId: z.string().describe("Parent block ID (NOT URL) where the new block will be added as a child. This should be the raw block ID without any URL prefix. When adding blocks at the page level (root level), use the extracted document ID from documentId parameter"),
+            level: z.number().min(1).max(9).describe("Heading level from 1 to 9, where 1 is the largest heading (h1) and 9 is the smallest (h9)"),
+            content: z.string().describe("Heading text content"),
+            index: z.number().optional().default(0).describe("Insertion position index. Default is 0 (insert at the beginning). If unsure about the position, use the get_feishu_doc_blocks tool first to understand the document structure. For consecutive insertions, calculate the next position as previous_index + 1 to avoid querying document structure repeatedly")
+        }, async ({ documentId, parentBlockId, level, content, index = 0 }) => {
+            try {
+                if (!this.feishuService) {
+                    return {
+                        content: [{ type: "text", text: "Feishu service is not initialized. Please check the configuration" }],
+                    };
+                }
+                Logger.log(`开始创建飞书标题块，文档ID: ${documentId}，父块ID: ${parentBlockId}，标题级别: ${level}，插入位置: ${index}`);
+                const result = await this.feishuService.createHeadingBlock(documentId, parentBlockId, content, level, index);
+                Logger.log(`飞书标题块创建成功`);
+                return {
+                    content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+                };
+            }
+            catch (error) {
+                Logger.error(`创建飞书标题块失败:`, error);
+                return {
+                    content: [{ type: "text", text: `创建飞书标题块失败: ${error}` }],
+                };
+            }
+        });
+    }
+    async connect(transport) {
+        // Logger.log("Connecting to transport...");
+        await this.server.connect(transport);
+        Logger.log = (...args) => {
+            this.server.server.sendLoggingMessage({
+                level: "info",
+                data: args,
+            });
+        };
+        Logger.error = (...args) => {
+            this.server.server.sendLoggingMessage({
+                level: "error",
+                data: args,
+            });
+        };
+        Logger.log("Server connected and ready to process requests");
+    }
+    async startHttpServer(port) {
+        const app = express();
+        app.get("/sse", async (_req, res) => {
+            console.log("New SSE connection established");
+            this.sseTransport = new SSEServerTransport("/messages", res);
+            await this.server.connect(this.sseTransport);
+        });
+        app.post("/messages", async (req, res) => {
+            if (!this.sseTransport) {
+                res.sendStatus(400);
+                return;
+            }
+            await this.sseTransport.handlePostMessage(req, res);
+        });
+        Logger.log = console.log;
+        Logger.error = console.error;
+        app.listen(port, () => {
+            Logger.log(`HTTP server listening on port ${port}`);
+            Logger.log(`SSE endpoint available at http://localhost:${port}/sse`);
+            Logger.log(`Message endpoint available at http://localhost:${port}/messages`);
+        });
+    }
+}

package/dist/services/feishu.js

@@ -0,0 +1,396 @@
+import axios, { AxiosError } from "axios";
+import { Logger } from "../server";
+export class FeishuService {
+    constructor(appId, appSecret) {
+        Object.defineProperty(this, "appId", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "appSecret", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "baseUrl", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: "https://open.feishu.cn/open-apis"
+        });
+        Object.defineProperty(this, "accessToken", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        Object.defineProperty(this, "tokenExpireTime", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        Object.defineProperty(this, "MAX_TOKEN_LIFETIME", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 2 * 60 * 60 * 1000
+        }); // 2小时的毫秒数
+        this.appId = appId;
+        this.appSecret = appSecret;
+    }
+    isTokenExpired() {
+        if (!this.accessToken || !this.tokenExpireTime)
+            return true;
+        return Date.now() >= this.tokenExpireTime;
+    }
+    async getAccessToken() {
+        if (this.accessToken && !this.isTokenExpired()) {
+            Logger.log('使用现有访问令牌，未过期');
+            return this.accessToken;
+        }
+        try {
+            const url = `${this.baseUrl}/auth/v3/tenant_access_token/internal`;
+            const requestData = {
+                app_id: this.appId,
+                app_secret: this.appSecret,
+            };
+            Logger.log('开始获取新的访问令牌...');
+            Logger.log(`请求URL: ${url}`);
+            Logger.log(`请求方法: POST`);
+            Logger.log(`请求数据: ${JSON.stringify(requestData, null, 2)}`);
+            const response = await axios.post(url, requestData);
+            Logger.log(`响应状态码: ${response.status}`);
+            Logger.log(`响应头: ${JSON.stringify(response.headers, null, 2)}`);
+            Logger.log(`响应数据: ${JSON.stringify(response.data, null, 2)}`);
+            if (response.data.code !== 0) {
+                Logger.error(`获取访问令牌失败，错误码: ${response.data.code}, 错误信息: ${response.data.msg}`);
+                throw {
+                    status: response.status,
+                    err: response.data.msg || "Unknown error",
+                };
+            }
+            this.accessToken = response.data.tenant_access_token;
+            this.tokenExpireTime = Date.now() + Math.min(response.data.expire * 1000, this.MAX_TOKEN_LIFETIME);
+            Logger.log(`成功获取新的访问令牌，有效期: ${response.data.expire} 秒`);
+            return this.accessToken; // 使用类型断言确保返回类型为string
+        }
+        catch (error) {
+            if (error instanceof AxiosError && error.response) {
+                Logger.error(`获取访问令牌请求失败:`);
+                Logger.error(`状态码: ${error.response.status}`);
+                Logger.error(`响应头: ${JSON.stringify(error.response.headers, null, 2)}`);
+                Logger.error(`响应数据: ${JSON.stringify(error.response.data, null, 2)}`);
+                throw {
+                    status: error.response.status,
+                    err: error.response.data?.msg || "Unknown error",
+                };
+            }
+            Logger.error('获取访问令牌时发生未知错误:', error);
+            throw new Error("Failed to get Feishu access token");
+        }
+    }
+    async request(endpoint, method = "GET", data) {
+        try {
+            const accessToken = await this.getAccessToken();
+            const url = `${this.baseUrl}${endpoint}`;
+            const headers = {
+                Authorization: `Bearer ${accessToken}`,
+                'Content-Type': 'application/json',
+            };
+            Logger.log('准备发送请求:');
+            Logger.log(`请求URL: ${url}`);
+            Logger.log(`请求方法: ${method}`);
+            Logger.log(`请求头: ${JSON.stringify(headers, null, 2)}`);
+            if (data) {
+                Logger.log(`请求数据: ${JSON.stringify(data, null, 2)}`);
+            }
+            const response = await axios({
+                method,
+                url,
+                headers,
+                data,
+            });
+            Logger.log('收到响应:');
+            Logger.log(`响应状态码: ${response.status}`);
+            Logger.log(`响应头: ${JSON.stringify(response.headers, null, 2)}`);
+            Logger.log(`响应数据: ${JSON.stringify(response.data, null, 2)}`);
+            return response.data;
+        }
+        catch (error) {
+            if (error instanceof AxiosError && error.response) {
+                Logger.error(`请求失败:`);
+                Logger.error(`状态码: ${error.response.status}`);
+                Logger.error(`响应头: ${JSON.stringify(error.response.headers, null, 2)}`);
+                Logger.error(`响应数据: ${JSON.stringify(error.response.data, null, 2)}`);
+                throw {
+                    status: error.response.status,
+                    err: error.response.data?.msg || "Unknown error",
+                };
+            }
+            Logger.error('发送请求时发生未知错误:', error);
+            throw new Error("Failed to make request to Feishu API");
+        }
+    }
+    // 创建新文档
+    async createDocument(title, folderToken) {
+        try {
+            Logger.log(`开始创建飞书文档，标题: ${title}${folderToken ? `，文件夹Token: ${folderToken}` : '，根目录'}`);
+            const endpoint = '/docx/v1/documents';
+            const data = {
+                title: title,
+            };
+            if (folderToken) {
+                data.folder_token = folderToken;
+            }
+            Logger.log(`准备请求API端点: ${endpoint}`);
+            Logger.log(`请求数据: ${JSON.stringify(data, null, 2)}`);
+            const response = await this.request(endpoint, 'POST', data);
+            if (response.code !== 0) {
+                throw new Error(`创建文档失败: ${response.msg}`);
+            }
+            const docInfo = response.data?.document;
+            Logger.log(`文档创建成功，文档ID: ${docInfo?.document_id}`);
+            Logger.log(`文档详情: ${JSON.stringify(docInfo, null, 2)}`);
+            return docInfo;
+        }
+        catch (error) {
+            Logger.error(`创建文档失败:`, error);
+            if (error instanceof AxiosError) {
+                Logger.error(`请求URL: ${error.config?.url}`);
+                Logger.error(`请求方法: ${error.config?.method?.toUpperCase()}`);
+                Logger.error(`状态码: ${error.response?.status}`);
+                if (error.response?.data) {
+                    Logger.error(`错误详情: ${JSON.stringify(error.response.data, null, 2)}`);
+                }
+            }
+            throw error;
+        }
+    }
+    // 获取文档信息
+    async getDocumentInfo(documentId) {
+        try {
+            const docId = this.extractDocIdFromUrl(documentId);
+            if (!docId) {
+                throw new Error(`无效的文档ID: ${documentId}`);
+            }
+            Logger.log(`开始获取文档信息，文档ID: ${docId}`);
+            const endpoint = `/docx/v1/documents/${docId}`;
+            Logger.log(`准备请求API端点: ${endpoint}`);
+            const response = await this.request(endpoint);
+            if (response.code !== 0) {
+                throw new Error(`获取文档信息失败: ${response.msg}`);
+            }
+            const docInfo = response.data?.document;
+            Logger.log(`文档信息获取成功: ${JSON.stringify(docInfo, null, 2)}`);
+            if (!docInfo) {
+                throw new Error(`获取文档信息失败: 返回的文档信息为空`);
+            }
+            return docInfo;
+        }
+        catch (error) {
+            Logger.error(`获取文档信息失败:`, error);
+            throw error;
+        }
+    }
+    // 获取文档纯文本内容
+    async getDocumentContent(documentId, lang = 0) {
+        try {
+            const docId = this.extractDocIdFromUrl(documentId);
+            if (!docId) {
+                throw new Error(`无效的文档ID: ${documentId}`);
+            }
+            Logger.log(`开始获取文档内容，文档ID: ${docId}，语言: ${lang}`);
+            const endpoint = `/docx/v1/documents/${docId}/raw_content?lang=${lang}`;
+            Logger.log(`准备请求API端点: ${endpoint}`);
+            const response = await this.request(endpoint);
+            if (response.code !== 0) {
+                throw new Error(`获取文档内容失败: ${response.msg}`);
+            }
+            Logger.log(`文档内容获取成功，长度: ${response.data?.content?.length || 0}字符`);
+            return response.data?.content || '';
+        }
+        catch (error) {
+            Logger.error(`获取文档内容失败:`, error);
+            throw error;
+        }
+    }
+    // 获取文档块
+    async getDocumentBlocks(documentId, pageSize = 500) {
+        try {
+            const docId = this.extractDocIdFromUrl(documentId);
+            if (!docId) {
+                throw new Error(`无效的文档ID: ${documentId}`);
+            }
+            Logger.log(`开始获取文档块，文档ID: ${docId}，页大小: ${pageSize}`);
+            const endpoint = `/docx/v1/documents/${docId}/blocks?document_revision_id=-1&page_size=${pageSize}`;
+            Logger.log(`准备请求API端点: ${endpoint}`);
+            const response = await this.request(endpoint);
+            if (response.code !== 0) {
+                throw new Error(`获取文档块失败: ${response.msg}`);
+            }
+            const blocks = response.data?.items || [];
+            Logger.log(`文档块获取成功，共 ${blocks.length} 个块`);
+            return blocks;
+        }
+        catch (error) {
+            Logger.error(`获取文档块失败:`, error);
+            throw error;
+        }
+    }
+    // 创建代码块
+    async createCodeBlock(documentId, parentBlockId, code, language = 0, wrap = false, index = 0) {
+        try {
+            const docId = this.extractDocIdFromUrl(documentId);
+            if (!docId) {
+                throw new Error(`无效的文档ID: ${documentId}`);
+            }
+            Logger.log(`开始创建代码块，文档ID: ${docId}，父块ID: ${parentBlockId}，语言: ${language}，自动换行: ${wrap}，插入位置: ${index}`);
+            const blockContent = {
+                block_type: 14, // 14表示代码块
+                code: {
+                    elements: [
+                        {
+                            text_run: {
+                                content: code,
+                                text_element_style: {
+                                    bold: false,
+                                    inline_code: false,
+                                    italic: false,
+                                    strikethrough: false,
+                                    underline: false
+                                }
+                            }
+                        }
+                    ],
+                    style: {
+                        language: language,
+                        wrap: wrap
+                    }
+                }
+            };
+            Logger.log(`代码块内容: ${JSON.stringify(blockContent, null, 2)}`);
+            return await this.createDocumentBlock(documentId, parentBlockId, blockContent, index);
+        }
+        catch (error) {
+            Logger.error(`创建代码块失败:`, error);
+            throw error;
+        }
+    }
+    // 创建文本块
+    async createTextBlock(documentId, parentBlockId, textContents, align = 1, index = 0) {
+        try {
+            const docId = this.extractDocIdFromUrl(documentId);
+            if (!docId) {
+                throw new Error(`无效的文档ID: ${documentId}`);
+            }
+            Logger.log(`开始创建文本块，文档ID: ${docId}，父块ID: ${parentBlockId}，对齐方式: ${align}，插入位置: ${index}`);
+            const blockContent = {
+                block_type: 2, // 2表示文本块
+                text: {
+                    elements: textContents.map(content => ({
+                        text_run: {
+                            content: content.text,
+                            text_element_style: content.style || {}
+                        }
+                    })),
+                    style: {
+                        align: align // 1 居左，2 居中，3 居右
+                    }
+                }
+            };
+            Logger.log(`文本块内容: ${JSON.stringify(blockContent, null, 2)}`);
+            return await this.createDocumentBlock(documentId, parentBlockId, blockContent, index);
+        }
+        catch (error) {
+            Logger.error(`创建文本块失败:`, error);
+            throw error;
+        }
+    }
+    // 创建文档块
+    async createDocumentBlock(documentId, parentBlockId, blockContent, index = 0) {
+        try {
+            const docId = this.extractDocIdFromUrl(documentId);
+            if (!docId) {
+                throw new Error(`无效的文档ID: ${documentId}`);
+            }
+            Logger.log(`开始创建文档块，文档ID: ${docId}，父块ID: ${parentBlockId}，插入位置: ${index}`);
+            const endpoint = `/docx/v1/documents/${docId}/blocks/${parentBlockId}/children?document_revision_id=-1`;
+            Logger.log(`准备请求API端点: ${endpoint}`);
+            const data = {
+                children: [blockContent],
+                index: index
+            };
+            Logger.log(`请求数据: ${JSON.stringify(data, null, 2)}`);
+            const response = await this.request(endpoint, 'POST', data);
+            if (response.code !== 0) {
+                throw new Error(`创建文档块失败: ${response.msg}`);
+            }
+            Logger.log(`文档块创建成功: ${JSON.stringify(response.data, null, 2)}`);
+            return response.data;
+        }
+        catch (error) {
+            Logger.error(`创建文档块失败:`, error);
+            throw error;
+        }
+    }
+    // 创建标题块
+    async createHeadingBlock(documentId, parentBlockId, text, level = 1, index = 0) {
+        try {
+            const docId = this.extractDocIdFromUrl(documentId);
+            if (!docId) {
+                throw new Error(`无效的文档ID: ${documentId}`);
+            }
+            Logger.log(`开始创建标题块，文档ID: ${docId}，父块ID: ${parentBlockId}，标题级别: ${level}，插入位置: ${index}`);
+            // 确保标题级别在有效范围内（1-9）
+            const safeLevel = Math.max(1, Math.min(9, level));
+            // 根据标题级别设置block_type和对应的属性名
+            // 飞书API中，一级标题的block_type为3，二级标题为4，以此类推
+            const blockType = 2 + safeLevel; // 一级标题为3，二级标题为4，以此类推
+            const headingKey = `heading${safeLevel}`; // heading1, heading2, ...
+            // 构建块内容
+            const blockContent = {
+                block_type: blockType
+            };
+            // 设置对应级别的标题属性
+            blockContent[headingKey] = {
+                elements: [
+                    {
+                        text_run: {
+                            content: text,
+                            text_element_style: {}
+                        }
+                    }
+                ],
+                style: {
+                    align: 1,
+                    folded: false
+                }
+            };
+            Logger.log(`标题块内容: ${JSON.stringify(blockContent, null, 2)}`);
+            return await this.createDocumentBlock(documentId, parentBlockId, blockContent, index);
+        }
+        catch (error) {
+            Logger.error(`创建标题块失败:`, error);
+            throw error;
+        }
+    }
+    extractDocIdFromUrl(url) {
+        // 处理飞书文档 URL，提取文档 ID
+        // 支持多种URL格式
+        // 1. 标准文档URL格式: https://xxx.feishu.cn/docs/xxx 或 https://xxx.feishu.cn/docx/xxx
+        const docxMatch = url.match(/\/docx\/(\w+)/); // 匹配 docx 格式
+        const docsMatch = url.match(/\/docs\/(\w+)/); // 匹配 docs 格式
+        // 2. API URL格式: https://open.feishu.cn/open-apis/doc/v2/documents/xxx
+        const apiMatch = url.match(/\/documents\/([\w-]+)/); // 匹配 API URL 格式
+        // 3. 直接使用文档ID
+        const directIdMatch = url.match(/^([\w-]+)$/); // 如果直接传入了文档ID
+        // 按优先级返回匹配结果
+        return docxMatch ? docxMatch[1] :
+            docsMatch ? docsMatch[1] :
+                apiMatch ? apiMatch[1] :
+                    directIdMatch ? directIdMatch[1] : null;
+    }
+}

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "feishu-mcp",
+  "version": "0.0.1",
+  "description": "Model Context Protocol server for Feishu integration",
+  "main": "dist/index.js",
+  "bin": {
+    "feishu-mcp": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc && tsc-alias",
+    "type-check": "tsc --noEmit",
+    "start": "node dist/index.js",
+    "start:cli": "cross-env NODE_ENV=cli node dist/index.js",
+    "start:http": "node dist/index.js",
+    "dev": "cross-env NODE_ENV=development tsx watch src/index.ts",
+    "dev:cli": "cross-env NODE_ENV=development tsx watch src/index.ts --stdio",
+    "lint": "eslint . --ext .ts",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "inspect": "pnpx @modelcontextprotocol/inspector",
+    "prepare": "pnpm run build && chmod +x ./dist/cli.js",
+    "pub:release": "pnpm build && npm publish"
+  },
+  "engines": {
+    "node": "^20.17.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/cso1z/Feishu-MCP.git"
+  },
+  "keywords": [
+    "feishu",
+    "lark",
+    "mcp",
+    "typescript"
+  ],
+  "author": "cso1z",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.6.1",
+    "@types/yargs": "^17.0.33",
+    "axios": "^1.7.9",
+    "cross-env": "^7.0.3",
+    "dotenv": "^16.4.7",
+    "express": "^4.21.2",
+    "remeda": "^2.20.1",
+    "yargs": "^17.7.2",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.0",
+    "@types/jest": "^29.5.11",
+    "@types/node": "^20.17.0",
+    "@typescript-eslint/eslint-plugin": "^8.24.0",
+    "@typescript-eslint/parser": "^8.24.0",
+    "eslint": "^9.20.1",
+    "eslint-config-prettier": "^10.0.1",
+    "jest": "^29.7.0",
+    "prettier": "^3.5.0",
+    "ts-jest": "^29.2.5",
+    "tsc-alias": "^1.8.10",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.3"
+  },
+  "pnpm": {
+    "overrides": {
+      "feishu-mcp": "link:"
+    }
+  }
+}