cosworkflow-mcp

Implementation Notes

This project follows the standard MCP TypeScript server layout: tsc → dist/, exposed via bin, consumed through npx. Dev uses tsx for instant transpile; releases ship the compiled dist/. Runs on Node.js + npm (Bun not required).

开发

npm install        # SDK(runtime)+ tsx/typescript/shx(dev/build)
npm start          # tsx 即时转译跑 src/index.ts(改代码即时生效)
npm run build      # tsc → dist/(含拷贝 ipd-api.cjs / ipd-token-logic.cjs)
npm run typecheck  # tsc --noEmit
npm run watch      # tsc --watch

作为 MCP server 消费(发布后)

发布到 npm 后,客户端 .mcp.json:

{
  "mcpServers": {
    "cosworkflow": {
      "command": "npx",
      "args": ["-y", "@costrict/cosworkflow@latest"]
    }
  }
}

不要在仓库内 .mcp.json 使用不带版本/标签的包规格:

{
  "command": "npx",
  "args": ["-y", "@costrict/cosworkflow"]
}

在本仓库根目录等同名 package 场景下,npm 会把 @costrict/cosworkflow 当作当前项目自引用,但不会为当前项目创建 _npx 临时安装包的 cosworkflow bin shim,最终报 cosworkflow 找不到。使用 @costrict/cosworkflow@latest 会强制走 registry 包解析,可稳定启动。

Windows 客户端:"command": "cmd","args": ["/c", "npx", "-y", "@costrict/cosworkflow@latest"]。 npx -y 首次运行自动从 npm 拉取本包及依赖,消费者无需手动安装(公共 scoped 包,免认证)。本地 dogfood 编译产物(不经 npx):"command": "node","args": ["dist/index.js"]。

发布(维护者)

发布由 GitHub Actions 自动完成(.github/workflows/release.yml):推 v* tag → npm ci → typecheck → build → npm publish 到 npmjs.org。

一次性准备:

1. 在 npm 创建组织 costrict(对应 scope @costrict),并确认 @costrict/cosworkflow 未被占用。
2. 生成 npm 发布 token(npm → Access Tokens → Classic/Granular,给 publish 权限)。
3. 在 GitHub 仓库 zgsm-sangfor/cosworkflow-mcp → Settings → Secrets and variables → Actions → 加仓库 secret NPM_TOKEN。

发版:

npm version patch          # 0.1.0 → 0.1.1,自动改 package.json + 打 tag v0.1.1
git push --follow-tags     # 推送 → Actions 自动构建并发布到 npm

publishConfig.access: "public" 让 scoped 包以公共可见发布。想先演练:Actions 页手动触发 "Release" workflow,勾选 dry-run。prepare 钩子会在 publish 前 npm run build,tarball 始终带最新 dist/;files: ["dist"] 只发布编译产物。

Multica integration is implemented through HTTP APIs, not the Multica CLI.

Key environment variables. The Multica mirror is mandatory: the server resolves credentials as ENV → ~/.costrict/share/auth.json → throw (see "复用 csc 的 CoStrict 登录" below). Placeholder values (e.g. __PASTE_MULTICA_JWT__) are treated as "not configured" and fall through to the file; if neither source yields both a token and a base URL, the server refuses to start.

| Variable | Purpose | |---|---| | COSTRICT_BASE_URL | Multica base URL. Its source decides URL construction (see "URL 拼接" below): set via ENV → bare base; fallback to ~/.costrict/share/auth.json → deployment prefixes applied. Missing both sources → startup error | | COSTRICT_TOKEN | Multica API token (falls back to ~/.costrict/share/auth.json; placeholder/missing → startup error) |

复用 csc 的 CoStrict 登录（~/.costrict/share/auth.json）

若你已通过 csc（CoStrict CLI）登录，COSTRICT_TOKEN 与 COSTRICT_BASE_URL 可不配：未设（或为占位符）时，自动回退读 csc 的 ~/.costrict/share/auth.json 里的 access_token 与 base_url。优先级：环境变量 > auth.json。

• 必需：Multica 镜像为强制项——env 与 auth.json 两级都解析不到（或只到其一）时，server 启动即抛错，不再静默降级为 IPD-only。
• COSTRICT_AUTH_JSON_PATH：可选，覆盖凭证文件路径（默认 ~/.costrict/share/auth.json）。
• 不查过期：access_token 过期后 Multica 会回 401，重新 csc 登录刷新即可。
• base_url 为 CoStrict 平台根地址（裸 host）即可；csc 登录来源会自动套 /workflow-backend（API）/ /cloud/workflow（协作页）前缀（见下「URL 拼接」）。如需切到非 csc 部署形态，改用 COSTRICT_BASE_URL（ENV）覆盖。

URL 拼接（按 BASE_URL 来源分流）

Multica 接口不返回页面 URL；协作页面 issueUrl 与 Multica API 请求地址均在本地拼接，规则取决于 COSTRICT_BASE_URL 的来源：

• ENV 来源（设了 COSTRICT_BASE_URL）：裸 base。
  • API 请求：{BASE_URL}/api/xxxxx
  • 协作页面：{BASE_URL}/{workspace}/issues/{issue_id}
