Skip to main content
Glama

CodeArts MCP

面向华为云 CodeArts 中国站的统一 MCP Server,将 8 个产品模块封装为标准化 MCP 工具集,支持本地 stdio 与团队共享 http 两种接入模式。

特性亮点

  • 8 模块统一封装 — Req / Repo / Pipeline / Check / TestPlan / Deploy / Build / Artifact 一站式覆盖

  • 双模式接入 — stdio 适合个人本地使用,http + session 适合团队共享部署

  • 会话隔离 — 共享模式下每个用户使用自己的 AK/SK,互不干扰

  • 加密持久化 — 凭证经 AES-256-GCM 加密落盘,服务重启后可恢复会话

  • Cookie / Token 双恢复 — 客户端保留 Cookie 或固定 auth_token 均可无缝重连

  • CLI 兼容 — 复用同一批 MCP 工具 handler,支持本地 AK/SK 直调和远程 HTTP /mcp/<family> 调用

  • 速率限制 — 写操作内置 per-session 限流,防止误操作风暴

  • 缓存加速 — 高频读工具带共享缓存与 in-flight dedupe,命中后毫秒级响应

Related MCP server: poly-git-mcp

技术栈

类别

技术

版本

运行时

Node.js

22 (Alpine)

语言

TypeScript

5.8+

MCP 协议

@modelcontextprotocol/sdk

1.12+

数据校验

Zod

3.24+

测试

Vitest

4.1+

构建

tsc + esbuild

代码规范

ESLint

9.0+

容器

Docker + Docker Compose

反向代理

Nginx

架构概览

stdio 模式

graph LR
    A[MCP Client] -->|stdio| B[MCP Server]
    B -->|API| C[CodeArts APIs]

http 模式

graph LR
    A[MCP Client] -->|HTTP/S| B[Nginx]
    B -->|proxy| C[HTTP Server :3000]
    C --> D[MCP Server]
    D -->|API| E[CodeArts APIs]

内部结构

graph TB
    subgraph MCP Server
        A[Auth / Session] --> B[Product Tools]
        B --> B1[Req]
        B --> B2[Repo]
        B --> B3[Pipeline]
        B --> B4[Check]
        B --> B5[TestPlan]
        B --> B6[Deploy]
        B --> B7[Build]
        B --> B8[Artifact]
        C[Cache] --> B
        D[Rate Limiter] --> B
    end

快速开始

1. 启动共享服务

cp .env.example .env
# 编辑 .env,至少填写 MCP_AUTH_MASTER_KEY
docker compose up -d --build

或宿主机直跑:

npm install && npm run build
node dist/src/server/index.js

2. 客户端添加服务

{
  "mcpServers": {
    "req": {
      "type": "http",
      "url": "http://your-server-ip/mcp/req"
    },
    "repo": {
      "type": "http",
      "url": "http://your-server-ip/mcp/repo"
    },
    "pipeline": {
      "type": "http",
      "url": "http://your-server-ip/mcp/pipeline"
    },
    "check": {
      "type": "http",
      "url": "http://your-server-ip/mcp/check"
    },
    "testplan": {
      "type": "http",
      "url": "http://your-server-ip/mcp/testplan"
    },
    "deploy": {
      "type": "http",
      "url": "http://your-server-ip/mcp/deploy"
    },
    "build": {
      "type": "http",
      "url": "http://your-server-ip/mcp/build"
    },
    "artifact": {
      "type": "http",
      "url": "http://your-server-ip/mcp/artifact"
    }
  }
}

当前已部署的共享服务按 8 个产品模块拆分接入,可以直接使用下面这份配置:

{
  "mcpServers": {
    "req": {
      "disabled": false,
      "timeout": 60,
      "type": "streamableHttp",
      "url": "http://39.106.183.205/mcp/req"
    },
    "repo": {
      "disabled": false,
      "timeout": 60,
      "type": "streamableHttp",
      "url": "http://39.106.183.205/mcp/repo"
    },
    "pipeline": {
      "disabled": false,
      "timeout": 60,
      "type": "streamableHttp",
      "url": "http://39.106.183.205/mcp/pipeline"
    },
    "check": {
      "disabled": false,
      "timeout": 60,
      "type": "streamableHttp",
      "url": "http://39.106.183.205/mcp/check"
    },
    "testplan": {
      "disabled": false,
      "timeout": 60,
      "type": "streamableHttp",
      "url": "http://39.106.183.205/mcp/testplan"
    },
    "deploy": {
      "disabled": false,
      "timeout": 60,
      "type": "streamableHttp",
      "url": "http://39.106.183.205/mcp/deploy"
    },
    "build": {
      "disabled": false,
      "timeout": 60,
      "type": "streamableHttp",
      "url": "http://39.106.183.205/mcp/build"
    },
    "artifact": {
      "disabled": false,
      "timeout": 60,
      "type": "streamableHttp",
      "url": "http://39.106.183.205/mcp/artifact"
    }
  }
}

