codearts-req-mcp-server

本地 stdio 类型的 MCP Server，封装华为云 CodeArts 需求管理（CodeArts Req） API，使用 AK/SK + SDK-HMAC-SHA256 签名鉴权。

• 服务名：codearts-req

• 传输方式：stdio（进程标准输入/输出，不监听端口）

• 运行时：Node.js（ESM）

• SDK：@modelcontextprotocol/sdk

• 工具：create_project、list_projects

功能

服务不会在启动时因为缺少环境变量而退出。缺少配置或参数错误会以 isError: true 的结构化中文结果返回给 MCP 客户端，便于智能体自行修正。

Related MCP server: plane-mcp

目录结构

codearts-req-mcp-server/
├── server.mjs                 # MCP Server、参数校验、签名、API 调用
├── package.json
├── package-lock.json
├── README.md
├── LICENSE
└── test/
    ├── signing.test.mjs       # 签名算法与固定测试向量
    ├── tools.test.mjs         # 参数校验、结果与错误处理
    └── mcp-server.test.mjs    # 真实 stdio + 本地 mock API 集成测试

环境要求

• Node.js >= 18.17.0（使用内置 fetch、AbortController、node:test）

• npm 9+（随 Node.js 安装即可）

• 已开通 CodeArts Req，并拥有创建/查询项目权限的华为云访问密钥（AK/SK）

安装

cd codearts-req-mcp-server
npm install

环境变量

终端节点与区域有关。华北-北京四使用 projectman-ext.cn-north-4.myhuaweicloud.com，其他区域请从 CodeArts Req 终端节点 查询。

CODEARTS_REQ_ENDPOINT 可以写成完整 URL，也可以只写域名（服务会自动补 https://）：

https://projectman-ext.cn-north-4.myhuaweicloud.com
projectman-ext.cn-north-4.myhuaweicloud.com

AK/SK 等价于账号凭证，请通过环境变量或 MCP 客户端的 environment 注入，不要写入代码、README 或提交到 Git。

Linux / macOS

export CODEARTS_REQ_ENDPOINT="https://projectman-ext.cn-north-4.myhuaweicloud.com"
export CODEARTS_REQ_AK="你的AK"
export CODEARTS_REQ_SK="你的SK"

Windows PowerShell

$env:CODEARTS_REQ_ENDPOINT = "https://projectman-ext.cn-north-4.myhuaweicloud.com"
$env:CODEARTS_REQ_AK = "你的AK"
$env:CODEARTS_REQ_SK = "你的SK"

启动

npm start
# 等价于
node server.mjs

服务启动后等待 MCP 客户端通过 stdin 发送 JSON-RPC 消息，不会在终端打印工具结果。直接运行后看不到输出是正常现象，请通过 MCP 客户端或 MCP Inspector 调试：

npx @modelcontextprotocol/inspector node server.mjs

码道配置

码道 IDE 与码道 CLI 的配置字段不同，请按使用的客户端选择。

码道 IDE：mcp_settings.json

码道 IDE 的项目级配置文件实际位于：

<项目根目录>/.codeartsdoer/mcp/mcp_settings.json

也可以通过 设置 → MCP 工具 → 配置 MCP 打开该文件。配置示例：

{
  "mcpServers": {
    "codearts-req": {
      "type": "stdio",
      "command": "C:\\Program Files\\nodejs\\node.exe",
      "args": [
        "E:\\shiyan\\1-8\\codearts-req-mcp-server\\server.mjs"
      ],
      "cwd": "E:\\shiyan\\1-8\\codearts-req-mcp-server",
      "env": {
        "CODEARTS_REQ_ENDPOINT": "https://projectman-ext.cn-north-4.myhuaweicloud.com",
        "CODEARTS_REQ_AK": "你的AK",
        "CODEARTS_REQ_SK": "你的SK"
      },
      "disabled": false,
      "timeout": 60000
    }
  }
}

注意：

• 码道 IDE 使用 stdio 类型：command 是字符串，脚本路径放在 args 数组中，环境变量字段名是 env。

• command 建议写 Node.js 的绝对路径，可用 where node 查询；Windows 路径在 JSON 中写成 \\ 转义形式，或使用正斜杠。

