feishu-mcp 0.0.12 → 0.0.14

package/dist/types/feishuSchema.js

@@ -11,14 +11,27 @@ export const ParentBlockIdSchema = z.string().describe('Parent block ID (require
 // 块ID参数定义
 export const BlockIdSchema = z.string().describe('Block ID (required). The ID of the specific block to get content from. You can obtain block IDs using the get_feishu_document_blocks tool.');
 // 插入位置索引参数定义
-export const IndexSchema = z.number().describe('Insertion position index (required). Specifies where the block should be inserted. Use 0 to insert at the beginning. ' +
+export const IndexSchema = z.number().describe('Insertion position index (required). This index is relative to the children array of the specified parentBlockId block (not the whole document).\n' +
+    'If parentBlockId is the document root (i.e., the document ID), index refers to the position among the document content blocks (excluding the title block itself).\n' +
+    '0 means to insert as the first content block after the title.\n' +
+    'If children is empty or missing, use 0 to insert the first content block.\n' +
+    'For nested blocks, index is relative to the parent block\'s children.\n' +
+    '**index must satisfy 0 ≤ index ≤ parentBlock.children.length, otherwise the API will return an error.**\n' +
+    'Note: The title block itself is not part of the children array and cannot be operated on with index.' +
+    'Specifies where the block should be inserted. Use 0 to insert at the beginning. ' +
     'Use get_feishu_document_blocks tool to understand document structure if unsure. ' +
     'For consecutive insertions, calculate next index as previous index + 1.');
 // 起始插入位置索引参数定义
-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. ' +
+export const StartIndexSchema = z.number().describe('Starting insertion position index (required). This index is relative to the children array of the specified parentBlockId block.\n' +
+    'For the document root, this means the content blocks after the title. For other blocks, it means the sub-blocks under that block.\n' +
+    'The index does not include the title block itself.' +
+    'Specifies where the first block should be inserted or deleted. 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). ' +
+export const EndIndexSchema = z.number().describe('Ending position index (required). This index is relative to the children array of the specified parentBlockId block.\n' +
+    'For the document root, this means the content blocks after the title. For other blocks, it means the sub-blocks under that block.\n' +
+    'The index does not include the title block itself.' +
+    '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.');
 // 文本对齐方式参数定义
@@ -41,11 +54,17 @@ export const TextStylePropertiesSchema = {
 };
 // 文本样式对象定义
 export const TextStyleSchema = z.object(TextStylePropertiesSchema).optional().describe('Text style settings. Explicitly set style properties instead of relying on Markdown syntax conversion.');
-// 文本内容单元定义
-export const TextElementSchema = z.object({
-    text: z.string().describe('Text content. Provide plain text without markdown syntax; use style object for formatting.'),
-    style: TextStyleSchema
-});
+// 文本内容单元定义 - 支持普通文本和公式元素
+export const TextElementSchema = z.union([
+    z.object({
+        text: z.string().describe('Text content. Provide plain text without markdown syntax; use style object for formatting.'),
+        style: TextStyleSchema
+    }).describe('Regular text element with optional styling.'),
+    z.object({
+        equation: z.string().describe('Mathematical equation content. The formula or expression to display. Format: LaTeX.'),
+        style: TextStyleSchema
+    }).describe('Mathematical equation element with optional styling.')
+]);
 // 文本内容数组定义
 export const TextElementsArraySchema = z.array(TextElementSchema).describe('Array of text content objects. A block can contain multiple text segments with different styles. Example: [{text:"Hello",style:{bold:true}},{text:" World",style:{italic:true}}]');
 // 代码块语言参数定义
@@ -62,10 +81,7 @@ export const CodeLanguageSchema = z.number().optional().default(1).describe("Pro
 export const CodeWrapSchema = z.boolean().optional().default(false).describe('Whether to enable automatic line wrapping. Default is false.');
 // 文本样式段落定义 - 用于批量创建块工具
 export const TextStyleBlockSchema = z.object({
-    textStyles: z.array(z.object({
-        text: z.string().describe('Text segment content. The actual text to display.'),
-        style: TextStyleSchema
-    })).describe('Array of text content objects with styles. A block can contain multiple text segments with different styles. Example: [{text:"Hello",style:{bold:true}},{text:" World",style:{italic:true}}]'),
+    textStyles: z.array(TextElementSchema).describe('Array of text content objects with styles. A block can contain multiple text segments with different styles, including both regular text and equations. Example: [{text:"Hello",style:{bold:true}},{equation:"1+2=3",style:{}}]'),
     align: z.number().optional().default(1).describe('Text alignment: 1 for left (default), 2 for center, 3 for right.'),
 });
 // 代码块内容定义 - 用于批量创建块工具
@@ -87,8 +103,15 @@ export const ListBlockSchema = z.object({
     align: AlignSchemaWithValidation,
 });
 // 块类型枚举 - 用于批量创建块工具
-export const BlockTypeEnum = z.string().describe("Block type (required). Supports: 'text', 'code', 'heading', 'list', as well as 'heading1' through 'heading9'. " +
-    "For headings, we recommend using 'heading' with level property, but 'heading1'-'heading9' are also supported.");
+export const BlockTypeEnum = z.string().describe("Block type (required). Supports: 'text', 'code', 'heading', 'list', 'image', 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 text blocks, you can include both regular text and equation elements in the same block.");
+// 图片块内容定义 - 用于批量创建块工具
+export const ImageBlockSchema = z.object({
+    width: z.number().optional().describe('Image width in pixels (optional). If not provided, default width will be used.'),
+    height: z.number().optional().describe('Image height in pixels (optional). If not provided, default height will be used.'),
+});
 // 块配置定义 - 用于批量创建块工具
 export const BlockConfigSchema = z.object({
     blockType: BlockTypeEnum,
@@ -97,6 +120,7 @@ export const BlockConfigSchema = z.object({
         z.object({ code: CodeBlockSchema }).describe("Code block options. Used when blockType is 'code'."),
         z.object({ heading: HeadingBlockSchema }).describe("Heading block options. Used with both 'heading' and 'headingN' formats."),
         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.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.'),
 });
@@ -112,11 +136,23 @@ export const FolderTokenSchema = z.string().describe('Folder token (required). T
     '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.');
 // 搜索关键字参数定义
 export const SearchKeySchema = z.string().describe('Search keyword (required). The keyword to search for in documents.');
+// 图片路径或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' +
+    '2. HTTP/HTTPS URL: e.g., "https://example.com/image.png"\n' +
+    'The tool will automatically detect the format and handle accordingly.');
+// 图片文件名参数定义
+export const ImageFileNameSchema = z.string().optional().describe('Image file name (optional). If not provided, a default name will be generated based on the source. ' +
+    'Should include the file extension, e.g., "image.png" or "photo.jpg".');
+// 图片宽度参数定义
+export const ImageWidthSchema = z.number().optional().describe('Image width in pixels (optional). If not provided, the original image width will be used.');
+// 图片高度参数定义
+export const ImageHeightSchema = z.number().optional().describe('Image height in pixels (optional). If not provided, the original image height will be used.');
+// 画板ID参数定义
+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"');
+// 文档标题参数定义
+export const DocumentTitleSchema = z.string().describe('Document title (required). This will be displayed in the Feishu document list and document header.');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "feishu-mcp",
-  "version": "0.0.12",
+  "version": "0.0.14",
   "description": "Model Context Protocol server for Feishu integration",
   "type": "module",
   "main": "dist/index.js",
@@ -41,12 +41,13 @@
   "author": "cso1z",
   "license": "MIT",
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.6.1",
+    "@modelcontextprotocol/sdk": "^1.13.1",
     "@types/yargs": "^17.0.33",
     "axios": "^1.7.9",
     "cross-env": "^7.0.3",
     "dotenv": "^16.4.7",
     "express": "^4.21.2",
+    "form-data": "^4.0.3",
     "remeda": "^2.20.1",
     "yargs": "^17.7.2",
     "zod": "^3.24.2"

package/README.en.md

@@ -1,201 +0,0 @@
-# Feishu MCP Server
-
-Provides access to Feishu (Lark) documents for [Cursor](https://cursor.sh/), [Windsurf](https://codeium.com/windsurf), [Cline](https://cline.bot/), and other AI-driven coding tools, implemented based on the [Model Context Protocol](https://modelcontextprotocol.io/introduction) server.
-
-When Cursor can access Feishu document data, it can understand and process document content more accurately, making it more efficient than other methods (such as copying and pasting text).
-
-## Core Features
-
-### Document Management
-- **Create Feishu Documents**: Support for creating new Feishu documents in specified folders
-- **Folder Management**:
-  - Get root folder information
-  - View folder contents and file lists
-  - Create new folders
-
-### Document Content Operations
-- **Get Document Information**:
-  - Get basic document information (title, version, etc.)
-  - Get document block structure and hierarchy
-  - Get detailed content of specific blocks
-- **Get Document Plain Text Content**: Support for extracting complete plain text content from documents for analysis and processing
-- **Edit Document Content**:
-  - **Text Block Operations**:
-    - Create and update text blocks with rich styles (bold, italic, underline, strikethrough, inline code)
-    - Support for text color settings (gray, brown, orange, yellow, green, blue, purple)
-    - Support for text alignment adjustment (left-aligned, centered, right-aligned)
-  - **Heading Block Operations**: Create headings from level one to level nine
-  - **Code Block Operations**:
-    - Create code blocks for multiple programming languages
-    - Support for code syntax highlighting
-    - Support for automatic line wrapping settings
-  - **List Operations**:
-    - Create ordered lists (numbered lists)
-    - Create unordered lists (bullet point lists)
-  - **Block Management Operations**:
-    - Batch content creation: Support for creating multiple different types of content blocks in a single operation
-    - Delete document blocks: Support for deleting one or more consecutive document blocks
-- **Wiki Document Support**:
-  - Convert Feishu Wiki links to compatible document IDs for use with other document operation tools
-- **Image Resource Processing**:
-  - Download images from Feishu using media IDs
-
-### Planned Features
-- **Advanced Content Insertion**:
-  - Table insertion: Support for row and column structured data
-  - Insert charts: Support for various data visualization charts
-  - Insert flowcharts: Support for flowcharts and mind maps
-  - Insert formulas: Support for mathematical formulas and scientific symbols
-- Recognition and parsing of charts and flowcharts
-
-Quick start, see the [Configuration](#configuration) section for details:
-
-```bash
-npx feishu-mcp --feishu-app-id=<YOUR_FEISHU_APP_ID> --feishu-app-secret=<YOUR_FEISHU_APP_SECRET>
-```
-
-## How It Works
-
-1. Open the editor in Cursor's Agent mode.
-2. Paste a Feishu document link.
-3. Ask Cursor to perform operations based on the Feishu document—for example, analyze document content or create related code.
-4. Cursor will retrieve relevant metadata from Feishu and use it to assist in writing code.
-
-This MCP server is designed specifically for Cursor. Before responding with content from the [Feishu API](https://open.feishu.cn/document/home/introduction-to-lark-open-platform/overview), it simplifies and transforms the responses, ensuring that only the most relevant document information is provided to the model.
-
-## Installation
-
-### Quickly Run the Server Using NPM
-
-You can quickly run the server using NPM without installing or building the repository:
-
-```bash
-npx feishu-mcp --feishu-app-id=<YOUR_FEISHU_APP_ID> --feishu-app-secret=<YOUR_FEISHU_APP_SECRET>
-
-# or
-pnpx feishu-mcp --feishu-app-id=<YOUR_FEISHU_APP_ID> --feishu-app-secret=<YOUR_FEISHU_APP_SECRET>
-
-# or
-yarn dlx feishu-mcp --feishu-app-id=<YOUR_FEISHU_APP_ID> --feishu-app-secret=<YOUR_FEISHU_APP_SECRET>
-
-# or
-bunx feishu-mcp --feishu-app-id=<YOUR_FEISHU_APP_ID> --feishu-app-secret=<YOUR_FEISHU_APP_SECRET>
-```
-
-**Published to the Smithery platform, available at: https://smithery.ai/server/@cso1z/feishu-mcp**
-
-Instructions on how to create a Feishu application and obtain application credentials can be found in the [official tutorial](https://open.feishu.cn/document/home/develop-a-bot-in-5-minutes/create-an-app).
-
-**Detailed Feishu application configuration steps**: For detailed guidance on registering a Feishu application, configuring permissions, and adding document access permissions, please refer to [Step-by-step tutorial FEISHU_CONFIG.md](FEISHU_CONFIG.md).
-
-### JSON Configuration for Tools Using Configuration Files
-
-Many tools such as Windsurf, Cline, and [Claude Desktop](https://claude.ai/download) use configuration files to start servers.
-
-The `feishu-mcp` server can be configured by adding the following to the configuration file:
-
-```json
-{
-  "mcpServers": {
-    "feishu-mcp": {
-      "command": "npx",
-      "args": ["-y", "feishu-mcp", "--stdio"],
-      "env": {
-        "FEISHU_APP_ID": "<YOUR_FEISHU_APP_ID>",
-        "FEISHU_APP_SECRET": "<YOUR_FEISHU_APP_SECRET>"
-      }
-    }
-  }
-}
-```
-
-### Run the Server from Local Source Code
-
-1. Clone the repository
-2. Install dependencies using `pnpm install`
-3. Copy `.env.example` to `.env` and fill in your [Feishu application credentials](https://open.feishu.cn/document/home/develop-a-bot-in-5-minutes/create-an-app).
-4. Run the server using `pnpm run dev`, with any flags from the [Command Line Arguments](#command-line-arguments) section.
-
-### Run the Server Using Docker
-
-You can use Docker to run the server, which avoids installing Node.js and other dependencies locally:
-
-1. Build the Docker image:
-```bash
-docker build -t feishu-mcp .
-```
-
-2. Run the Docker container:
-```bash
-docker run -p 3333:3333 --env FEISHU_APP_ID=<YOUR_FEISHU_APP_ID> --env FEISHU_APP_SECRET=<YOUR_FEISHU_APP_SECRET> feishu-mcp
-```
-
-Alternatively, you can use docker-compose:
-
-1. Edit the `.env` file and add your Feishu application credentials:
-```
-FEISHU_APP_ID=<YOUR_FEISHU_APP_ID>
-FEISHU_APP_SECRET=<YOUR_FEISHU_APP_SECRET>
-```
-
-2. Run docker-compose:
-```bash
-docker-compose up -d
-```
-
-This will start the server in the background and expose it on port 3333.
-
-## Configuration
-
-The server can be configured using environment variables (via the `.env` file) or command line arguments. Command line arguments take precedence over environment variables.
-
-### Environment Variables
-
-- `FEISHU_APP_ID`: Your [Feishu application ID](https://open.feishu.cn/document/home/develop-a-bot-in-5-minutes/create-an-app) (required)
-- `FEISHU_APP_SECRET`: Your [Feishu application secret](https://open.feishu.cn/document/home/develop-a-bot-in-5-minutes/create-an-app) (required)
-- `PORT`: The port to run the server on (default: 3333)
-
-### Command Line Arguments
-
-- `--version`: Show version number
-- `--feishu-app-id`: Your Feishu application ID
-- `--feishu-app-secret`: Your Feishu application secret
-- `--port`: The port to run the server on
-- `--stdio`: Run the server in command mode instead of the default HTTP/SSE
-- `--help`: Show help menu
-
-## Connecting to Cursor
-
-### Configuring Cursor
-
-1. Open Cursor settings
-2. Navigate to `Settings > AI > MCP Servers`
-3. Add a new server with the URL `http://localhost:3333` (or your configured port)
-4. Click "Verify Connection" to ensure the connection is successful
-
-## Usage
-
-1. In Cursor, open the AI panel (default shortcut `Cmd+K` or `Ctrl+K`)
-2. If you need to create a new Feishu document, you should explicitly specify a folderToken, which you can find by opening a Feishu document directory like: `https://vq5xxxxx7bc.feishu.cn/drive/folder/FPKvfjdxxxxx706RnOc`
-3. If you need to modify Feishu document content, you should explicitly provide the Feishu document link, for example: `https://vq5ixxxx7bc.feishu.cn/docx/J6T0d6exxxxxxxDdc1zqwnph`
-4. Ask questions about the document or request operations based on the document content
-5. Creating and editing documents requires permissions, and you can test your account on the Feishu open platform: `https://open.feishu.cn/api-explorer/cli_a75a8ca0ac79100c?apiName=tenant_access_token_internal&from=op_doc&project=auth&resource=auth&version=v3`
-
-## Document Permissions and Troubleshooting
-
-### Permission Types
-Permissions are divided into two types: robot permissions and document access permissions.
-
-### Permission Verification and Troubleshooting
-1. Get token: [https://open.feishu.cn/api-explorer/cli_a7582508c93ad00d?apiName=tenant_access_token_internal&project=auth&resource=auth&version=v3](https://open.feishu.cn/api-explorer/cli_a7582508c93ad00d?apiName=tenant_access_token_internal&project=auth&resource=auth&version=v3)
-2. Using the token obtained in step 1, verify whether you have permission to access the document: [https://open.feishu.cn/api-explorer/cli_a7582508c93ad00d?apiName=get&project=docx&resource=document&version=v1](https://open.feishu.cn/api-explorer/cli_a7582508c93ad00d?apiName=get&project=docx&resource=document&version=v1)
-
-### Troubleshooting Method
-Test permissions normally on the Feishu development platform (when debugging on the open platform, there will be sufficient prompt information and guidance in case of failure).
-
-### Document Authorization
-If you encounter permission issues, please refer to [Cloud Document FAQ](https://open.feishu.cn/document/ukTMukTMukTM/uczNzUjL3czM14yN3MTN), [Knowledge Base FAQ](https://open.feishu.cn/document/server-docs/docs/wiki-v2/wiki-qa), especially focusing on how to grant document permissions to applications or users.
-
-## License
-
-MIT 

package/dist/config.js

@@ -1,104 +0,0 @@
-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;
-}