当前共享 HTTP MCP 只保留按产品拆开的 8 个子路径:

  • /mcp/req

  • /mcp/repo

  • /mcp/pipeline

  • /mcp/check

  • /mcp/testplan

  • /mcp/deploy

  • /mcp/build

  • /mcp/artifact

这些子路径共用同一套鉴权持久化、Cookie 和 auth_token;也就是说,可以先在任意一个入口调用 auth_configure_session,再在另一个入口通过 Cookie 或 Bearer token 复用凭证。需要注意的是,mcp-session-id 仍然是按路径隔离的,/mcp/req 的 session 不能直接拿去请求 /mcp/repo

若客户端不保留 Cookie,请使用 Authorization: Bearer <auth_token> 复用凭证。不要把 token 放到 URL query;URL 容易进入代理日志、浏览器历史和监控系统。

Authorization: Bearer replace-with-auth-token

3. 首次鉴权

连接后调用 auth_configure_session

{
  "access_key": "your-ak",
  "secret_key": "your-sk",
  "region": "cn-north-4"
}

4. 验证连通

以下四个读工具能正常返回即表示接通成功:

验证工具

所属模块

req_list_projects

Req

repo_list_repositories

Repo

pipeline_list_pipelines

Pipeline

build_list_jobs

Build

部署方式

部署方式对比

特性

Docker Compose

PM2 + Nginx

本地 stdio

适用场景

团队共享(推荐)

团队共享(无 Docker)

个人本地

隔离性

容器隔离

进程级隔离

无隔离

HTTPS

docker-compose.ssl.yml

Nginx 配置

不适用

会话持久化

支持

支持

不适用

运维复杂度

最低

水平扩展

可配合负载均衡

可配合负载均衡

不适用

健康检查

内置 /health

需手动配置

不适用

Docker Compose 部署(推荐)

# HTTP
docker compose up -d --build

# HTTPS(需先准备证书,见 deploy/nginx/ssl/)
docker compose -f docker-compose.ssl.yml up -d --build

必需环境变量:

MCP_TRANSPORT=http
MCP_HTTP_PORT=3000
MCP_HTTP_HOST=0.0.0.0
MCP_SERVER_NAME=codearts-mcp
MCP_SERVER_VERSION=0.1.0
MCP_AUTH_MASTER_KEY=replace-with-a-long-random-secret
MCP_AUTH_DATA_PATH=.codearts-mcp/auth-store.json

PM2 部署

使用项目提供的部署脚本:

# 初始化
bash deploy/bootstrap-shared.sh

# 部署前自检
bash deploy/preflight-shared.sh

# 启动/停止/重启
bash deploy/manage-shared-pm2.sh start|stop|restart

脚本

用途

deploy/bootstrap-shared.sh

初始化环境与目录结构

deploy/preflight-shared.sh

部署前自检

deploy/manage-shared-pm2.sh

PM2 进程管理

deploy/ops-shared.sh

运维工具集

deploy/manage-shared.sh

Docker Compose 管理

本地 stdio

MCP_TRANSPORT=stdio
HUAWEICLOUD_AK=your-ak
HUAWEICLOUD_SK=your-sk
HUAWEICLOUD_REGION=cn-north-4
MCP_SERVER_NAME=codearts-mcp
MCP_SERVER_VERSION=0.1.0

客户端启动命令:

node dist/src/server/index.js

CLI 怎么用

CLI 就是“用命令行调用 MCP 工具”。它有两种用法:

你要做什么

用哪种模式

凭证从哪里来

在自己电脑或 CI 里直接调用 CodeArts

本地模式

本机环境变量里的 HUAWEICLOUD_AK / HUAWEICLOUD_SK

调用已经部署好的团队共享 MCP 服务

远程模式

共享服务返回的 auth_token

1. 本地模式:不需要启动服务

先设置 AK/SK:

$env:HUAWEICLOUD_AK="your-ak"
$env:HUAWEICLOUD_SK="your-sk"
$env:HUAWEICLOUD_REGION="cn-north-4"
$env:MCP_SERVER_NAME="codearts-mcp"
$env:MCP_SERVER_VERSION="0.1.0"

