@danyow/lark-mcp 0.5.1

package/docs/troubleshooting/faq-zh.md

@@ -0,0 +1,67 @@
+## 常见问题（FAQ）
+
+以下为常见问题与解决方案，附加补充说明便于定位原因与快速处理。
+
+### 无法连接到飞书/Lark API
+
+解决方案：
+- 检查本地网络连接、代理设置。
+- 核对 `APP_ID`、`APP_SECRET` 是否填写正确。
+- 测试是否能正常访问开放平台 API 域名（如 `https://open.feishu.cn` 或 `https://open.larksuite.com`）。
+
+### 使用 user_access_token 报错
+
+解决方案：
+- 检查 token 是否过期（通常 2 小时有效）。
+- 建议优先使用 `login` 获取并保存用户令牌。
+- 若在服务器/CI 环境使用，确保安全管理令牌并妥善刷新。
+
+### 启动 MCP 服务后调用某些 API 提示权限不足
+
+解决方案：
+- 在开发者后台为应用开通对应 API 权限，并等待审批通过。
+- 以用户身份调用（需要 `user_access_token`）的场景，确认授权范围（`scope`）是否包含对应权限。如果授权范围不足，需要重新登录。
+
+### 图片或文件上传/下载相关 API 失败
+
+解决方案：
+- 当前版本暂不支持文件/图片上传下载，相关能力将于后续版本支持。
+
+### Windows 终端显示乱码
+
+解决方案：
+- 在命令提示符中执行 `chcp 65001` 切换为 UTF-8。
+- PowerShell 用户可调整字体或相关终端设置以提升兼容性。
+
+### 安装时遇到权限错误
+
+解决方案：
+- macOS/Linux：使用 `sudo npm install -g @larksuiteoapi/lark-mcp` 或调整 npm 全局路径权限。
+- Windows：尝试以管理员身份运行命令提示符。
+
+### 启动 MCP 服务后提示 token 超过上限
+
+解决方案：
+- 使用 `-t`（或在 MCP 配置中 `args` 的 `-t`）减少启用的 API 数量。
+- 使用支持更大上下文长度的模型。
+
+### SSE/Streamable 模式下无法连接或接收消息
+
+解决方案：
+- 检查端口占用情况，必要时更换端口。
+- 确保客户端正确连接到对应端点并能处理事件流。
+
+### Linux 环境启动报错 [StorageManager] Failed to initialize: xxx
+
+说明：
+- 不影响“手动传入 `user_access_token`”或“不使用 `user_access_token`”的场景。
+
+原因：`StorageManager` 使用 keytar 对 `user_access_token` 做加密存储。
+
+解决方案：
+- 安装 `libsecret` 依赖：
+  - Debian/Ubuntu: `sudo apt-get install libsecret-1-dev`
+  - Red Hat-based: `sudo yum install libsecret-devel`
+  - Arch Linux: `sudo pacman -S libsecret`
+
+

package/docs/troubleshooting/faq.md

