feishu-user-plugin 1.3.1 → 1.3.3

package/src/index.js

@@ -1,4 +1,14 @@
 #!/usr/bin/env node
+// MCP stdio protocol uses stdout for JSON-RPC. ANY accidental stdout write from
+// this process or its dependencies will corrupt the transport and disconnect the
+// client. v1.3.1 patched the Lark SDK's defaultLogger via a custom logger, but
+// that only covers one dependency. This global redirect is defense-in-depth:
+// any present or future module that calls console.log (or console.info) goes to
+// stderr instead, so MCP stdio stays clean no matter what.
+// Do this BEFORE any other require() so even early log calls are captured.
+console.log = (...args) => console.error(...args);
+console.info = (...args) => console.error(...args);
+
 const { Server } = require('@modelcontextprotocol/sdk/server/index.js');
 const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.js');
 const {
@@ -144,12 +154,17 @@ const TOOLS = [
   // ========== User Identity — Send Messages ==========
   {
     name: 'send_as_user',
-    description: '[User Identity] Send a text message as the logged-in Feishu user. Supports reply threading.',
+    description: '[User Identity] Send a text message as the logged-in Feishu user. Supports reply threading and real @-mentions (triggers push notifications).',
     inputSchema: {
       type: 'object',
       properties: {
         chat_id: { type: 'string', description: 'Target chat ID (numeric)' },
-        text: { type: 'string', description: 'Message text' },
+        text: { type: 'string', description: 'Message text. If `ats` is provided, include the display marker for each @ in this text (default marker is `@<name>`).' },
+        ats: {
+          type: 'array',
+          description: 'Optional @-mentions. Each entry: {userId: "ou_xxx", name: "DisplayName"}. The text must contain each @<name> marker in order — it gets spliced into a real AT element so the mentioned user receives a notification.',
+          items: { type: 'object', properties: { userId: { type: 'string' }, name: { type: 'string' }, marker: { type: 'string' } } },
+        },
         root_id: { type: 'string', description: 'Thread root message ID (for reply, optional)' },
         parent_id: { type: 'string', description: 'Parent message ID (for nested reply, optional)' },
       },
@@ -164,6 +179,11 @@ const TOOLS = [
       properties: {
         user_name: { type: 'string', description: 'Recipient name (Chinese or English)' },
         text: { type: 'string', description: 'Message text' },
+        ats: {
+          type: 'array',
+          description: 'Optional @-mentions. Same format as send_as_user.ats: [{userId, name}]. Text must contain the `@<name>` marker for each entry.',
+          items: { type: 'object', properties: { userId: { type: 'string' }, name: { type: 'string' }, marker: { type: 'string' } } },
+        },
       },
       required: ['user_name', 'text'],
     },
@@ -176,6 +196,11 @@ const TOOLS = [
       properties: {
         group_name: { type: 'string', description: 'Group chat name' },
         text: { type: 'string', description: 'Message text' },
+        ats: {
+          type: 'array',
+          description: 'Optional @-mentions that trigger real notifications. Each entry: {userId, name}. Text must contain `@<name>` marker for each entry.',
+          items: { type: 'object', properties: { userId: { type: 'string' }, name: { type: 'string' }, marker: { type: 'string' } } },
+        },
       },
       required: ['group_name', 'text'],
     },
@@ -222,7 +247,7 @@ const TOOLS = [
   },
   {
     name: 'send_post_as_user',
-    description: '[User Identity] Send a rich text (POST) message with title and formatted paragraphs.',
+    description: '[User Identity] Send a rich text (POST) message with title and formatted paragraphs. Supports real @-mentions that trigger notifications.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -230,7 +255,7 @@ const TOOLS = [
         title: { type: 'string', description: 'Post title (optional)' },
         paragraphs: {
           type: 'array',
-          description: 'Array of paragraphs. Each paragraph is an array of elements: {tag:"text",text:"..."} or {tag:"a",href:"...",text:"..."} or {tag:"at",userId:"..."}',
+          description: 'Array of paragraphs. Each paragraph is an array of elements:\n• {tag:"text",text:"..."} — plain text\n• {tag:"a",href:"https://...",text:"display"} — hyperlink\n• {tag:"at",userId:"ou_xxx",name:"Display Name"} — real @-mention (triggers notification)',
           items: { type: 'array', items: { type: 'object' } },
         },
         root_id: { type: 'string', description: 'Thread root message ID (optional)' },
@@ -674,13 +699,13 @@ const TOOLS = [
   // ========== IM — Bot Send / Edit / Delete ==========
   {
     name: 'send_message_as_bot',
-    description: '[Official API] Send a message as the bot to any chat. Supports text, post, interactive, etc.',
+    description: '[Official API] Send a message as the bot to any chat. Supports text, post, interactive, etc. This is the reliable path for @-mentions: include `<at user_id="ou_xxx">Name</at>` inline in text content and Feishu resolves it to a real @-notification.',
     inputSchema: {
       type: 'object',
       properties: {
         chat_id: { type: 'string', description: 'Target chat_id (oc_xxx) or open_id' },
         msg_type: { type: 'string', description: 'Message type: text, post, image, interactive, etc.', enum: ['text', 'post', 'image', 'interactive', 'share_chat', 'share_user', 'audio', 'media', 'file', 'sticker'] },
-        content: { description: 'Message content (string or object, auto-serialized). For text: {"text":"hello"}' },
+        content: { description: 'Message content (string or object, auto-serialized). Plain text: {"text":"hello"}. Text with @-mention: {"text":"<at user_id=\\"ou_xxx\\">Alice</at> hi"} — the inline tag becomes a real @-notification.' },
       },
       required: ['chat_id', 'msg_type', 'content'],
     },
@@ -977,6 +1002,20 @@ const TOOLS = [
     },
   },
 
+  // ========== Message Resources (Image/File Download) ==========
+  {
+    name: 'download_image',
+    description: '[User Identity / Official API] Download an image embedded in a message so the model can actually see it. Pass the message_id and image_key returned by read_messages / read_p2p_messages. Tries user identity first (works for any chat the user sees), falls back to app identity (requires the bot to be in the same chat).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        message_id: { type: 'string', description: 'The message_id (om_xxx) that contains the image — from read_messages / read_p2p_messages' },
+        image_key: { type: 'string', description: 'The image_key from the message content (img_xxx)' },
+      },
+      required: ['message_id', 'image_key'],
+    },
+  },
+
 ];
 
 // --- Server ---
@@ -1008,7 +1047,7 @@ async function handleTool(name, args) {
 
     case 'send_as_user': {
       const c = await getUserClient();
-      const r = await c.sendMessage(args.chat_id, args.text, { rootId: args.root_id, parentId: args.parent_id });
+      const r = await c.sendMessage(args.chat_id, args.text, { rootId: args.root_id, parentId: args.parent_id, ats: args.ats });
       return sendResult(r, `Text sent as user to ${args.chat_id}`);
     }
     case 'send_to_user': {
@@ -1023,7 +1062,7 @@ async function handleTool(name, args) {
       const user = users[0];
       const chatId = await c.createChat(user.id);
       if (!chatId) return text(`Failed to create chat with ${user.title}`);
-      const r = await c.sendMessage(chatId, args.text);
+      const r = await c.sendMessage(chatId, args.text, { ats: args.ats });
       return sendResult(r, `Text sent to ${user.title} (chat: ${chatId})`);
     }
     case 'send_to_group': {
@@ -1036,7 +1075,7 @@ async function handleTool(name, args) {
         return text(`Multiple groups match "${args.group_name}":\n${candidates}\nUse search_contacts to find the exact group, then send_as_user with the ID.`);
       }
       const group = groups[0];
-      const r = await c.sendMessage(group.id, args.text);
+      const r = await c.sendMessage(group.id, args.text, { ats: args.ats });
       return sendResult(r, `Text sent to group "${group.title}" (${group.id})`);
     }
 
@@ -1124,9 +1163,20 @@ async function handleTool(name, args) {
         parts.push(`  ${status.message}`);
       } catch (e) { parts.push(`Cookie: ${e.message}`); }
       const hasApp = !!(process.env.LARK_APP_ID && process.env.LARK_APP_SECRET);
-      parts.push(`App credentials: ${hasApp ? 'Configured' : 'Not set'}`);
-      const official = hasApp ? getOfficialClient() : null;
-      parts.push(`User access token: ${official?.hasUAT ? 'Configured (P2P reading enabled)' : 'Not set (optional — needed for P2P chat reading. Run OAuth flow to obtain, see README for details)'}`);
+      if (!hasApp) {
+        parts.push(`App credentials: Not set`);
+      } else {
+        const official = getOfficialClient();
+        const probe = await official.verifyApp();
+        if (probe.valid) {
+          const nameBit = probe.appName ? ` "${probe.appName}"` : '';
+          parts.push(`App credentials: Valid — app_id=${probe.appId}${nameBit}`);
+        } else {
+          parts.push(`App credentials: INVALID — app_id=${probe.appId} rejected by Feishu (${probe.error})`);
+          parts.push(`  → Likely wrong/stale APP_ID. Re-run the install prompt from team-skills/plugins/feishu-user-plugin/README.md to get the correct credentials.`);
+        }
+        parts.push(`User access token: ${official.hasUAT ? 'Configured (P2P reading enabled)' : 'Not set (optional — needed for P2P chat reading. Run OAuth flow to obtain, see README for details)'}`);
+      }
       return text(parts.join('\n'));
     }
 
@@ -1221,32 +1271,17 @@ async function handleTool(name, args) {
     case 'get_doc_blocks':
       return json(await getOfficialClient().getDocBlocks(args.document_id));
     case 'create_doc': {
-      const official = getOfficialClient();
-      if (official.hasUAT) {
-        try {
-          const result = await official.createDocAsUser(args.title, args.folder_id);
-          return text(`Document created (as user): ${result.documentId}`);
-        } catch (e) {
-          console.error(`[feishu-user-plugin] UAT createDoc failed, falling back to app: ${e.message}`);
-        }
-      }
-      return text(`Document created: ${(await official.createDoc(args.title, args.folder_id)).documentId}`);
+      const r = await getOfficialClient().createDoc(args.title, args.folder_id);
+      const ownership = r.viaUser ? ' (as user)' : ' (as app — UAT unavailable or failed; document owned by the app, not you)';
+      return text(`Document created${ownership}: ${r.documentId}`);
     }
 
     // --- Official API: Bitable ---
 
     case 'create_bitable': {
-      const official = getOfficialClient();
-      if (official.hasUAT) {
-        try {
-          const r = await official.createBitableAsUser(args.name, args.folder_id);
-          return text(`Bitable created (as user): ${r.appToken}\nURL: ${r.url || ''}`);
-        } catch (e) {
-          console.error(`[feishu-user-plugin] UAT createBitable failed, falling back to app: ${e.message}`);
-        }
-      }
-      const r = await official.createBitable(args.name, args.folder_id);
-      return text(`Bitable created: ${r.appToken}\nURL: ${r.url || ''}`);
+      const r = await getOfficialClient().createBitable(args.name, args.folder_id);
+      const ownership = r.viaUser ? ' (as user)' : ' (as app — UAT unavailable or failed; bitable owned by the app, not you)';
+      return text(`Bitable created${ownership}: ${r.appToken}\nURL: ${r.url || ''}`);
     }
     case 'list_bitable_tables':
       return json(await getOfficialClient().listBitableTables(args.app_token));
@@ -1297,15 +1332,9 @@ async function handleTool(name, args) {
     case 'list_files':
       return json(await getOfficialClient().listFiles(args.folder_token));
     case 'create_folder': {
-      const official = getOfficialClient();
-      if (official.hasUAT) {
-        try {
-          return text(`Folder created (as user): ${(await official.createFolderAsUser(args.name, args.parent_token)).token}`);
-        } catch (e) {
-          console.error(`[feishu-user-plugin] UAT createFolder failed, falling back to app: ${e.message}`);
-        }
-      }
-      return text(`Folder created: ${(await official.createFolder(args.name, args.parent_token)).token}`);
+      const r = await getOfficialClient().createFolder(args.name, args.parent_token);
+      const ownership = r.viaUser ? ' (as user)' : ' (as app — UAT unavailable or failed; folder owned by the app, not you)';
+      return text(`Folder created${ownership}: ${r.token}`);
     }
 
     // --- Official API: Contact ---
@@ -1398,6 +1427,18 @@ async function handleTool(name, args) {
     case 'delete_file':
       return text(`File deleted: task=${(await getOfficialClient().deleteFile(args.file_token, args.type)).taskId}`);
 
+    case 'download_image': {
+      const r = await getOfficialClient().downloadMessageResource(args.message_id, args.image_key, 'image');
+      // Return as MCP image content so the model sees the pixels directly.
+      // Also include a tiny text preamble so the via-identity + size are visible in transcript.
+      return {
+        content: [
+          { type: 'text', text: `Image downloaded (${r.viaUser ? 'as user' : 'as app'}, ${r.bytes} bytes, ${r.mimeType}):` },
+          { type: 'image', data: r.base64, mimeType: r.mimeType },
+        ],
+      };
+    }
+
     default:
       return text(`Unknown tool: ${name}`);
   }
@@ -1427,6 +1468,27 @@ async function main() {
   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');
+
+  // Validate APP_ID/SECRET against Feishu before serving any tool calls.
+  // Catches the "Claude filled in a wrong/stale APP_ID during install" failure mode
+  // that otherwise surfaces as cryptic 401s on every Official API call (looks like
+  // "MCP 掉线" to the user). Non-blocking — we warn but still serve, because the
+  // user may only need user-identity (cookie) tools.
+  if (hasApp) {
+    try {
+      const probe = await getOfficialClient().verifyApp();
+      if (probe.valid) {
+        const nameBit = probe.appName ? ` "${probe.appName}"` : '';
+        console.error(`[feishu-user-plugin] App verified: ${probe.appId}${nameBit}`);
+      } else {
+        console.error(`[feishu-user-plugin] ERROR: LARK_APP_ID=${probe.appId} was REJECTED by Feishu (${probe.error}).`);
+        console.error('[feishu-user-plugin] → Every Official API tool call will fail. Likely wrong/stale APP_ID.');
+        console.error('[feishu-user-plugin] → Re-run the install prompt from team-skills/plugins/feishu-user-plugin/README.md to get the correct credentials.');
+      }
+    } catch (e) {
+      console.error(`[feishu-user-plugin] WARNING: Could not verify APP_ID (${e.message}); network issue or cold start. Proceeding anyway.`);
+    }
+  }
 }
 
 main().catch(console.error);