chuxubank Feishu Project Skill
Query, browse, and manage Feishu Project (飞书项目/Meego) workspaces, work items,
views, schedules, and team information via the mcp__feishu__* MCP tool suite.
Core Workflow
1. Identify the Space (空间)
Before any query, determine the project_key (空间标识). Resolve in this order:
A URL the user provides (extract
project_keyfrom the URL path)The user naming the space directly — pass the name to
search_project_infoPrior conversation context
Fallback: Read project-local configuration files and extract a Feishu Project key. Check these files in order, if they exist:
.agents/constant.md.agents/constants.mdlocal.properties.env.env.local
Recognize any of these keys:
feishu-project-keyfeishu_project_keyFEISHU_PROJECT_KEYproject_key
# .agents/constant.md example
- feishu-project-key: my_project_key
# local.properties example
feishu-project-key=my_project_key
When using fallback files, read only the candidate key lines silently and use the first value found without asking the user. Do not print or expose unrelated local configuration values, secrets, tokens, or credentials. If none of the files exist or none contains a project key, then ask the user to provide one.
search_project_info(project_key="<name or key>")
2. Identify the Work Item Type (工作项类型)
Most tools require a work_item_type. Common built-in types:
| 中文名 | Key |
|---|---|
| 需求 | story |
| 缺陷 | issue |
| 任务 | task |
| 子任务 | sub_task |
For custom types, call:
list_workitem_types(project_key="...")
3. Choose the Right Tool
Route to the appropriate reference document by category:
| Category | Covers | Reference |
|---|---|---|
| Space & Metadata | 空间信息、工作项类型、字段/角色配置、关联关系定义 | references/space-metadata.md |
| Work Items | 查询、创建、修改、状态流转（状态流工作项） | references/work-items.md |
| Views & Charts | 视图搜索/详情、图表、固定视图管理 | references/views-charts.md |
| Nodes & Subtasks | 节点详情、子任务 CRUD、节点流转/回滚（节点流工作项） | references/nodes-subtasks.md |
| Teams & Users | 团队列表/成员、用户信息查询、排期/工作量 | references/teams-users.md |
| Activity | 评论列表/添加、操作记录、工时登记 | references/activity.md |
| Resource Work Items | 资源库配置、资源实例创建、从资源创建工作项、交付物查询 | references/resource-work-items.md |
| Attachments | 附件上传/下载、分片上传、富文本图片 | references/attachments.md |
| MQL Queries | 复杂条件搜索语法（含节点/关联/状态时间高级函数） | references/mql-guide.md |
4. Present Results
- Render work item lists as Markdown tables with key columns: ID, name, status, assignee, priority.
- For single work item details, use structured sections.
- Always include the work item URL when available.
- When results are paginated, inform the user of the total count and offer to fetch more.
Key Workflows
Searching Work Items with MQL
For complex queries, use search_by_mql. Always call list_workitem_field_config
first to discover field keys and enum values before composing MQL.
Refer to references/mql-guide.md for full MQL syntax, functions, and examples.
Quick pattern:
SELECT `work_item_id`, `name`, `current_status_name`, `priority`
FROM `<space>`.`<work_item_type>`
WHERE <conditions>
Viewing My Todo List
list_todo(action="todo", page_num=1) # 待办
list_todo(action="done", page_num=1) # 已办
list_todo(action="overdue", page_num=1) # 逾期
list_todo(action="this_week", page_num=1) # 本周待办
Each page returns 50 items. To get all results, iterate page_num until fewer than
50 items are returned.
Viewing Work Item Details
get_workitem_brief(work_item_id="<id>", project_key="<key>",
fields=["name", "current_status_name", "priority", ...])
Pass specific field keys to retrieve only relevant fields. See references/work-items.md for querying patterns including MQL and todo list.
Creating Work Items
See references/work-items.md for the required preparation steps and field format reference.
Updating Work Items
See references/work-items.md for field update patterns and references/nodes-subtasks.md for node/subtask updates.
Working with URLs
When the user provides a Feishu project URL, extract parameters from it:
project_key— the space identifierwork_item_type— the work item type keywork_item_id— the specific work item IDview_id— the view identifier
Many tools accept a url parameter that auto-extracts these values.
Field Type Quick Reference
| Field Type | Value Format |
|---|---|
| text / number / bool / link | Literal value |
| select / radio / tree-select | Option ID (from field config) |
| multi-select | [{"option_id": "..."}] |
| user | user_key string |
| multi-user | ["user_key_1", "user_key_2"] |
| date | Millisecond timestamp |
| schedule | [start_ms, end_ms] |
| precise_date | {"start_time": ms, "end_time": ms} |
| workitem_related_select | Work item ID (number) |
| workitem_related_multi_select | [id1, id2] (number array) |
| multi-text | Markdown string |
| role_owners | [{"role": "RoleName", "owners": ["user_key"]}] |
Pagination
Most list endpoints return paginated results (default 50/page). When the user asks
for "all" items, loop page_num starting from 1 until a page returns fewer items
than the page size.
Additional Resources
Reference Files
references/space-metadata.md— Space info, work item types, field/role configs, relation definitions.references/work-items.md— Querying, creating, and updating work items; field type reference; todo list.references/views-charts.md— Views search/detail, chart listing, fixed view management.references/nodes-subtasks.md— Node detail, subtask CRUD, node/state transitions.references/teams-users.md— Team lists, team members, user info lookup, schedule/workload.references/activity.md— Comments, operation records, man-hour logs.references/resource-work-items.md— Resource library config, resource instance CRUD, deliverables.references/attachments.md— File upload/download, multipart upload, rich text images.references/mql-guide.md— Full MQL syntax, functions, field type mapping, and query examples.