Skip to content

Commit 35c7cbd

Browse files
transformgroupclaude
transformgroup
and
claude
committed
docs(readme): lead with Lark MCP; add Vietnamese README
Rework README.md to feature the MCP bridge (21 tools, Desktop stdio + web HTTP/bearer, 23 Cowork skills) at the top with quick starts and a docs index. Add full Vietnamese README.vi.md and EN/VI/中文 switcher. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
1 parent 01f6c1a commit 35c7cbd

2 files changed

Lines changed: 286 additions & 5 deletions

File tree

‎README.md‎

Lines changed: 98 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,107 @@
1-
# lark-cli
1+
# lark-mcp-cli — Lark/Feishu × Claude (MCP)
22

33
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
44
[![Go Version](https://img.shields.io/badge/go-%3E%3D1.23-blue.svg)](https://go.dev/)
5-
[![npm version](https://img.shields.io/npm/v/@larksuite/cli.svg)](https://www.npmjs.com/package/@larksuite/cli)
5+
[![MCP](https://img.shields.io/badge/MCP-stdio%20%2B%20http-7C3AED.svg)](#-lark-mcp--use-lark-from-claude-desktop--web)
6+
[![Tools](https://img.shields.io/badge/MCP%20tools-21-0EA5E9.svg)](./docs/06-cong-cu-mcp.md)
7+
[![Cowork Skills](https://img.shields.io/badge/Cowork%20skills-23-F59E0B.svg)](./docs/05-bo-skill-cowork.md)
68

7-
[中文版](./README.zh.md) | [English](./README.md)
9+
**English** | [Tiếng Việt](./README.vi.md) | [中文版](./README.zh.md)
810

9-
The official [Lark/Feishu](https://www.larksuite.com/) CLI tool, maintained by the [larksuite](https://github.com/larksuite) team — built for humans and AI Agents. Covers core business domains including Messenger, Docs, Base, Sheets, Slides, Calendar, Mail, Tasks, Meetings, Markdown, and more, with 200+ commands and 26 AI Agent [Skills](./skills/).
11+
> **Drive your Lark/Feishu workspace from Claude — read mail, summarize meetings, triage tasks, send messages, create docs, approve requests — in plain language, right inside Claude Desktop (Cowork) or claude.ai (web). No Claude Code, no copy-paste, no coding.**
1012
11-
[Install](#installation--quick-start) · [AI Agent Skills](#agent-skills) · [Auth](#authentication) · [Commands](#three-layer-command-system) · [Advanced](#advanced-usage) · [Security](#security--risk-warnings-read-before-use) · [Contributing](#contributing)
13+
This is `lark-cli` (the official [Lark/Feishu](https://www.larksuite.com/) CLI — 200+ commands across 18 business domains) **plus a built‑in MCP server** and a **Cowork skill kit**, so any [Claude](https://claude.ai) surface can operate Lark out of the box.
14+
15+
[🚀 Lark MCP](#-lark-mcp--use-lark-from-claude-desktop--web) · [Install](#installation--quick-start) · [21 MCP Tools](./docs/06-cong-cu-mcp.md) · [Cowork Skills](./docs/05-bo-skill-cowork.md) · [Full Docs](./docs/README.md) · [Security](#security--risk-warnings-read-before-use)
16+
17+
---
18+
19+
## 🚀 Lark MCP — use Lark from Claude Desktop & web
20+
21+
> **What's new in this build:** a native [MCP](https://modelcontextprotocol.io/) server (`lark-cli mcp serve`) that turns the CLI into **the hands of Claude** inside Lark — plus 23 ready‑made Cowork workflow skills. Built for **business users**, not just developers.
22+
23+
| | |
24+
| --- | --- |
25+
| 🧰 **21 curated MCP tools** | IM, Mail, Calendar, Docs, Base, Contact, Task, Drive, Sheets, Meetings, OKR + a generic `lark_api` escape hatch → [tool reference](./docs/06-cong-cu-mcp.md) |
26+
| 🖥️ **Claude Desktop (Cowork)** | Local **stdio** transport — one config block, restart, done → [desktop guide](./docs/02-cai-dat-claude-desktop.md) |
27+
| 🌐 **claude.ai (web)** | **Streamable‑HTTP** transport + Cloudflare Tunnel + built‑in **bearer‑token** gate → [web guide](./docs/03-ket-noi-web-claude-ai.md) |
28+
| 🧠 **23 Cowork skills** | `morning-brief`, `inbox-zero`, `meeting-prep`, `task-prioritizer`, `approval-triage`… speak naturally, Claude runs the chain → [skills](./docs/05-bo-skill-cowork.md) |
29+
| 🔐 **Safe by default** | Dry‑run on every write, mail saved as draft until confirmed, audit log, OS‑keychain credentials, bearer‑token + constant‑time check → [security](./docs/07-bao-mat-quyen-rieng-tu.md) |
30+
31+
### How it works
32+
33+
```
34+
You ──"What's on my plate today?"──▶ Claude (Desktop / Web)
35+
│ picks a tool + args
36+
▼
37+
lark-cli mcp serve (on your machine)
38+
│ runs lark-cli <verb> with YOUR auth
39+
▼
40+
open.larksuite.com / open.feishu.cn
41+
```
42+
43+
The MCP server spawns `lark-cli` subprocesses per tool call, reusing the existing auth, profile, and keychain — so **your data only ever goes to Lark**, never a third party (in stdio/local mode).
44+
45+
### 60‑second quick start (Claude Desktop)
46+
47+
```bash
48+
# 1. Build & install the binary (adds the `mcp` command)
49+
./scripts/setup-mcp.sh # installs to ~/bin/lark-cli
50+
lark-cli mcp tools # should list 21 tools
51+
52+
# 2. Log in to Lark once (browser OAuth, token stored in OS keychain)
53+
lark-cli auth login
54+
55+
# 3. Wire into Claude Desktop config, then restart Claude Desktop:
56+
# ~/Library/Application Support/Claude/claude_desktop_config.json
57+
```
58+
59+
```json
60+
{
61+
"mcpServers": {
62+
"lark-cli": {
63+
"command": "/absolute/path/to/lark-cli",
64+
"args": ["mcp", "serve"],
65+
"env": { "NO_COLOR": "1" }
66+
}
67+
}
68+
}
69+
```
70+
71+
Now ask Cowork: *"List my calendar today"* or *"Find the contact named Alice"*. → **Full step‑by‑step:** [docs/02](./docs/02-cai-dat-claude-desktop.md). **Web (claude.ai):** [docs/03](./docs/03-ket-noi-web-claude-ai.md).
72+
73+
### Expose to the web (claude.ai) — securely
74+
75+
```bash
76+
export LARK_MCP_BEARER_TOKEN=$(openssl rand -hex 32) # secret stays in env
77+
lark-cli mcp serve --transport http --addr 127.0.0.1:3000 --audit-log ~/.lark-mcp-audit.ndjson
78+
cloudflared tunnel --url http://127.0.0.1:3000 # → public HTTPS URL
79+
```
80+
81+
The HTTP endpoint enforces `Authorization: Bearer <token>` on `/` and `/mcp` (constant‑time, `/health` stays open). **Never expose the tunnel without the token.** Add the URL (`https://…/mcp`) as a Custom Connector in claude.ai → [secure web guide](./docs/03-ket-noi-web-claude-ai.md).
82+
83+
### 📚 MCP documentation (business‑user friendly)
84+
85+
| Doc | What |
86+
| --- | --- |
87+
| [docs/README](./docs/README.md) | Index + 3‑step start |
88+
| [01 — Overview & value](./docs/01-tong-quan.md) | Why MCP, ROI |
89+
| [02 — Claude Desktop setup](./docs/02-cai-dat-claude-desktop.md) | stdio, step‑by‑step |
90+
| [03 — claude.ai web setup](./docs/03-ket-noi-web-claude-ai.md) | HTTP + tunnel + bearer token |
91+
| [04 — Login & permissions](./docs/04-dang-nhap-va-quyen.md) | user/bot, scopes |
92+
| [05 — Cowork skills](./docs/05-bo-skill-cowork.md) | 23 workflows |
93+
| [06 — MCP tools](./docs/06-cong-cu-mcp.md) | 21 tools reference |
94+
| [07 — Security & privacy](./docs/07-bao-mat-quyen-rieng-tu.md) | bearer, audit, data flow |
95+
| [08 — Troubleshooting](./docs/08-xu-ly-su-co.md) | incl. known issues |
96+
| [09 — Update & maintenance](./docs/09-cap-nhat-bao-tri.md) | upgrades |
97+
| [30‑slide deck](./docs/SLIDE-DECK-30.md) | presentation prompts |
98+
| [MCP_QUICKSTART](./MCP_QUICKSTART.md) | all MCP hosts (Cursor, Zed, Cline…) |
99+
100+
> Building or extending tools? See [`cmd/mcp/README.md`](./cmd/mcp/README.md) for the bridge architecture and the `/mcp-add` workflow.
101+
102+
---
103+
104+
## Why lark-cli?
12105

13106
## Why lark-cli?
14107

‎README.vi.md‎

Lines changed: 188 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,188 @@
1+
# lark-mcp-cli — Lark/Feishu × Claude (MCP)
2+
3+
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
4+
[![Go Version](https://img.shields.io/badge/go-%3E%3D1.23-blue.svg)](https://go.dev/)
5+
[![MCP](https://img.shields.io/badge/MCP-stdio%20%2B%20http-7C3AED.svg)](#-lark-mcp--dùng-lark-ngay-trong-claude-desktop--web)
6+
[![Tools](https://img.shields.io/badge/MCP%20tools-21-0EA5E9.svg)](./docs/06-cong-cu-mcp.md)
7+
[![Cowork Skills](https://img.shields.io/badge/Cowork%20skills-23-F59E0B.svg)](./docs/05-bo-skill-cowork.md)
8+
9+
[English](./README.md) | **Tiếng Việt** | [中文版](./README.zh.md)
10+
11+
> **Điều khiển Lark/Feishu bằng Claude — đọc mail, tóm họp, dọn task, gửi tin nhắn, tạo doc, duyệt approval — bằng prompt tiếng Việt, ngay trong Claude Desktop (Cowork) hoặc claude.ai (web). Không cần Claude Code, không copy-paste, không cần biết lập trình.**
12+
13+
Đây là `lark-cli` (CLI chính thức của [Lark/Feishu](https://www.larksuite.com/) — 200+ lệnh, 18 nhóm nghiệp vụ) **kèm một MCP server tích hợp sẵn** và **bộ skill Cowork**, để mọi giao diện [Claude](https://claude.ai) thao tác Lark ngay lập tức.
14+
15+
[🚀 Lark MCP](#-lark-mcp--dùng-lark-ngay-trong-claude-desktop--web) · [Cài đặt](#cài-đặt-nhanh) · [21 công cụ MCP](./docs/06-cong-cu-mcp.md) · [Skill Cowork](./docs/05-bo-skill-cowork.md) · [Tài liệu đầy đủ](./docs/README.md) · [Bảo mật](./docs/07-bao-mat-quyen-rieng-tu.md)
16+
17+
---
18+
19+
## 🚀 Lark MCP — dùng Lark ngay trong Claude Desktop & web
20+
21+
> **Điểm mới của bản dựng này:** một MCP server gốc ([Model Context Protocol](https://modelcontextprotocol.io/)) — `lark-cli mcp serve` — biến CLI thành **tay chân của Claude** trong Lark, kèm 23 skill workflow Cowork. Hướng tới **business user**, không chỉ lập trình viên.
22+
23+
| | |
24+
| --- | --- |
25+
| 🧰 **21 công cụ MCP** | IM, Mail, Calendar, Docs, Base, Contact, Task, Drive, Sheets, Meetings, OKR + cửa thoát hiểm `lark_api` → [tham chiếu công cụ](./docs/06-cong-cu-mcp.md) |
26+
| 🖥️ **Claude Desktop (Cowork)** | Transport **stdio** local — 1 khối cấu hình, restart, xong → [hướng dẫn desktop](./docs/02-cai-dat-claude-desktop.md) |
27+
| 🌐 **claude.ai (web)** | Transport **HTTP streamable** + Cloudflare Tunnel + **bearer token** tích hợp → [hướng dẫn web](./docs/03-ket-noi-web-claude-ai.md) |
28+
| 🧠 **23 skill Cowork** | `morning-brief`, `inbox-zero`, `meeting-prep`, `task-prioritizer`, `approval-triage`… nói tự nhiên, Claude chạy cả chuỗi → [skill](./docs/05-bo-skill-cowork.md) |
29+
| 🔐 **An toàn mặc định** | Dry-run mọi thao tác ghi, mail lưu nháp tới khi xác nhận, audit log, token trong OS keychain, bearer-token so sánh constant-time → [bảo mật](./docs/07-bao-mat-quyen-rieng-tu.md) |
30+
31+
### Cách hoạt động
32+
33+
```
34+
Bạn ──"Sáng nay tôi có gì?"──▶ Claude (Desktop / Web)
35+
│ chọn công cụ + tham số
36+
▼
37+
lark-cli mcp serve (trên máy bạn)
38+
│ chạy lark-cli <verb> bằng auth CỦA BẠN
39+
▼
40+
open.larksuite.com / open.feishu.cn
41+
```
42+
43+
MCP server spawn subprocess `lark-cli` cho mỗi tool call, tái dùng auth/profile/keychain sẵn có → **data chỉ đi tới Lark**, không qua bên thứ ba (ở chế độ stdio/local).
44+
45+
### Khởi động 60 giây (Claude Desktop)
46+
47+
```bash
48+
# 1. Build & cài binary (thêm lệnh `mcp`)
49+
./scripts/setup-mcp.sh # cài vào ~/bin/lark-cli
50+
lark-cli mcp tools # phải liệt kê 21 tool
51+
52+
# 2. Đăng nhập Lark một lần (OAuth trình duyệt, token lưu OS keychain)
53+
lark-cli auth login
54+
55+
# 3. Khai báo vào file cấu hình Claude Desktop, rồi restart Claude Desktop:
56+
# ~/Library/Application Support/Claude/claude_desktop_config.json
57+
```
58+
59+
```json
60+
{
61+
"mcpServers": {
62+
"lark-cli": {
63+
"command": "/đường-dẫn-tuyệt-đối/tới/lark-cli",
64+
"args": ["mcp", "serve"],
65+
"env": { "NO_COLOR": "1" }
66+
}
67+
}
68+
}
69+
```
70+
71+
Giờ hỏi Cowork: *"Liệt kê lịch hôm nay của tôi"* hoặc *"Tìm liên hệ tên Nguyễn Văn A"*. → **Đầy đủ từng bước:** [docs/02](./docs/02-cai-dat-claude-desktop.md). **Web (claude.ai):** [docs/03](./docs/03-ket-noi-web-claude-ai.md).
72+
73+
### Mở ra web (claude.ai) — an toàn
74+
75+
```bash
76+
export LARK_MCP_BEARER_TOKEN=$(openssl rand -hex 32) # secret nằm trong biến môi trường
77+
lark-cli mcp serve --transport http --addr 127.0.0.1:3000 --audit-log ~/.lark-mcp-audit.ndjson
78+
cloudflared tunnel --url http://127.0.0.1:3000 # → URL HTTPS công khai
79+
```
80+
81+
Endpoint HTTP bắt buộc `Authorization: Bearer <token>` ở `/` và `/mcp` (so sánh constant-time, `/health` để mở cho liveness). **Tuyệt đối không mở tunnel khi chưa có token.** Thêm URL (`https://…/mcp`) làm Custom Connector trên claude.ai → [hướng dẫn web an toàn](./docs/03-ket-noi-web-claude-ai.md).
82+
83+
### 📚 Tài liệu MCP (cho business user)
84+
85+
| Tài liệu | Nội dung |
86+
| --- | --- |
87+
| [docs/README](./docs/README.md) | Mục lục + bắt đầu 3 bước |
88+
| [01 — Tổng quan & giá trị](./docs/01-tong-quan.md) | Vì sao MCP, ROI |
89+
| [02 — Cài Claude Desktop](./docs/02-cai-dat-claude-desktop.md) | stdio, từng bước |
90+
| [03 — Kết nối web claude.ai](./docs/03-ket-noi-web-claude-ai.md) | HTTP + tunnel + bearer token |
91+
| [04 — Đăng nhập & quyền](./docs/04-dang-nhap-va-quyen.md) | user/bot, scopes |
92+
| [05 — Skill Cowork](./docs/05-bo-skill-cowork.md) | 23 workflow |
93+
| [06 — Công cụ MCP](./docs/06-cong-cu-mcp.md) | tham chiếu 21 tool |
94+
| [07 — Bảo mật & riêng tư](./docs/07-bao-mat-quyen-rieng-tu.md) | bearer, audit, data flow |
95+
| [08 — Xử lý sự cố](./docs/08-xu-ly-su-co.md) | gồm sự cố đã biết |
96+
| [09 — Cập nhật & bảo trì](./docs/09-cap-nhat-bao-tri.md) | nâng cấp |
97+
| [Bộ 30 slide](./docs/SLIDE-DECK-30.md) | prompt thuyết trình |
98+
| [MCP_QUICKSTART](./MCP_QUICKSTART.md) | mọi MCP host (Cursor, Zed, Cline…) |
99+
100+
> Muốn xây/mở rộng tool? Xem [`cmd/mcp/README.md`](./cmd/mcp/README.md) cho kiến trúc bridge và quy trình `/mcp-add`.
101+
102+
---
103+
104+
## Vì sao chọn lark-cli?
105+
106+
- **Thiết kế Agent-Native** — bộ [Skill](./skills/) có cấu trúc, tương thích các công cụ AI phổ biến; Agent thao tác Lark không cần cấu hình thêm.
107+
- **Phủ rộng** — 18 nhóm nghiệp vụ, 200+ lệnh, kèm 23 skill Cowork + 21 công cụ MCP.
108+
- **Tối ưu cho AI** — mọi lệnh tham số gọn, default thông minh, output có cấu trúc để tăng tỉ lệ gọi thành công.
109+
- **Mã nguồn mở, không rào cản** — giấy phép MIT.
110+
- **Chạy trong vài phút** — tạo app, đăng nhập tương tác, từ cài tới lần gọi API đầu rất nhanh.
111+
- **An toàn, kiểm soát được** — chống injection input, làm sạch output terminal, lưu credential bằng keychain hệ điều hành.
112+
- **Kiến trúc 3 lớp** — Shortcuts (thân thiện người & AI) → API Commands (đồng bộ nền tảng) → Raw API (phủ toàn bộ).
113+
114+
## Năng lực theo nhóm
115+
116+
| Nhóm | Năng lực |
117+
| --- | --- |
118+
| 📅 Calendar | Xem/tạo/cập nhật lịch, mời người, đặt phòng họp, RSVP, tra free/busy |
119+
| 💬 Messenger | Gửi/trả lời tin, tạo & quản group, lịch sử & thread, tìm tin, tải media |
120+
| 📄 Docs | Tạo/đọc/sửa/tìm doc, media & whiteboard |
121+
| 📁 Drive | Upload/download file, tìm doc & wiki, quản lý comment |
122+
| 📊 Base | Bảng, field, record, view, dashboard, workflow, form, role; thống kê & phân tích |
123+
| 📈 Sheets | Tạo/đọc/ghi/append/tìm/export dữ liệu |
124+
| 🖼️ Slides | Tạo & quản presentation, đọc nội dung, thêm/xoá slide |
125+
| ✅ Tasks | Tạo/tra/cập nhật/hoàn tất task; cl.list, subtask, nhắc việc |
126+
| 📚 Wiki | Quản lý không gian tri thức, node, doc |
127+
| 👤 Contact | Tìm người theo tên/email/sđt, lấy hồ sơ |
128+
| 📧 Mail | Đọc/tìm/gửi/trả lời/forward, quản nháp, theo dõi mail mới |
129+
| 🎥 Meetings | Tìm bản ghi họp, truy minutes & recording |
130+
| ✍️ Approval | Tra/duyệt/từ chối/chuyển task, huỷ & CC instance |
131+
| 🎯 OKR | Tra/tạo/cập nhật OKR; objective, key result, tiến độ |
132+
133+
## Cài đặt nhanh
134+
135+
### Yêu cầu
136+
137+
- Node.js (`npm`/`npx`)
138+
- Go `v1.23`+ và Python 3 (chỉ cần khi build từ mã nguồn)
139+
140+
### Build từ mã nguồn (kèm lệnh MCP)
141+
142+
```bash
143+
make build # tạo ./lark-cli
144+
./scripts/setup-mcp.sh # cài vào ~/bin/lark-cli + verify 21 tool
145+
lark-cli config init # cấu hình app (tương tác, 1 lần)
146+
lark-cli auth login # đăng nhập
147+
```
148+
149+
> Hướng dẫn cài cho **business user** (không cần dev) — desktop & web: xem [docs/](./docs/README.md).
150+
151+
## Đăng nhập
152+
153+
```bash
154+
lark-cli auth login # đăng nhập tương tác (TUI chọn domain & mức quyền)
155+
lark-cli auth login --recommend # tự chọn các scope thường dùng
156+
lark-cli auth status # kiểm tra user/bot
157+
lark-cli <lệnh> --as user|bot # chọn danh tính khi chạy lệnh
158+
```
159+
160+
Chi tiết user vs bot, scope, app riêng cho enterprise: [docs/04](./docs/04-dang-nhap-va-quyen.md).
161+
162+
## Hệ thống lệnh 3 lớp
163+
164+
1. **Shortcuts** — 1 lệnh gói nhiều API, thân thiện người & AI (ví dụ `im +messages-send`, `mail +triage`).
165+
2. **API Commands** — 1 lệnh = 1 API, tham số có cấu trúc (`im chats search`…).
166+
3. **Raw API** — tương đương curl, phủ toàn bộ (`lark-cli api POST /open-apis/...`).
167+
168+
AI tự chọn lớp phù hợp dựa vào skill. (Bản tiếng Anh có ví dụ đầy đủ: [README.md](./README.md#three-layer-command-system).)
169+
170+
## Bảo mật & cảnh báo (đọc trước khi dùng)
171+
172+
- Mọi thao tác **ghi** có **dry-run** xem trước; **mail mặc định lưu nháp** (cần `confirm_send=true` mới gửi).
173+
- Token nằm trong **OS keychain**; secret (bearer token) truyền qua **biến môi trường** `LARK_MCP_BEARER_TOKEN`.
174+
- **Mở cổng web = phơi toàn quyền tài khoản Lark** → bắt buộc bật bearer token và/hoặc Cloudflare Access; bật `--audit-log`.
175+
- Chống injection input, làm sạch output terminal.
176+
177+
Đầy đủ: [docs/07 — Bảo mật & quyền riêng tư](./docs/07-bao-mat-quyen-rieng-tu.md).
178+
179+
## Đóng góp
180+
181+
Hoan nghênh đóng góp! Mở [Issue](https://github.com/pluginmd/lark-mcp-cli/issues) hoặc [Pull Request](https://github.com/pluginmd/lark-mcp-cli/pulls). Trước khi mở PR, xem [AGENTS.md](./AGENTS.md) cho quy trình build/test/checklist.
182+
183+
## Giấy phép
184+
185+
Dự án theo giấy phép **MIT**. Là sản phẩm phái sinh từ [larksuite/cli](https://github.com/larksuite/cli) (cũng MIT). Khi chạy, công cụ gọi API Lark/Feishu Open Platform — bạn phải tuân thủ điều khoản & chính sách của Lark/Feishu:
186+
187+
- [Feishu User Terms](https://www.feishu.cn/terms) · [Feishu Privacy](https://www.feishu.cn/privacy)
188+
- [Lark User Terms](https://www.larksuite.com/user-terms-of-service) · [Lark Privacy](https://www.larksuite.com/privacy-policy)

0 commit comments

Comments
 (0)