然后调用:

npm run cli -- tools --format table
npm run cli -- call req_list_projects --input '{"page":1,"page_size":20}' --format table

2. 远程模式:调用产品级 /mcp/<family>

npm run cli -- call req_list_projects `
  --transport http `
  --endpoint https://your-domain.example/mcp/req `
  --token replace-with-auth-token `
  --input '{"page":1}' `
  --format table

3. 常用命令

命令

用途

npm run cli -- tools --format table

查看有哪些工具

npm run cli -- schema repo_list_repositories

查看某个工具需要哪些参数

npm run cli -- call req_list_projects --input '{"page":1}' --format table

调用工具

npm run cli -- call repo_list_repositories --file params.json --pretty

从 JSON 文件读取参数

npm run cli -- completion powershell

生成 PowerShell 自动补全脚本

更多 profile、补全、文件输入示例见 CLI Usage

API 文档入口

文档

用途

CLI Usage

命令行调用 MCP 工具:本地模式、远程模式、profile、表格输出和补全

HTTP MCP Interface

HTTP 端点、MCP JSON-RPC、鉴权会话、请求响应和接入示例

Function API Reference

完整 MCP 功能 API 总目录;完整参数表、字段对应和 JSON Schema 按模块拆分到明细页

CodeArts MCP API Reference

8 个 CodeArts 服务的 MCP API 总览、基础 URL、工具清单和 live 边界

Req MCP API Reference

Req 深度 API 文档,包含 Scrum、需求池、IPD、写入 gate 和 smoke 样本缺口

Module Functions Overview

按模块解释每个服务能做什么、适合什么场景

Capability Matrix

各模块读写规模、live 状态和关键缺口

模块现状总表

  • 8 product modules

  • 2334 product tools

  • 2 session/auth tools for shared http mode

  • 2336 total MCP tools in shared http mode

工具读写分布:读操作 177 (63.7%) / 写操作 101 (36.3%)

Module

Tools

Live status

Current breakdown

Req

363

Partial

Expanded Req surface with current-user info/role and user-feature reads, project bug/summary/statistics/metric reads, project domain reads, work-item-tree count/list, work-item tag/index-count reads, project work-item history reads, child work-item reads, work-hours/work-hour-type reads, issue image upload/download, attachment upload/download/delete, associated wiki reads, plan work-item management, plan image update, plan-context work item creation, work-item template/copy writes, project-template update/delete writes, project due-days-after/workhour-config reads, status-name check, status/status-attribute/status-detail/workflow-config/template/template-config/custom-field/status-rule-flag/status-config/optional-status-config/tracker-handler and project-public-config reads plus field/cache reads and board work-item reads; see docs/wiki/Req-Live-Validated.md for validated paths and remaining live-depth gaps

Repo

459

Partial

25 Full / 0 Reachable / 0 Unpublished / 6 Code

Pipeline

257

Partial

16 Full / 4 Reachable / 1 Unpublished / 52 Code

Check

135

Partial

14 Full / 0 Reachable / 0 Unpublished / 5 Code

TestPlan

762

Partial

1 Full / 2 Reachable / 4 Unpublished / 0 Code

Deploy

110

Partial

Expanded v4 surface with partial live closure; see docs/wiki/Module-Live-Readiness.md

Build

167

Validated

Expanded metadata read surface with live smoke coverage

Artifact

81

Partial

5 Full / 0 Reachable / 7 Unpublished / 0 Code

Live 状态说明:

状态

含义

Validated

所有工具已通过真实 AK/SK 联调验证

Partial

部分工具已验证,其余可用但受租户样本或区域发布限制

环境变量参考

必需变量

变量

说明

默认值

MCP_TRANSPORT

传输模式:httpstdio

MCP_SERVER_NAME

服务名称

MCP_SERVER_VERSION

服务版本

MCP_AUTH_MASTER_KEY

会话加密主密钥(http 模式必需)

可选变量

变量

说明

默认值

MCP_HTTP_PORT

HTTP 监听端口

3000

MCP_HTTP_HOST

HTTP 监听地址;本地默认只监听回环地址,共享/容器部署需显式设为 0.0.0.0

127.0.0.1

MCP_HTTP_ALLOWED_ORIGINS

允许携带 Origin 访问 /mcp/<family> 的浏览器来源,多个值用英文逗号分隔

MCP_ENABLED_PRODUCT_FAMILIES

限制当前实例只暴露指定产品族;可填 artifact,build,check,deploy,pipeline,repo,req,testplan 的逗号列表

