@danyow/lark-mcp 0.5.1

package/CHANGELOG.md

@@ -0,0 +1,62 @@
+# 0.5.1
+- Fix: 修复login再次登录的时候没有正确唤起授权
+
+- Fix: Resolved the issue where the authorization process was not properly triggered during re-login.
+
+# 0.5.0
+- Feat: 使用Login登录会自动用浏览器打开登录链接，且login不在会判断是否已经登录，再次登录会直接用新的token覆盖旧的token
+- Fix: SSE/Streamable 模式下未开启oauth错误需要鉴权流程的问题
+- Chore：优化鉴权失败的文案，和 keytar 不可用时的文案
+- Chore: 同步最新Open API, 移除了Helpdesk部分不可用的API
+
+- Feat: Using Login to log in will automatically open the login link in the browser, and if login is not present, it will check whether you have already logged in. Logging in again will directly overwrite the old token with a new one.
+- Fix: The issue where the unopened oauth error in SSE/Streamable mode requires an authentication process.
+- Chore: Optimize the copy for authentication failure and the copy when keytar is unavailable.
+- Chore: Sync the latest Open API.
+
+# 0.4.1
+Fix: 开放平台开发文档检索 MCP 错误需要鉴权流程的问题
+Fix: Fixed authentication process issue in Open Platform Development Documentation Retrieval MCP 
+
+# 0.4.0
+Feat: 新增 StreamableHttp 的传输模式
+Feat: StreamableHttp/SSE 支持 [MCP Auth](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization)
+Feat: Stdio（本地） 模式支持 login 和 logout 命令登录登出和自动使用 refresh_token 刷新
+Fix: 修复 TokenMode=Auto 模式下没有设置UserAccessToken且CallTool传递参数useUAT=true依然使用应用身份
+Bump： 升级 @modelcontextprotocol/sdk 到 1.12.1
+BREAK: 由于升级了 @modelcontextprotocol/sdk，最低兼容 Node 版本调整为 Node 20
+
+Feat: Added StreamableHttp transport mode
+Feat: StreamableHttp/SSE supports [MCP Auth](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization)
+Feat: Stdio (local) mode supports login and logout commands for authentication and automatic refresh_token renewal
+Fix: Fixed issue where TokenMode=Auto would still use app identity when UserAccessToken is not set but CallTool parameter useUAT=true
+Bump: Upgraded @modelcontextprotocol/sdk to 1.12.1
+BREAK: Due to @modelcontextprotocol/sdk upgrade, minimum compatible Node version is now Node 20
+
+
+# 0.3.1
+Fix: 修复使用 configFile 配置 mode 参数不生效的问题
+Fix: 修复由于使用了z.record(z.any())类型的字段导致直接传给豆包模型无法使用的问题
+Feat: 新增 preset.light 预设
+
+Fix: Fix the problem that the mode parameter configured by configFile does not take effect
+Fix: Fix the problem that the z.record(z.any()) type field is passed directly to the doubao model and cannot be used
+Feat: Add preset.light preset
+
+# 0.3.0
+
+New: 开放平台开发文档检索 MCP，旨在帮助用户输入自身诉求后迅速检索到自己需要的开发文档，帮助开发者在AI IDE中编写与飞书集成的代码
+New: 新增--token-mode，现在可以在启动的时候指定调用API的token类型，支持auto/tenant_access_token/user_access_token
+New: -t 支持配置 preset.default preset.im.default preset.bitable.default preset.doc.default 等默认预设
+Bump： 升级 @modelcontextprotocol/sdk 到 1.11.0
+
+New：Retrieval of Open Platform Development Documents in MCP aims to enable users to quickly find the development documents they need after inputting their own requirements, and assist developers in writing code integrated with Feishu in the AI IDE.
+New: Added --token-mode, now you can specify the API token type when starting, supporting auto/tenant_access_token/user_access_token
+New: -t supports configuring preset.default preset.im.default preset.bitable.default preset.doc.default etc.
+Bump: Upgraded @modelcontextprotocol/sdk to 1.11.0
+
+# 0.2.0
+
+飞书/Lark OpenAPI MCP 工具，可以帮助你快速开始使用MCP协议连接飞书/Lark，实现 Agent 与飞书/Lark平台的高效协作
+
+Feishu/Lark OpenAPI MCP tool helps you quickly start using the MCP protocol to connect with Feishu/Lark, enabling efficient collaboration between Agent and the Feishu/Lark platform

