meegle-cli-mcp

文档说明与引用

本 README 同时参考以下来源进行整理与校验：

• 用户提供的《Meegle MCP 功能验证测试报告》（测试时间：2026-07-25 11:25 ~ 11:33 CST，项目：产研工作空间-测试，project_key: 69afc3cc1f11d2763e9711bf）
• 官方文档：https://github.com/larksuite/meegle-cli/blob/main/README.zh-CN.md

其中，工具能力边界、流程建议与排障提示以本仓库实现为准；安装与配置细节补充参考官方文档。

一个基于本地 meegle CLI 的 stdio MCP server，面向 VS Code / Copilot 等 MCP 客户端使用。

它遵循两条原则：

• 不处理登录，只复用本机已经可用的 meegle 认证状态
• 不假设默认项目，多项目场景统一先走 project_search

快速开始

前提：

• 本机已安装并可执行 meegle
• 本机 meegle auth status 已通过
• Node.js 18+

Meegle CLI 安装与配置（来自官方 README）

官方来源：

• https://github.com/larksuite/meegle-cli/blob/main/README.zh-CN.md

1) 安装（交互式）

前置条件：

• Node.js >= 16（含 npm / npx）

运行安装向导（会安装或升级 CLI、配置 host，并引导登录）：

npx @lark-project/meegle@latest install

2) 安装（AI Agent / CI / 无头环境）

在无浏览器或无 TTY 场景，建议启用 Device Code：

npx -y @lark-project/meegle@latest install --host <host> --device-code --lang zh

<host> 示例：

• project.feishu.cn
• meegle.com
• 自建租户域名

安装后建议先验证：

meegle auth status

3) 认证常用命令

meegle auth login
meegle auth login --device-code
meegle auth status
meegle auth logout

4) 配置常用命令

meegle config init
meegle config show
meegle config set host project.feishu.cn
meegle config get host

配置文件位置：

• ~/.meegle/config.json

5) 多环境 Profile

meegle config profile create staging
meegle config profile list
meegle config profile use staging
meegle config profile current
meegle config profile delete staging

临时指定 profile 运行：

meegle mywork todo --action this_week --page-num 1 --profile staging

6) 沙盒 / CI 环境变量注入

export MEEGLE_HOST=project.feishu.cn
export MEEGLE_USER_ACCESS_TOKEN=<your-user-token>
export MEEGLE_USER_AGENT=ci-runner

可选：自定义 token header（覆盖默认 Authorization）

export MEEGLE_ACCESS_TOKEN_HEADER=x-meegle-auth

说明：

• 设置 MEEGLE_USER_ACCESS_TOKEN 后，CLI 会优先使用环境变量 token。
• 可在 config.json 使用 ${VAR} 模板引用环境变量（仅整串占位符会展开）。

安装依赖：

npm install

启动 server：

npm start

本地检查：

npm run check
npm run smoke:test

VS Code 配置

如果你在 VS Code / Copilot MCP 配置里接入，通常可以直接使用：

{
  "servers": {
    "meegle-cli": {
      "type": "stdio",
      "command": "node",
      "args": ["/Users/betty/meegle-cli-mcp/src/server.mjs"]
    }
  }
}

通用 mcpServers 写法也可用：

{
  "mcpServers": {
    "meegle-cli": {
      "command": "node",
      "args": ["/Users/betty/meegle-cli-mcp/src/server.mjs"]
    }
  }
}

如果你现在是在 AWS Q 或其他使用 mcpServers 结构的客户端里接入，也可以直接按下面这种方式配置：

{
  "mcpServers": {
    "meegle-cli": {
      "command": "node",
      "args": ["/absolute/path/to/meegle-cli-mcp/src/server.mjs"]
    }
  }
}

如果你之前已经有类似这样的配置：

{
  "mcpServers": {
    "lark": {
      "command": "node",
      "args": ["/absolute/path/to/lark-cli-mcp/server.mjs"]
    }
  }
}

那么新增 meegle-cli 时，只需要并列加一个 server：

