feishu-user-plugin 1.1.0 → 1.1.1

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "feishu-user-plugin",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "All-in-one Feishu plugin for Claude Code — send messages as yourself, read chats, manage docs/tables/wiki. 33 tools + 9 skills, 3 auth layers.",
   "author": {
     "name": "EthanQC"

package/CHANGELOG.md

@@ -4,6 +4,13 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/), and this project adheres to [Semantic Versioning](https://semver.org/).
 
+## [1.1.1] - 2026-03-11
+
+### Fixed
+- **read_messages can't read external groups**: `read_messages` now auto-falls back to UAT when bot API fails (e.g. bot not in group, external groups). No need to manually switch to `read_p2p_messages`.
+- **Chat name resolution for external groups**: Added Strategy 3 using `search_contacts` (cookie-based) to find groups not visible to bot or `im.chat.search`.
+- **Numeric chat IDs not accepted by read_messages**: `resolveToOcId` now passes through numeric IDs directly.
+
 ## [1.1.0] - 2026-03-11
 
 ### Fixed

package/package.json

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

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

@@ -1,6 +1,6 @@
 ---
 name: feishu-user-plugin
-version: "1.1.0"
+version: "1.1.1"
 description: "All-in-one Feishu plugin — send messages as yourself, read group/P2P chats, manage docs/tables/wiki. Replaces and extends the official Feishu MCP."
 allowed-tools: send_to_user, send_to_group, send_as_user, send_image_as_user, send_file_as_user, send_post_as_user, send_sticker_as_user, send_audio_as_user, search_contacts, create_p2p_chat, get_chat_info, get_user_info, get_login_status, read_p2p_messages, list_user_chats, list_chats, read_messages, reply_message, forward_message, search_docs, read_doc, create_doc, list_bitable_tables, list_bitable_fields, search_bitable_records, create_bitable_record, update_bitable_record, list_wiki_spaces, search_wiki, list_wiki_nodes, list_files, create_folder, find_user
 user_invocable: true

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

@@ -30,7 +30,7 @@ All-in-one Feishu plugin for Claude Code with three auth layers:
 - `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)
-- `list_chats` / `read_messages` — Chat history (read_messages accepts chat name, auto-resolves to oc_ ID)
+- `list_chats` / `read_messages` — Chat history (accepts chat name, oc_ ID, or numeric ID; auto-falls back to UAT for external groups)
 - `reply_message` / `forward_message` — Message operations (as bot). reply_message only works for text messages.
 - `search_docs` / `read_doc` / `create_doc` — Document operations
 - `list_bitable_tables` / `list_bitable_fields` / `search_bitable_records` — Table queries
@@ -42,7 +42,7 @@ All-in-one Feishu plugin for Claude Code with three auth layers:
 ## Usage Patterns
 - 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 any group chat history → `read_messages` with chat name or ID (auto-handles external groups via UAT fallback)
 - 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)

package/src/index.js

@@ -48,6 +48,8 @@ class ChatIdMapper {
 
   async resolveToOcId(chatIdOrName, official) {
     if (chatIdOrName.startsWith('oc_')) return chatIdOrName;
+    // Also accept raw numeric IDs (from search_contacts)
+    if (/^\d+$/.test(chatIdOrName)) return chatIdOrName;
     // Strategy 1: Search in bot's group list cache
     const cached = await this.findByName(chatIdOrName, official);
     if (cached) return cached;
@@ -67,6 +69,27 @@ class ChatIdMapper {
     }
     return null;
   }
+
+  // Strategy 3: Use search_contacts (cookie-based) to find external groups by name
+  // Returns numeric chat_id that works with UAT readMessagesAsUser
+  async resolveViaContacts(chatName, userClient) {
+    if (!userClient) return null;
+    try {
+      const results = await userClient.search(chatName);
+      const groups = results.filter(r => r.type === 'group');
+      // Exact match first
+      for (const g of groups) {
+        if (g.title === chatName) return String(g.id);
+      }
+      // Partial match
+      for (const g of groups) {
+        if (g.title && g.title.includes(chatName)) return String(g.id);
+      }
+    } catch (e) {
+      console.error('[feishu-user-plugin] search_contacts fallback failed:', e.message);
+    }
+    return null;
+  }
 }
 
 // --- Client Singletons ---
@@ -306,11 +329,11 @@ const TOOLS = [
   },
   {
     name: 'read_messages',
-    description: '[Official API] Read message history. Accepts oc_xxx ID or chat name (auto-searched via bot group list + im.chat.search). Returns newest messages first by default, with sender names resolved.',
+    description: '[Official API + UAT fallback] Read message history from any group. Accepts oc_xxx ID, numeric ID, or chat name (auto-searched). Auto-falls back to UAT for external groups the bot cannot access. Returns newest messages first by default, with sender names resolved.',
     inputSchema: {
       type: 'object',
       properties: {
-        chat_id: { type: 'string', description: 'Chat ID (oc_xxx) or chat name (auto-searched)' },
+        chat_id: { type: 'string', description: 'Chat ID (oc_xxx), numeric ID, or chat name (auto-searched via bot groups, im.chat.search, and user contacts)' },
         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)' },
@@ -508,7 +531,7 @@ const TOOLS = [
 // --- Server ---
 
 const server = new Server(
-  { name: 'feishu-user-plugin', version: '1.1.0' },
+  { name: 'feishu-user-plugin', version: '1.1.1' },
   { capabilities: { tools: {} } }
 );
 
@@ -653,14 +676,38 @@ async function handleTool(name, args) {
       return json(await getOfficialClient().listChats({ pageSize: args.page_size, pageToken: args.page_token }));
     case 'read_messages': {
       const official = getOfficialClient();
+      const msgOpts = { pageSize: args.page_size, startTime: args.start_time, endTime: args.end_time, sortType: args.sort_type };
       const resolvedChatId = await chatIdMapper.resolveToOcId(args.chat_id, official);
-      if (!resolvedChatId) {
-        return text(`Cannot resolve "${args.chat_id}" to oc_ ID. Searched bot's group list and used im.chat.search API — no match found.\nTry: list_chats to see all bot groups, or provide the oc_xxx ID directly.\nIf the bot is not in this group, use read_p2p_messages with UAT instead.`);
+
+      // Try bot API first if we resolved an oc_ ID
+      if (resolvedChatId) {
+        try {
+          return json(await official.readMessages(resolvedChatId, msgOpts));
+        } catch (botErr) {
+          // Bot API failed (e.g. bot not in group, no permission) — fall through to UAT
+          console.error(`[feishu-user-plugin] read_messages bot API failed for ${resolvedChatId}: ${botErr.message}`);
+          if (official.hasUAT) {
+            try {
+              return json(await official.readMessagesAsUser(resolvedChatId, msgOpts));
+            } catch (uatErr) {
+              console.error(`[feishu-user-plugin] read_messages UAT fallback also failed for ${resolvedChatId}: ${uatErr.message}`);
+            }
+          }
+          throw botErr; // Re-throw original error if UAT also failed
+        }
       }
-      return json(await official.readMessages(resolvedChatId, {
-        pageSize: args.page_size, startTime: args.start_time, endTime: args.end_time,
-        sortType: args.sort_type,
-      }));
+
+      // Bot couldn't resolve the chat name — try search_contacts + UAT for external groups
+      if (official.hasUAT) {
+        let contactClient = null;
+        try { contactClient = await getUserClient(); } catch (_) {}
+        const contactChatId = await chatIdMapper.resolveViaContacts(args.chat_id, contactClient);
+        if (contactChatId) {
+          return json(await official.readMessagesAsUser(contactChatId, msgOpts));
+        }
+      }
+
+      return text(`Cannot resolve "${args.chat_id}" to a chat ID.\nSearched: bot's group list, im.chat.search API, and user contacts (search_contacts).\nTry: provide the oc_xxx or numeric chat ID directly.`);
     }
     case 'reply_message':
       return text(`Reply sent: ${(await getOfficialClient().replyMessage(args.message_id, args.text)).messageId}`);
@@ -725,7 +772,7 @@ async function main() {
   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.1.0 — ${TOOLS.length} tools`);
+  console.error(`[feishu-user-plugin] MCP Server v1.1.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');

package/src/test-comprehensive.js

@@ -274,7 +274,7 @@ async function testUAT() {
 }
 
 async function main() {
-  console.log('=== feishu-user-plugin v1.1.0 — Comprehensive Test ===\n');
+  console.log('=== feishu-user-plugin v1.1.1 — Comprehensive Test ===\n');
 
   await testUserIdentity();
   console.log('');