feishu-mcp 0.0.8 → 0.0.9-alpha

package/LICENSE

@@ -1,21 +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.
+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.en.md

@@ -0,0 +1,201 @@
+# 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/README.md

@@ -1,160 +1,164 @@
-# 飞书 MCP 服务器
-
-为 [Cursor](https://cursor.sh/)、[Windsurf](https://codeium.com/windsurf)、[Cline](https://cline.bot/) 和其他 AI 驱动的编码工具提供访问飞书文档的能力，基于 [Model Context Protocol](https://modelcontextprotocol.io/introduction) 服务器实现。
-
-当 Cursor 能够访问飞书文档数据时，它可以更准确地理解和处理文档内容，比其他方法（如复制粘贴文本）更加高效。
-
-## 核心功能
-
-### 文档管理
-- **创建飞书文档**：支持在指定文件夹中创建新的飞书文档
-
-### 文档内容操作
-- **获取文档信息**：
-  - 获取文档基本信息（标题、版本等）
-  - 获取文档区块结构和层级
-  - 获取特定区块的详细内容
-- **获取文档纯文本内容**：支持提取文档的完整纯文本内容，便于分析和处理
-- **编辑文档内容**：
-  - **文本块操作**：
-    - 创建和更新带有丰富样式的文本块（粗体、斜体、下划线、删除线、行内代码）
-    - 支持文本颜色设置（灰色、棕色、橙色、黄色、绿色、蓝色、紫色）
-    - 支持文本对齐方式调整（左对齐、居中、右对齐）
-  - **标题块操作**：创建从一级到九级的不同级别标题
-  - **代码块操作**：
-    - 创建多种编程语言的代码块
-    - 支持代码语法高亮
-    - 支持自动换行设置
-  - **列表操作**：
-    - 创建有序列表（编号列表）
-    - 创建无序列表（项目符号列表）
-  - **批量内容创建**：支持在单次操作中创建多个不同类型的内容块
-
-### 计划中的功能
-- **高级内容插入**：
-  - 表格插入：支持行列结构化数据
-  - 插入图表：支持各类数据可视化图表
-  - 插入流程图：支持流程图和思维导图
-  - 插入公式：支持数学公式和科学符号
-- 图表、流程图的内容识别和解析
-
-快速开始，详见[配置](#配置)部分：
-
-```bash
-npx feishu-mcp --feishu-app-id=<你的飞书应用ID> --feishu-app-secret=<你的飞书应用密钥>
-```
-
-## 工作原理
-
-1. 在 Cursor 的 Agent 模式下打开编辑器。
-2. 粘贴飞书文档的链接。
-3. 要求 Cursor 基于飞书文档执行操作——例如，分析文档内容或创建相关代码。
-4. Cursor 将从飞书获取相关元数据并使用它来辅助编写代码。
-
-这个 MCP 服务器专为 Cursor 设计。在响应来自[飞书 API](https://open.feishu.cn/document/home/introduction-to-lark-open-platform/overview) 的内容之前，它会简化和转换响应，确保只向模型提供最相关的文档信息。
-## 安装
-
-### 使用 NPM 快速运行服务器
-
-你可以使用 NPM 快速运行服务器，无需安装或构建仓库：
-
-```bash
-npx feishu-mcp --feishu-app-id=<你的飞书应用ID> --feishu-app-secret=<你的飞书应用密钥>
-
-# 或
-pnpx feishu-mcp --feishu-app-id=<你的飞书应用ID> --feishu-app-secret=<你的飞书应用密钥>
-
-# 或
-yarn dlx feishu-mcp --feishu-app-id=<你的飞书应用ID> --feishu-app-secret=<你的飞书应用密钥>
-
-# 或
-bunx feishu-mcp --feishu-app-id=<你的飞书应用ID> --feishu-app-secret=<你的飞书应用密钥>
-```
-
-**已发布到smithery平台，可访问:https://smithery.ai/server/@cso1z/feishu-mcp**
-
-
-关于如何创建飞书应用和获取应用凭证的说明可以在[这里](https://open.feishu.cn/document/home/develop-a-bot-in-5-minutes/create-an-app)找到。
-
-### 使用配置文件的工具的 JSON 配置
-
-许多工具如 Windsurf、Cline 和 [Claude Desktop](https://claude.ai/download) 使用配置文件来启动服务器。
-
-`feishu-mcp` 服务器可以通过在配置文件中添加以下内容来配置：
-
-```json
-{
-  "mcpServers": {
-    "feishu-mcp": {
-      "command": "npx",
-      "args": ["-y", "feishu-mcp", "--stdio"],
-      "env": {
-        "FEISHU_APP_ID": "<你的飞书应用ID>",
-        "FEISHU_APP_SECRET": "<你的飞书应用密钥>"
-      }
-    }
-  }
-}
-```
-
-### 从本地源代码运行服务器
-
-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`
-
-## 文档权限与故障排查
-
-### 权限类型
-权限分为两种：机器人权限、文档访问权限
-
-### 权限验证与排查
-1. 获取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. 使用第1步获取的token，验证是否有权限访问该文档：[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)
-
-### 排查方法
-在飞书开发平台测试权限正常（在开放平台调试，失败时会有充足提示信息和指导）
-
-### 文档授权
-如遇到权限问题，请参考[云文档常见问题](https://open.feishu.cn/document/ukTMukTMukTM/uczNzUjL3czM14yN3MTN)、[知识库常见问题](https://open.feishu.cn/document/server-docs/docs/wiki-v2/wiki-qa)，特别关注如何为应用或用户开通文档权限。
-
-## 许可证
-
-MIT
+# 飞书 MCP 服务器
+
+为 [Cursor](https://cursor.sh/)、[Windsurf](https://codeium.com/windsurf)、[Cline](https://cline.bot/) 和其他 AI 驱动的编码工具提供访问飞书文档的能力，基于 [Model Context Protocol](https://modelcontextprotocol.io/introduction) 服务器实现。
+
+当 Cursor 能够访问飞书文档数据时，它可以更准确地理解和处理文档内容，比其他方法（如复制粘贴文本）更加高效。
+
+## 核心功能
+
+### 文档管理
+- **创建飞书文档**：支持在指定文件夹中创建新的飞书文档
+
+### 文档内容操作
+- **获取文档信息**：
+  - 获取文档基本信息（标题、版本等）
+  - 获取文档区块结构和层级
+  - 获取特定区块的详细内容
+- **获取文档纯文本内容**：支持提取文档的完整纯文本内容，便于分析和处理
+- **编辑文档内容**：
+  - **文本块操作**：
+    - 创建和更新带有丰富样式的文本块（粗体、斜体、下划线、删除线、行内代码）
+    - 支持文本颜色设置（灰色、棕色、橙色、黄色、绿色、蓝色、紫色）
+    - 支持文本对齐方式调整（左对齐、居中、右对齐）
+  - **标题块操作**：创建从一级到九级的不同级别标题
+  - **代码块操作**：
+    - 创建多种编程语言的代码块
+    - 支持代码语法高亮
+    - 支持自动换行设置
+  - **列表操作**：
+    - 创建有序列表（编号列表）
+    - 创建无序列表（项目符号列表）
+  - **批量内容创建**：支持在单次操作中创建多个不同类型的内容块
+
+### 计划中的功能
+- **高级内容插入**：
+  - 表格插入：支持行列结构化数据
+  - 插入图表：支持各类数据可视化图表
+  - 插入流程图：支持流程图和思维导图
+  - 插入公式：支持数学公式和科学符号
+- 图表、流程图的内容识别和解析
+
+快速开始，详见[配置](#配置)部分：
+
+```bash
+npx feishu-mcp --feishu-app-id=<你的飞书应用ID> --feishu-app-secret=<你的飞书应用密钥>
+```
+
+## 工作原理
+
+1. 在 Cursor 的 Agent 模式下打开编辑器。
+2. 粘贴飞书文档的链接。
+3. 要求 Cursor 基于飞书文档执行操作——例如，分析文档内容或创建相关代码。
+4. Cursor 将从飞书获取相关元数据并使用它来辅助编写代码。
+
+这个 MCP 服务器专为 Cursor 设计。在响应来自[飞书 API](https://open.feishu.cn/document/home/introduction-to-lark-open-platform/overview) 的内容之前，它会简化和转换响应，确保只向模型提供最相关的文档信息。
+## 安装
+
+### 使用 NPM 快速运行服务器
+
+你可以使用 NPM 快速运行服务器，无需安装或构建仓库：
+
+```bash
+npx feishu-mcp --feishu-app-id=<你的飞书应用ID> --feishu-app-secret=<你的飞书应用密钥>
+
+# 或
+pnpx feishu-mcp --feishu-app-id=<你的飞书应用ID> --feishu-app-secret=<你的飞书应用密钥>
+
+# 或
+yarn dlx feishu-mcp --feishu-app-id=<你的飞书应用ID> --feishu-app-secret=<你的飞书应用密钥>
+
+# 或
+bunx feishu-mcp --feishu-app-id=<你的飞书应用ID> --feishu-app-secret=<你的飞书应用密钥>
+```
+
+**已发布到smithery平台，可访问:https://smithery.ai/server/@cso1z/feishu-mcp**
+
+
+关于如何创建飞书应用和获取应用凭证的说明可以在[官方教程](https://open.feishu.cn/document/home/develop-a-bot-in-5-minutes/create-an-app)找到。
+
+
+**详细的飞书应用配置步骤**：有关注册飞书应用、配置权限、添加文档访问权限的详细指南，请参阅 [手把手教程 FEISHU_CONFIG.md](FEISHU_CONFIG.md)。
+
+
+### 使用配置文件的工具的 JSON 配置
+
+许多工具如 Windsurf、Cline 和 [Claude Desktop](https://claude.ai/download) 使用配置文件来启动服务器。
+
+`feishu-mcp` 服务器可以通过在配置文件中添加以下内容来配置：
+
+```json
+{
+  "mcpServers": {
+    "feishu-mcp": {
+      "command": "npx",
+      "args": ["-y", "feishu-mcp", "--stdio"],
+      "env": {
+        "FEISHU_APP_ID": "<你的飞书应用ID>",
+        "FEISHU_APP_SECRET": "<你的飞书应用密钥>"
+      }
+    }
+  }
+}
+```
+
+### 从本地源代码运行服务器
+
+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`
+
+## 文档权限与故障排查
+
+### 权限类型
+权限分为两种：机器人权限、文档访问权限
+
+### 权限验证与排查
+1. 获取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. 使用第1步获取的token，验证是否有权限访问该文档：[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)
+
+### 排查方法
+在飞书开发平台测试权限正常（在开放平台调试，失败时会有充足提示信息和指导）
+
+### 文档授权
+如遇到权限问题，请参考[云文档常见问题](https://open.feishu.cn/document/ukTMukTMukTM/uczNzUjL3czM14yN3MTN)、[知识库常见问题](https://open.feishu.cn/document/server-docs/docs/wiki-v2/wiki-qa)，特别关注如何为应用或用户开通文档权限。
+
+## 许可证
+
+MIT