• auth.json 来源（回退 ~/.costrict/share/auth.json 的 base_url，即 csc 登录态）：自动套部署前缀。
  • API 请求：{BASE_URL}/workflow-backend/api/xxxxx
  • 协作页面：{BASE_URL}/cloud/workflow/{workspace}/issues/{issue_id}

COSTRICT_WEB_BASE_URL 已移除：协作页面地址完全由来源推导，不再支持单独覆盖。

Current behavior:

• list_issues: read-only IPD query, enriches each feature item with its current stage when present. Mirror issue (collaboration) links are not returned for now.
• get_issue_detail: read-only IPD detail, includes mirror issue and stage-comment archive when present.
• transition_state: updates IPD status (best-effort; IPD status keys are pending IPD-side confirmation). For feature -> in_progress it bootstraps the mirror — creates/reuses the feature mirror issue and builds the four-stage status board. tech -> in_progress creates/reuses the mirror issue (no stage board). Task transitions only sync an existing mirror issue's status and optional notes. Only feature/tech/task may transition.
• upload_artifacts: uploads the artifact to IPD and appends an archive comment to the id-derived Multica mirror issue (rec.issue.id via ensureMirrorChain) when the mirror is present.
• create_subissue: creates IPD child issues and mirrors newly created children into Multica.

Multica 镜像字段同步

写工具（create_subissue / transition_state / upload_artifacts）在触达镜像时，会按 IPD 为源回填字段到已存在的 Multica 镜像 issue（公共入口 src/mirror-reconcile.ts 的 reconcileMirror）：

• 原生字段：title / description / priority（IPD 改动后下次触达即更新）。
• metadata：ipd_assignee_id / ipd_assignee_name / ipd_url / ipd_update_at（责任人只入 metadata，不改 Multica assignee）。
• 不改动：assignee_type / assignee_id、status（由 transition_state 单独管）。
• 变更检测：ipd_update_at 未变则跳过写。

list_issues / get_issue_detail 为只读，不产生 Multica 写。get_issue_detail 展示镜像协作入口；list_issues 富化全 type 的协作页面 / 协作 issue id。二者均展示（已同步的）IPD 责任人。

自包含 MCP Server：IPD 客户端已内置于项目（src/ipd-api.cjs），无需外部依赖即可运行，为 CSC Agent 提供「以 feature 进入系统需求 → 拉取用户需求 → 推回 IPD」的工作流原语。

src/ipd-api.cjs 是从 qianliu-ipd/scripts/ipd_api.js 集成进来的 IPD HTTP 客户端（仅依赖 Node 内置模块）。凭证优先级：环境变量 > 配置文件；支持 IPD_TOKEN / IPD_PRODUCT / IPD_BASE_URL / QIANLIU_CONFIG_PATH 环境变量。配置文件（默认 ~/.qianliu/config.json）可选——env 齐全时无需该文件。

工具

| 工具 | 读写 | 用途 | 底层 IPD 接口 | |---|---|---|---| | list_issues | 读 | 查询当前登录用户名下工作项清单 | getCurrentUser / getIssuesByScope / getSubIssues / getIssue | | get_issue_detail | 读 | 按 feature id 拉取 feature 描述 + 其下各 story 描述（系统需求的「用户需求」输入），返回可保存的结构化 JSON 块 | getIssueDetail / getSubIssues | | create_subissue | 写 | 在父节点下创建 Story/Tech/task（推回系统需求与设计拆解），按标题去重 | createIssue / createTask / getSubIssues | | transition_state | 写 | 切状态(epic/feature/story/tech/task);IPD 切换成功为前提,再同步镜像链 + 置镜像状态 | updateIssue | | upload_artifacts | 写 | 把系统需求/设计文档作为附件上传到需求节点，并写入 id 反查镜像 issue 的协作评论 | uploadIssueAttachment |

工具面对齐 CosWorkflow-MCP-接口文档.md 的 5 工具（list_issues / get_issue_detail / create_subissue / transition_state / upload_artifacts）。create_subissue/transition_state/upload_artifacts 均经 reconcileMirror 做 Multica 镜像字段同步（见上节）；list_issues/get_issue_detail 只读。

典型流程（系统需求入口 ↔ 推回 IPD）

get_issue_detail(featureId)            # 拉取 feature.desc + 各 story.desc = 用户需求，持久化为输入
  → system-requirement-analysis / design-spec（cospowers skills）
  → upload_artifacts(featureId, 系统需求文档/设计文档)   # 附件 + 评论（归档到 featureId 的镜像 issue）
  → create_subissue(featureId, [story/tech/task ...])  # 推回拆解结构
  → transition_state(featureId, in_progress)        # IPD 切换成功后,同步镜像链 + 置 feature 镜像状态为进行中

运行

npm start

默认使用内置 IPD 客户端 src/ipd-api.cjs，只需 ~/.qianliu/config.json 配好 ipd.token（创建需求还需 ipd.product）。 如需改用外部实现，可设 COSWORKFLOW_IPD_API_PATH 覆盖：

# 可选：覆盖为外部 IPD 客户端
COSWORKFLOW_IPD_API_PATH="/abs/path/to/ipd_api.js" npm start

错误码

工具失败时返回 AUTH_EXPIRED / NOT_FOUND / UPSTREAM_TIMEOUT / UPSTREAM_ERROR / INVALID_INPUT 前缀的错误文本。