@@ -0,0 +1,67 @@
+## Frequently Asked Questions (FAQ)
+
+Below are common issues and solutions, with additional explanations to help identify causes and process quickly.
+
+### Unable to connect to Feishu/Lark API
+
+Solutions:
+- Check local network connection and proxy settings.
+- Verify that `APP_ID` and `APP_SECRET` are filled in correctly.
+- Test if you can access the open platform API domain normally (such as `https://open.feishu.cn` or `https://open.larksuite.com`).
+
+### Error when using user_access_token
+
+Solutions:
+- Check if the token has expired (usually valid for 2 hours).
+- It's recommended to use `login` to obtain and save user tokens first.
+- If using in server/CI environment, ensure secure token management and proper refresh.
+
+### Permission denied when calling certain APIs after starting MCP service
+
+Solutions:
+- Enable corresponding API permissions for the application in the developer console and wait for approval.
+- For scenarios calling as a user (requiring `user_access_token`), ensure the authorization scope (`scope`) includes the corresponding permissions. If not, you need to login again.
+
+### Image or file upload/download related API failures
+
+Solutions:
+- The current version does not support file/image upload and download yet. These capabilities will be supported in future versions.
+
+### Garbled characters in Windows terminal
+
+Solutions:
+- Execute `chcp 65001` in Command Prompt to switch to UTF-8.
+- PowerShell users can adjust fonts or related terminal settings to improve compatibility.
+
+### Permission errors during installation
+
+Solutions:
+- macOS/Linux: Use `sudo npm install -g @larksuiteoapi/lark-mcp` or adjust npm global path permissions.
+- Windows: Try running Command Prompt as administrator.
+
+### Token limit exceeded prompt after starting MCP service
+
+Solutions:
+- Use `-t` (or `-t` in MCP configuration `args`) to reduce the number of enabled APIs.
+- Use models that support larger context lengths.
+
+### Unable to connect or receive messages in SSE/Streamable mode
+
+Solutions:
+- Check port usage and change ports if necessary.
+- Ensure the client connects correctly to the corresponding endpoint and can handle event streams.
+
+### Linux environment startup error [StorageManager] Failed to initialize: xxx
+
+Note:
+- Does not affect scenarios of "manually passing `user_access_token`" or "not using `user_access_token`".
+
+`StorageManager` uses keytar for encrypted storage of `user_access_token`.
+
+Solutions:
+- Install `libsecret` dependency:
+  - Debian/Ubuntu: `sudo apt-get install libsecret-1-dev`
+  - Red Hat-based: `sudo yum install libsecret-devel`
+  - Arch Linux: `sudo pacman -S libsecret`
+
+

package/docs/usage/configuration/configuration-zh.md

