dt-ai-mcp

在 Cursor 等支持 MCP 的 IDE 中连接 AI管理平台（OAuth2 设备码登录）。

功能

• auth_login：methods / start / poll / status（OAuth2 设备码）
• auth_me：当前用户
• auth_logout：退出登录并清理本地凭证
• assets_search：查询资产列表
• assets_detail：按 ID 查单条详情（assetType 可选；不传时由后端按统一 ID 自动识别）
• assets_download：按 ID 导出资产（rule/skill 通过 dir 指定导出根目录；不传时按 CLIENT_TYPE 推断默认目录）
• assets_update：更新资产（仅 rule/skill）；可传 dir 由 MCP 自动把本地目录转换后提交更新（不传时按 CLIENT_TYPE 推断并要求确认）
• assets_create：创建资产（仅 rule/skill，权限由后端拦截）

使用

npx -y dt-ai-mcp@latest

在 Cursor 的 MCP 配置里将启动命令设为上述命令，并配置下方环境变量。

环境变量

export BASE_URL="http://localhost:8080"
export CLIENT_TYPE="cursor"   # cursor | workbuddy

补充说明（重点：CLIENT_TYPE）

为避免“为什么这次没提示选择目录/CLIENT_TYPE”的疑惑，建议按下面规则理解：

• 参数优先级：dir > CLIENT_TYPE > 补参提示

  • 传了 dir：直接按 dir 执行，不看 CLIENT_TYPE
  • 没传 dir 但有 CLIENT_TYPE：按 CLIENT_TYPE 推断默认目录
  • 两者都没有：返回 needMoreInput=true，提示补 CLIENT_TYPE 或直接传 dir

• CLIENT_TYPE 只接受两个值（不区分大小写，内部会转小写）：

  • cursor：默认目录 {工作区}/.cursor
  • workbuddy：默认目录 {工作区}/.workbuddy
  • 通用规则：默认目录 = {工作区}/.${CLIENT_TYPE}
  • 其他值会被当作未配置处理

• {工作区} 的来源：

  • 直接使用当前运行目录

• 各动作行为差异：

  • assets_download：
    • cursor/workbuddy：未传 dir 且未传 useGlobalDir 时会先补问“是否全局导出”
    • 其余情况：useGlobalDir=true 走固定全局目录（需 CLIENT_TYPE 且会校验写权限）；否则走工作区默认目录
  • assets_create / assets_update：未传 dir 时，除推断目录外还需要 confirmDefaultDir=true 才继续

• 常见原因与排查：

  • 改了 .cursor/mcp.json 但行为没变化：通常是 MCP 进程未重启，重启后再试
  • 仍提示缺少 CLIENT_TYPE：确认配置写在当前工程的 MCP server env 下，而不是其他工程
  • 希望行为稳定可预期：调用时显式传 dir，不依赖默认推断

登录（设备码）

推荐按下面的“用户可理解流程”执行：

1. 调用 auth_login，{ "action": "start" }
2. 把返回的 verificationUriComplete 原样发给用户，让用户点击并在浏览器完成授权
3. 用户回复“已授权”后，调用 auth_login，{ "action": "poll" }
4. 调用 auth_me 确认已登录

可直接发给用户的话术：

请点击此链接完成授权：verificationUriComplete。完成后回复“已授权”，我将继续登录。

可先调用 { "action": "methods" } 查看说明。请在浏览器中登录，不要在对话里向 MCP 发送密码。

assets_search

• assetType：rule | skill | mcp | all（默认 all）
• keyword：关键词，透传后端，与平台搜索一致
• mine：可选，true 仅查当前用户自己的资产
• status：主要用于 mine=true 的场景（筛自己资产状态）
• categoryId / categoryIds：分类筛选
• page：页码，默认 1；用户要翻页时传目标页码
• pageSize：每页条数，默认 10，上限 50
• all：走统一接口 GET /v1/assets 的聚合查询；其他类型走 GET /v1/assets/{assetType}

响应结构：

{
  "ok": true,
  "message": "查询成功",
  "summary": "共 23 条，共 3 页（当前第 1 页，每页 10 条）。",
  "paginationHint": "若需翻页，请告知目标页码（1 到 3），我会带 page=<页码> 重新查询。",
  "data": {
    "assetType": "rule",
    "page": {
      "records": [/* ... */],
      "page": 1,
      "pageSize": 10,
      "total": 23,
      "totalPages": 3,
      "hasNext": true,
      "hasPrev": false
    }
  }
}

summary 与 paginationHint 是给上层助手直接面向用户复述的中文摘要，总条数/总页数/当前页已经算好；翻页时把目标 page 透传回来即可。

assets_detail

• id：资产 ID（必填，正整数）
• assetType：rule | skill | mcp（可选；传入则直查，不传走统一详情）

无查看权限或资源不存在时，接口会失败；与 Web 端一致，由后端统一鉴权。

assets_download

• assetType、id：同 assets_detail（无权限则无法拉取内容）
• dir：可选，单参数决定导出根目录
  • 支持绝对路径（如 /Users/me/.workbuddy 或 C:\\Users\\me\\.workbuddy）
  • 支持相对工作区路径（如 .cursor、.workbuddy、exports/workbuddy）
  • 支持 ~（如 ~/.cursor、~/.workbuddy）