• 保存后等待 MCP 工具页显示服务已连接；如未生效，重启 IDE 或在该页面重启 MCP Server。

码道 CLI：codearts_cli.jsonc

项目级配置放在项目根目录的 .codeartsdoer/codearts_cli.jsonc；个人级配置放在 ~/.codeartsdoer/codearts_cli.jsonc（Windows 为 C:\Users\<用户名>\.codeartsdoer\）。

{
  "mcp": {
    "codearts-req": {
      "type": "local",
      "command": [
        "node",
        "E:/shiyan/1-8/codearts-req-mcp-server/server.mjs"
      ],
      "environment": {
        "CODEARTS_REQ_ENDPOINT": "https://projectman-ext.cn-north-4.myhuaweicloud.com",
        "CODEARTS_REQ_AK": "你的AK",
        "CODEARTS_REQ_SK": "你的SK"
      },
      "enabled": true,
      "timeout": 60000
    }
  }
}

保存并重启码道 CLI 后，执行 /mcps 查看 codearts-req 是否为 Enabled。

其他 MCP 客户端

使用常见 mcpServers 格式的客户端（命令与参数分开）可这样配置：

{
  "mcpServers": {
    "codearts-req": {
      "command": "node",
      "args": [
        "E:/shiyan/1-8/codearts-req-mcp-server/server.mjs"
      ],
      "env": {
        "CODEARTS_REQ_ENDPOINT": "https://projectman-ext.cn-north-4.myhuaweicloud.com",
        "CODEARTS_REQ_AK": "你的AK",
        "CODEARTS_REQ_SK": "你的SK"
      }
    }
  }
}

工具说明

create_project

创建项目，对应 POST /v4/project。

template_id 含义：

• 10001：IPD-系统设备类

• 10002：IPD-独立软件类

• 10003：IPD-自运营软件/云服务类

成功返回示例：

{
  "project_id": "2e76d6f0b2c5403796e36bf63c5d5561",
  "project_num_id": 708168641,
  "project_name": "demo-project",
  "project_type": "scrum",
  "user_num_id": 700145037
}

调用示例（MCP 客户端视角）：

{
  "name": "create_project",
  "arguments": {
    "project_name": "demo-project",
    "project_type": "ipd",
    "description": "由 MCP 创建",
    "template_id": 10002
  }
}

list_projects

查询项目列表，对应 GET /v4/projects。

sort 的字段可使用 API 支持的项目字段，例如：

name:asc
name:asc,created_on:desc

成功返回示例：

{
  "projects": [
    {
      "project_id": "41bd3eab86544863b8fc92ffcd35e3c8",
      "project_name": "demo-project",
      "project_type": "scrum"
    }
  ],
  "total": 1
}

错误处理

所有错误都作为 MCP 工具结果返回：isError: true，content[0].text 为 JSON 字符串。服务不会静默吞错，也不会因为单次工具调用失败而退出。

INVALID_ARGUMENTS

{
  "error_code": "INVALID_ARGUMENTS",
  "error_msg": "参数校验失败：offset：须为 limit（当前为 10）的整数倍",
  "details": [
    "offset：须为 limit（当前为 10）的整数倍"
  ]
}

MISSING_CONFIG

{
  "error_code": "MISSING_CONFIG",
  "error_msg": "配置缺失或无效：缺少环境变量 CODEARTS_REQ_ENDPOINT、CODEARTS_REQ_AK、CODEARTS_REQ_SK",
  "missing": [
    "CODEARTS_REQ_ENDPOINT",
    "CODEARTS_REQ_AK",
    "CODEARTS_REQ_SK"
  ]
}

API 错误透传

CodeArts Req 返回 4xx/5xx 时，原始错误码和错误信息会原样透传，并补充 HTTP 状态码：

{
  "error_code": "PM.00000001",
  "error_msg": "项目名称已存在",
  "http_status": 400
}

NETWORK_ERROR

{
  "error_code": "NETWORK_ERROR",
  "error_msg": "请求 CodeArts Req API 时发生网络异常，请检查网络、终端节点与代理设置",
  "detail": "connect ECONNREFUSED 127.0.0.1:443"
}

AK/SK 签名说明

