Meego Skill（飞书项目全能力技能）#

本技能通过飞书项目官方 MCP 接口提供全部能力。 底层调用工具： meego-mcporter（MCP over stdio 协议），凭证通过 OAuth 管理。

---

一、完整功能索引#

#功能场景核心工具需要 OAuth1查我的在途工作项list_todo✅2查任意工作项详情get_workitem_brief✅3查工作项节点/子任务get_node_detail✅4流转工作项状态get_transitable_states + update_field✅5添加评论add_comment✅6创建工作项create_workitem✅7修改工作项字段update_field✅8查工时记录get_workitem_man_hour_records✅9查字段配置list_workitem_field_config✅10查工作项类型list_workitem_types✅11查团队成员list_team_members / list_project_team✅12查成员排期list_schedule✅13查项目空间信息search_project_info✅14按标题搜索视图search_view_by_title✅15查视图下图表list_charts / get_chart_detail✅16MQL 自由查询search_by_mql✅17查工作项操作记录get_workitem_op_record✅18关联工作项查询list_related_workitems✅

---

二、前置条件（逐项检查）#

依赖要求检查命令检查失败怎么做Node.js≥ 16node --version升级 Node.jsnpm任意版本npm --version随 Node.js 自动安装mcporter已安装并可用mcporter --help见安装步骤第一步meego-mcporter已安装并可用meego-mcporter --help 或 npx @lark-project/meego-mcporter --help见安装步骤第二步OAuth 凭证已完成授权并同步到服务器meego-mcporter call meego list_todo --args '{}'见安装步骤第三步飞书项目已开通企业版联系管理员—

一键检查脚本：

bash

node --version && mcporter --help && meego-mcporter --help && echo "✅ 工具就绪"

---

三、完整安装步骤（两步完成）#

核心原理： meego-mcporter 通过 MCP over stdio 协议连接飞书项目 MCP 服务器，OAuth 授权由 mcporter 管理。安装只需两步：装工具 → 做授权。

第一步：安装工具（服务器 + 本地电脑都要装）#

服务器端（已有 Node.js 环境）：

bash

npm install -g mcporter
npm install -g @lark-project/meego-mcporter

本地电脑（用于完成 OAuth 授权）：

powershell

# Windows PowerShell / 命令提示符
npm install -g mcporter
npm install -g @lark-project/meego-mcporter

bash

# Mac/Linux 终端
sudo npm install -g mcporter
sudo npm install -g @lark-project/meego-mcporter

验证安装（服务器或本地都行）：

bash

meego-mcporter --help

---

第二步：在本地电脑完成 OAuth 授权（关键步骤）#

第一步：创建配置文件

在本地电脑新建 meego-config.json（内容固定，服务器地址不变）：

json

{
  "mcpServers": {
    "meego": {
      "url": "https://project.feishu.cn/mcp_server/v1",
      "auth": "oauth"
    }
  }
}

⚠️ meego 是服务器名称，不要改。 url 和 auth 字段固定，不需要填 App ID/Secret。

第二步：触发授权

powershell

npx @lark-project/meego-mcporter auth meego --config meego-config.json

bash

# Mac/Linux
npx @lark-project/meego-mcporter auth meego --config ./meego-config.json

这个命令会：

1. 启动一个本地 HTTP 服务监听 callback
2. 自动打开浏览器跳转发书授权页面
3. 用户在飞书点击"授权"后，callback 收到 code
4. 自动用 code 换取 access_token + refresh_token
5. 自动保存到 ~/.mcporter/credentials.json（本地电脑）

预期输出：

text

Opening browser for OAuth authorization...
Authorization received. Exchanging for tokens...
Success! Credentials saved to ~/.mcporter/credentials.json

第三步：把 credentials 上传到服务器

授权完成后，在本地电脑执行：

bash

type %USERPROFILE%\.mcporter\credentials.json
# Windows PowerShell:
# Get-Content $env:USERPROFILE\.mcporter\credentials.json

bash

# Mac/Linux:
cat ~/.mcporter/credentials.json

把完整 JSON 内容发给 AI助手（粘贴到聊天里），AI会自动写入服务器的 /root/.mcporter/credentials.json。

服务器credentials路径： /root/.mcporter/credentials.json（Linux服务器） 本地 credentials 路径： ~/.mcporter/credentials.json

---

验证连接#

服务器上执行：

bash

meego-mcporter call meego list_todo --args '{}'