package/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2025 Lark Technologies Pte. Ltd.
+
+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,215 @@
+# Feishu/Lark OpenAPI MCP
+
+[![npm version](https://img.shields.io/npm/v/@larksuiteoapi/lark-mcp.svg)](https://www.npmjs.com/package/@larksuiteoapi/lark-mcp)
+[![npm downloads](https://img.shields.io/npm/dm/@larksuiteoapi/lark-mcp.svg)](https://www.npmjs.com/package/@larksuiteoapi/lark-mcp)
+[![Node.js Version](https://img.shields.io/node/v/@larksuiteoapi/lark-mcp.svg)](https://nodejs.org/)
+
+English | [中文](./README_ZH.md)
+
+[Developer Documentation Retrieval MCP](./docs/recall-mcp/README.md)
+
+[Official Document](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/mcp_integration/mcp_introduction)
+
+[Trouble Shooting](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/mcp_integration/use_cases)
+
+> **⚠️ Beta Version Notice**: This tool is currently in Beta stage. Features and APIs may change, so please stay updated with version releases.
+
+This is the Feishu/Lark official OpenAPI MCP (Model Context Protocol) tool designed to help users quickly connect to the Feishu/Lark platform and enable efficient collaboration between AI Agents and Feishu/Lark. The tool encapsulates Feishu/Lark Open Platform API interfaces as MCP tools, allowing AI assistants to directly call these interfaces and implement various automation scenarios such as document processing, conversation management, calendar scheduling, and more.
+
+## Preparation
+
+### Creating a Feishu/Lark Application
+
+Before using the lark-mcp tool, you need to create a Feishu/Lark application:
+
+1. Visit the [Feishu Open Platform](https://open.feishu.cn/) or [Lark Open Platform](https://open.larksuite.com/) and log in
+2. Click "Console" and create a new application
+3. Obtain the App ID and App Secret, which will be used for API authentication
+4. Add the necessary permissions for your application based on your usage scenario
+5. If you need to call APIs as a user, set the OAuth 2.0 redirect URL to http://localhost:3000/callback
+
+For detailed application creation and configuration guidelines, please refer to the [Feishu Open Platform Documentation - Creating an Application](https://open.feishu.cn/document/home/introduction-to-custom-app-development/self-built-application-development-process#a0a7f6b0).
+
+### Installing Node.js
+
+Before using the lark-mcp tool, you need to install the Node.js environment.
+
+**Using the Official Installer (Recommended)**:
+
+1. Visit the [Node.js website](https://nodejs.org/)
+2. Download and install the LTS version
+3. After installation, verify in the terminal:
+
+```bash
+node -v
+npm -v
+```
+
+## Quick Start
+
+### Using with Trae/Cursor/Claude
+
+To integrate Feishu/Lark functionality in AI tools like Trae, Cursor or Claude, install using the button below.
+
+[![Install MCP Server](https://cursor.com/deeplink/mcp-install-light.svg)](https://cursor.com/install-mcp?name=lark-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBsYXJrc3VpdGVvYXBpL2xhcmstbWNwIiwibWNwIiwiLWEiLCJ5b3VyX2FwcF9pZCIsIi1zIiwieW91cl9hcHBfc2VjcmV0Il19)
+
+[![Install MCP Server](./assets/trae-cn.svg)](trae-cn://trae.ai-ide/mcp-import?source=lark&type=stdio&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBsYXJrc3VpdGVvYXBpL2xhcmstbWNwIiwibWNwIiwiLWEiLCJ5b3VyX2FwcF9pZCIsIi1zIiwieW91cl9hcHBfc2VjcmV0Il19)  [![Install MCP Server](./assets/trae.svg)](trae://trae.ai-ide/mcp-import?source=lark&type=stdio&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBsYXJrc3VpdGVvYXBpL2xhcmstbWNwIiwibWNwIiwiLWEiLCJ5b3VyX2FwcF9pZCIsIi1zIiwieW91cl9hcHBfc2VjcmV0Il19)
+
+or add the following to your configuration file:
+
+```json
+{
+  "mcpServers": {
+    "lark-mcp": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@larksuiteoapi/lark-mcp",
+        "mcp",
+        "-a",
+        "<your_app_id>",
+        "-s",
+        "<your_app_secret>"
+      ]
+    }
+  }
+}
+```
+
+If you need to access APIs with **user identity**, you need to login first using the login command in the terminal. Note that you need to configure the application's redirect URL in the developer console first, default is http://localhost:3000/callback
+
+```bash
+
+# Login and get user access token
+npx -y @larksuiteoapi/lark-mcp login -a cli_xxxx -s yyyyy
+   
+# Or optionally, login with specific OAuth scope - if not specified, all permissions will be authorized by default
+npx -y @larksuiteoapi/lark-mcp login -a cli_xxxx -s yyyyy --scope offline_access docx:document
+
+```
+
+Then add the following to your configuration file:
+
+```json
+{
+  "mcpServers": {
+    "lark-mcp": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@larksuiteoapi/lark-mcp",
+        "mcp",
+        "-a",
+        "<your_app_id>",
+        "-s",
+        "<your_app_secret>",
+        "--oauth",
+        "--token-mode", "user_access_token"
+      ]
+    }
+  }
+}
+```
+
+Note: When enabling `--oauth`, it's recommended to explicitly set `--token-mode` to `user_access_token`, which means calling APIs with user access tokens, suitable for accessing user resources or scenarios requiring user authorization (such as reading personal documents, sending IM messages). If you keep the default `auto`, some APIs AI may fallback to `tenant_access_token`, which could result in insufficient permissions or inability to access user private data.
+
+### Domain Configuration
+
+Based on your usage scenario, lark-mcp supports configuring different domain environments:
+
+**Feishu (China Version)**:
+- Default uses `https://open.feishu.cn` domain
+- Suitable for users in China
+
+**Lark (International Version)**:
+- Uses `https://open.larksuite.com` domain
+- Suitable for overseas users or international version of Lark
+
+To switch to the international version of Lark, add the `--domain` parameter in your configuration:
+
+```json
+{
+  "mcpServers": {
+    "lark-mcp": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@larksuiteoapi/lark-mcp",
+        "mcp",
+        "-a",
+        "<your_app_id>",
+        "-s",
+        "<your_app_secret>",
+        "--domain",
+        "https://open.larksuite.com"
+      ]
+    }
+  }
+}
+```
+
+> **💡 Tip**: Ensure your application is created in the corresponding domain environment's open platform. International version applications cannot be used with Feishu China version, and vice versa.
+
+## Custom API Configuration
+
+> ⚠️ **File Upload/Download**: File upload and download operations are not yet supported
+
+> ⚠️ **Document Editing**: Direct editing of Feishu cloud documents is not supported (only importing and reading are available)
+
+By default, the MCP service enables common APIs. To enable other tools or only specific APIs or presets, you can specify them using the `-t` parameter in the MCP Client configuration (JSON):
+
+```json
+{
+  "mcpServers": {
+    "lark-mcp": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@larksuiteoapi/lark-mcp",
+        "mcp",
+        "-a", "<your_app_id>",
+        "-s", "<your_app_secret>",
+        "-t", "im.v1.message.create,im.v1.message.list,im.v1.chat.create,preset.calendar.default"
+      ]
+    }
+  }
+}
+```
+
+For detailed information about all preset tool collections and which tools are included in each preset, please refer to the [Preset Tool Collections Reference](./docs/reference/tool-presets/presets.md).
+
+A complete list of all supported Feishu/Lark tools can be found in [tools.md](./docs/reference/tool-presets/tools-en.md).
+
+> **⚠️ Notice**：Non-preset APIs have not undergone compatibility testing, and the AI may not perform optimally during the process of understanding and using them.
+
+### Development Integration
+
+Developers can refer to the minimal example for integrating with Agent: [`lark-samples/mcp_quick_demo`](https://github.com/larksuite/lark-samples/tree/main/mcp_quick_demo).
+
+You can also refer to the Lark bot integration example: [`lark-samples/mcp_larkbot_demo/nodejs`](https://github.com/larksuite/lark-samples/tree/main/mcp_larkbot_demo/nodejs).
+
+This example demonstrates how to integrate MCP capabilities into Feishu/Lark bots, triggering tool calls and message sending through bot conversations, suitable for scenarios that integrate existing tools into Bot.
+
+### Advanced Configuration
+
+For detailed configuration options and deployment scenarios, please refer to our [Configuration Guide](./docs/usage/configuration/configuration.md).
+
+For detailed information about all available command line parameters and their usage, please refer to the [Command Line Reference](./docs/reference/cli/cli.md).
+
+## FAQ
+
+- [FAQ (Frequently Asked Questions)](./docs/troubleshooting/faq.md)
+- [Common Issues and Use Cases](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/mcp_integration/use_cases)
+
+## Related Links
+
+- [Feishu Open Platform](https://open.feishu.cn/)
+- [Development Documentation: OpenAPI MCP](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/mcp_integration/mcp_introduction)
+- [Lark International Open Platform](https://open.larksuite.com/)
+- [Feishu Open Platform API Documentation](https://open.feishu.cn/document/home/index)
+- [Node.js Website](https://nodejs.org/)
+- [npm Documentation](https://docs.npmjs.com/)
+
+## Feedback
+
+Issues are welcome to help improve this tool. If you have any questions or suggestions, please raise them in the GitHub repository.

package/README_ZH.md

@@ -0,0 +1,212 @@
+# 飞书/Lark OpenAPI MCP
+
+[![npm version](https://img.shields.io/npm/v/@larksuiteoapi/lark-mcp.svg)](https://www.npmjs.com/package/@larksuiteoapi/lark-mcp)
+[![npm downloads](https://img.shields.io/npm/dm/@larksuiteoapi/lark-mcp.svg)](https://www.npmjs.com/package/@larksuiteoapi/lark-mcp)
+[![Node.js Version](https://img.shields.io/node/v/@larksuiteoapi/lark-mcp.svg)](https://nodejs.org/)
+
+中文 | [English](./README.md) 
+
+[开发文档检索 MCP](./docs/recall-mcp/README_ZH.md) 
+
+[官方文档](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/mcp_integration/mcp_introduction)
+
+[常见问题](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/mcp_integration/use_cases)
+
+> **⚠️ Beta版本提示**：当前工具处于Beta版本阶段，功能和API可能会有变更，请密切关注版本更新。
+
+飞书/Lark官方 OpenAPI MCP（Model Context Protocol）工具，旨在帮助用户快速连接飞书平台并实现 AI Agent 与飞书的高效协作。该工具将飞书开放平台的 API 接口封装为 MCP 工具，使 AI 助手能够直接调用这些接口，实现文档处理、会话管理、日历安排等多种自动化场景。
+
+## 使用准备
+
+### 创建应用
+
+在使用lark-mcp工具前，您需要先创建一个飞书应用：
+
+1. 访问[飞书开放平台](https://open.feishu.cn/)并登录
+2. 点击"开发者后台"，创建一个新应用
+3. 获取应用的App ID和App Secret，这将用于API认证
+4. 根据您的使用场景，为应用添加所需的权限
+5. 如需以用户身份调用API，请设置OAuth 2.0重定向URL为 http://localhost:3000/callback
+
+详细的应用创建和配置指南，请参考[飞书开放平台文档 - 创建应用](https://open.feishu.cn/document/home/introduction-to-custom-app-development/self-built-application-development-process#a0a7f6b0)。
+
+### 安装Node.js
+
+在使用lark-mcp工具之前，您需要先安装Node.js环境。
+
+**使用官方安装包（推荐）**：
+
+1. 访问[Node.js官网](https://nodejs.org/)
+2. 下载并安装LTS版本
+3. 安装完成后，打开终端验证：
+
+```bash
+  node -v
+  npm -v
+```
+
+## 快速开始
+
+### 在Trae/Cursor中使用
+
+如需在Trae、Cursor等AI工具中集成飞书/Lark功能，你可以通过下方按钮安装，将 `app_id` 和 `app_secret` 填入安装弹窗或客户端配置 JSON 的 `args` 中：
+
+[![Install MCP Server](https://cursor.com/deeplink/mcp-install-light.svg)](https://cursor.com/install-mcp?name=lark-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBsYXJrc3VpdGVvYXBpL2xhcmstbWNwIiwibWNwIiwiLWEiLCJ5b3VyX2FwcF9pZCIsIi1zIiwieW91cl9hcHBfc2VjcmV0Il19)
+[![Install MCP Server](./assets/trae-cn.svg)](trae-cn://trae.ai-ide/mcp-import?source=lark&type=stdio&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBsYXJrc3VpdGVvYXBpL2xhcmstbWNwIiwibWNwIiwiLWEiLCJ5b3VyX2FwcF9pZCIsIi1zIiwieW91cl9hcHBfc2VjcmV0Il19)  [![Install MCP Server](./assets/trae.svg)](trae://trae.ai-ide/mcp-import?source=lark&type=stdio&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBsYXJrc3VpdGVvYXBpL2xhcmstbWNwIiwibWNwIiwiLWEiLCJ5b3VyX2FwcF9pZCIsIi1zIiwieW91cl9hcHBfc2VjcmV0Il19)
+
+
+也可以直接在 MCP Client 的配置文件中添加以下内容（JSON），客户端会按配置启动 `lark-mcp`：
+
+```json
+{
+  "mcpServers": {
+    "lark-mcp": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@larksuiteoapi/lark-mcp",
+        "mcp",
+        "-a",
+        "<your_app_id>",
+        "-s",
+        "<your_app_secret>"
+      ]
+    }
+  }
+}
+```
+
+如需使用**用户身份**访问 API：
+1) 在终端运行 `login`（会保存令牌，后续客户端可直接复用）。
+2) 在 MCP Client 配置中加入 `--oauth`。
+
+注意需要先在开发者后台配置应用的重定向 URL，默认是 `http://localhost:3000/callback`。
+
+```bash
+npx -y @larksuiteoapi/lark-mcp login -a cli_xxxx -s yyyyy
+```
+
+然后在 MCP Client 中启用 `--oauth`
+
+```json
+{
+  "mcpServers": {
+    "lark-mcp": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@larksuiteoapi/lark-mcp",
+        "mcp",
+        "-a", "<your_app_id>",
+        "-s", "<your_app_secret>",
+        "--oauth",
+        "--token-mode", "user_access_token"
+      ]
+    }
+  }
+}
+```
+
+说明：在启用 `--oauth` 时，建议显式设置 `--token-mode` 为 `user_access_token`，表示以用户访问令牌调用 API，适用于访问用户资源或需要用户授权的场景（如读取个人文档、发送 IM 消息）。若保留默认 `auto`，可能在AI推理使用 `tenant_access_token`，导致权限不足或无法访问用户私有数据。
+
+### 域名配置
+
+根据您的使用场景，lark-mcp 支持配置不同的域名环境：
+
+**飞书**：
+- 默认使用 `https://open.feishu.cn` 域名
+- 适用于飞书用户
+
+**Lark（国际版）**：
+- 使用 `https://open.larksuite.com` 域名
+- 适用于国际版Lark用户
+
+如需切换至国际版Lark，请在配置中添加 `--domain` 参数：
+
+```json
+{
+  "mcpServers": {
+    "lark-mcp": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@larksuiteoapi/lark-mcp",
+        "mcp",
+        "-a",
+        "<your_app_id>",
+        "-s",
+        "<your_app_secret>",
+        "--domain",
+        "https://open.larksuite.com"
+      ]
+    }
+  }
+}
+```
+
+> **💡 提示**：确保您的应用已在对应域名环境的开放平台创建。国际版应用无法在飞书中国版使用，反之亦然。
+
+
+## 自定义配置开启API
+
+> ⚠️ **文件上传下载**：暂不支持文件的上传和下载操作
+
+> ⚠️ **云文档编辑**：暂不支持直接编辑飞书云文档内容（仅支持导入和读取）
+
+默认情况下，MCP 服务启用常用 API。如需启用其他工具或仅启用特定 API 或 preset，推荐在 MCP Client 配置（JSON）中通过 `-t` 指定（用逗号分隔）：
+
+```json
+{
+  "mcpServers": {
+    "lark-mcp": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@larksuiteoapi/lark-mcp",
+        "mcp",
+        "-a", "<your_app_id>",
+        "-s", "<your_app_secret>",
+        "-t", "im.v1.message.create,im.v1.message.list,im.v1.chat.create,preset.calendar.default"
+      ]
+    }
+  }
+}
+```
+
+关于所有预设工具集的详细信息以及每个预设包含哪些工具，请参考[预设工具集参考文档](./docs/reference/tool-presets/presets-zh.md)。
+
+对于所有支持的飞书/Lark工具列表可以在[tools.md](./docs/reference/tool-presets/tools-zh.md)中查看。
+
+> **⚠️ 提示**：非预设 API 没有经过兼容性测试，AI在理解使用的过程中可能效果不理想
+
+### 在开发Agent中使用
+
+开发者可参考在 Agent 中集成的最小示例：[`lark-samples/mcp_quick_demo`](https://github.com/larksuite/lark-samples/tree/main/mcp_quick_demo)。
+
+另外可参考 Lark 机器人集成示例：[`lark-samples/mcp_larkbot_demo/nodejs`](https://github.com/larksuite/lark-samples/tree/main/mcp_larkbot_demo/nodejs)。
+
+该示例展示如何将 MCP 能力集成到飞书/Lark 机器人中，通过机器人会话触发工具调用与消息收发，适用于将已有工具接入 Bot 的场景。
+
+### 高级配置
+
+更详细的配置选项和部署场景，请参考我们的[配置指南](./docs/usage/configuration/configuration-zh.md)。
+
+关于所有可用命令行参数及其使用方法的详细信息，请参考[命令行参考文档](./docs/reference/cli/cli-zh.md)。
+
+## 常见问题
+
+- [常见问题（FAQ）](./docs/troubleshooting/faq-zh.md)
+- [常见问题与使用案例](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/mcp_integration/use_cases)
+
+## 相关链接
+
+- [飞书开放平台](https://open.feishu.cn/)
+- [开发文档：OpenAPI MCP](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/mcp_integration/mcp_introduction)
+- [Lark国际版开放平台](https://open.larksuite.com/)
+- [飞书开放平台API文档](https://open.feishu.cn/document/home/index)
+- [Node.js官网](https://nodejs.org/)
+- [npm文档](https://docs.npmjs.com/)
+
+## 反馈
+
+欢迎提交Issues来帮助改进这个工具。如有问题或建议，请在GitHub仓库中提出。

package/dist/auth/config.d.ts

@@ -0,0 +1,12 @@
+export declare const AUTH_CONFIG: {
+    readonly SERVER_NAME: "lark-mcp";
+    readonly AES_KEY_NAME: "encryption-key";
+    readonly STORAGE_DIR: string;
+    readonly STORAGE_FILE: "storage.json";
+    readonly ENCRYPTION: {
+        readonly ALGORITHM: "aes-256-cbc";
+        readonly KEY_LENGTH: 32;
+        readonly IV_LENGTH: 16;
+    };
+};
+export type AuthConfig = typeof AUTH_CONFIG;

package/dist/auth/config.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AUTH_CONFIG = void 0;
+const constants_1 = require("../utils/constants");
+exports.AUTH_CONFIG = {
+    SERVER_NAME: 'lark-mcp',
+    AES_KEY_NAME: 'encryption-key',
+    STORAGE_DIR: constants_1.ENV_PATHS.data,
+    STORAGE_FILE: 'storage.json',
+    ENCRYPTION: {
+        ALGORITHM: 'aes-256-cbc',
+        KEY_LENGTH: 32, // 256 bits
+        IV_LENGTH: 16, // 128 bits
+    },
+};

package/dist/auth/handler/handler-local.d.ts

@@ -0,0 +1,21 @@
+import { Request, Response } from 'express';
+import { LarkAuthHandler } from './handler';
+export declare class LarkAuthHandlerLocal extends LarkAuthHandler {
+    private static readonly LOCAL_CLIENT_ID;
+    private expressServer;
+    private timeoutId;
+    private startServer;
+    private stopServer;
+    protected callback(req: Request, res: Response): Promise<void>;
+    refreshToken(accessToken: string): Promise<{
+        access_token: string;
+        token_type: string;
+        expires_in?: number | undefined;
+        scope?: string | undefined;
+        refresh_token?: string | undefined;
+    }>;
+    reAuthorize(accessToken?: string, ignoreCheck?: boolean): Promise<{
+        accessToken: string;
+        authorizeUrl: string;
+    }>;
+}

package/dist/auth/handler/handler-local.js

@@ -0,0 +1,123 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LarkAuthHandlerLocal = void 0;
+const handler_1 = require("./handler");
+const store_1 = require("../store");
+const is_token_valid_1 = require("../utils/is-token-valid");
+const pkce_1 = require("../utils/pkce");
+const logger_1 = require("../../utils/logger");
+class LarkAuthHandlerLocal extends handler_1.LarkAuthHandler {
+    constructor() {
+        super(...arguments);
+        this.expressServer = null;
+        this.timeoutId = null;
+    }
+    async startServer() {
+        if (this.expressServer) {
+            return;
+        }
+        return new Promise((resolve, reject) => {
+            logger_1.logger.info(`[LarkAuthHandlerLocal] Starting server on ${this.options.host}:${this.options.port}`);
+            this.expressServer = this.app.listen(this.options.port, this.options.host, (error) => {
+                if (error) {
+                    reject(error);
+                }
+                logger_1.logger.info(`[LarkAuthHandlerLocal] Server started on ${this.options.host}:${this.options.port}`);
+                resolve(true);
+            });
+        });
+    }
+    async stopServer() {
+        if (this.timeoutId) {
+            clearTimeout(this.timeoutId);
+            this.timeoutId = null;
+        }
+        return new Promise((resolve, reject) => {
+            if (!this.expressServer) {
+                resolve(true);
+                return;
+            }
+            logger_1.logger.info(`[LarkAuthHandlerLocal] Stopping server`);
+            this.expressServer.close((error) => {
+                if (error) {
+                    reject(error);
+                }
+                else {
+                    logger_1.logger.info(`[LarkAuthHandlerLocal] Server stopped`);
+                    resolve(true);
+                }
+                this.expressServer = null;
+            });
+        });
+    }
+    async callback(req, res) {
+        if (!req.query.code || typeof req.query.code !== 'string') {
+            logger_1.logger.error(`[LarkAuthHandlerLocal] callback: Failed to exchange authorization code: ${req.query.code}`);
+            res.end('error, failed to exchange authorization code, please try again');
+            return;
+        }
+        const codeVerifier = store_1.authStore.getCodeVerifier(LarkAuthHandlerLocal.LOCAL_CLIENT_ID);
+        if (!codeVerifier) {
+            logger_1.logger.error(`[LarkAuthHandlerLocal] callback: Code verifier not found`);
+            res.end('error: code_verifier not found, please try again');
+            return;
+        }
+        const token = await this.provider.exchangeAuthorizationCode({ client_id: LarkAuthHandlerLocal.LOCAL_CLIENT_ID, redirect_uris: [] }, req.query.code, codeVerifier, this.callbackUrl);
+        store_1.authStore.removeCodeVerifier(LarkAuthHandlerLocal.LOCAL_CLIENT_ID);
+        await store_1.authStore.storeLocalAccessToken(token.access_token, this.options.appId);
+        logger_1.logger.info(`[LarkAuthHandlerLocal] callback: Successfully exchanged authorization code`);
+        res.end('success, you can close this page now');
+        setTimeout(async () => {
+            try {
+                await this.stopServer();
+            }
+            catch (error) {
+                logger_1.logger.error(`[LarkAuthHandlerLocal] callback: Error stopping server: ${error}`);
+            }
+        }, 1000);
+    }
+    async refreshToken(accessToken) {
+        const newToken = await super.refreshToken(accessToken);
+        await store_1.authStore.storeLocalAccessToken(newToken.access_token, this.options.appId);
+        return newToken;
+    }
+    async reAuthorize(accessToken, ignoreCheck = false) {
+        var _a;
+        const localAccessToken = await store_1.authStore.getLocalAccessToken(this.options.appId);
+        const { valid } = await (0, is_token_valid_1.isTokenValid)(localAccessToken);
+        if (ignoreCheck || accessToken === localAccessToken || !localAccessToken || !valid) {
+            const scope = (_a = this.options.scope) === null || _a === void 0 ? void 0 : _a.join(' ');
+            logger_1.logger.info(`[LarkAuthHandlerLocal] reAuthorize: Registering client`);
+            await store_1.authStore.registerClient({
+                client_id: LarkAuthHandlerLocal.LOCAL_CLIENT_ID,
+                client_secret: LarkAuthHandlerLocal.LOCAL_CLIENT_ID,
+                scope,
+                redirect_uris: [this.callbackUrl],
+            });
+            await this.startServer();
+            if (this.timeoutId) {
+                clearTimeout(this.timeoutId);
+            }
+            this.timeoutId = setTimeout(() => this.stopServer(), 60 * 1000);
+            const { codeVerifier, codeChallenge } = (0, pkce_1.generatePKCEPair)();
+            store_1.authStore.storeCodeVerifier(LarkAuthHandlerLocal.LOCAL_CLIENT_ID, codeVerifier);
+            const authorizeUrl = new URL(`http://${this.options.host}:${this.options.port}/authorize`);
+            authorizeUrl.searchParams.set('client_id', LarkAuthHandlerLocal.LOCAL_CLIENT_ID);
+            authorizeUrl.searchParams.set('response_type', 'code');
+            authorizeUrl.searchParams.set('code_challenge', codeChallenge);
+            authorizeUrl.searchParams.set('code_challenge_method', 'S256');
+            authorizeUrl.searchParams.set('redirect_uri', this.callbackUrl);
+            authorizeUrl.searchParams.set('state', 'reauthorize');
+            if (scope) {
+                authorizeUrl.searchParams.set('scope', scope);
+            }
+            return {
+                accessToken: '',
+                authorizeUrl: authorizeUrl.toString(),
+            };
+        }
+        return { accessToken: localAccessToken, authorizeUrl: '' };
+    }
+}
+exports.LarkAuthHandlerLocal = LarkAuthHandlerLocal;
+LarkAuthHandlerLocal.LOCAL_CLIENT_ID = 'client_id_for_local_auth';