feishu-interaction

# Feishu/Lark Platform Interaction You have access to the Feishu/Lark platform via MCP tools (prefixed `feishu-lark__`). This enables you to interact with the user's Feishu workspace: search and read documents, manage tasks, create calendar events, operate Bitable databases, and send messages. ## Available Capabilities ### Documents (文档) - `docx.v1.document.rawContent` — Read document content - `docx.builtin.import` — Import documents (create new docs from content) - `docx.builtin.search` — Search documents by keyword - `wiki.v2.space.getNode` — Get Wiki node content - `wiki.v1.node.search` — Search Wiki nodes ### Tasks (任务) - `task.v2.task.create` — Create a new task with title, description, due date - `task.v2.task.patch` — Update an existing task - `task.v2.task.addMembers` — Add members to a task - `task.v2.task.addReminders` — Add reminders to a task ### Calendar (日历) - `calendar.v4.calendarEvent.create` — Create a calendar event - `calendar.v4.calendarEvent.patch` — Modify a calendar event - `calendar.v4.calendarEvent.get` — Get calendar event details - `calendar.v4.freebusy.list` — Query free/busy status - `calendar.v4.calendar.primary` — Get primary calendar info ### Bitable (多维表格) - `bitable.v1.appTable.list` — List tables in a base - `bitable.v1.appTableField.list` — List fields in a table - `bitable.v1.appTableRecord.search` — Search records - `bitable.v1.appTableRecord.create` — Create records - `bitable.v1.appTableRecord.update` — Update records ### Messaging (消息) - `im.v1.message.create` — Send a message to a chat or user - `im.v1.message.list` — List messages in a chat - `im.v1.chat.create` — Create a new group chat - `im.v1.chat.list` — List chats the bot is in ### Contacts (通讯录) - `contact.v3.user.batchGetId` — Batch get user IDs by email/mobile ## Best Practices ### Document Operations 1. **Search before read** — Always search for documents first to find the correct `document_id` 2. **Prefer Wiki nodes** — If the user mentions "知识库" or "Wiki", use wiki APIs 3. **Cite sources** — When referencing document content in replies, include the document title ### Task Management 1. **Match user intent** — When user says "帮我创建一个任务", use `task.v2.task.create` 2. **Set due dates** — Always ask for or infer a due date when creating tasks 3. **Add members** — If the user mentions specific people, resolve their user IDs via contacts API first ### Calendar Events 1. **Check availability** — Before creating an event, use `freebusy.list` to check conflicts 2. **Time zones** — Default to Asia/Shanghai unless the user specifies otherwise 3. **Include details** — Set description, location, and attendees when provided ### Bitable Operations 1. **Discover structure** — List tables and fields before searching records 2. **Filter queries** — Use search with filter conditions rather than fetching all records 3. **Batch operations** — For multiple records, prefer batch create/update when available ### Messaging 1. **Format appropriately** — Use markdown formatting for rich messages 2. **Respect context** — Only send messages when the user explicitly asks to notify someone 3. **Interactive cards** — For structured information, use `msg_type: 'interactive'` with card JSON 4. **Send text** — Prefer native tool `feishu_send_message` (or MCP `im.v1.message.create`) 5. **Send local images** — Use native tool `feishu_send_image` with the absolute file path. Feishu MCP **cannot** upload images/files. Never claim an image was sent via MCP alone. 6. **Empty chat list** — `im.v1.chat.list` only returns groups the bot has joined. If it returns `items: []`, do **not** give up: resolve the user's `open_id` (e.g. via `calendar.v4.calendar.primary` → `user_id`, or `contact.v3.user.batchGetId`) and send with `receive_id_type=open_id` (p2p / "发到我的飞书"). ## Important Notes - Tool names are prefixed with `feishu-lark__` (e.g., `feishu-lark__docx.builtin.search`) - Document editing is NOT supported — you can only read and import - File/image upload via MCP is NOT supported — use `feishu_send_image` for local images - Always handle API errors gracefully and report them to the user - Respect rate limits: 1000 requests/minute per API endpoint ## Permission Error Handling When a tool call returns an error containing `code: 99991672` or "Access denied...scopes required", it means the Feishu application has not been granted the necessary API permissions. In this case: 1. **Extract the authorization URL** from the error message (starts with `https://open.feishu.cn/app/`) 2. **Present the link to the user** clearly, explaining they need to click it to authorize the required permissions 3. **Do NOT retry** the same tool call — it will continue to fail until permissions are granted 4. **List the missing scopes** mentioned in the error so the user knows what to authorize Example response format: > The Feishu app needs additional permissions to perform this operation. > Please open the following link to authorize, then try again: > > [https://open.feishu.cn/app/cli_xxx/auth?q=docs:doc,drive:drive,...](https://open.feishu.cn/app/cli_xxx/auth?q=docs:doc,drive:drive,...) > > Missing scopes: docs:doc, drive:drive Always use the full URL as both the link text AND the href (i.e. `[full_url](full_url)`), so the user can both see the complete URL and click it directly.