{
  "mcpServers": {
    "lark": {
      "command": "node",
      "args": ["/absolute/path/to/lark-cli-mcp/server.mjs"]
    },
    "meegle-cli": {
      "command": "node",
      "args": ["/absolute/path/to/meegle-cli-mcp/src/server.mjs"]
    }
  }
}

Claude Desktop / Cursor 一般也可复用同一套 stdio 配置。

多项目原则

这套 server 明确按多项目场景设计：

• 不依赖 MEEGLE_DEFAULT_PROJECT_KEY
• 没有明确项目时，先调用 project_search
• 有多个候选项目时，先确认项目，再继续项目级工具
• 后续项目级工具尽量显式传 project_key

推荐顺序：

1. project_search
2. workitem_meta_types / view_search / team_list 等项目内解析工具
3. 具体业务 tool

VS Code 使用建议

对模型最关键的信息来自三层：

1. tool 的 description
2. tool 的 inputSchema
3. tool 的 annotations

当前 server 已补齐这些元数据。模型在 tools/list 后，应该能知道：

• 哪些 tool 是只读查询
• 哪些 tool 有副作用
• 哪些写操作默认要先 dry_run=true
• 多项目场景应先用 project_search

Tool 标签约定

• readOnlyHint=true：纯查询工具
• destructiveHint=true：可能写数据或触发动作
• idempotentHint=true：适合探测或重试
• openWorldHint=true：会访问外部 Meegle 系统

Tool 索引

认证与发现

• auth_status：检查本地 meegle 登录态
• project_search：多项目第一入口，解析项目或列最近项目
• inspect_command：查看底层 meegle CLI 命令 schema
• meegle_command：原始 argv 透传兜底工具

工作项查询

• workitem_meta_types：查询项目支持的工作项类型
• workitem_meta_fields：查询字段 key、字段类型和选项
• workitem_discover_status_values：采样某类工作项里实际出现过的状态 key 和显示标签，避免猜 OPEN、IN_PROGRESS
• workitem_query：项目级列表 / 搜索入口，要求完整 MQL
• workitem_query：项目级列表 / 搜索入口，要求完整 MQL；状态或枚举过滤要用项目实际显示值，不要假设 OPEN、IN_PROGRESS
• workitem_get：查询单个工作项详情
• workitem_batch_get：批量查询多个工作项

工作项写操作

• workitem_create：创建工作项，默认 dry_run=true
• workitem_update：更新字段或角色，默认 dry_run=true

评论与附件

• comment_list：查询评论
• comment_add：新增评论，默认 dry_run=true
• attachment_prepare_download：下载前预处理
• attachment_prepare_upload：上传前预处理

关系、视图、图表

• relation_meta_definitions：查询关系定义
• relation_list：查询关联工作项
• view_search：按名称解析 view_id
• view_get：查询视图下工作项
• chart_list：查询视图下图表
• chart_get：查询单个图表详情

团队、用户、工时

• user_resolve_keys：把姓名 / 邮箱 / 别名解析为规范 user_key
• user_search：查询用户明细（底层透传）
• team_list：查询团队
• team_list_members：查询团队成员
• workhour_list_schedule：查询排期与工作量

我的工作台与流程

• mywork_todo：查询我的待办、已办、逾期、本周任务
• workflow_get_node：查询节点详情和子任务上下文
• workflow_list_state_transitions：查询可流转状态
• workflow_smart_transition：自动识别节点流 / 状态流并执行对应流转（默认 dry_run=true）
• workflow_transition：节点流流转，默认 dry_run=true
• workflow_transition_state：状态流流转，默认 dry_run=true
• subtask_update：子任务创建 / 更新 / 完成 / 回滚，默认 dry_run=true；若项目未开启资源库会返回专用 hint

Prompt 模板

除了 tool，这个 server 还暴露了一组 prompt 模板，给模型提供稳定的工作流模板：

