trustasia-ones-mcp

亚数 ONES 的 Model Context Protocol (MCP) server，让 Claude Desktop / Claude Code / Cursor 能直接创建、修改需求，管理 Wiki 知识库。

• 一次配置永久无感：浏览器交互登录钉钉，session 有效期最长 400 天
• 零代码安装：一条 npx 命令搞定，无需 git clone、无需 npm install
• 跨机器复制即用：Claude Desktop 配置同步到新机器，立刻可用

非技术同事：请直接跳到 docs/USER_GUIDE.md，零代码前提的三步指南。

30 秒安装（产品同事版）

# 1) 首装：弹出浏览器完成钉钉登录，自动打通 Claude Desktop
npx -y trustasia-ones-mcp setup

# 2) 按提示重启 Claude Desktop，完成

常用命令：

npx -y trustasia-ones-mcp status   # 看登录状态、剩余 session 寿命
npx -y trustasia-ones-mcp login    # 手动重新登录（密码改了用这个）

工具列表（16 个）

工作项

| 工具 | 说明 | |---|---| | list_projects | 列出团队下所有项目 | | list_issue_types | 列出团队下所有工作项类型（需求/任务/缺陷等） | | create_issue | 创建工作项 | | update_issue | 修改工作项（标题/描述/状态/负责人/优先级） | | get_issue | 按 UUID 查询单个工作项 | | search_issues | 按项目/关键字/状态/类型搜索 | | list_issue_fields | 列出某个工作项可用的字段（含自定义字段） | | list_issue_comments | 列出工作项评论与动态（默认仅评论） | | post_issue_comment | 在工作项下发表评论（Markdown 自动转 HTML） | | list_executable_workflows | 列出工作项当前能执行的状态流转动作 | | execute_workflow | 推进工作项执行一个状态流转，可附带评论 |

Wiki

| 工具 | 说明 | |---|---| | list_wiki_spaces | 列出可访问的知识库空间 | | list_wiki_pages | 列出空间下所有页面 | | create_wiki_page | 创建草稿 + 设标题（正文需在浏览器手动粘贴+发布，原因见下） | | update_wiki_page | 修改页面标题（正文同上限制） | | get_wiki_page | 查看页面 |

Wiki 内容写入限制：ONES Wiki 用 CRDT 协同编辑，正文写入需要 WebSocket 协议。 当前版本只能创建草稿、设标题，正文部分会渲染为 HTML 返回，请人工粘贴到浏览器编辑器后发布。

鉴权路径

ones-mcp 自动按优先级选择鉴权方式：

1. .env 里有完整 ONES_USER_ID + ONES_AUTH_TOKEN + ONES_TEAM_UUID → 走静态 token（legacy）
2. 本地 ~/.config/ones-mcp/session.json 存在且有效 → silent refresh（400 天无感）
3. 以上都没有 → 弹出浏览器让用户完成钉钉登录（扫码或输入密码）

产品同事走第 3 条（setup 会自动引导）；开发者如果只想要一次性跑跑可以走第 1 条。

示例对话

用户：帮我在 GoHTTPS 项目下建一个需求，标题"支持 IPv6"，描述用 markdown 写一下需求点

Claude 自动调用：

1. list_projects → 找到 GoHTTPS 的 UUID
2. list_issue_types → 找到"需求"类型 UUID
3. create_issue → 创建并返回新需求编号

开发者（从源码跑）

git clone https://git.trustasia.cn/trustasia/ones-mcp.git
cd ones-mcp
npm install
cp .env.example .env   # 按注释填 ONES_USER_ID/ONES_AUTH_TOKEN（可选，不填则走浏览器登录）
npm run dev            # 直接用 tsx 跑 stdio
npm run dev:http       # HTTP server 模式（多人共享）
npm test
npm run typecheck

目录结构

src/
├── auth/        # 鉴权：CredentialProvider、DingTalk 登录自动化、Chromium 自愈
├── cli/         # CLI 子命令：setup / login / status / stdio dispatcher
├── client/      # ONES HTTP + GraphQL 封装
├── tools/       # 11 个 MCP 工具实现
├── schemas/     # Zod 输入校验
├── utils/       # 错误、日志、UUID 生成
└── index.ts     # stdio 入口（被 cli/index.ts 委托）

HTTP server 模式（团队共享）

一台服务器起 ones-mcp，每个同事各自在 Claude 配置里填 header 传自己的 token。见 .env.server.example。

cp .env.server.example .env
npm run start:http
# ones-mcp HTTP server ready on http://127.0.0.1:3000

每人在 ~/.claude.json / .mcp.json 里写：

{
  "mcpServers": {
    "ones": {
      "type": "http",
      "url": "http://your-server:3000/mcp",
      "headers": {
        "X-Ones-User-Id": "自己的 uuid",
        "X-Ones-Auth-Token": "自己的 token"
      }
    }
  }
}

Token 抓取方法见 scripts/refresh-token.md（HTTP 模式下仍需 F12 手抓，或者在每个同事本机跑一次 setup 拿 token 回填 header）。

已知限制

• Wiki 正文写入需 CRDT WebSocket，当前不支持
• 钉钉风控可能触发滑块/SMS 验证（用户需在浏览器中手动完成一次）
• 搜索的 keyword 是客户端过滤（先拉一批再筛），适合小数据量

License

MIT