MCP_PRODUCT_WRITE_RATE_LIMIT_MAX_REQUESTS

产品写入每个 action/session 的限流次数

3000

MCP_PRODUCT_WRITE_RATE_LIMIT_WINDOW_MS

产品写入限流窗口

60000

MCP_AUTH_WRITE_RATE_LIMIT_MAX_REQUESTS

鉴权写入每个 session 的限流次数

3000

MCP_AUTH_WRITE_RATE_LIMIT_WINDOW_MS

鉴权写入限流窗口

60000

MCP_AUTH_DATA_PATH

加密凭证持久化路径

.codearts-mcp/auth-store.json

MCP_AUTH_COOKIE_SECURE

HTTPS 环境下设置 Cookie Secure 标志

false

CODEARTS_CLI_TRANSPORT

CLI 默认调用模式:localhttp

local

CODEARTS_MCP_URL

CLI 远程 HTTP MCP 入口

CODEARTS_MCP_AUTH_TOKEN

CLI 远程调用使用的 Bearer token

CODEARTS_CLI_PROFILE

CLI 默认 profile 名称

CODEARTS_CLI_CONFIG

CLI profile 配置文件路径

~/.codearts-mcp-cli.json

CODEARTS_CLI_FORMAT

CLI 默认输出格式:jsontexttable

json

HUAWEICLOUD_AK

默认 AK(stdio 模式)

HUAWEICLOUD_SK

默认 SK(stdio 模式)

HUAWEICLOUD_REGION

默认区域(stdio 模式)

产品 URL 覆盖(cn-north-4 默认值)

标准区域会根据 region 自动推导,通常无需手动填写。以下为 cn-north-4 默认映射:

变量

默认值

REQ_BASE_URL

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

REPO_BASE_URL

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

PIPELINE_BASE_URL

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

CHECK_BASE_URL

https://codearts-check.cn-north-4.myhuaweicloud.com

TESTPLAN_BASE_URL

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

DEPLOY_BASE_URL

https://codearts-deploy.cn-north-4.myhuaweicloud.com

BUILD_BASE_URL

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

ARTIFACT_BASE_URL

https://artifact.cn-north-4.myhuaweicloud.cn

常用命令

命令

说明

npm run dev

开发模式启动(stdio)

npm run dev:http

开发模式启动(http)

npm run cli -- tools

列出 CLI 可调用工具

npm run cli -- schema <tool>

输出某个工具的输入/输出 JSON Schema

npm run cli -- call <tool> --input <json>

CLI 直接调用 MCP 工具并输出 JSON

npm run cli -- completion <shell>

生成 PowerShell、Bash 或 Zsh 补全脚本

npm run build

TypeScript 编译

npm run check

本地完整检查:lint、类型、ToolManifest、文档同步、测试、构建

npm test

运行测试

npm run test:fast

快速测试(无隔离)

npm run test:isolate

隔离模式测试

npm run lint

代码规范检查

npm run stats:modules

输出模块统计

npm run tool-manifest:check

检查 ToolManifest 与实际 stdio/http 工具注册是否一致

npm run stats:check-docs

检查 README/Wiki 统计块是否漂移

npm run stats:sync-docs

同步自动统计区块到文档

npm run probe:edge

对共享 HTTP 入口做多轮连通性与延迟采样

Windows 本机 Node/npm 包装脚本:

powershell -ExecutionPolicy Bypass -File .\scripts\npmw.ps1 run check
powershell -ExecutionPolicy Bypass -File .\scripts\npmw.ps1 run test:live
powershell -ExecutionPolicy Bypass -File .\scripts\nodew.ps1 .\dist\src\server\cli.js tools
.\scripts\nodew.cmd -e "console.log(process.version)"
.\scripts\npmw.cmd -v
.\scripts\npxw.cmd vitest --version

如果你想让当前 PowerShell 会话直接可用 tsxvitesteslint 这类本地二进制,先执行:

. .\scripts\use-local-node.ps1

如果你想直接打开一个已经切好本机 Node/npm 的新 PowerShell,执行:

.\scripts\dev-shell.cmd

只做环境探测时可以运行:

npm run env:node

说明:

  • 这两个脚本会优先使用本机 npm.cmd / node.exe,避免误落到不可用的内置运行时。

  • 可通过 CODEARTS_MCP_NPM_CMDCODEARTS_MCP_NODE_EXE 显式覆盖路径。

安全特性

特性

说明

会话隔离

共享模式下每个用户独立会话,AK/SK 互不可见

加密持久化

