@liselvins/lark-mcp 0.1.0

package/docs/usage/configuration/configuration.md

@@ -0,0 +1,344 @@
+# Lark MCP Configuration Guide
+
+This document provides detailed information about advanced configuration options for the lark-mcp tool, organized by different usage scenarios.
+
+## Table of Contents
+
+- [📋 Prerequisites](#-prerequisites)
+- [🚀 Basic Usage](#-basic-usage)
+- [👤 Using User Identity](#-using-user-identity)  
+- [🌐 Service Deployment](#-service-deployment)
+- [⚙️ Advanced Configuration Options](#️-advanced-configuration-options)
+- [📝 Configuration Parameters Reference](#-configuration-parameters-reference)
+
+
+## 📋 Prerequisites
+
+### Creating an Application
+
+Before using the lark-mcp tool, you need to create a Lark/Feishu application:
+
+1. Visit [Lark Open Platform](https://open.feishu.cn/) and log in
+2. Click "Developer Console" and create a new application
+3. Obtain the App ID and App Secret of the application, which will be used for API authentication
+4. Add the required permissions to the application based on your use case
+5. If you need to call APIs with user identity, please set the OAuth 2.0 redirect URL to http://localhost:3000/callback
+
+For detailed application creation and configuration guides, please refer to [Lark Open Platform Documentation - Creating Applications](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 first.
+
+**Using Official Installer (Recommended)**:
+
+1. Visit [Node.js official website](https://nodejs.org/)
+2. Download and install the LTS version
+3. After installation, open terminal to verify:
+
+```bash
+node -v
+npm -v
+```
+
+## 🚀 Basic Usage
+
+Suitable for most individual users, using app identity to access APIs with simple configuration and out-of-the-box functionality.
+
+### Installation Methods
+
+**Method 1: Install Button**
+
+Click the corresponding button and fill in your App ID and App Secret in the popup window:
+
+[![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)
+
+
+**Method 2: Manual JSON Configuration**
+
+Add the following content to your MCP client configuration file:
+
+```json
+{
+  "mcpServers": {
+    "lark-mcp": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@larksuiteoapi/lark-mcp",
+        "mcp",
+        "-a", "your_app_id",
+        "-s", "your_app_secret"
+      ]
+    }
+  }
+}
+```
+
+### Features
+
+- ✅ **Simple Configuration**: Only requires App ID and App Secret
+- ✅ **App Identity**: Uses app identity to call APIs, suitable for most scenarios
+- ✅ **Automatic Management**: MCP client automatically starts and manages the service process
+
+> 💡 **Tip**: This configuration uses the default stdio transport mode and app identity, suitable for personal use and most API calling scenarios.
+
+## 👤 Using User Identity
+
+When you need to access user's personal data (such as personal documents, sending messages to others, etc.), you need to use user identity instead of app identity.
+
+### Use Cases
+
+- 📄 Reading user's personal documents
+- 💬 Sending messages as the user
+- 📅 Accessing user's calendar data
+- 👥 Getting user's contact information
+
+### Configuration Steps
+
+**Step 1: User Login in Terminal**
+
+First, you need to perform OAuth authentication in the command line to obtain user tokens:
+
+```bash
+npx -y @larksuiteoapi/lark-mcp login -a cli_xxxx -s your_secret
+```
+
+This command will:
+- Start a local server (default `http://localhost:3000/callback`)
+- Open browser for authorization
+- Save user token locally
+
+> ⚠️ **Note**: You need to configure the redirect URL as `http://localhost:3000/callback` in the Lark Open Platform backend
+
+**Step 2: Enable OAuth in MCP Client Configuration**
+
+After login is complete, add OAuth-related parameters to the MCP client configuration:
+
+```json
+{
+  "mcpServers": {
+    "lark-mcp": {
+      "command": "npx",
+      "args": [
+        "-y", "@larksuiteoapi/lark-mcp", "mcp",
+        "-a", "cli_xxxx", "-s", "your_secret",
+        "--oauth", "--token-mode", "user_access_token"
+      ]
+    }
+  }
+}
+```
+
+### Features
+
+- ✅ **User Identity**: Calls APIs as user identity, can access user private data
+
+> 💡 **Tip**: It's recommended to explicitly set `--token-mode user_access_token` to ensure always using user identity for API calls.
+
+## 🌐 Service Deployment (Alpha)
+
+Suitable for team usage, multi-client sharing, or server deployment scenarios, using streamable mode to provide HTTP interface.
+
+### Use Cases
+
+- 🏢 Team sharing the same lark-mcp service
+- ☁️ Cloud server deployment with remote access
+
+### Configuration Steps
+
+**Step 1: Start HTTP Service on Server**
+
+```bash
+# Basic startup command
+npx -y @larksuiteoapi/lark-mcp mcp \
+  -a cli_xxxx \
+  -s your_secret \
+  -m streamable \
+  --host 0.0.0.0 \
+  -p 3000
+```
+
+
+
+**Step 2: Configure URL in MCP Client**
+
+After the server starts, configure the connection URL in each MCP client:
+
+```json
+{
+  "mcpServers": {
+    "lark-mcp": {
+       "url": "http://localhost:3000/mcp"
+    }
+  }
+}
+```
+
+> 💡 **Tip**: The streamable server will continue running after startup. It's recommended to use a process manager (such as PM2) to ensure service stability.
+
+### Enable OAuth User Identity Authentication
+
+When you need to use user identity for API calls in service deployment, you can enable OAuth authentication functionality.
+
+> ⚠️ **Important Note**: Enabling MCP OAuth requires client support for OAuth authentication functionality. Please ensure your MCP client version supports this feature.
+
+**Start streamable service with OAuth:**
+
+```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 Limitation**: Currently, streamable service with OAuth only supports localhost and cannot be broadcasted to other users.
+
+**MCP client configuration remains unchanged:**
+
+```json
+{
+  "mcpServers": {
+    "lark-mcp": {
+      "url": "http://localhost:3000/mcp"
+    }
+  }
+}
+```
+
+## ⚙️ Advanced Configuration Options
+
+This section introduces more advanced configuration methods, including environment variables, configuration files, etc.
+
+### Environment Variable Configuration
+
+Using environment variables can avoid exposing sensitive information in configuration files, especially suitable for server deployment:
+
+**Set Environment Variables:**
+
+```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
+```
+
+**Simplified MCP Client Configuration:**
+
+```json
+{
+  "mcpServers": {
+    "lark-mcp": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@larksuiteoapi/lark-mcp", 
+        "mcp"
+      ]
+    }
+  }
+}
+```
+
+> 💡 **Tip**: The system will automatically read `APP_ID` and `APP_SECRET` environment variables, no need to specify them again in args.
+
+### Configuration File Usage
+
+For complex configurations, you can use JSON configuration files:
+
+**1. Create Configuration File (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. Reference Configuration File in MCP Client:**
+
+```json
+{
+  "mcpServers": {
+    "lark-mcp": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@larksuiteoapi/lark-mcp",
+        "mcp",
+        "--config", "./config.json"
+      ]
+    }
+  }
+}
+```
+
+## 📝 Configuration Parameters Reference
+
+### Supported Environment Variables
+
+| Environment Variable | Command Line Parameter | Description | Example Value |
+|---------------------|------------------------|-------------|---------------|
+| `APP_ID` | `-a, --app-id` | Lark/Feishu app App ID | `cli_xxxx` |
+| `APP_SECRET` | `-s, --app-secret` | Lark/Feishu app App Secret | `your_secret` |
+| `USER_ACCESS_TOKEN` | `-u, --user-access-token` | User access token | `u-zzzzz` |
+| `LARK_TOOLS` | `-t, --tools` | List of enabled API tools | `im.v1.message.create,calendar.v4.calendar.list` |
+| `LARK_DOMAIN` | `-d, --domain` | API domain | `https://open.feishu.cn` |
+| `LARK_TOKEN_MODE` | `--token-mode` | Token mode | `auto` |
+
+> ⚠️ **Note**: Other parameters (such as `-l`, `-c`, `-m`, `--host`, `-p`, `--oauth`, etc.) do not support environment variables and can only be specified through command line parameters.
+
+### Configuration File Fields
+
+| Field | Type | Description | Default Value |
+|-------|------|-------------|---------------|
+| `appId` | string | Application ID | Required |
+| `appSecret` | string | Application secret | Required |
+| `domain` | string | API domain | `https://open.feishu.cn` |
+| `tools` | array | List of enabled tools | `["preset.default"]` |
+| `toolNameCase` | string | Tool naming format | `snake` |
+| `language` | string | Tool language | `zh` |
+| `userAccessToken` | string | User access token | `""` |
+| `tokenMode` | string | Token mode | `auto` |
+| `mode` | string | Transport mode (default: stdio) | `stdio` |
+| `host` | string | Listen host | `localhost` |
+| `port` | string/number | Listen port | `3000` |
+| `oauth` | boolean | Enable OAuth | `false` |
+| `scope` | string | OAuth permission scope | `""` |
+
+### Configuration Priority
+
+Configuration parameter priority from high to low:
+
+1. **Command Line Parameters** - Highest priority
+2. **Environment Variables** - Medium priority  
+3. **Configuration File** - Lowest priority
+4. **Default Values** - Fallback values
+
+## Container Deployment (Alpha)
+
+For detailed information, please refer to: [Docker Usage Guide](../docker/docker.md)
+
+## More Information
+
+- [Main Documentation](../../../README.md)
+- [Tools List](../../reference/tool-presets/tools-en.md)
+- [FAQ](../../troubleshooting/faq.md)

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

@@ -0,0 +1,101 @@
+# 在 Docker 中使用 lark-mcp (Alpha)
+
+本文档将介绍如何构建并运行官方 lark-mcp Docker 镜像，内置 keytar 安全存储，开箱即用。
+
+[English Version](./docker.md)
+
+## 前置条件
+- 已安装 Docker Desktop（或任意 Docker 运行时）
+- 拥有你的飞书/Lark 应用 App ID 和 App Secret
+
+## 1）构建镜像
+```bash
+# 在项目根目录执行
+docker build -t lark-mcp:latest .
+```
+
+## 2）快速检查
+- 查看帮助
+```bash
+docker run --rm -it lark-mcp:latest --help
+```
+- 查看登录状态（会初始化存储）
+```bash
+docker run --rm -it lark-mcp:latest whoami
+```
+
+
+## 3）MCP 客户端配置
+
+启动Docker容器后，还需要在MCP客户端中进行相应配置才能使用。
+
+### stdio 模式配置
+
+如果使用默认的stdio模式，在MCP客户端（如Cursor）配置文件中添加：
+
+```json
+{
+  "mcpServers": {
+    "lark-mcp": {
+      "command": "docker",
+      "args": [
+        "run", "--rm", "-i",
+        "-v", "lark_mcp_data:/home/node/.local/share",
+        "lark-mcp:latest", "mcp",
+        "-a", "your_app_id",
+        "-s", "your_app_secret"
+      ]
+    }
+  }
+}
+```
+
+### streamable 模式配置
+
+如果使用streamable（HTTP）模式，需要先启动容器：
+
+```bash
+docker run --rm -it \
+  -p 3000:3000 \
+  -v lark_mcp_data:/home/node/.local/share \
+  lark-mcp:latest mcp -a <your_app_id> -s <your_app_secret> -m streamable --host 0.0.0.0 -p 3000
+```
+
+然后在MCP客户端配置文件中添加：
+
+```json
+{
+  "mcpServers": {
+    "lark-mcp": {
+      "url": "http://localhost:3000/mcp"
+    }
+  }
+}
+```
+
+### 用户身份配置（user_access_token）
+
+> ⚠️ **重要提示**：在Docker环境中，暂不支持 OAuth，请手动传入 user_access_token 进行用户身份验证。
+
+```json
+{
+  "mcpServers": {
+    "lark-mcp": {
+      "command": "docker",
+      "args": [
+        "run", "--rm", "-i",
+        "-v", "lark_mcp_data:/home/node/.local/share",
+        "lark-mcp:latest", "mcp",
+        "-a", "your_app_id",
+        "-s", "your_app_secret",
+        "-u", "your_user_access_token",
+         "--token-mode", "user_access_token"
+      ]
+    }
+  }
+}
+```
+
+## 提示
+- 无需输入密码：容器内已自动初始化 secrets 服务，keytar 无需交互即可安全存储令牌。
+- 持久化令牌：建议始终挂载 `lark_mcp_data` 数据卷。

package/docs/usage/docker/docker.md

@@ -0,0 +1,106 @@
+# Use lark-mcp in Docker (Alpha)
+
+This document describes how to build and run the official lark-mcp Docker image with built-in keytar secure storage, ready to use out of the box.
+
+[中文版本](./docker-zh.md)
+
+## Prerequisites
+- Docker Desktop installed (or any Docker runtime)
+- Your Feishu/Lark application App ID and App Secret
+
+## 1) Build the image
+```bash
+# Execute from project root directory
+docker build -t lark-mcp:latest .
+```
+
+## 2) Quick checks
+- View help
+```bash
+docker run --rm -it lark-mcp:latest --help
+```
+- Check login status (will initialize storage)
+```bash
+docker run --rm -it lark-mcp:latest whoami
+```
+
+
+## 3) MCP Client Configuration
+
+After starting the Docker container, you need to configure your MCP client accordingly to use it.
+
+### stdio Mode Configuration
+
+If using the default stdio mode, add the following to your MCP client (e.g., Cursor) configuration file:
+
+```json
+{
+  "mcpServers": {
+    "lark-mcp": {
+      "command": "docker",
+      "args": [
+        "run", "--rm", "-i",
+        "-v", "lark_mcp_data:/home/node/.local/share",
+        "lark-mcp:latest", "mcp",
+        "-a", "your_app_id",
+        "-s", "your_app_secret"
+      ]
+    }
+  }
+}
+```
+
+### streamable Mode Configuration
+
+If using streamable (HTTP) mode, first start the container:
+
+```bash
+docker run --rm -it \
+  -p 3000:3000 \
+  -v lark_mcp_data:/home/node/.local/share \
+  lark-mcp:latest mcp -a <your_app_id> -s <your_app_secret> -m streamable --host 0.0.0.0 -p 3000
+```
+
+Then add the following to your MCP client configuration file:
+
+```json
+{
+  "mcpServers": {
+    "lark-mcp": {
+      "url": "http://localhost:3000/mcp"
+    }
+  }
+}
+```
+
+### User Identity Configuration (user_access_token)
+
+
+> ⚠️ **Important Note**: In Docker environment, OAuth mode does not support yet. Please  use -u for user authentication.
+
+
+1. **MCP client configuration**:
+```json
+{
+  "mcpServers": {
+    "lark-mcp": {
+      "command": "docker",
+      "args": [
+        "run", "--rm", "-i",
+        "-v", "lark_mcp_data:/home/node/.local/share",
+        "lark-mcp:latest", "mcp",
+        "-a", "your_app_id",
+        "-s", "your_app_secret",
+        "-u", "your_user_access_token",
+        "--token-mode", "user_access_token"
+      ]
+    }
+  }
+}
+```
+
+
+
+## Tips
+- No password required: The container automatically initializes the secrets service, allowing keytar to securely store tokens without interaction.
+- Token persistence: Suggest always mount the `lark_mcp_data` volume.

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@liselvins/lark-mcp",
+  "version": "0.1.0",
+  "description": "Feishu/Lark OpenAPI MCP",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "author": "Li-Xingyu",
+  "license": "MIT",
+  "bin": {
+    "lark-mcp": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "docs",
+    "CHANGELOG.md",
+    "README.md",
+    "README_ZH.md",
+    "README_RECALL.md",
+    "README_RECALL_ZH.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc",
+    "dev": "ts-node src/index.ts",
+    "dev:cli": "ts-node src/cli.ts",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "prepare": "yarn build",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage"
+  },
+  "keywords": [
+    "feishu",
+    "lark",
+    "mcp",
+    "open-api",
+    "ai"
+  ],
+  "homepage": "https://github.com/larksuite/lark-openapi-mcp",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "dependencies": {
+    "@larksuiteoapi/node-sdk": "^1.50.0",
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "axios": "^1.8.4",
+    "commander": "^13.1.0",
+    "dotenv": "^16.4.7",
+    "env-paths": "^2.2.1",
+    "express": "^5.1.0",
+    "keytar": "^7.9.0",
+    "open": "^8.4.2",
+    "proxy-agent": "^6.5.0"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.1",
+    "@types/jest": "^29.5.14",
+    "@types/node": "^20.4.5",
+    "jest": "^29.7.0",
+    "prettier": "^3.5.3",
+    "ts-jest": "^29.3.2",
+    "ts-node": "^10.9.1",
+    "typescript": "^5.0.0"
+  }
+}