# 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，并引导登录）：

```bash
npx @lark-project/meegle@latest install
```

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

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

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

`<host>` 示例：

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

安装后建议先验证：

```bash
meegle auth status
```

### 3) 认证常用命令

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

### 4) 配置常用命令

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

配置文件位置：

- `~/.meegle/config.json`

### 5) 多环境 Profile

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

临时指定 profile 运行：

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

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

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

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

```bash
export MEEGLE_ACCESS_TOKEN_HEADER=x-meegle-auth
```

说明：

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

安装依赖：

```bash
npm install
```

启动 server：

```bash
npm start
```

本地检查：

```bash
npm run check
npm run smoke:test
```

## VS Code 配置

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

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

通用 `mcpServers` 写法也可用：

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

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

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

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

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

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

```json
{
  "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 能否被正常加载：

```bash
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 客户端消费结构化输出