实现遵循华为云 API 签名指南的 SDK-HMAC-SHA256：

1. 构造 CanonicalRequest：HTTP 方法、CanonicalURI、CanonicalQueryString、CanonicalHeaders、SignedHeaders、SHA-256(RequestPayload)。

2. 构造 StringToSign：SDK-HMAC-SHA256\n<X-Sdk-Date>\nSHA-256(CanonicalRequest)。

3. 计算 Signature = HexEncode(HMAC-SHA256(SK, StringToSign))。

4. 发送 X-Sdk-Date 与 Authorization：

Authorization: SDK-HMAC-SHA256 Access=<AK>, SignedHeaders=content-type;host;x-sdk-date, Signature=<签名>

实现细节：

• X-Sdk-Date 使用 UTC 格式 YYYYMMDDTHHMMSSZ，本地时钟与标准时间偏差超过 15 分钟会被网关拒绝。

• CanonicalURI 必须以 / 结尾（例如签名 /v4/project/，实际请求 /v4/project）。

• 查询参数按 RFC 3986 编码（空格为 %20），按编码后的参数名升序排序；空值和 false 不会被丢弃。

• 固定签名 content-type、host、x-sdk-date；host 由 Node.js fetch 根据 URL 自动设置。

• 不跟随 HTTP 重定向，避免将签名请求转发到其他主机。

测试

npm test

当前共 53 个用例，使用 Node.js 内置 node:test，不访问真实华为云：

• 签名测试：CanonicalQueryString、CanonicalURI、CanonicalHeaders、UTC 时间、固定 HMAC 测试向量。

• 工具测试：创建/查询参数边界、ipd 模板约束、错误码透传、网络异常、超时、异常响应。

• MCP 集成测试：启动真实 stdio 子进程，通过官方 MCP Client 执行 tools/list 与 tools/call，用本地 HTTP 服务验证方法、路径、查询参数、请求体、签名头和错误恢复；测试侧会独立重算 Authorization 签名，校验实际发出的 host、路径、查询串和请求体。

常见问题

工具返回 MISSING_CONFIG

MCP 客户端启动子进程时不会自动继承你终端里临时 export 的变量。请在码道 IDE 配置的 env（码道 CLI 为 environment）中显式写入三个变量，或在启动 MCP 客户端前设置系统环境变量。

返回 401 / APIG.0301

• 检查 AK/SK 是否正确、是否已启用。

• 检查本机时间是否准确（签名有效期通常为 15 分钟）。

• 检查终端节点区域是否与账号/项目区域一致。

返回 PM.02100546 / “该企业租户服务处于关闭状态”

说明当前企业租户未开通 CodeArts Req 服务。AK/SK 和签名可能已经正确，但业务层拒绝创建项目。请前往华为云控制台开通/购买 CodeArts 套餐（其中包含需求管理服务），开通后重试。参见 官方 FAQ。

返回 403

AK/SK 对应的 IAM 用户或委托缺少 CodeArts Req 项目创建/查询权限。请在 IAM 中补充相应权限后重试。

返回 404 或连接失败

• 确认 CODEARTS_REQ_ENDPOINT 使用 CodeArts Req 的终端节点，例如 projectman-ext.cn-north-4.myhuaweicloud.com。

• 确认 URL 使用 https://，且没有多余路径、查询参数。

• 如果使用代理，请确认运行 Node.js 的网络环境能访问该终端节点。

offset 报“须为 limit 的整数倍”

分页偏移量必须从 0 开始按页大小递增，例如 limit=10 时 offset 只能是 0、10、20……

码道中服务启动失败

• 先在本机执行 node server.mjs，确认没有模块缺失；若缺少模块，在项目目录执行 npm install。

• 使用 Node.js 的绝对路径，例如 C:\\Program Files\\nodejs\\node.exe。

• 确认码道 IDE 的 type、command、args、env 字段，或码道 CLI 的 type、command、environment 字段拼写正确，保存后重启客户端。

• Windows 路径中的反斜杠必须转义，或改用 /。

参考文档

• 创建项目 - CreateProjectV4

• 查询项目列表 - ListProjectsV4

• CodeArts Req 终端节点

• 华为云 API 签名认证机制

• MCP TypeScript SDK

License

MIT