@yoreland/lark-cli-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 yoreland
+
+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,135 @@
+# @yoreland/lark-cli-mcp
+
+> One-line `npx` MCP server that lets AI clients (Amazon Quick Desktop, Claude Desktop, …) operate **Feishu / Lark as your own user identity** — send, read, reply, and search messages.
+
+It wraps the official [`lark-cli`](https://github.com/larksuite/cli) (bundled as a dependency, no separate install) and exposes 7 messaging tools over MCP stdio. Because every call runs with `--as user`, the sender shown in Feishu is **you**, not a bot.
+
+---
+
+## Quick start (for workshop attendees)
+
+```bash
+# 1) Log in once (OAuth device flow — opens a URL / shows a QR code)
+npx -y @yoreland/lark-cli-mcp auth
+
+# 2) Sanity check
+npx -y @yoreland/lark-cli-mcp doctor
+```
+
+Then add the MCP server in your client:
+
+| Field        | Value                          |
+| ------------ | ------------------------------ |
+| Connection   | Local (stdio)                  |
+| Command      | `npx`                          |
+| Arguments    | `-y @yoreland/lark-cli-mcp`    |
+
+You should see **7 tools · Connected** ✅
+
+> Quick Desktop tip: arguments are space-split. `-y @yoreland/lark-cli-mcp` is fine (no spaces inside the package name).
+
+---
+
+## Prerequisites
+
+- **Node.js v18+** (`node -v`)
+- An MCP client (Amazon Quick Desktop / Claude Desktop / etc.)
+- A Feishu/Lark account in the org running the workshop
+- Network access to npm registry and Feishu OAuth
+
+The Feishu **App ID / Secret** is provided centrally by the workshop host and baked into the shared `lark-cli` config — attendees only do the OAuth login step. (See [Host setup](#host-setup).)
+
+> Behind the Great Firewall? Use a mirror: `npm config set registry https://registry.npmmirror.com`
+
+---
+
+## Commands
+
+```bash
+npx -y @yoreland/lark-cli-mcp            # start MCP server (stdio) — what the client runs
+npx -y @yoreland/lark-cli-mcp auth       # OAuth device-flow login (user identity)
+npx -y @yoreland/lark-cli-mcp status     # show auth status
+npx -y @yoreland/lark-cli-mcp logout     # clear token
+npx -y @yoreland/lark-cli-mcp doctor     # environment + login self-check
+npx -y @yoreland/lark-cli-mcp -- <args>  # passthrough to bundled lark-cli
+```
+
+---
+
+## The 7 tools
+
+| Tool                     | What it does            | lark-cli command                       |
+| ------------------------ | ----------------------- | -------------------------------------- |
+| `feishu_send_message`    | Send a message          | `im +messages-send --as user`          |
+| `feishu_get_messages`    | Read recent messages    | `im +chat-messages-list --as user`     |
+| `feishu_reply_message`   | Reply (thread optional) | `im +messages-reply --as user`         |
+| `feishu_search_messages` | Search messages         | `im +messages-search --as user`        |
+| `feishu_list_chats`      | Find group chats        | `im +chat-search --as user`            |
+| `feishu_search_user`     | Find a user (→ open_id) | `contact +search-user --as user`       |
+| `feishu_get_thread`      | View a thread           | `im +threads-messages-list --as user`  |
+
+### Talk to it naturally
+
+| Goal            | Say to your assistant                       |
+| --------------- | ------------------------------------------- |
+| Read a group    | "看看 XX 群最近聊了什么"                      |
+| Send            | "在 XX 群说：明天会议改到 3 点"               |
+| Reply           | "回复那条消息：收到，我来跟进"                |
+| Search          | "搜一下谁提过客户报价"                        |
+| Find someone    | "帮我找一下张三的 open_id"                    |
+| View a thread   | "看看那条消息下面的讨论"                      |
+
+---
+
+## Host setup
+
+The workshop host creates **one** Feishu custom app and configures it so attendees share the same App ID/Secret but each authorize their own account.
+
+1. [Feishu Open Platform](https://open.feishu.cn) → create an internal custom app → note **App ID / App Secret**.
+2. Enable **User token scopes** matching the `im`, `contact`, `search` domains (message read/write, reply, chat read, user search, message search).
+3. Distribute the App ID/Secret to attendees via `lark-cli config` (or a pre-bound config). The login step requests scopes via `--domain im,contact,search`.
+
+`auth` uses **OAuth Device Flow**, so no `redirect URL` / `localhost:3000` callback configuration is required.
+
+---
+
+## Troubleshooting
+
+**`missing required scope(s)`** — re-login with the needed domain:
+```bash
+npx -y @yoreland/lark-cli-mcp auth --domain im,contact,search
+```
+
+**Client shows "No tools loaded"** — run `npx -y @yoreland/lark-cli-mcp doctor`; confirm Node ≥18 and that `auth status` is OK.
+
+**Token expired** — just re-run `auth`.
+
+---
+
+## Known limitations
+
+- No image/file attachment sending (text + markdown only)
+- No interactive cards
+- No group creation
+- Tokens expire; re-run `auth` when they do
+
+---
+
+## How it works
+
+```
+MCP client (Quick Desktop / Claude Desktop)
+    │  stdio (MCP / JSON-RPC)
+    ▼
+@yoreland/lark-cli-mcp  (server.mjs)
+    │  child_process.execFile (no shell → injection-safe)
+    ▼
+lark-cli --as user   (bundled dependency)
+    │  OAuth user_access_token (device flow)
+    ▼
+Feishu / Lark Open API
+```
+
+## License
+
+MIT

package/bin/cli.mjs

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+/**
+ * @yoreland/lark-cli-mcp — CLI entry point (npx target)
+ *
+ *   npx @yoreland/lark-cli-mcp            # start the MCP server (stdio)
+ *   npx @yoreland/lark-cli-mcp auth       # OAuth device-flow login (as user)
+ *   npx @yoreland/lark-cli-mcp status     # show auth status
+ *   npx @yoreland/lark-cli-mcp doctor     # environment self-check
+ *   npx @yoreland/lark-cli-mcp -- <args>  # passthrough to bundled lark-cli
+ *
+ * Designed so workshop attendees never install lark-cli separately:
+ * the bundled binary ships as a dependency of this package.
+ */
+import { spawn } from "node:child_process";
+import { createRequire } from "node:module";
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// Default scopes for a Feishu messaging workshop (user identity).
+// `im` domain covers send/read/reply; `contact` for user search;
+// `search` for cross-chat message search.
+const DEFAULT_DOMAINS = "im,contact,search";
+
+function resolveLarkCli() {
+  if (process.env.LARK_CLI_BIN && existsSync(process.env.LARK_CLI_BIN)) {
+    return process.env.LARK_CLI_BIN;
+  }
+  try {
+    const require = createRequire(import.meta.url);
+    const pkgJson = require.resolve("@larksuite/cli/package.json");
+    const binDir = join(dirname(pkgJson), "..", "..", ".bin");
+    const candidate = join(
+      binDir,
+      process.platform === "win32" ? "lark-cli.cmd" : "lark-cli"
+    );
+    if (existsSync(candidate)) return candidate;
+  } catch {
+    /* fall through */
+  }
+  return "lark-cli";
+}
+
+const LARK_CLI = resolveLarkCli();
+
+function runLark(args, opts = {}) {
+  return new Promise((resolve) => {
+    const child = spawn(LARK_CLI, args, { stdio: "inherit", ...opts });
+    child.on("exit", (code) => resolve(code ?? 0));
+    child.on("error", (err) => {
+      console.error(`无法运行 lark-cli (${LARK_CLI}): ${err.message}`);
+      resolve(1);
+    });
+  });
+}
+
+function startServer() {
+  const serverPath = join(__dirname, "..", "server.mjs");
+  const child = spawn(process.execPath, [serverPath], { stdio: "inherit" });
+  child.on("exit", (code) => process.exit(code ?? 0));
+  child.on("error", (err) => {
+    console.error(`MCP server 启动失败: ${err.message}`);
+    process.exit(1);
+  });
+}
+
+async function main() {
+  const [cmd, ...rest] = process.argv.slice(2);
+
+  switch (cmd) {
+    case undefined:
+    case "serve":
+    case "start":
+      startServer();
+      return;
+
+    case "auth":
+    case "login": {
+      // Allow override: `... auth --domain im,calendar` or `... auth --scope "..."`
+      const hasScopeArg = rest.some(
+        (a) => a === "--scope" || a === "--domain" || a === "--recommend"
+      );
+      const args = ["auth", "login"];
+      if (hasScopeArg) args.push(...rest);
+      else args.push("--domain", DEFAULT_DOMAINS, ...rest);
+      console.error(
+        `\n🔑 飞书 OAuth 登录（用户身份，scopes domains: ${
+          hasScopeArg ? "(custom)" : DEFAULT_DOMAINS
+        }）`
+      );
+      console.error("   浏览器/二维码授权后即可使用。\n");
+      process.exit(await runLark(args));
+      return;
+    }
+
+    case "status":
+      process.exit(await runLark(["auth", "status", ...rest]));
+      return;
+
+    case "logout":
+      process.exit(await runLark(["auth", "logout", ...rest]));
+      return;
+
+    case "doctor": {
+      console.log("🩺 lark-cli-mcp 环境自检\n");
+      console.log(`Node:      ${process.version}`);
+      console.log(`Platform:  ${process.platform}/${process.arch}`);
+      console.log(`lark-cli:  ${LARK_CLI}`);
+      console.log(`  exists:  ${existsSync(LARK_CLI) || LARK_CLI === "lark-cli"}`);
+      console.log("\n检查登录状态:\n");
+      const code = await runLark(["auth", "status"]);
+      console.log(
+        code === 0
+          ? "\n✅ 看起来已登录。现在可在 MCP 客户端用 `npx @yoreland/lark-cli-mcp` 启动。"
+          : "\n⚠️  未登录。请先运行：npx @yoreland/lark-cli-mcp auth"
+      );
+      process.exit(code);
+      return;
+    }
+
+    case "--":
+      // Passthrough to bundled lark-cli
+      process.exit(await runLark(rest));
+      return;
+
+    case "-h":
+    case "--help":
+    case "help":
+      printHelp();
+      return;
+
+    default:
+      // Unknown -> passthrough to lark-cli for power users
+      process.exit(await runLark([cmd, ...rest]));
+  }
+}
+
+function printHelp() {
+  console.log(`@yoreland/lark-cli-mcp — Feishu/Lark MCP server (user identity)
+
+USAGE
+  npx @yoreland/lark-cli-mcp              启动 MCP server (stdio) — 给 MCP 客户端用
+  npx @yoreland/lark-cli-mcp auth         OAuth 设备码登录（用户身份）
+  npx @yoreland/lark-cli-mcp status       查看登录状态
+  npx @yoreland/lark-cli-mcp logout       退出登录
+  npx @yoreland/lark-cli-mcp doctor       环境与登录自检
+  npx @yoreland/lark-cli-mcp -- <args>    透传给底层 lark-cli
+
+MCP 客户端配置 (Quick Desktop / Claude Desktop):
+  Command:   npx
+  Arguments: -y @yoreland/lark-cli-mcp
+
+更多: https://github.com/yoreland/lark-cli-mcp`);
+}
+
+main();

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@yoreland/lark-cli-mcp",
+  "version": "1.0.0",
+  "description": "MCP server that wraps lark-cli to operate Feishu/Lark as your own user identity (send/read/reply/search messages). Designed for one-line npx launch.",
+  "type": "module",
+  "bin": {
+    "lark-cli-mcp": "./bin/cli.mjs"
+  },
+  "main": "./server.mjs",
+  "files": [
+    "server.mjs",
+    "bin/cli.mjs",
+    "README.md"
+  ],
+  "scripts": {
+    "start": "node server.mjs"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "feishu",
+    "lark",
+    "lark-cli",
+    "larksuite"
+  ],
+  "author": "yoreland",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yoreland/lark-cli-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/yoreland/lark-cli-mcp/issues"
+  },
+  "homepage": "https://github.com/yoreland/lark-cli-mcp#readme",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@larksuite/cli": "^1.0.47"
+  }
+}

package/server.mjs

@@ -0,0 +1,269 @@
+#!/usr/bin/env node
+/**
+ * @yoreland/lark-cli-mcp — MCP server
+ *
+ * Wraps the official `lark-cli` (Feishu/Lark CLI) and exposes message
+ * operations as MCP tools. All actions run with `--as user`, so messages
+ * are sent/read as the logged-in human, not as a bot.
+ *
+ * The bundled `lark-cli` binary (a dependency of this package) is resolved
+ * automatically, so end users only need `npx @yoreland/lark-cli-mcp`.
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { createRequire } from "node:module";
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const execFileAsync = promisify(execFile);
+
+/**
+ * Resolve the lark-cli executable.
+ * Priority:
+ *   1. LARK_CLI_BIN env override
+ *   2. bundled binary inside this package's node_modules (.bin)
+ *   3. fall back to "lark-cli" on PATH (global install)
+ */
+function resolveLarkCli() {
+  if (process.env.LARK_CLI_BIN && existsSync(process.env.LARK_CLI_BIN)) {
+    return process.env.LARK_CLI_BIN;
+  }
+  try {
+    const require = createRequire(import.meta.url);
+    // Locate the package, then walk to the .bin shim.
+    const pkgJson = require.resolve("@larksuite/cli/package.json");
+    const pkgDir = dirname(pkgJson);
+    // node_modules/@larksuite/cli -> node_modules/.bin/lark-cli
+    const binDir = join(pkgDir, "..", "..", ".bin");
+    const candidate = join(
+      binDir,
+      process.platform === "win32" ? "lark-cli.cmd" : "lark-cli"
+    );
+    if (existsSync(candidate)) return candidate;
+  } catch {
+    /* ignore — fall through to PATH */
+  }
+  return "lark-cli";
+}
+
+const LARK_CLI = resolveLarkCli();
+
+const server = new Server(
+  { name: "lark-cli-mcp", version: "1.0.0" },
+  { capabilities: { tools: {} } }
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [
+    {
+      name: "feishu_send_message",
+      description:
+        "以用户身份发送飞书/Lark 消息到群聊或个人（支持纯文本与 Markdown）",
+      inputSchema: {
+        type: "object",
+        properties: {
+          chat_id: { type: "string", description: "群聊 ID（oc_xxx）" },
+          user_id: {
+            type: "string",
+            description: "用户 open_id（ou_xxx），发私聊",
+          },
+          text: { type: "string", description: "纯文本消息内容" },
+          markdown: {
+            type: "string",
+            description: "Markdown 消息内容（与 text 二选一）",
+          },
+        },
+      },
+    },
+    {
+      name: "feishu_get_messages",
+      description: "查看群聊或私聊的最近消息记录",
+      inputSchema: {
+        type: "object",
+        properties: {
+          chat_id: { type: "string", description: "群聊 ID（oc_xxx）" },
+          user_id: { type: "string", description: "用户 open_id（查私聊）" },
+          count: { type: "number", description: "消息数量，默认 20" },
+          start_time: { type: "string", description: "起始时间（Unix 秒）" },
+          end_time: { type: "string", description: "结束时间（Unix 秒）" },
+        },
+      },
+    },
+    {
+      name: "feishu_reply_message",
+      description: "回复某条飞书消息（支持线程回复）",
+      inputSchema: {
+        type: "object",
+        properties: {
+          message_id: { type: "string", description: "消息 ID（om_xxx）" },
+          text: { type: "string", description: "回复内容" },
+          in_thread: { type: "boolean", description: "是否线程回复" },
+        },
+        required: ["message_id", "text"],
+      },
+    },
+    {
+      name: "feishu_search_messages",
+      description: "跨群搜索飞书消息（用户身份）",
+      inputSchema: {
+        type: "object",
+        properties: {
+          keyword: { type: "string", description: "搜索关键词" },
+          chat_id: { type: "string", description: "限定群（可选）" },
+          start_time: { type: "string", description: "起始时间（Unix 秒）" },
+          end_time: { type: "string", description: "结束时间（Unix 秒）" },
+        },
+        required: ["keyword"],
+      },
+    },
+    {
+      name: "feishu_list_chats",
+      description: "搜索飞书群聊列表（按关键词找 chat_id）",
+      inputSchema: {
+        type: "object",
+        properties: {
+          keyword: { type: "string", description: "搜索关键词（可选）" },
+        },
+      },
+    },
+    {
+      name: "feishu_search_user",
+      description: "按名字/邮箱搜索飞书用户，拿到 open_id",
+      inputSchema: {
+        type: "object",
+        properties: {
+          query: { type: "string", description: "用户名字或邮箱" },
+        },
+        required: ["query"],
+      },
+    },
+    {
+      name: "feishu_get_thread",
+      description: "查看某条消息的完整线程讨论",
+      inputSchema: {
+        type: "object",
+        properties: {
+          message_id: { type: "string", description: "消息/线程 ID（om_/omt_）" },
+          count: { type: "number", description: "回复数量，默认 50" },
+        },
+        required: ["message_id"],
+      },
+    },
+  ],
+}));
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args = {} } = request.params;
+  try {
+    switch (name) {
+      case "feishu_send_message": {
+        const { chat_id, user_id, text, markdown } = args;
+        if (!chat_id && !user_id) return error("需要 chat_id 或 user_id");
+        if (!text && !markdown) return error("需要 text 或 markdown");
+        const cmd = ["im", "+messages-send", "--as", "user"];
+        if (chat_id) cmd.push("--chat-id", chat_id);
+        else cmd.push("--user-id", user_id);
+        if (markdown) cmd.push("--markdown", markdown);
+        else cmd.push("--text", text);
+        return await run(cmd);
+      }
+      case "feishu_get_messages": {
+        const { chat_id, user_id, count, start_time, end_time } = args;
+        if (!chat_id && !user_id) return error("需要 chat_id 或 user_id");
+        const cmd = ["im", "+chat-messages-list", "--as", "user"];
+        if (chat_id) cmd.push("--chat-id", chat_id);
+        else cmd.push("--user-id", user_id);
+        if (count) cmd.push("--page-size", String(count));
+        if (start_time) cmd.push("--start-time", start_time);
+        if (end_time) cmd.push("--end-time", end_time);
+        return await run(cmd);
+      }
+      case "feishu_reply_message": {
+        const { message_id, text, in_thread } = args;
+        const cmd = [
+          "im",
+          "+messages-reply",
+          "--as",
+          "user",
+          "--message-id",
+          message_id,
+          "--text",
+          text,
+        ];
+        if (in_thread === true) cmd.push("--reply-in-thread");
+        return await run(cmd);
+      }
+      case "feishu_search_messages": {
+        const { keyword, chat_id, start_time, end_time } = args;
+        const cmd = [
+          "im",
+          "+messages-search",
+          "--as",
+          "user",
+          "--query",
+          keyword,
+        ];
+        if (chat_id) cmd.push("--chat-id", chat_id);
+        if (start_time) cmd.push("--start-time", start_time);
+        if (end_time) cmd.push("--end-time", end_time);
+        return await run(cmd);
+      }
+      case "feishu_list_chats": {
+        const { keyword } = args;
+        const cmd = ["im", "+chat-search", "--as", "user"];
+        if (keyword) cmd.push("--query", keyword);
+        return await run(cmd);
+      }
+      case "feishu_search_user": {
+        const { query } = args;
+        return await run([
+          "contact",
+          "+search-user",
+          "--as",
+          "user",
+          "--query",
+          query,
+        ]);
+      }
+      case "feishu_get_thread": {
+        const { message_id, count } = args;
+        const cmd = [
+          "im",
+          "+threads-messages-list",
+          "--as",
+          "user",
+          "--thread",
+          message_id,
+        ];
+        if (count) cmd.push("--page-size", String(count));
+        return await run(cmd);
+      }
+      default:
+        return error(`未知工具: ${name}`);
+    }
+  } catch (err) {
+    return error(`执行失败: ${err.message}\n${err.stderr || ""}`);
+  }
+});
+
+async function run(cmdArgs) {
+  const { stdout, stderr } = await execFileAsync(LARK_CLI, cmdArgs, {
+    timeout: 60000,
+    maxBuffer: 1024 * 1024 * 5,
+  });
+  return { content: [{ type: "text", text: stdout || stderr || "(no output)" }] };
+}
+
+function error(msg) {
+  return { content: [{ type: "text", text: msg }], isError: true };
+}
+
+const transport = new StdioServerTransport();
+await server.connect(transport);