feishu-user-plugin 1.3.0 → 1.3.1

package/README.md

@@ -3,22 +3,25 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18-green.svg)](https://nodejs.org)
 [![MCP](https://img.shields.io/badge/MCP-Compatible-purple.svg)](https://modelcontextprotocol.io)
-[![Tools](https://img.shields.io/badge/Tools-33-orange.svg)](#tools-33-total)
+[![Tools](https://img.shields.io/badge/Tools-76-orange.svg)](#tools)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
 
-**All-in-one Feishu/Lark MCP Server -- 33 tools, 9 skills, 3 auth layers for messaging, docs, tables, wiki, and drive.**
+**All-in-one Feishu/Lark MCP Server -- 76 tools, 9 skills, 3 auth layers for messaging, docs, bitable, calendar, tasks, drive, and more.**
 
-The only MCP server that lets you send messages as your **personal identity** (not a bot), while also integrating the full official Feishu API for documents, spreadsheets, wikis, and more.
+The only MCP server that lets you send messages as your **personal identity** (not a bot), while also integrating the full official Feishu API. Works with Claude Code, Cursor, Windsurf, OpenClaw, and any MCP-compatible client.
 
 ## Highlights
 
 - **Send as yourself** -- Messages show your real name, not a bot. Supports text, rich text, images, files, stickers, and audio.
 - **Read everything** -- Group chats via bot API, P2P (direct messages) via OAuth UAT.
-- **Full Feishu suite** -- Docs, Bitable (spreadsheets), Wiki, Drive, Contacts -- all in one plugin.
-- **3 auth layers** -- Cookie-based user identity, app credentials (Official API), and OAuth UAT (P2P reading). All three are needed for full functionality.
+- **Full Feishu suite** -- Docs, Bitable, Wiki, Drive, Calendar, Tasks, Contacts -- all in one plugin.
+- **3 auth layers** -- Cookie-based user identity, app credentials (Official API), and OAuth UAT (P2P reading).
+- **Group management** -- Create groups, add/remove members, pin messages, emoji reactions.
+- **Document editing** -- Not just read/create, but insert/update/delete content blocks.
+- **Calendar & Tasks** -- Create events, check free/busy, manage tasks.
 - **9 slash commands** for Claude Code -- `/send`, `/reply`, `/search`, `/digest`, `/doc`, `/table`, `/wiki`, `/drive`, `/status`
 - **Auto session management** -- Cookie heartbeat every 4h, UAT auto-refresh with token rotation.
-- **Chat name resolution** -- Pass a group name instead of `oc_xxx` ID; it resolves automatically.
+- **Multi-platform** -- Claude Code, Cursor, Windsurf, VS Code, OpenClaw.
 
 ## Why This Exists
 
@@ -284,6 +287,34 @@ Add to `.vscode/mcp.json` in your project:
 }
 ```
 
+### OpenClaw
+
+Add to `~/.openclaw/openclaw.json` (note: key path is `mcp.servers`, not `mcpServers`):
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "feishu-user-plugin": {
+        "command": "npx",
+        "args": ["-y", "feishu-user-plugin"],
+        "env": {
+          "LARK_COOKIE": "your-cookie-string",
+          "LARK_APP_ID": "cli_xxxxxxxxxxxx",
+          "LARK_APP_SECRET": "your-app-secret",
+          "LARK_USER_ACCESS_TOKEN": "your-uat",
+          "LARK_USER_REFRESH_TOKEN": "your-refresh-token"
+        }
+      }
+    }
+  }
+}
+```
+
+Or via CLI: `openclaw mcp set feishu-user-plugin '{"command":"npx","args":["-y","feishu-user-plugin"],"env":{...}}'`
+
+> OpenClaw's built-in Feishu channel handles receiving messages (bot identity). This plugin adds user identity messaging + docs/bitable/calendar/tasks.
+
 ### Windsurf
 
 Add to `~/.codeium/windsurf/mcp_config.json`:
@@ -306,86 +337,119 @@ Add to `~/.codeium/windsurf/mcp_config.json`:
 }
 ```
 
-## Tools (33 total)
+## Tools (76 total)
 
-### User Identity -- Messaging (cookie auth, Protobuf)
-
-Send messages as yourself, not as a bot.
+### User Identity -- Messaging (8 tools, cookie auth)
 
 | Tool | Description |
 |------|-------------|
 | `send_to_user` | Search user by name + send text -- one step |
 | `send_to_group` | Search group by name + send text -- one step |
-| `send_as_user` | Send text to any chat by ID, supports reply threading (`root_id` / `parent_id`) |
-| `send_image_as_user` | Send image (requires `image_key` from upload) |
-| `send_file_as_user` | Send file (requires `file_key` from upload) |
-| `send_post_as_user` | Send rich text with title + formatted paragraphs (links, @mentions) |
+| `send_as_user` | Send text to any chat by ID, supports reply threading |
+| `send_image_as_user` | Send image (requires `image_key` from `upload_image`) |
+| `send_file_as_user` | Send file (requires `file_key` from `upload_file`) |
+| `send_post_as_user` | Send rich text with title + formatted paragraphs |
 | `send_sticker_as_user` | Send sticker/emoji |
 | `send_audio_as_user` | Send audio message |
 
-### User Identity -- Contacts & Info (cookie auth)
+### User Identity -- Contacts & Info (5 tools, cookie auth)
 
 | Tool | Description |
 |------|-------------|
 | `search_contacts` | Search users, bots, or group chats by name |
-| `create_p2p_chat` | Create/get P2P (direct message) chat, returns numeric `chat_id` |
-| `get_chat_info` | Group details: name, description, member count, owner |
+| `create_p2p_chat` | Create/get P2P (direct message) chat |
+| `get_chat_info` | Group details (supports both oc_xxx and numeric ID) |
 | `get_user_info` | User display name lookup by user ID |
 | `get_login_status` | Check cookie, app credentials, and UAT status |
 
-### User OAuth UAT -- P2P Chat Reading
+### User OAuth UAT -- P2P Chat Reading (2 tools)
 
 | Tool | Description |
 |------|-------------|
-| `read_p2p_messages` | Read P2P (direct message) history. Works for chats the bot cannot access. |
-| `list_user_chats` | List group chats the user is in. Note: only returns groups, not P2P. |
+| `read_p2p_messages` | Read P2P (direct message) history |
+| `list_user_chats` | List group chats the user is in |
 
-### Official API -- IM (Bot Identity)
+### Official API -- IM (17 tools)
 
 | Tool | Description |
 |------|-------------|
 | `list_chats` | List all chats the bot has joined |
-| `read_messages` | Read message history (accepts chat name or `oc_xxx` ID) |
-| `reply_message` | Reply to a specific message by `message_id` (as bot) |
+| `read_messages` | Read message history (accepts chat name, oc_xxx, or numeric ID) |
+| `send_message_as_bot` | Send message as bot to any chat |
+| `reply_message` | Reply to a specific message (as bot) |
 | `forward_message` | Forward a message to another chat |
-
-### Official API -- Documents
+| `delete_message` | Recall/delete a bot message |
+| `update_message` | Edit a sent bot message |
+| `add_reaction` | Add emoji reaction to a message |
+| `delete_reaction` | Remove emoji reaction |
+| `pin_message` | Pin a message in chat |
+| `unpin_message` | Unpin a message |
+| `create_group` | Create a new group chat |
+| `update_group` | Update group name/description |
+| `list_members` | List group members |
+| `add_members` | Add users to a group |
+| `remove_members` | Remove users from a group |
+| `upload_image` / `upload_file` | Upload image/file, returns key for sending |
+
+### Official API -- Documents (7 tools)
 
 | Tool | Description |
 |------|-------------|
 | `search_docs` | Search documents by keyword |
-| `read_doc` | Read raw text content of a document |
+| `read_doc` | Read raw text content |
+| `get_doc_blocks` | Get structured block tree |
 | `create_doc` | Create a new document |
+| `create_doc_block` | Insert content blocks into a document |
+| `update_doc_block` | Update a specific block |
+| `delete_doc_blocks` | Delete a range of blocks |
+
+### Official API -- Bitable (17 tools)
+
+| Tool | Description |
+|------|-------------|
+| `create_bitable` | Create a new Bitable app |
+| `list_bitable_tables` / `create_bitable_table` / `delete_bitable_table` | Table management |
+| `list_bitable_fields` / `create_bitable_field` / `update_bitable_field` / `delete_bitable_field` | Field management |
+| `list_bitable_views` | List views |
+| `search_bitable_records` / `get_bitable_record` | Query records |
+| `create_bitable_record` / `update_bitable_record` / `delete_bitable_record` | Single record CRUD |
+| `batch_create_bitable_records` / `batch_update_bitable_records` / `batch_delete_bitable_records` | Batch operations (max 500/call) |
 
-### Official API -- Bitable (Spreadsheets)
+### Official API -- Calendar (5 tools)
 
 | Tool | Description |
 |------|-------------|
-| `list_bitable_tables` | List all tables in a Bitable app |
-| `list_bitable_fields` | List all fields (columns) in a table |
-| `search_bitable_records` | Query records with filter and sort |
-| `create_bitable_record` | Create a new record (row) |
-| `update_bitable_record` | Update an existing record |
+| `list_calendars` | List accessible calendars |
+| `create_calendar_event` | Create a calendar event |
+| `list_calendar_events` | List events in a calendar |
+| `delete_calendar_event` | Delete an event |
+| `get_freebusy` | Check user availability |
 
-### Official API -- Wiki
+### Official API -- Tasks (5 tools)
 
 | Tool | Description |
 |------|-------------|
-| `list_wiki_spaces` | List all accessible wiki spaces |
-| `search_wiki` | Search wiki/docs by keyword |
-| `list_wiki_nodes` | Browse wiki node tree |
+| `create_task` | Create a task |
+| `get_task` | Get task details |
+| `list_tasks` | List tasks |
+| `update_task` | Update a task |
+| `complete_task` | Mark task as complete |
 
-### Official API -- Drive
+### Official API -- Drive (5 tools)
 
 | Tool | Description |
 |------|-------------|
 | `list_files` | List files in a folder |
 | `create_folder` | Create a new folder |
+| `copy_file` | Copy a file |
+| `move_file` | Move a file |
+| `delete_file` | Delete a file/folder |
 
-### Official API -- Contacts
+### Official API -- Wiki & Contacts (4 tools)
 
 | Tool | Description |
 |------|-------------|
+| `list_wiki_spaces` / `search_wiki` / `list_wiki_nodes` | Wiki spaces, search, browse |
 | `find_user` | Find user by email or mobile number |
 
 ## Claude Code Slash Commands (9 skills)
@@ -444,7 +508,7 @@ feishu-user-plugin/
 │       ├── SKILL.md         # Main skill definition (trigger, tools, auth)
 │       └── references/      # 8 skill reference docs + CLAUDE.md
 ├── src/
-│   ├── index.js             # MCP server entry point (33 tools)
+│   ├── index.js             # MCP server entry point (76 tools)
 │   ├── client.js            # User identity client (Protobuf gateway)
 │   ├── official.js          # Official API client (REST, UAT)
 │   ├── utils.js             # ID generators, cookie parser

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "feishu-user-plugin",
-  "version": "1.3.0",
-  "description": "All-in-one Feishu plugin for Claude Code — messaging, docs, bitable, calendar, tasks, drive. 76 tools + 9 skills, 3 auth layers.",
+  "version": "1.3.1",
+  "description": "All-in-one Feishu plugin for Claude Code & Codex — messaging, docs, bitable, wiki, drive. 66 tools + 9 skills, 3 auth layers.",
   "main": "src/index.js",
   "bin": {
     "feishu-user-plugin": "src/cli.js"
@@ -10,7 +10,8 @@
     "start": "node src/index.js",
     "test": "node src/test-all.js",
     "test:quick": "node src/test-send.js",
-    "oauth": "node src/oauth.js"
+    "oauth": "node src/oauth.js",
+    "prepublishOnly": "node scripts/confirm-version.js"
   },
   "keywords": [
     "feishu",
@@ -37,6 +38,7 @@
   "files": [
     "src/",
     "proto/",
+    "scripts/",
     ".claude-plugin/",
     "skills/",
     ".mcp.json.example",

package/scripts/confirm-version.js

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+/**
+ * Pre-publish version confirmation gate.
+ * Runs as prepublishOnly — blocks `npm publish` until version is confirmed.
+ * Automatically skipped in CI (GitHub Actions handles tag/version check separately).
+ */
+
+if (process.env.CI || process.env.GITHUB_ACTIONS) {
+  process.exit(0);
+}
+
+const readline = require('readline');
+const pkg = require('../package.json');
+
+const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+
+console.log(`\n  Package:  ${pkg.name}`);
+console.log(`  Version:  ${pkg.version}`);
+console.log(`  Tools:    ${pkg.description}\n`);
+
+rl.question(`  Confirm publish v${pkg.version}? (y/N): `, (answer) => {
+  rl.close();
+  if (answer.trim().toLowerCase() !== 'y') {
+    console.error('\n  Publish cancelled. Update version in package.json if needed.\n');
+    process.exit(1);
+  }
+  console.log('  Confirmed. Proceeding with publish...\n');
+});

package/scripts/mcp_stdio_bridge.js

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+
+const { spawn } = require('child_process');
+
+const defaultCommand = ['node', '/Users/abble/feishu-user-plugin/src/index.js'];
+const childCommand = process.argv.slice(2);
+const [command, ...args] = childCommand.length > 0 ? childCommand : defaultCommand;
+
+const child = spawn(command, args, {
+  stdio: ['pipe', 'pipe', 'pipe'],
+  env: process.env,
+});
+
+let parentMode = null; // 'content-length' | 'newline'
+let parentInBuffer = Buffer.alloc(0);
+let childOutBuffer = '';
+
+function writeToParent(jsonLine) {
+  if (parentMode === 'content-length') {
+    const body = Buffer.from(jsonLine, 'utf8');
+    process.stdout.write(`Content-Length: ${body.length}\r\n\r\n`);
+    process.stdout.write(body);
+    return;
+  }
+  process.stdout.write(jsonLine + '\n');
+}
+
+function handleParentMessage(message) {
+  const line = typeof message === 'string' ? message : JSON.stringify(message);
+  child.stdin.write(line + '\n');
+}
+
+function tryParseParentBuffer() {
+  while (parentInBuffer.length > 0) {
+    if (parentMode === 'content-length' || (!parentMode && parentInBuffer.includes(Buffer.from('\r\n\r\n')))) {
+      parentMode = 'content-length';
+      const headerEnd = parentInBuffer.indexOf(Buffer.from('\r\n\r\n'));
+      if (headerEnd === -1) return;
+      const headerText = parentInBuffer.subarray(0, headerEnd).toString('utf8');
+      const match = headerText.match(/Content-Length:\s*(\d+)/i);
+      if (!match) {
+        process.stderr.write('[mcp-bridge] Missing Content-Length header\n');
+        process.exit(1);
+      }
+      const bodyLength = Number(match[1]);
+      const totalLength = headerEnd + 4 + bodyLength;
+      if (parentInBuffer.length < totalLength) return;
+      const body = parentInBuffer.subarray(headerEnd + 4, totalLength).toString('utf8');
+      parentInBuffer = parentInBuffer.subarray(totalLength);
+      handleParentMessage(body);
+      continue;
+    }
+
+    parentMode = 'newline';
+    const newlineIndex = parentInBuffer.indexOf(0x0a);
+    if (newlineIndex === -1) return;
+    const line = parentInBuffer.subarray(0, newlineIndex).toString('utf8').replace(/\r$/, '');
+    parentInBuffer = parentInBuffer.subarray(newlineIndex + 1);
+    if (line.trim()) handleParentMessage(line);
+  }
+}
+
+process.stdin.on('data', (chunk) => {
+  parentInBuffer = Buffer.concat([parentInBuffer, chunk]);
+  tryParseParentBuffer();
+});
+
+child.stdout.on('data', (chunk) => {
+  childOutBuffer += chunk.toString('utf8');
+  while (true) {
+    const newlineIndex = childOutBuffer.indexOf('\n');
+    if (newlineIndex === -1) break;
+    const line = childOutBuffer.slice(0, newlineIndex).replace(/\r$/, '');
+    childOutBuffer = childOutBuffer.slice(newlineIndex + 1);
+    if (line.trim()) writeToParent(line);
+  }
+});
+
+child.stderr.on('data', (chunk) => {
+  process.stderr.write(chunk);
+});
+
+child.on('exit', (code, signal) => {
+  if (signal) {
+    process.stderr.write(`[mcp-bridge] Child exited via signal ${signal}\n`);
+    process.exit(1);
+  }
+  process.exit(code ?? 0);
+});
+
+child.on('error', (error) => {
+  process.stderr.write(`[mcp-bridge] Failed to spawn child: ${error.message}\n`);
+  process.exit(1);
+});
+
+process.on('SIGINT', () => child.kill('SIGINT'));
+process.on('SIGTERM', () => child.kill('SIGTERM'));

package/skills/feishu-user-plugin/references/CLAUDE.md

@@ -6,7 +6,7 @@ All-in-one Feishu plugin for Claude Code with three auth layers:
 - **Official API** (app credentials): Read group messages, docs, tables, wiki, drive, contacts, upload files
 - **User OAuth UAT** (user_access_token): Read P2P chat history, list all user's chats
 
-## Tool Categories (76 tools)
+## Tool Categories (66 tools)
 
 ### User Identity — Messaging (reverse-engineered, cookie-based)
 - `send_to_user` — Search user + send text (one step, most common). Returns candidates if multiple matches.
@@ -25,9 +25,10 @@ All-in-one Feishu plugin for Claude Code with three auth layers:
 - `get_user_info` — User display name lookup (official API first, cookie cache fallback)
 - `get_login_status` — Check cookie, app, and UAT status
 
-### User OAuth UAT Tools (P2P chat reading)
+### User OAuth UAT Tools (P2P chat reading + user-identity creation)
 - `read_p2p_messages` — Read P2P (direct message) chat history. chat_id accepts both numeric IDs (from create_p2p_chat) and oc_xxx format. Returns newest messages first by default.
 - `list_user_chats` — List group chats the user is in. Note: API only returns groups, not P2P. For P2P, use: `search_contacts` → `create_p2p_chat` → `read_p2p_messages`.
+- `create_doc` / `create_bitable` / `create_folder` — **UAT-first**: creates resources as the user (not the app) when UAT with write scopes is available. Falls back to app token.
 
 ### Official API Tools (app credentials)
 - `list_chats` / `read_messages` — Chat history (read_messages accepts chat name, oc_ ID, or numeric ID; auto-resolves via bot's group list → im.chat.search → search_contacts). **Auto-falls back to UAT for external groups the bot cannot access.** Returns newest messages first by default. Messages include sender names.
@@ -35,26 +36,22 @@ All-in-one Feishu plugin for Claude Code with three auth layers:
 - `reply_message` / `forward_message` — Message operations (as bot)
 - `delete_message` / `update_message` — Recall or edit bot's own messages
 - `add_reaction` / `delete_reaction` — Emoji reactions on messages
-- `pin_message` / `unpin_message` — Pin/unpin messages in chat
+- `pin_message` — Pin or unpin a message (pinned=true/false)
 - `create_group` / `update_group` — Create and manage group chats
-- `list_members` / `add_members` / `remove_members` — Group membership management
+- `list_members` / `manage_members` — Group membership (manage_members: action=add/remove)
 - `search_docs` / `read_doc` / `get_doc_blocks` / `create_doc` — Document operations
 - `create_doc_block` / `update_doc_block` / `delete_doc_blocks` — Document content editing (insert/update/delete blocks)
-- `create_bitable` — Create a new Bitable (multi-dimensional table) app
-- `list_bitable_tables` / `create_bitable_table` — Table management
+- `create_bitable` / `get_bitable_meta` / `copy_bitable` — Bitable app management (create, get info, copy)
+- `list_bitable_tables` / `create_bitable_table` / `update_bitable_table` / `delete_bitable_table` — Table management (CRUD + rename)
 - `list_bitable_fields` / `create_bitable_field` / `update_bitable_field` / `delete_bitable_field` — Field (column) management
-- `list_bitable_views` — List views in a table
-- `search_bitable_records` — Query records with filter/sort
-- `create_bitable_record` / `update_bitable_record` / `delete_bitable_record` — Single record CRUD
-- `batch_create_bitable_records` / `batch_update_bitable_records` / `batch_delete_bitable_records` — Batch operations (max 500/call)
+- `list_bitable_views` / `create_bitable_view` / `delete_bitable_view` — View management (grid, kanban, gallery, form, gantt, calendar)
+- `search_bitable_records` / `get_bitable_record` — Query records
+- `batch_create_bitable_records` / `batch_update_bitable_records` / `batch_delete_bitable_records` — Record CRUD (single or batch, max 500/call)
 - `list_wiki_spaces` / `search_wiki` / `list_wiki_nodes` — Wiki
 - `list_files` / `create_folder` — Drive
 - `copy_file` / `move_file` / `delete_file` — Drive file operations (copy, move, delete)
 - `upload_image` / `upload_file` — Upload image/file, returns key for send_image/send_file
 - `find_user` — Contact lookup by email/mobile
-- `list_calendars` / `create_calendar_event` / `list_calendar_events` / `delete_calendar_event` — Calendar management
-- `get_freebusy` — Check user availability
-- `create_task` / `get_task` / `list_tasks` / `update_task` / `complete_task` — Task management
 
 ## Usage Patterns
 
@@ -73,14 +70,18 @@ All-in-one Feishu plugin for Claude Code with three auth layers:
 
 ### Bitable (Multi-dimensional Tables)
 - Create a bitable from scratch → `create_bitable` → `create_bitable_table` → `create_bitable_field`
+- Get bitable info → `get_bitable_meta`
+- Copy a bitable → `copy_bitable` with name and optional folder
 - Query data → `list_bitable_tables` → `list_bitable_fields` → `search_bitable_records`
-- Single record CRUD → `create_bitable_record` / `update_bitable_record` / `delete_bitable_record`
-- Bulk operations → `batch_create_bitable_records` / `batch_update_bitable_records` / `batch_delete_bitable_records` (max 500/call)
+- Rename table → `update_bitable_table` with new name
+- Read single record → `get_bitable_record`
+- Create/update/delete records → `batch_create_bitable_records` / `batch_update_bitable_records` / `batch_delete_bitable_records` (works for single or up to 500)
 - Manage fields → `create_bitable_field` / `update_bitable_field` (requires type param) / `delete_bitable_field`
+- Manage views → `create_bitable_view` (type: grid/kanban/gallery/form/gantt/calendar) / `delete_bitable_view`
 
 ### Group Management
 - Create a group → `create_group` with name and optional member open_ids
-- Add/remove members → `add_members` / `remove_members` with chat_id + user open_ids
+- Add/remove members → `manage_members` with chat_id + member_ids + action (add/remove)
 - List members → `list_members`
 
 ### Document Editing
@@ -88,15 +89,6 @@ All-in-one Feishu plugin for Claude Code with three auth layers:
 - Edit existing block → `get_doc_blocks` to find block_id → `update_doc_block`
 - Delete blocks → `delete_doc_blocks` with start/end index range
 
-### Calendar
-- View schedule → `list_calendars` → `list_calendar_events`
-- Create event → `create_calendar_event` with calendar_id, summary, start/end time
-- Check availability → `get_freebusy` with user open_ids and time range
-
-### Tasks
-- Create task → `create_task` with summary, optional description/due
-- Track tasks → `list_tasks` → `update_task` / `complete_task`
-
 ### Diagnostics
 - Diagnose issues → `get_login_status` first
 
@@ -237,10 +229,16 @@ Tell user to restart Claude Code. Only ONE restart should be needed.
 
 ## Troubleshooting Guide
 
+### If MCP disconnects mid-session
+- **Root cause** (fixed in v1.3.1): `@larksuiteoapi/node-sdk`'s `defaultLogger.error` uses `console.log` (stdout). MCP protocol uses stdout for JSON-RPC, so SDK error logs corrupt the transport and cause immediate disconnect.
+- **Fix**: Custom logger redirects all SDK output to stderr. Already applied in `src/official.js`.
+- If still happening: check for any `console.log` calls in server code (only `console.error` is safe in MCP servers).
+
 ### If MCP tools are not available
 1. Check `~/.claude.json` — config must be in **top-level** `mcpServers`, not inside `projects[*]`
-2. Restart Claude Code after config changes
-3. After restart, tools may take a few seconds to register — if first call fails with "No such tool", wait and retry once
+2. For Codex: check `~/.codex/config.toml` has `[mcp_servers.feishu-user-plugin]` section
+3. Restart Claude Code / Codex after config changes
+4. After restart, tools may take a few seconds to register — if first call fails with "No such tool", wait and retry once
 
 ### If cookie authentication fails
 - `document.cookie` in browser console CANNOT access HttpOnly cookies (`session`, `sl_session`)
@@ -282,9 +280,17 @@ Tell user to restart Claude Code. Only ONE restart should be needed.
 - **team-skills plugin**: Skills + CLAUDE.md only (no .mcp.json). For internal team members.
 
 ### Config management
-- `src/config.js`: Unified config module. Discovers config in `~/.claude.json` (top-level + project-level) and `.mcp.json`.
-- `setup` always writes to `~/.claude.json` top-level `mcpServers` (global).
-- `persistToConfig()` finds the correct config entry and writes back (used by heartbeat + UAT refresh).
+- `src/config.js`: Unified config module. Discovers config in `~/.claude.json` (top-level + project-level), `.mcp.json`, and `~/.codex/config.toml`.
+- `setup` writes to `~/.claude.json` (default) or `~/.codex/config.toml` (with `--client codex`), or both (`--client both`).
+- `persistToConfig()` finds the correct config entry and writes back atomically (used by heartbeat + UAT refresh).
+- All config writes use atomic write (tmp file + rename) to prevent race conditions with Claude Code.
+
+### Multi-client support
+- **Claude Code**: JSON config in `~/.claude.json` mcpServers
+- **Codex**: TOML config in `~/.codex/config.toml` mcp_servers
+- Setup: `npx feishu-user-plugin setup --client codex` or `--client both`
+- MCP server code is identical for both clients — only config format differs
+- Codex does not support Claude Code slash commands (skills) — only MCP tools are available
 
 ## Development & Publishing
 
@@ -315,6 +321,32 @@ cp .claude-plugin/plugin.json /path/to/team-skills/plugins/feishu-user-plugin/.c
 
 ## Development Workflow
 
+### Keeping all docs in sync
+When making ANY code change (new tools, bug fixes, features), update ALL of these:
+
+**本仓库内：**
+- `CLAUDE.md` — tool count, tool list, usage patterns, known limitations
+- `README.md` — tool count (badge + heading + tool table), feature highlights, OpenClaw/Claude Code config examples
+- `ROADMAP.md` — check off completed items, add new findings
+- `package.json` — version, description (tool count)
+- `skills/feishu-user-plugin/references/CLAUDE.md` — always copy from root: `cp CLAUDE.md skills/feishu-user-plugin/references/CLAUDE.md`
+- `prompts/openclaw-setup.md` — if OpenClaw 相关配置变了要更新
+
+**team-skills 仓库 (`/Users/abble/team-skills/plugins/feishu-user-plugin/`)：**
+- `skills/` — 同步技能文件: `cp -r skills/ /Users/abble/team-skills/plugins/feishu-user-plugin/skills/`
+- `README.md` — team-skills 有自己的 README（含团队 APP_ID/SECRET），需要同步更新：工具数量、功能列表、更新日志、安装 prompt
+- 两个 README 都必须包含 Claude Code 安装 prompt 和 OpenClaw 安装 prompt
+- team-skills README 的安装 prompt 包含团队共享的 APP_ID/SECRET（hardcoded），本仓库 README 用占位符
+
+**同步命令（每次发版后执行）：**
+```bash
+# 1. 同步 skills
+cp CLAUDE.md skills/feishu-user-plugin/references/CLAUDE.md
+cp -r skills/ /Users/abble/team-skills/plugins/feishu-user-plugin/skills/
+# 2. 手动更新 team-skills README（工具数、功能列表、更新日志）
+# 3. 提交并推送两个仓库
+```
+
 ### Keeping ROADMAP.md up to date
 - When completing a feature or fixing a bug, check the corresponding item in ROADMAP.md as `[x]` done
 - When discovering new bugs, limitations, or feature ideas during development, add them to the appropriate section in ROADMAP.md
@@ -341,10 +373,20 @@ cp .claude-plugin/plugin.json /path/to/team-skills/plugins/feishu-user-plugin/.c
 - `chore:` dependencies, CI, config changes
 
 ### Publishing
-1. Update `version` in `package.json`
-2. `git add <files> && git commit -m "v1.x.x: description"`
-3. `git tag v1.x.x && git push && git push --tags`
-4. GitHub Actions auto-publishes to npm. Users get the new version on next Claude Code restart.
+**IMPORTANT: Version number must ALWAYS be confirmed with the user before publishing.**
+Any operation involving `npm version`, modifying `package.json` version, `git tag v*`, or `git push --tags` requires explicit user confirmation of the target version number. Do not auto-decide version numbers.
+
+Three-layer version safety:
+1. **Claude rule** (this section): Ask user to confirm version before any publish-related operation
+2. **Local gate** (`prepublishOnly`): Interactive confirmation when running `npm publish` locally (skipped in CI)
+3. **CI gate** (`.github/workflows/publish.yml`): Tag must match `package.json` version or publish fails
+
+Steps:
+1. Confirm target version with user
+2. Update `version` in `package.json`
+3. `git add <files> && git commit -m "v1.x.x: description"`
+4. `git tag v1.x.x && git push && git push --tags`
+5. GitHub Actions verifies tag matches package.json, then auto-publishes to npm
 
 ### Syncing to team-skills (after any CLAUDE.md or skills change)
 1. Copy CLAUDE.md to skill reference: `cp CLAUDE.md skills/feishu-user-plugin/references/CLAUDE.md`

package/src/cli.js

@@ -41,23 +41,28 @@ function printHelp() {
 feishu-user-plugin — All-in-one Feishu MCP Server
 
 Commands:
-  (default)   Start MCP server (used by Claude Code)
+  (default)   Start MCP server (used by Claude Code / Codex)
   setup       Interactive setup wizard — writes MCP config
   oauth       Run OAuth flow to obtain user_access_token
   status      Check authentication status
   keepalive   Refresh cookie + UAT to prevent expiration (for cron jobs)
   help        Show this help
 
-Quick Start (team members):
+Setup options:
+  --app-id <id>       App ID (non-interactive mode)
+  --app-secret <s>    App Secret (non-interactive mode)
+  --cookie <c>        Cookie string (optional)
+  --client <target>   Config target: claude (default), codex, or both
+
+Quick Start (Claude Code):
   1. npx feishu-user-plugin setup
   2. Follow the prompts to configure credentials
   3. Restart Claude Code
 
-Quick Start (external users):
-  1. Create a Feishu app at https://open.feishu.cn/app
-  2. npx feishu-user-plugin setup
-  3. npx feishu-user-plugin oauth
-  4. Restart Claude Code
+Quick Start (Codex):
+  1. npx feishu-user-plugin setup --client codex
+  2. Follow the prompts to configure credentials
+  3. Restart Codex
 
 Auto-renewal (optional):
   Add to crontab to keep tokens alive even when Claude Code is closed: