CodeArts MCP

CodeArts MCP

Unified MCP server that wraps 8 Huawei Cloud CodeArts modules (Req, Repo, Pipeline, Check, TestPlan, Deploy, Build, Artifact) into a standardized toolset, supporting local stdio and shared HTTP modes with session isolation and encrypted credential storage.

Category
Visit Server

README

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，命中后毫秒级响应

技术栈

类别 技术 版本
运行时 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 状态和关键缺口

模块现状总表

<!-- GENERATED:readme-exposure-summary:start -->

  • 8 product modules
  • 2334 product tools
  • 2 session/auth tools for shared http mode
  • 2336 total MCP tools in shared http mode <!-- GENERATED:readme-exposure-summary:end -->

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

<!-- GENERATED:readme-module-numbers:start -->

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
<!-- GENERATED:readme-module-numbers:end -->

Live 状态说明：

状态 含义
Validated 所有工具已通过真实 AK/SK 联调验证
Partial 部分工具已验证，其余可用但受租户样本或区域发布限制

环境变量参考

必需变量

变量 说明 默认值
MCP_TRANSPORT 传输模式：http 或 stdio —
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 默认调用模式：local 或 http 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 默认输出格式：json、text 或 table 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 会话直接可用 tsx、vitest、eslint 这类本地二进制，先执行：

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

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

.\scripts\dev-shell.cmd

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

npm run env:node

说明：

  • 这两个脚本会优先使用本机 npm.cmd / node.exe，避免误落到不可用的内置运行时。
  • 可通过 CODEARTS_MCP_NPM_CMD、CODEARTS_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_KEY 和 MCP_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

Recommended Servers

playwright-mcp

playwright-mcp

A Model Context Protocol server that enables LLMs to interact with web pages through structured accessibility snapshots without requiring vision models or screenshots.

Official
Featured
TypeScript
Magic Component Platform (MCP)

Magic Component Platform (MCP)

An AI-powered tool that generates modern UI components from natural language descriptions, integrating with popular IDEs to streamline UI development workflow.

Official
Featured
Local
TypeScript
Audiense Insights MCP Server

Audiense Insights MCP Server

Enables interaction with Audiense Insights accounts via the Model Context Protocol, facilitating the extraction and analysis of marketing insights and audience data including demographics, behavior, and influencer engagement.

Official
Featured
Local
TypeScript
VeyraX MCP

VeyraX MCP

Single MCP tool to connect all your favorite tools: Gmail, Calendar and 40 more.

Official
Featured
Local
graphlit-mcp-server

graphlit-mcp-server

The Model Context Protocol (MCP) Server enables integration between MCP clients and the Graphlit service. Ingest anything from Slack to Gmail to podcast feeds, in addition to web crawling, into a Graphlit project - and then retrieve relevant contents from the MCP client.

Official
Featured
TypeScript
Kagi MCP Server

Kagi MCP Server

An MCP server that integrates Kagi search capabilities with Claude AI, enabling Claude to perform real-time web searches when answering questions that require up-to-date information.

Official
Featured
Python
E2B

E2B

Using MCP to run code via e2b.

Official
Featured
Neon Database

Neon Database

MCP server for interacting with Neon Management API and databases

Official
Featured
Exa Search

Exa Search

A Model Context Protocol (MCP) server lets AI assistants like Claude use the Exa AI Search API for web searches. This setup allows AI models to get real-time web information in a safe and controlled way.

Official
Featured
Qdrant Server

Qdrant Server

This repository is an example of how to create a MCP server for Qdrant, a vector search engine.

Official
Featured