• useGlobalDir：可选，布尔值；仅在未提供 dir 时生效
• 路径决策优先级：
  • 传了 dir：直接使用 dir
  • CLIENT_TYPE=cursor|workbuddy 且未传 dir、未传 useGlobalDir：先返回补参，要求确认 useGlobalDir（true/false）
  • 未传 dir 且 useGlobalDir=true：按 CLIENT_TYPE 固定全局目录
    • cursor -> ~/.cursor
    • workbuddy -> ~/.workbuddy
    • 会先检查写权限；无权限时报错 GLOBAL_DIR_NOT_WRITABLE
    • 若缺少 CLIENT_TYPE，返回补参提示
  • 未传 dir 且 useGlobalDir!=true：按 CLIENT_TYPE 推断工作区默认目录
    • cursor -> {工作区}/.cursor
    • workbuddy -> {工作区}/.workbuddy
• 当 dir 缺失且无法通过上述规则确定目录时，会返回补参提示
• 覆盖策略：下载前会先删除本地目标目录及同名 .zip（若存在），不做版本比对，始终按本次拉取结果整包覆盖。
• rule / skill：从 OSS 版本文件（manifest + file-content）重建内容；无 bundle 时为单个 .md，有 bundle 时展开为多文件目录（不生成 .zip）
• mcp：不写入本地文件，直接返回 configJson / toolsJson / remark 供复制使用

assets_create

• 仅支持 rule / skill
• 必填：assetType（如能从 dir 路径推断也可省略；见下方决策规则）
• 可选：name（不传时默认使用 dir 目录名）、description、version、tags（version 省略时后端默认 v1.0）
• dir：可选，本地目录（绝对路径或相对工程根；工程根固定为当前进程 cwd）；传入后由 MCP 自动转换：
  • rule / skill：目录文件转 ASSET_BUNDLE_V1 内容并写入 content

路径决策（cursor / workbuddy 一致）

• 传了 dir：
  • 路径段含 rules（不含 skills）→ 自动判定为 rule
  • 路径段含 skills（不含 rules）→ 自动判定为 skill
  • 同时含 / 都不含 → 返回 needMoreInput，要求传 assetType
  • 用户显式传 assetType 时，优先采用，不再做路径推断
• 未传 dir：
  • 必须先有 CLIENT_TYPE（cursor 或 workbuddy），否则返回补参
  • 必须先有 assetType（仅 rule / skill），否则返回补参
  • MCP 会列出候选目录供用户选择：
    • 项目目录：{工作区}/.${CLIENT_TYPE}/{rules|skills}/*
    • 全局目录：~/.${CLIENT_TYPE}/{rules|skills}/*
  • 候选条目带 source: 'project' | 'global' 与 path，按最近修改时间倒序
  • 候选为空时不阻塞：candidateDirs: [] + 提示用户直接传 dir
  • 不再使用 confirmDefaultDir（已废弃）

错误处理

• 上传过程遇到本地文件系统权限错误（EACCES / EPERM）：直接把原始错误信息抛给用户，不做任何兜底/重试/回退

assets_update

• 仅支持 rule / skill（mcp 资产不在此工具受理范围）
• 已发布资产：后端只更新草稿；你作为作者/管理员在详情、或列表带 mine=true 时会优先看到草稿，所以体感像「一保存就变了」；访客/公共列表仍读已发布版本，真正对外替换要走平台「申请发布 → 审核」。
• 必填：id、changeLog
• 可选：assetType、name、description、tags、version、reuseDraftVersion、dir、entryPath、content
• assetType 处理：
  • 不传 → MCP 按 id 拉详情自动确定
  • 传了且与详情不一致 → 以详情为准，并在响应 warnings 中提示
  • 详情类型为 mcp → 直接拒绝（请走平台其他入口）
• name 默认沿用线上资产名；用户显式传 name 优先
• 草稿复用：已发布且存在未发布草稿时，可传 reuseDraftVersion=true 沿用当前草稿版本号（与手动传 version 二选一）

路径决策（与 assets_create 一致）

• 传了 dir：直接使用（仅支持目录，不支持单文件）
  • 如果 dir 路径段（rules/skills）与详情类型不一致，仍按详情类型为准，并在响应 warnings 中提示
• 未传 dir：
  • 必须先有 CLIENT_TYPE（cursor 或 workbuddy），否则返回补参
  • 按详情的 assetType 列出候选目录供用户选择：
    • 项目目录：{工作区}/.${CLIENT_TYPE}/{rules|skills}/*
    • 全局目录：~/.${CLIENT_TYPE}/{rules|skills}/*
  • 候选条目带 source: 'project' | 'global' 与 path，按最近修改时间倒序
  • 候选为空时不阻塞：candidateDirs: [] + 提示用户直接传 dir
  • 不再使用 confirmDefaultDir（已废弃）

错误处理

• 上传过程遇到本地文件系统权限错误（EACCES / EPERM）：直接把原始错误信息抛给用户，不做任何兜底/重试/回退