happycapy-ai 飞书 MCP 安装向导
首先询问用户： 你是否已经有飞书应用的 App ID 和 App Secret？
- 有的话：直接告知你，Claude 立即进入第二步执行安装和 OAuth 授权。
- 没有的话：按第一步引导用户创建应用。
第一步：引导用户创建飞书应用（仅在用户没有凭证时执行）
告知用户按以下步骤操作，完成后把 App ID 和 App Secret 发给你：
- 打开 https://open.feishu.cn/app 并登录
- 右上角点击创建应用 → 自建应用，填写任意名称（如
Claude MCP） - 进入应用后，凭证与基础信息页面找到 App ID 和 App Secret
- 左侧菜单进入安全设置 → 重定向 URL → 添加：
http://localhost:3000/callback - 左侧菜单进入权限管理 → 右上角点击批量导入权限 → 粘贴以下 JSON 后确认导入：
重要： 每次引导用户时，必须读取
assets/feishu-permissions.json并将其完整内容全量输出，不得省略、截断或用省略号代替任何内容。
左侧菜单进入添加应用能力 → 务必开启 机器人 能力
左侧菜单进入事件与回调 → 事件配置：
- 请求方式选择：使用长连接接收事件（无需公网服务器）
- 点击添加事件，搜索
im.message.receive_v1（接收消息），勾选添加
左侧菜单进入版本管理与发布，创建版本并发布（内部测试版即可）
第二步：自动安装配置（收到凭证后 Claude 执行）
2.1 注册 MCP 到全局配置
直接编辑 ~/.claude.json，向其中写入 mcpServers 字段（保留已有内容）：
python3 -c "
import json, os
f = os.path.expanduser('~/.claude.json')
with open(f) as fp:
cfg = json.load(fp)
cfg.setdefault('mcpServers', {})['lark-mcp'] = {
'command': 'npx',
'args': ['-y', '@larksuiteoapi/lark-mcp', 'mcp',
'-a', '<APP_ID>', '-s', '<APP_SECRET>',
'--oauth',
'--tools', 'preset.default,im.v1.message.reply,im.v1.message.get,im.v1.message.patch,im.v1.message.delete,im.v1.chat.get,im.v1.chat.search']
}
with open(f, 'w') as fp:
json.dump(cfg, fp, indent=2, ensure_ascii=False)
print('MCP 注册完成')
"
2.2 定位 lark-mcp 缓存目录（后续步骤共用）
无桌面 Linux 环境中 keytar 依赖 dbus-launch，导致 token 只存内存、重启即丢失。先触发下载并定位目录：
# 触发一次确保包已下载
npx -y @larksuiteoapi/lark-mcp --version 2>/dev/null || true
# 定位缓存目录，后续 2.3 和 2.4 共用此变量
LARK_DIR=$(find ~/.npm/_npx -name "package.json" 2>/dev/null \
| xargs grep -l '"@larksuiteoapi/lark-mcp"' 2>/dev/null \
| grep -v node_modules | head -1 | xargs dirname)
echo "LARK_DIR: $LARK_DIR"
2.3 修复 headless 环境 token 持久化（替换 keytar 为文件存储）
使用 skill 内置的预置文件替换 keytar（token 保存在 ~/.lark-mcp-keychain.json）：
KEYTAR_PATH="$LARK_DIR/node_modules/keytar/lib/keytar.js"
cp "$KEYTAR_PATH" "${KEYTAR_PATH}.bak"
cp ~/.claude/skills/happycapy-feishu/assets/keytar-file-storage.js "$KEYTAR_PATH"
echo "keytar 替换完成: $KEYTAR_PATH"
2.4 延长 OAuth 超时至 5 分钟
lark-mcp 有两处独立超时需要同时修改，必须用 perl -i 而非 sed -i（后者在此环境会截断文件）：
# 修复 handler-local.js（HTTP 服务器超时）
HANDLER="$LARK_DIR/node_modules/@larksuiteoapi/lark-mcp/dist/auth/handler/handler-local.js"
perl -i -pe 's/this\.stopServer\(\), 60 \* 1000/this.stopServer(), 300 * 1000/g' "$HANDLER"
# 修复 login-handler.js（token 轮询超时）
LOGIN_HANDLER="$LARK_DIR/node_modules/@larksuiteoapi/lark-mcp/dist/cli/login-handler.js"
perl -i -pe 's/timeout = 60000/timeout = 300000/g' "$LOGIN_HANDLER"
echo "handler-local: $(grep -o '[0-9]* \* 1000' $HANDLER)"
echo "login-handler: $(grep -o 'timeout = [0-9]*' $LOGIN_HANDLER)"
第三步：OAuth 授权（用户只需做一个操作）
3.1 启动 login 进程，获取 code_challenge
kill $(lsof -ti:3000) 2>/dev/null; sleep 1
nohup npx -y @larksuiteoapi/lark-mcp login \
-a <APP_ID> -s <APP_SECRET> > /tmp/lark-oauth.log 2>&1 &
sleep 5 && cat /tmp/lark-oauth.log
从日志的 Authorization URL 中提取 code_challenge= 后面的值。
3.2 服务端 curl /authorize（必须执行，存储 PKCE 状态）
跳过此步会导致 callback 时报错
PKCE validation failed: code challenge not found
FEISHU_URL=$(curl -s -w "%{redirect_url}" -o /dev/null \
"http://localhost:3000/authorize?client_id=client_id_for_local_auth&response_type=code&code_challenge=<CODE_CHALLENGE>&code_challenge_method=S256&redirect_uri=http%3A%2F%2Flocalhost%3A3000%2Fcallback&state=reauthorize")
echo "$FEISHU_URL"
3.3 让用户完成授权
把上一步输出的 https://open.feishu.cn/... 链接发给用户，明确告知以下三点：
第一步： 在浏览器打开上面的链接，用飞书账号登录并点击授权。
第二步： 授权完成后，浏览器会自动跳转到一个以
http://localhost:3000/callback?code=...开头的地址，并显示"无法访问此网站"或"连接被拒绝"的错误页面——这是完全正常的，不要关闭页面。第三步： 忽略错误提示，直接复制浏览器地址栏的完整 URL（以
http://localhost:3000/callback开头），粘贴发给我。
3.4 收到 callback URL 后立即提交
curl -s "<用户发来的完整 URL>"
# 返回 "success, you can close this page now" 即成功
3.5 验证
npx -y @larksuiteoapi/lark-mcp whoami