feishu-user-plugin 1.0.0 → 1.0.1

package/.env.example

@@ -1,6 +1,6 @@
 # === User Identity (reverse-engineered protocol) ===
 # Required for: send_as_user, send_to_user, send_to_group, search_contacts, etc.
-# How to get: Login to feishu.cn → Playwright context.cookies() or DevTools
+# How to get: Login to feishu.cn → Playwright context.cookies() or DevTools Network tab
 LARK_COOKIE=
 
 # === Official API (Feishu Open Platform) ===
@@ -9,9 +9,9 @@ LARK_COOKIE=
 LARK_APP_ID=
 LARK_APP_SECRET=
 
-# === User OAuth UAT (optional, for P2P chat reading) ===
+# === User OAuth UAT (required for P2P chat reading) ===
 # Required for: read_p2p_messages, list_user_chats
-# How to get: Run "node src/oauth.js" after configuring App ID/Secret above
+# How to get: Run "node src/oauth.js" after configuring Cookie + App ID/Secret above
 # These are auto-populated by the OAuth flow and auto-refreshed at runtime
 LARK_USER_ACCESS_TOKEN=
 LARK_USER_REFRESH_TOKEN=

package/.mcp.json.example

@@ -6,7 +6,9 @@
       "env": {
         "LARK_COOKIE": "YOUR_FEISHU_COOKIE_HERE",
         "LARK_APP_ID": "YOUR_APP_ID_HERE",
-        "LARK_APP_SECRET": "YOUR_APP_SECRET_HERE"
+        "LARK_APP_SECRET": "YOUR_APP_SECRET_HERE",
+        "LARK_USER_ACCESS_TOKEN": "YOUR_UAT_HERE",
+        "LARK_USER_REFRESH_TOKEN": "YOUR_REFRESH_TOKEN_HERE"
       }
     }
   }

package/README.md

@@ -15,7 +15,7 @@ The only MCP server that lets you send messages as your **personal identity** (n
 - **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). Each is independent; configure only what you need.
+- **3 auth layers** -- Cookie-based user identity, app credentials (Official API), and OAuth UAT (P2P reading). All three are needed for full functionality.
 - **8 slash commands** for Claude Code -- `/send`, `/reply`, `/search`, `/digest`, `/doc`, `/table`, `/wiki`, `/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.
@@ -110,11 +110,9 @@ Add your bot to the group chats where you want it to read messages. The bot can
 | `LARK_APP_ID` | Official API tools | App ID from Feishu Open Platform. Needed for `read_messages`, docs, tables, wiki, drive. |
 | `LARK_APP_SECRET` | Official API tools | App Secret from Feishu Open Platform. Used together with `LARK_APP_ID`. |
 | `LARK_USER_ACCESS_TOKEN` | P2P chat reading | OAuth user token. Needed for `read_p2p_messages` and `list_user_chats`. Obtained via `node src/oauth.js`. |
+| `LARK_USER_REFRESH_TOKEN` | UAT auto-refresh | Refresh token for automatic UAT renewal. Obtained together with UAT via OAuth flow. |
 
-Each auth layer is independent. You can configure:
-- **Cookie only** -- for sending messages as yourself
-- **App credentials only** -- for reading docs, tables, wiki, group chats
-- **All three** -- for the full feature set
+All five variables are required for full functionality. Configure all of them during setup.
 
 ## How to Get Your Cookie
 
@@ -147,9 +145,9 @@ Claude Code will automatically:
 
 > The server automatically refreshes the session via heartbeat every 4 hours. The `sl_session` cookie has a 12-hour max-age.
 
-## How to Set Up P2P Chat Reading (OAuth)
+## Set Up OAuth (Required for P2P Chat Reading)
 
-To read direct message history with `read_p2p_messages` and `list_user_chats`:
+To enable `read_p2p_messages` and `list_user_chats`:
 
 1. Your Feishu app must be a **Custom App** (自建应用), NOT marketplace/third-party
 2. Add scopes: `im:message`, `im:message:readonly`, `im:chat:readonly`
@@ -166,7 +164,7 @@ cd $(npm root -g)/feishu-user-plugin && node src/oauth.js
 # Or clone the repo just for the OAuth step, then use npx for daily use
 ```
 
-A browser window will open for OAuth consent. The token is saved to `.env` automatically and auto-refreshes at runtime. Add the resulting `LARK_USER_ACCESS_TOKEN` to your `.mcp.json` env.
+A browser window will open for OAuth consent. The token is saved to `.env` automatically and auto-refreshes at runtime. Add both `LARK_USER_ACCESS_TOKEN` and `LARK_USER_REFRESH_TOKEN` from `.env` to your MCP config's `env` section.
 
 ## MCP Client Configuration
 