• resolve_project_context：多项目场景第一入口
• query_project_workitems：查需求 / 缺陷 / 任务
• safe_workitem_update：安全更新工作项
• inspect_view_and_chart：查视图和图表
• personal_work_queue：查个人待办和追踪详情
• workflow_and_subtask_action：处理工作流和子任务

这些 prompt 不替代 tool，而是告诉模型“应该先做什么，再做什么”。

常用调用范式

先解析项目

• 用户只说“帮我看产研工作空间”：先 project_search
• 没有任何项目线索：空参调用 project_search
• 多个候选项目都像目标：先确认项目，再继续

查工作项

• 按状态筛选前先探测：workitem_discover_status_values -> workitem_query
• 查某个空间里有什么需求：project_search -> workitem_meta_types -> workitem_query
• 按标题模糊找工作项：workitem_query -> workitem_get
• 更新前查字段 schema：workitem_meta_fields -> workitem_update
• 按状态筛选工作项：优先使用项目里的状态显示值；不要直接猜 OPEN、IN_PROGRESS 这类英文常量

查视图 / 图表

• 先按名字找视图：view_search
• 再查视图内容：view_get
• 再查图表：chart_list -> chart_get

查节点 / 子任务 / 状态流

• 先查节点：workflow_get_node
• 查可流转状态：workflow_list_state_transitions
• 首选自动流转：workflow_smart_transition
• 节点流或状态流写操作：先 dry_run=true，确认后再 dry_run=false

workflow_smart_transition 关键参数：

• mode=auto：自动判定节点流 / 状态流
• work_item_type：状态流且未提供 transition_id 时必填
• target_status_label：按目标状态名匹配 transition
• auto_pick_first_transition=true：当状态流有多条候选、且没给 transition_id/target_status_label 时，自动选第一条

查人 / 团队 / 排期

• 先解析用户：user_resolve_keys
• 先解析团队：team_list
• 再查成员或排期：team_list_members / workhour_list_schedule

推荐用户字段写入链路：

1. user_resolve_keys 拿到 resolved_user_keys
2. 把 resolved_user_keys 写入 workitem_create/workitem_update/subtask_update 相关用户字段

参数约定

项目参数

• 多项目场景建议显式传 project_key
• 项目不明确时不要猜，先调用 project_search

写操作参数

• workitem_create
• workitem_update
• comment_add
• workflow_transition
• workflow_transition_state
• subtask_update

这些默认都应先保持 dry_run=true。

复杂字段值

对 workitem_create / workitem_update / subtask_update 等工具：

• 数组和对象值可以直接传给 MCP tool
• server 会自动转成 meegle CLI 需要的 JSON 字符串

MQL 状态与枚举值

• workitem_query 里的状态、枚举、下拉选项值通常是项目自己的显示值
• 不要假设所有项目都支持 OPEN、IN_PROGRESS、DONE 这种英文常量
• 字符串值优先使用单引号，例如 '新建'
• 当状态过滤失败时，优先判断是不是“值不属于这个项目的实际标签”，而不是 tool 本身坏了

本地联调

npm run smoke:test 会自动完成：

1. tools/list
2. tools/call -> project_search
3. prompts/list
4. tools/call -> auth_status
5. tools/call -> workitem_meta_types，但只在先拿到项目后再调用
6. tools/call -> workitem_discover_status_values
7. prompts/get -> safe_workitem_update

如果你只想确认 server 能否被正常加载：

npm run check

排障

工具调用失败

• 先调 auth_status
• 再看是否缺少 project_key
• 多项目场景先回到 project_search

写操作不生效

• 检查是否还在 dry_run=true
• 检查字段 key 是否来自 workitem_meta_fields

项目选错

• 不要依赖历史上下文猜项目
• 重新调用 project_search
• 必要时让用户确认候选项目

说明

• 这个 server 不处理登录流程，只复用当前 shell 环境里已经可用的 meegle 认证状态
• 所有命令都通过 spawn('meegle', args) 调用，不经过 shell
• 工具默认追加 --format json，便于 MCP 客户端消费结构化输出