凭证使用 AES-256-GCM 加密,密钥由 MCP_AUTH_MASTER_KEY 派生

Cookie / Token 恢复

支持 Cookie 自动重连或 auth_token 固定重连,无需重复输入凭证

HTTPS 支持

通过 docker-compose.ssl.yml 或 Nginx 配置启用,生产环境建议启用 MCP_AUTH_COOKIE_SECURE

写操作速率限制

内置 per-session 限流,防止误操作或自动化脚本产生写风暴

凭证清除

调用 auth_clear_session 可立即撤销当前用户的持久化凭证

运维注意:MCP_AUTH_MASTER_KEYMCP_AUTH_DATA_PATH 必须稳定保存,否则服务重启后无法恢复已有会话。

项目结构

codearts-mcp/
├── src/
│   ├── server/            # 服务入口、工具注册、会话管理
│   ├── products/          # 8 个产品模块(artifact/build/check/deploy/pipeline/repo/req/testplan)
│   ├── core/              # 通用能力(auth/cache/config/errors/http/pagination)
│   └── contracts/         # 共享类型与校验 schema
├── deploy/                # 部署脚本与 Nginx 配置
├── tests/                 # 测试用例(与 src 镜像目录结构)
├── Dockerfile             # 两阶段构建,node:22-alpine,暴露 3000,健康检查 /health
├── docker-compose.yml     # HTTP 模式
├── docker-compose.ssl.yml # HTTPS 模式
├── ecosystem.config.cjs   # PM2 配置
└── vitest.config.ts       # 测试配置

故障排查

现象

可能原因

解决方案

GET /health 无响应

服务未启动或端口未暴露

检查 docker compose logs;确认 MCP_HTTP_PORT 映射

auth_configure_session 返回失败

AK/SK 错误或区域不支持

确认 AK/SK 有效且 region 填写正确(如 cn-north-4)

Cookie 重连后仍需重新鉴权

MCP_AUTH_MASTER_KEY 变更或数据文件丢失

确认 MASTER_KEY 和 AUTH_DATA_PATH 在重启间保持不变

写操作被限流

触发 per-session 速率限制

等待限流窗口重置,或减少并发写操作

某模块工具返回区域不可用

该产品尚未在当前区域发布

检查模块 Live 状态;参考区域 URL 默认映射

tools/list 为空

stdio 模式下环境变量缺失

确认 HUAWEICLOUD_AK/SK/REGION 已设置

HTTPS 下 Cookie 不生效

未设置 MCP_AUTH_COOKIE_SECURE

启用 HTTPS 后设置 MCP_AUTH_COOKIE_SECURE=true

Docker 构建失败

Node 版本或依赖不匹配

确认 Dockerfile 基础镜像为 node:22-alpine;执行 npm ci

进阶文档入口

入门与部署

  1. docs/wiki/Home.md — 项目总览

  2. docs/wiki/Getting-Started.md — 详细上手指南

  3. docs/wiki/Team-Deployment.md — 团队部署方案

  4. docs/wiki/Testing-and-Live-Ops.md — 测试与线上运维

  5. docs/wiki/Troubleshooting.md — 故障排查手册

架构与能力

  • docs/product-overview.md — 产品概览

  • docs/service-profile.md — 服务画像

  • docs/wiki/Architecture-Deep-Dive.md — 架构深潜

  • docs/wiki/Capability-Matrix.md — 能力矩阵

  • docs/wiki/Module-Live-Readiness.md — 模块 Live 就绪状态

API 对齐

  • docs/wiki/Official-API-Alignment.md — 官方 API 对齐总览

  • docs/wiki/Official-PDF-MCP-Coverage-Summary.md — PDF 覆盖摘要

  • docs/wiki/Official-Category-Coverage-Matrix.md — 分类覆盖矩阵

  • docs/wiki/Official-Endpoint-Mapping-Req-Repo-Pipeline.md — Req/Repo/Pipeline 端点映射

  • docs/wiki/Official-Endpoint-Mapping-Check-Build-Deploy-Artifact-TestPlan.md — Check/Build/Deploy/Artifact/TestPlan 端点映射

模块验证

  • docs/wiki/Req-Live-Validated.md

  • docs/wiki/Check-Live-Validated.md

  • docs/wiki/Build-Live-Validated.md

  • docs/wiki/Deploy-Live-Validated.md

  • docs/wiki/Artifact-Live-Validated.md

  • docs/wiki/TestPlan-Live-Validated.md

A
license - permissive license
-
quality - not tested
-
maintenance - not tested

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/David-piex/codearts-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server