@@ -185,7 +183,9 @@ Add to your project's `.mcp.json` (or `~/.claude/.mcp.json` for global):
       "env": {
         "LARK_COOKIE": "your-cookie-string",
         "LARK_APP_ID": "cli_xxxxxxxxxxxx",
-        "LARK_APP_SECRET": "your-app-secret"
+        "LARK_APP_SECRET": "your-app-secret",
+        "LARK_USER_ACCESS_TOKEN": "your-uat",
+        "LARK_USER_REFRESH_TOKEN": "your-refresh-token"
       }
     }
   }
@@ -203,7 +203,9 @@ Add to your project's `.mcp.json` (or `~/.claude/.mcp.json` for global):
       "env": {
         "LARK_COOKIE": "your-cookie-string",
         "LARK_APP_ID": "cli_xxxxxxxxxxxx",
-        "LARK_APP_SECRET": "your-app-secret"
+        "LARK_APP_SECRET": "your-app-secret",
+        "LARK_USER_ACCESS_TOKEN": "your-uat",
+        "LARK_USER_REFRESH_TOKEN": "your-refresh-token"
       }
     }
   }
@@ -228,7 +230,9 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
       "env": {
         "LARK_COOKIE": "your-cookie-string",
         "LARK_APP_ID": "cli_xxxxxxxxxxxx",
-        "LARK_APP_SECRET": "your-app-secret"
+        "LARK_APP_SECRET": "your-app-secret",
+        "LARK_USER_ACCESS_TOKEN": "your-uat",
+        "LARK_USER_REFRESH_TOKEN": "your-refresh-token"
       }
     }
   }
@@ -248,7 +252,9 @@ Add to `.cursor/mcp.json` in your project:
       "env": {
         "LARK_COOKIE": "your-cookie-string",
         "LARK_APP_ID": "cli_xxxxxxxxxxxx",
-        "LARK_APP_SECRET": "your-app-secret"
+        "LARK_APP_SECRET": "your-app-secret",
+        "LARK_USER_ACCESS_TOKEN": "your-uat",
+        "LARK_USER_REFRESH_TOKEN": "your-refresh-token"
       }
     }
   }
@@ -269,7 +275,9 @@ Add to `.vscode/mcp.json` in your project:
       "env": {
         "LARK_COOKIE": "your-cookie-string",
         "LARK_APP_ID": "cli_xxxxxxxxxxxx",
-        "LARK_APP_SECRET": "your-app-secret"
+        "LARK_APP_SECRET": "your-app-secret",
+        "LARK_USER_ACCESS_TOKEN": "your-uat",
+        "LARK_USER_REFRESH_TOKEN": "your-refresh-token"
       }
     }
   }