预期：返回当前用户在飞书项目中的在途工作项列表。

✅ 全部通过 → 配置完成！

---

四、调用格式详解#

标准格式（服务器上直接用）#

bash

meego-mcporter call meego <工具名> --args '<JSON参数>'

凭证自动从 /root/.mcporter/credentials.json 读取，无需每次传 --config。

⚠️ JSON 参数必须用单引号包裹，外层用双引号。这是 shell 转义要求。

传 URL 自动解析（最简单）#

如果用户提供了一个 Meego 链接，直接把完整 URL 作为 url 参数传入，系统自动解析 project_key 和 work_item_id：

bash

meego-mcporter call meego get_workitem_brief --args '{
  "url": "https://project.feishu.cn/more/more?workitem_id=123456&project_key=你的project_key"
}'

分页查询#

所有 list 类工具支持分页，用 page_num（从1开始）：

bash

meego-mcporter call meego list_todo --args '{"page_num": 2}'

---

五、每个场景的完整调用示例#

场景 1：查我的在途工作项（最高频）#

bash

meego-mcporter call meego list_todo --args '{}'

返回：工作项ID、名称、类型、当前节点、计划开始/结束时间。 分页：每页50条。

---

场景 2：查任意工作项详情#

bash

meego-mcporter call meego get_workitem_brief --args '{
  "project_key": "你的project_key",
  "work_item_id": 123456
}' --config /workspace/meego-config.json

也支持直接传 URL：

bash

meego-mcporter call meego get_workitem_brief --args '{
  "url": "https://project.feishu.cn/more/more?workitem_id=123456&project_key=你的project_key"
}' --config /workspace/meego-config.json

---

场景 3：查工作项节点（子任务）#

bash

meego-mcporter call meego get_node_detail --args '{
  "project_key": "你的project_key",
  "work_item_id": 123456,
  "need_sub_task": true
}' --config /workspace/meego-config.json

---

场景 4：流转工作项状态（三步完成）#

第一步：查可流转到哪些状态

bash

meego-mcporter call meego get_transitable_states --args '{
  "project_key": "你的project_key",
  "work_item_id": 123456,
  "work_item_type": "issue",
  "user_key": "你的user_key（从 list_todo 返回中获取）"
}' --config /workspace/meego-config.json

第二步：查目标状态需要填哪些必填字段

bash

meego-mcporter call meego get_transition_required --args '{
  "project_key": "你的project_key",
  "work_item_id": 123456,
  "state_key": "RESOLVED"
}' --config /workspace/meego-config.json

第三步：执行流转

bash

meego-mcporter call meego update_field --args '{
  "project_key": "你的project_key",
  "work_item_id": 123456,
  "fields": ["work_item_status:RESOLVED"]
}' --config /workspace/meego-config.json

---

场景 5：添加评论#

bash

meego-mcporter call meego add_comment --args '{
  "project_key": "你的project_key",
  "work_item_id": 123456,
  "comment_content": "## 修复方案\n\n已定位原因，正在修复中，请稍候。\n\n@负责人 请review"
}' --config /workspace/meego-config.json

评论内容支持 Markdown。

---

场景 6：创建工作项#

第一步：查该类型的必填字段（必须先做）

bash

meego-mcporter call meego get_workitem_field_meta --args '{
  "project_key": "你的project_key",
  "work_item_type": "issue"
}' --config /workspace/meego-config.json

第二步：创建工作项

bash

meego-mcporter call meego create_workitem --args '{
  "project_key": "你的project_key",
  "work_item_type": "issue",
  "fields": [
    "name:缺陷标题",
    "priority:1",
    "severity:2",
    "work_item_status:OPEN"
  ]
}' --config /workspace/meego-config.json

字段 key 从第一步返回获取。常见 key： name（标题）、 priority（优先级）、 severity（严重程度）、 work_item_status（状态）。

---

场景 7：修改工作项字段#

bash

# 单个字段
meego-mcporter call meego update_field --args '{
  "project_key": "你的project_key",
  "work_item_id": 123456,
  "fields": ["priority:0"]
}' --config /workspace/meego-config.json

# 多个字段
meego-mcporter call meego update_field --args '{
  "project_key": "你的project_key",
  "work_item_id": 123456,
  "fields": ["priority:1", "name:新标题"]
}' --config /workspace/meego-config.json

---

场景 8：查工时记录#

bash