@@ -0,0 +1,344 @@
+# Lark MCP 使用指南
+
+本文档详细介绍 lark-mcp 工具的高级配置选项，按照不同的使用场景来介绍配置方法。
+
+## 目录
+
+- [📋 使用准备](#-使用准备)
+- [🚀 基础使用](#-基础使用)
+- [👤 使用用户身份](#-使用用户身份)  
+- [🌐 服务化部署](#-服务化部署)
+- [⚙️ 高级配置选项](#️-高级配置选项)
+- [📝 配置参数详解](#-配置参数详解)
+
+
+## 📋 使用准备
+
+### 创建应用
+
+在使用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
+```
+
+## 🚀 基础使用
+
+适用于大多数个人用户，使用应用身份访问 API，配置简单，开箱即用。
+
+### 安装方式
+
+**方式一：通过安装按钮**
+
+点击对应的按钮，在弹出窗口中填入你的 App ID 和 App Secret：
+
+[![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)
+
+
+**方式二：手动配置 JSON**
+
+在 MCP 客户端的配置文件中添加以下内容：
+
+```json
+{
+  "mcpServers": {
+    "lark-mcp": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@larksuiteoapi/lark-mcp",
+        "mcp",
+        "-a", "your_app_id",
+        "-s", "your_app_secret"
+      ]
+    }
+  }
+}
+```
+
+### 特点说明
+
+- ✅ **配置简单**：只需要提供 App ID 和 App Secret
+- ✅ **应用身份**：使用应用身份调用 API，适合大部分场景
+- ✅ **自动管理**：MCP 客户端自动启动和管理服务进程
+
+> 💡 **提示**：此配置使用默认的 stdio 传输模式和应用身份，适合个人使用和大部分 API 调用场景。
+
+## 👤 使用用户身份
+
+当你需要访问用户的个人数据（如个人文档、发送消息给他人等）时，需要使用用户身份而不是应用身份。
+
+### 使用场景
+
+- 📄 读取用户的个人文档
+- 💬 以用户身份发送消息
+- 📅 访问用户的日历数据
+- 👥 获取用户的联系人信息
+
+### 配置步骤
+
+**第1步：在终端进行用户登录**
+
+首先需要在命令行中进行 OAuth 认证，获取用户令牌：
+
+```bash
+npx -y @larksuiteoapi/lark-mcp login -a cli_xxxx -s your_secret
+```
+
+这个命令会：
+- 启动本地服务器（默认 `http://localhost:3000/callback`）
+- 打开浏览器进行授权
+- 保存用户令牌到本地
+
+> ⚠️ **注意**：需要在飞书开放平台后台配置重定向 URL 为 `http://localhost:3000/callback`
+
+**第2步：在 MCP 客户端配置中启用 OAuth**
+
+登录完成后，在 MCP 客户端配置中添加 OAuth 相关参数：
+
+```json
+{
+  "mcpServers": {
+    "lark-mcp": {
+      "command": "npx",
+      "args": [
+        "-y", "@larksuiteoapi/lark-mcp", "mcp",
+        "-a", "cli_xxxx", "-s", "your_secret",
+        "--oauth", "--token-mode", "user_access_token"
+      ]
+    }
+  }
+}
+```
+
+### 特点说明
+
+- ✅ **用户身份**：以用户身份调用 API，可访问用户私有数据
+
+> 💡 **提示**：建议显式设置 `--token-mode user_access_token`，确保始终使用用户身份调用 API。
+
+## 🌐 服务化部署（Alpha）
+
+适用于团队使用、多客户端共享或服务器部署的场景，使用 streamable 模式提供 HTTP 接口。
+
+### 使用场景
+
+- 🏢 团队多人共享同一个 lark-mcp 服务
+- ☁️ 云服务器部署，远程访问
+
+### 配置步骤
+
+**第1步：在服务器启动 HTTP 服务**
+
+```bash
+# 基础启动命令
+npx -y @larksuiteoapi/lark-mcp mcp \
+  -a cli_xxxx \
+  -s your_secret \
+  -m streamable \
+  --host 0.0.0.0 \
+  -p 3000
+```
+
+
+
+**第2步：在 MCP 客户端配置 URL**
+
+服务器启动后，在各个 MCP 客户端中配置连接 URL：
+
+```json
+{
+  "mcpServers": {
+    "lark-mcp": {
+       "url": "http://localhost:3000/mcp"
+    }
+  }
+}
+```
+
+> 💡 **提示**：streamable 服务器启动后会持续运行，建议使用进程管理器（如 PM2）来确保服务稳定性。
+
+### 启用 OAuth 用户身份认证
+
+当需要在服务化部署中使用用户身份调用 API 时，可以启用 OAuth 认证功能。
+
+> ⚠️ **重要提示**：开启 MCP OAuth 需要客户端支持 OAuth 认证功能。请确保您的 MCP 客户端版本支持此功能。
+
+**启动带 OAuth 的 streamable 服务：**
+
+```bash
+npx -y @larksuiteoapi/lark-mcp mcp \
+  -a cli_xxxx \
+  -s your_secret \
+  -m streamable \
+  --host localhost \
+  -p 3000 \
+  --oauth \
+  --token-mode user_access_token
+```
+
+> ⚠️ **OAuth 限制**：当前带 OAuth 的 streamable 服务只支持 localhost，暂时不能广播给其他用户使用。
+
+**MCP 客户端配置保持不变：**
+
+```json
+{
+  "mcpServers": {
+    "lark-mcp": {
+      "url": "http://localhost:3000/mcp"
+    }
+  }
+}
+```
+
+## ⚙️ 高级配置选项
+
+本节介绍更高级的配置方法，包括环境变量、配置文件等。
+
+### 环境变量配置
+
+使用环境变量可以避免在配置文件中暴露敏感信息，特别适合服务器部署：
+
+**设置环境变量：**
+
+```bash
+# Windows (PowerShell)
+$env:APP_ID="cli_xxxx"
+$env:APP_SECRET="your_secret"
+$env:LARK_TOOLS="im.v1.message.create,calendar.v4.calendar.list"
+$env:LARK_DOMAIN="https://open.feishu.cn"
+$env:LARK_TOKEN_MODE="auto"
+
+# macOS/Linux (Bash/Zsh)
+export APP_ID=cli_xxxx
+export APP_SECRET=your_secret
+export LARK_TOOLS=im.v1.message.create,calendar.v4.calendar.list
+export LARK_DOMAIN=https://open.feishu.cn
+export LARK_TOKEN_MODE=auto
+```
+
+**简化 MCP 客户端配置：**
+
+```json
+{
+  "mcpServers": {
+    "lark-mcp": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@larksuiteoapi/lark-mcp", 
+        "mcp"
+      ]
+    }
+  }
+}
+```
+
+> 💡 **提示**：系统会自动读取 `APP_ID` 和 `APP_SECRET` 环境变量，无需在 args 中重复指定。
+
+### 配置文件使用
+
+对于复杂配置，可以使用 JSON 配置文件：
+
+**1. 创建配置文件 (config.json)：**
+
+```json
+{
+  "appId": "cli_xxxx",
+  "appSecret": "your_secret", 
+  "tools": ["im.v1.message.create", "calendar.v4.calendar.list"],
+  "language": "zh",
+  "oauth": true,
+  "tokenMode": "user_access_token"
+}
+```
+
+**2. 在 MCP 客户端中引用配置文件：**
+
+```json
+{
+  "mcpServers": {
+    "lark-mcp": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@larksuiteoapi/lark-mcp",
+        "mcp",
+        "--config", "./config.json"
+      ]
+    }
+  }
+}
+```
+
+## 📝 配置参数详解
+
+### 支持的环境变量
+
+| 环境变量名 | 命令行参数 | 描述 | 示例值 |
+|-----------|------------|------|--------|
+| `APP_ID` | `-a, --app-id` | 飞书/Lark应用的App ID | `cli_xxxx` |
+| `APP_SECRET` | `-s, --app-secret` | 飞书/Lark应用的App Secret | `your_secret` |
+| `USER_ACCESS_TOKEN` | `-u, --user-access-token` | 用户访问令牌 | `u-zzzzz` |
+| `LARK_TOOLS` | `-t, --tools` | 启用的API工具列表 | `im.v1.message.create,calendar.v4.calendar.list` |
+| `LARK_DOMAIN` | `-d, --domain` | API域名 | `https://open.feishu.cn` |
+| `LARK_TOKEN_MODE` | `--token-mode` | 令牌模式 | `auto` |
+
+> ⚠️ **注意**：其他参数（如 `-l`, `-c`, `-m`, `--host`, `-p`, `--oauth` 等）不支持环境变量，只能通过命令行参数指定。
+
+### 配置文件字段
+
+| 字段名 | 类型 | 描述 | 默认值 |
+|--------|------|------|--------|
+| `appId` | string | 应用ID | 必填 |
+| `appSecret` | string | 应用密钥 | 必填 |
+| `domain` | string | API域名 | `https://open.feishu.cn` |
+| `tools` | array | 启用的工具列表 | `["preset.default"]` |
+| `toolNameCase` | string | 工具命名格式 | `snake` |
+| `language` | string | 工具语言 | `zh` |
+| `userAccessToken` | string | 用户访问令牌 | `""` |
+| `tokenMode` | string | 令牌模式 | `auto` |
+| `mode` | string | 传输模式（默认：stdio） | `stdio` |
+| `host` | string | 监听主机 | `localhost` |
+| `port` | string/number | 监听端口 | `3000` |
+| `oauth` | boolean | 启用OAuth | `false` |
+| `scope` | string | OAuth权限范围 | `""` |
+
+### 配置优先级
+
+配置参数的优先级从高到低为：
+
+1. **命令行参数** - 最高优先级
+2. **环境变量** - 中等优先级  
+3. **配置文件** - 最低优先级
+4. **默认值** - 兜底值
+
+## 容器化部署 (Alpha)
+
+详细信息请参考：[Docker 使用指南](../docker/docker-zh.md)
+
+## 更多信息
+
+- [主要文档](../../../README_ZH.md)
+- [工具列表](../../reference/tool-presets/tools-zh.md)
+- [常见问题](../../troubleshooting/faq-zh.md)