@@ -289,7 +297,9 @@ Add to `~/.codeium/windsurf/mcp_config.json`:
       "env": {
         "LARK_COOKIE": "your-cookie-string",
         "LARK_APP_ID": "cli_xxxxxxxxxxxx",
-        "LARK_APP_SECRET": "your-app-secret"
+        "LARK_APP_SECRET": "your-app-secret",
+        "LARK_USER_ACCESS_TOKEN": "your-uat",
+        "LARK_USER_REFRESH_TOKEN": "your-refresh-token"
       }
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "feishu-user-plugin",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "All-in-one Feishu plugin for Claude Code — send messages as yourself, read chats, manage docs/tables/wiki. 33 tools + 8 skills, 3 auth layers.",
   "main": "src/index.js",
   "bin": {

package/skills/feishu-user-plugin/SKILL.md

@@ -61,7 +61,8 @@ Check cookie / app credentials / UAT — all three auth layers at once.
 | LARK_COOKIE | **You** | Send messages as yourself | Yes (for messaging) |
 | LARK_APP_ID | **You** (create a Feishu app) | Official API access | Yes |
 | LARK_APP_SECRET | **You** (from your Feishu app) | Official API access | Yes |
-| LARK_USER_ACCESS_TOKEN | **You** (OAuth flow, optional) | Read P2P chat history | Optional |
+| LARK_USER_ACCESS_TOKEN | **You** (OAuth flow) | Read P2P chat history | Yes (for P2P reading) |
+| LARK_USER_REFRESH_TOKEN | **You** (OAuth flow) | UAT auto-refresh | Yes (for P2P reading) |
 
 ### Getting Your Cookie (Automated via Playwright)
 

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

@@ -4,7 +4,7 @@
 All-in-one Feishu plugin for Claude Code with three auth layers:
 - **User Identity** (cookie auth): Send messages (text, image, file, post, sticker, audio) as yourself
 - **Official API** (app credentials): Read group messages, docs, tables, wiki, drive, contacts
-- **User OAuth UAT** (user_access_token): Read P2P chat history
+- **User OAuth UAT** (user_access_token): Read P2P chat history, list all user's chats
 
 ## Tool Categories
 
@@ -26,7 +26,7 @@ All-in-one Feishu plugin for Claude Code with three auth layers:
 - `get_login_status` — Check cookie, app, and UAT status
 
 ### User OAuth UAT Tools (P2P chat reading)
-- `read_p2p_messages` — Read P2P (direct message) chat history. Requires OAuth setup.
+- `read_p2p_messages` — Read P2P (direct message) chat history. chat_id accepts both numeric IDs (from create_p2p_chat) and oc_xxx format.
 - `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`.
 
 ### Official API Tools (app credentials)
@@ -43,7 +43,7 @@ All-in-one Feishu plugin for Claude Code with three auth layers:
 - Send text as yourself → `send_to_user` or `send_to_group`
 - Send rich content → `send_post_as_user` (formatted text), `send_image_as_user` (images)
 - Read group chat history → `read_messages` with chat name or oc_ ID
-- Read P2P chat history → `search_contacts` → `create_p2p_chat` → `read_p2p_messages` (requires OAuth UAT)
+- Read P2P chat history → `search_contacts` → `create_p2p_chat` → `read_p2p_messages`
 - Reply as user in thread → `send_as_user` with root_id
 - Reply as bot → `reply_message` (official API, text messages only)
 - Diagnose issues → `get_login_status` first
@@ -51,44 +51,82 @@ All-in-one Feishu plugin for Claude Code with three auth layers:
 ## Auth & Session
 - **LARK_COOKIE**: Required for user identity tools. Session auto-refreshed every 4h via heartbeat.
 - **LARK_APP_ID + LARK_APP_SECRET**: Required for official API tools.
-- **LARK_USER_ACCESS_TOKEN**: Required for P2P reading. Obtained via OAuth flow. Auto-refreshed via refresh_token.
+- **LARK_USER_ACCESS_TOKEN + LARK_USER_REFRESH_TOKEN**: Required for P2P reading. Auto-refreshed via refresh_token.
 
 ## Automated Cookie Setup via Playwright
 
-When LARK_COOKIE is missing or expired, automatically obtain it using Playwright MCP.
-Do NOT ask the user to manually copy cookies from DevTools.
+When LARK_COOKIE is missing or expired, obtain it using Playwright MCP.
 
 ### Prerequisites
-Playwright MCP must be available. If not, tell the user:
+Playwright MCP must be available. If not:
 > Run: `npx @anthropic-ai/claude-code mcp add playwright -- npx @anthropic-ai/mcp-server-playwright`
 > Then restart Claude Code.
 
-### Automated Flow
-1. `browser_navigate` → `https://www.feishu.cn/messenger/`
-2. `browser_take_screenshot` → show QR code to user, ask them to scan with Feishu app
-3. Poll `browser_snapshot` every 3-5s until messenger page loads
-4. `browser_run_code`:
-   ```js
-   const cookies = await context.cookies('https://www.feishu.cn');
-   const feishuCookies = cookies.filter(c => c.domain.endsWith('feishu.cn'));
-   const cookieStr = feishuCookies.map(c => c.name + '=' + c.value).join('; ');
-   ```
-5. Read user's `.mcp.json`, update `LARK_COOKIE` value
-6. Tell user to restart Claude Code
-
-### Cookie Refresh
-When cookie auth fails, offer to re-run the Playwright flow. Heartbeat auto-refreshes every 4h.
+### Automated Flow — FOLLOW EXACTLY
+
+**Step 1: Clear cookies first** (Playwright uses persistent browser profile that may have a DIFFERENT account cached):
+```
+browser_run_code: await context.clearCookies();
+browser_navigate: https://www.feishu.cn/messenger/
+```
+
+**Step 2: Show QR code and wait for login**:
+```
+browser_take_screenshot
+```
+Poll `browser_snapshot` every 5s until URL changes from `/accounts/`.
+
+**Step 3: Extract cookie — TWO-STEP approach** (NEVER use browser_run_code output directly as cookie):
+
+Step 3a via `browser_run_code`:
+```js
+const cookies = await page.context().cookies('https://www.feishu.cn');
+const str = cookies.map(c => c.name + '=' + c.value).join('; ');
+await page.evaluate(s => { window.__COOKIE__ = s; }, str);
+return 'Stored ' + cookies.length + ' cookies, length=' + str.length;
+```
+
+Step 3b via `browser_evaluate`:
+```js
+window.__COOKIE__
+```
+
+**Step 4: Validate** — Must be pure ASCII, contain `session=` and `sl_session=`, length 500-5000. If >10000, it's contaminated.
+
+**Step 5: Write config** using exact format (NO `"type": "stdio"`):
+```json
+{
+  "feishu-user-plugin": {
+    "command": "npx",
+    "args": ["-y", "feishu-user-plugin"],
+    "env": {
+      "LARK_COOKIE": "<cookie>",
+      "LARK_APP_ID": "<id>",
+      "LARK_APP_SECRET": "<secret>",
+      "LARK_USER_ACCESS_TOKEN": "<uat>",
+      "LARK_USER_REFRESH_TOKEN": "<refresh>"
+    }
+  }
+}
+```
 
 ## Troubleshooting
 
 ### If cookie authentication fails
-- **Best method**: Playwright `context.cookies()` (includes HttpOnly)
-- **Manual fallback**: Network tab → Disable cache → reload → first request → Request Headers → Cookie → Copy value
+- **Best method**: Playwright two-step extraction (see above)
+- **Manual fallback**: Network tab → first request → Request Headers → Cookie → Copy value
 - Do NOT use `document.cookie` or Application → Cookies (misses HttpOnly cookies)
 
+### If Playwright logs into the wrong account
+- Always `context.clearCookies()` BEFORE navigating to feishu.cn
+- Verify account by checking URL domain after login
+
+### If UAT refresh fails with "invalid_grant" (error 28003/20003/20005)
+- Refresh token expired — re-run `node src/oauth.js` (needs LARK_APP_ID + LARK_APP_SECRET in `.env`)
+- Copy new UAT + refresh token from `.env` to MCP config, then restart Claude Code
+
 ### If list_user_chats doesn't return P2P chats
-- This is expected — the Feishu API only returns group chats at this endpoint.
-- Use the P2P flow: `search_contacts` → `create_p2p_chat` → `read_p2p_messages`.
+- Expected — API only returns groups. Use: `search_contacts` → `create_p2p_chat` → `read_p2p_messages`.
 
 ### If reply_message fails with error 230054
-- "This operation is not supported for this message type" — only text messages can be replied to.
+- Only text messages can be replied to via this API.

package/src/index.js

@@ -255,7 +255,7 @@ const TOOLS = [
     inputSchema: {
       type: 'object',
       properties: {
-        chat_id: { type: 'string', description: 'Chat ID (oc_xxx). Use list_user_chats to find P2P chat IDs.' },
+        chat_id: { type: 'string', description: 'Chat ID (numeric from create_p2p_chat, or oc_xxx from list_user_chats). Both formats work.' },
         page_size: { type: 'number', description: 'Messages to fetch (default 20, max 50)' },
         start_time: { type: 'string', description: 'Start timestamp in seconds (optional)' },
         end_time: { type: 'string', description: 'End timestamp in seconds (optional)' },
@@ -691,7 +691,16 @@ async function handleTool(name, args) {
 async function main() {
   const transport = new StdioServerTransport();
   await server.connect(transport);
-  console.error('[feishu-user-plugin] MCP Server v1.0.0 — %d tools available', TOOLS.length);
+
+  // Startup diagnostics
+  const hasCookie = !!process.env.LARK_COOKIE;
+  const hasApp = !!(process.env.LARK_APP_ID && process.env.LARK_APP_SECRET);
+  const hasUAT = !!process.env.LARK_USER_ACCESS_TOKEN;
+  console.error(`[feishu-user-plugin] MCP Server v1.0.1 — ${TOOLS.length} tools`);
+  console.error(`[feishu-user-plugin] Auth: Cookie=${hasCookie ? 'YES' : 'NO'} App=${hasApp ? 'YES' : 'NO'} UAT=${hasUAT ? 'YES' : 'NO'}`);
+  if (!hasCookie) console.error('[feishu-user-plugin] WARNING: LARK_COOKIE not set — user identity tools (send_to_user, etc.) will fail');
+  if (!hasApp) console.error('[feishu-user-plugin] WARNING: LARK_APP_ID/SECRET not set — official API tools (read_messages, docs, etc.) will fail');
+  if (!hasUAT) console.error('[feishu-user-plugin] WARNING: LARK_USER_ACCESS_TOKEN not set — P2P chat reading (read_p2p_messages) will fail');
 }
 
 main().catch(console.error);