meego-mcporter call meego get_workitem_man_hour_records --args '{
  "project_key": "你的project_key",
  "work_item_id": 123456,
  "work_item_type": "issue"
}' --config /workspace/meego-config.json

---

场景 9：查工作项字段配置#

bash

# 查某类型的完整字段列表（含选项值）
meego-mcporter call meego list_workitem_field_config --args '{
  "project_key": "你的project_key",
  "work_item_type": "issue",
  "page_num": 1
}' --config /workspace/meego-config.json

# 模糊搜索字段（找负责人的字段key等）
meego-mcporter call meego list_node_field_config --args '{
  "project_key": "你的project_key",
  "work_item_type": "issue",
  "query": "负责人"
}' --config /workspace/meego-config.json

---

场景 10：查工作项类型#

bash

meego-mcporter call meego list_workitem_types --args '{
  "project_key": "你的project_key"
}' --config /workspace/meego-config.json

返回： type_key（如 issue/ story/ sub_task）。

---

场景 11：查团队成员#

bash

# 查项目下所有团队
meego-mcporter call meego list_project_team --args '{
  "project_key": "你的project_key"
}' --config /workspace/meego-config.json

# 查某团队的成员
meego-mcporter call meego list_team_members --args '{
  "project_key": "你的project_key",
  "team_id": "team_xxx"
}' --config /workspace/meego-config.json

---

场景 12：查成员排期#

bash

meego-mcporter call meego list_schedule --args '{
  "project_key": "你的project_key",
  "user_keys": ["你的user_key"],
  "start_time": "2026-03-01",
  "end_time": "2026-03-31"
}' --config /workspace/meego-config.json

• 时间格式： YYYY-MM-DD，最大范围3个月
• user_keys：从 list_team_members 或 list_todo 中获取的 user_key 列表

---

场景 13：查项目空间信息（获取 project_key）#

bash

# 用项目中文名查询
meego-mcporter call meego search_project_info --args '{
  "project_key": "你的项目名称"
}' --config /workspace/meego-config.json

# 用 simple_name 查询
meego-mcporter call meego search_project_info --args '{
  "project_key": "your_simple_name"
}' --config /workspace/meego-config.json

返回： project_key（数字）、 simple_name、 project_name。

---

场景 14：MQL 自由查询#

⚠️ MQL 语法严格，字段名必须与 API 字段名完全一致。先用 list_workitem_field_config 查实名字段 key 再填入。

bash

# 查所有 OPEN 状态的缺陷
meego-mcporter call meego search_by_mql --args '{
  "project_key": "你的project_key",
  "mql": "work_item_status = \"OPEN\" and work_item_type_key = \"issue\""
}' --config /workspace/meego-config.json

# 查高优先级在途缺陷
meego-mcporter call meego search_by_mql --args '{
  "project_key": "你的project_key",
  "mql": "priority = \"0\" and work_item_status not in (\"CLOSED\",\"REJECTED\")"
}' --config /workspace/meego-config.json

# 分页查询
meego-mcporter call meego search_by_mql --args '{
  "project_key": "你的project_key",
  "mql": "work_item_status not in (\"CLOSED\")",
  "session_id": "上次返回的session_id"
}' --config /workspace/meego-config.json

issue（缺陷）状态值：

状态 key含义OPEN开始IN PROGRESS待确认REPAIRING待修复IN REPAIRING修复中RESOLVED已修复VERIFYING验证中REOPENED重新打开CLOSED已关闭REJECTED拒绝ABONDONED废弃

常用字段速查：

字段key示例值名称name字符串状态work_item_status见上方状态值优先级priority``0（最高）/ 1（高）/ 2（中）/ 99（低）严重程度severity``1（致命）/ 2（严重）/ 3（一般）/ 4（轻微）当前负责人current_status_operatoruser_key 字符串创建者owneruser_key 字符串

---

六、异常处理（完整版）#

运行时错误速查#

错误现象第一步排查解决方案OAuth authorization required / xdg-open ENOENT服务器无浏览器，OAuth 授权未完成见下方「授权异常」专项处理401 Unauthorizedtoken 过期见下方「token 刷新」专项处理403 Forbidden应用权限不足飞书开放平台 → 权限管理申请权限 → 重新发版404 Not Foundproject_key 或 work_item_id 错误确认 URL 中参数正确MCP error -32000: Connection closedOAuth token 无效或已过期刷新 token，见下方流程Permission denied应用未被加入项目空间项目管理员 → 设置 → 成员管理 → 添加应用workflow:invalid_state流转到不合法的状态先用 get_transitable_states 查可流转状态Command not found: meego-mcportermeego-mcporter 未安装npm install -g @lark-project/meego-mcporterMQL syntax error字段名拼写错误用 list_workitem_field_config 确认字段 key工具调用无输出/超时token 失效刷新 token

---

专项一：授权异常（最常见）#

错误 1： xdg-open ENOENT（服务器无浏览器环境）

服务器环境没有浏览器，无法自动打开授权页面。解决流程：

第一步：本地完成授权

powershell

# 本地电脑执行（Windows）
npx @lark-project/meego-mcporter auth meego --config meego-config.json

bash

# Mac/Linux
npx @lark-project/meego-mcporter auth meego --config ./meego-config.json

第二步：导出 credentials

powershell

# 本地电脑执行
type $env:USERPROFILE\.mcporter\credentials.json

第三步：发给 AI助手，AI自动写入服务器 /root/.mcporter/credentials.json

---

错误 2： OAuth authorization required for 'meego'（token 不存在）

服务器上 credentials 文件缺失或内容为空。同上流程：本地完成授权 → 导出 credentials → 发给 AI。

---

专项二：Token 过期处理#

错误： MCP error -32000: Connection closed 或 401 Unauthorized

原因： OAuth access_token 有效期 2 小时，refresh_token 有效期 30 天。

自动刷新（推荐）：

本地完成一次 meego-mcporter auth meego --config meego-config.json（会覆盖 credentials），然后重新导出 credentials 上传到服务器。

手动刷新（无浏览器时）：

access_token 过期后，refresh_token 还在有效期内（30天），直接替换 credentials 中的 access_token 即可：

powershell

# 本地执行，导出最新 credentials
type $env:USERPROFILE\.mcporter\credentials.json

把新 credentials 发给 AI助手 更新到服务器。

---

专项三：权限类错误#

错误信息原因解决方法permission denied应用未开通飞书项目权限飞书开放平台 → 权限管理 → 申请 project 权限 → 重新发版project:workitem:not_found应用未被加入项目空间项目管理员 → 设置 → 成员管理 → 添加应用workflow:invalid_state流转到不合法的状态先用 get_transitable_states 查可流转状态

---

专项四：网络与连接错误#

错误信息原因解决方法Connection timeout网络超时确认服务器可访问 project.feishu.cn``HTTP 403IP 白名单限制飞书后台 → 安全设置 → 关闭 IP 白名单HTTP 429请求过快降低调用频率，加 sleep 1 延时

---

七、调试与排障流程图#

text

工具调用报错
  │
  ├─ OAuth authorization required / xdg-open ENOENT
  │     → 本地执行 auth → 导出 credentials → 发给 AI 更新服务器
  │
  ├─ MCP error -32000: Connection closed / 401 Unauthorized
  │     → token 过期
  │     → 本地执行 auth 刷新 → 新 credentials 发给 AI
  │
  ├─ 403 Forbidden / permission denied
  │     ├─ 应用权限未申请 → 飞书开放平台申请 + 发版
  │     └─ 应用未加入项目 → 项目设置 → 成员管理 → 添加应用
  │
  ├─ 404 Not Found
  │     → 检查 project_key 和 work_item_id 是否正确
  │
  ├─ MQL syntax error
  │     → 字段名拼写错误，用 list_workitem_field_config 确认 key
  │
  └─ 返回空列表
        → 可能无数据（非错误），确认查询条件是否合理

---

八、凭证与权限体系#

凭证文件#

环境文件路径用途服务器（Linux）/root/.mcporter/credentials.jsonOAuth token（AI助手写入）本地电脑~/.mcporter/credentials.jsonOAuth token（auth 命令自动写入）

配置格式不是 app_id + app_secret JSON，而是 OAuth credentials JSON（由飞书授权流程自动生成）。

权限申请检查表#

需要的功能必须申请的权限是否需重新发版工作项读写project:workitem✅状态流转project:workflowstatus✅评论project:comment✅成员查询project:member✅排期查询project:schedule✅视图查询project:view✅基础读写project✅

---

九、参考文件索引#

文件内容references/tools.md所有工具完整清单（40+ 接口）references/mql.mdMQL 查询语法与完整示例references/fields.md工作项字段配置参考