# 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` 调用
- **速率限制** — 写操作内置 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 模式

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

### http 模式

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

### 内部结构

```mermaid
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. 启动共享服务

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

或宿主机直跑：

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

### 2. 客户端添加服务

```json
{
  "mcpServers": {
    "codearts": {
      "type": "http",
      "url": "http://your-server-ip/mcp"
    }
  }
}
```

当前已部署的共享服务推荐使用一个统一入口，可以直接使用下面这份配置：

```json
{
  "mcpServers": {
    "codearts": {
      "disabled": false,
      "timeout": 60,
      "type": "streamableHttp",
      "url": "https://codeartsmcp.top/mcp",
      "headers": {
        "X-CodeArts-AK": "your-ak",
        "X-CodeArts-SK": "your-sk",
        "X-CodeArts-Region": "cn-north-4"
      }
    }
  }
}
```

共享 HTTPS 服务已启用客户端凭证 Header 模式。每个用户只需在自己的 MCP 配置中填写 AK、SK 和区域即可访问，不需要调用 `auth_configure_session`；请勿把真实凭证提交到代码仓库或发送到群聊。

统一入口 `/mcp` 一次暴露 Req、Repo、Pipeline、Check、TestPlan、Deploy、Build、Artifact 全部工具。旧的产品子路径仍保留兼容：

- `/mcp/req`
- `/mcp/repo`
- `/mcp/pipeline`
- `/mcp/check`
- `/mcp/testplan`
- `/mcp/deploy`
- `/mcp/build`
- `/mcp/artifact`

如果客户端希望按产品模块分别启用工具，也可以沿用原来的 8 个服务配置：

```json
{
  "mcpServers": {
    "req": {
      "disabled": false,
      "timeout": 60,
      "type": "streamableHttp",
      "url": "https://codeartsmcp.top/mcp/req",
      "headers": {
        "X-CodeArts-AK": "your-ak",
        "X-CodeArts-SK": "your-sk",
        "X-CodeArts-Region": "cn-north-4"
      }
    },
    "repo": {
      "disabled": false,
      "timeout": 60,
      "type": "streamableHttp",
      "url": "https://codeartsmcp.top/mcp/repo",
      "headers": {
        "X-CodeArts-AK": "your-ak",
        "X-CodeArts-SK": "your-sk",
        "X-CodeArts-Region": "cn-north-4"
      }
    },
    "pipeline": {
      "disabled": false,
      "timeout": 60,
      "type": "streamableHttp",
      "url": "https://codeartsmcp.top/mcp/pipeline",
      "headers": {
        "X-CodeArts-AK": "your-ak",
        "X-CodeArts-SK": "your-sk",
        "X-CodeArts-Region": "cn-north-4"
      }
    },
    "check": {
      "disabled": false,
      "timeout": 60,
      "type": "streamableHttp",
      "url": "https://codeartsmcp.top/mcp/check",
      "headers": {
        "X-CodeArts-AK": "your-ak",
        "X-CodeArts-SK": "your-sk",
        "X-CodeArts-Region": "cn-north-4"
      }
    },
    "testplan": {
      "disabled": false,
      "timeout": 60,
      "type": "streamableHttp",
      "url": "https://codeartsmcp.top/mcp/testplan",
      "headers": {
        "X-CodeArts-AK": "your-ak",
        "X-CodeArts-SK": "your-sk",
        "X-CodeArts-Region": "cn-north-4"
      }
    },
    "deploy": {
      "disabled": false,
      "timeout": 60,
      "type": "streamableHttp",
      "url": "https://codeartsmcp.top/mcp/deploy",
      "headers": {
        "X-CodeArts-AK": "your-ak",
        "X-CodeArts-SK": "your-sk",
        "X-CodeArts-Region": "cn-north-4"
      }
    },
    "build": {
      "disabled": false,
      "timeout": 60,
      "type": "streamableHttp",
      "url": "https://codeartsmcp.top/mcp/build",
      "headers": {
        "X-CodeArts-AK": "your-ak",
        "X-CodeArts-SK": "your-sk",
        "X-CodeArts-Region": "cn-north-4"
      }
    },
    "artifact": {
      "disabled": false,
      "timeout": 60,
      "type": "streamableHttp",
      "url": "https://codeartsmcp.top/mcp/artifact",
      "headers": {
        "X-CodeArts-AK": "your-ak",
        "X-CodeArts-SK": "your-sk",
        "X-CodeArts-Region": "cn-north-4"
      }
    }
  }
}
```

这种配置会在客户端显示 8 个独立 MCP 服务，每个服务只加载对应产品的工具；需要哪个模块就启用哪个。8 个入口可以使用同一组个人 AK/SK，但各自维护独立的 MCP session。

统一入口共用一个 MCP session、鉴权持久化、Cookie 和 `auth_token`。兼容子路径仍按路径隔离 session；新接入不需要配置或切换这些子路径。

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

```http
Authorization: Bearer replace-with-auth-token
```

### 3. 首次鉴权

共享服务可以由运维侧只开启一次客户端凭证 Header 模式：

```env
MCP_AUTH_ALLOW_CLIENT_CREDENTIAL_HEADERS=true
```

之后每个用户在自己的 MCP 配置里填写自己的 AK/SK，不需要管理员预置用户，也不需要调用 `auth_configure_session`：

```json
{
  "mcpServers": {
    "codearts": {
      "type": "streamableHttp",
      "url": "https://your-server-domain/mcp",
      "headers": {
        "X-CodeArts-AK": "your-ak",
        "X-CodeArts-SK": "your-sk",
        "X-CodeArts-Region": "cn-north-4"
      }
    }
  }
}
```

该模式必须使用 HTTPS。AK/SK 会保存在用户本机的 MCP 配置中，并随请求发送；服务端不会把它们写入请求日志，但反向代理也必须禁止记录请求头。不同用户的 Header 会建立相互隔离的加密会话。

默认共享模式下，连接后调用 `auth_configure_session`：

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

单账号部署可以在服务端 `.env` 预置 `HUAWEICLOUD_AK`、`HUAWEICLOUD_SK`、`HUAWEICLOUD_REGION` 和随机的 `MCP_AUTH_STATIC_TOKEN`。MCP 客户端直接配置固定 Bearer 请求头即可，不需要再通过自然语言调用鉴权工具：

```json
{
  "mcpServers": {
    "codearts": {
      "type": "streamableHttp",
      "url": "http://your-server-ip/mcp",
      "headers": {
        "Authorization": "Bearer replace-with-mcp-auth-static-token"
      }
    }
  }
}
```

静态模式的 AK/SK 只保留在服务端环境变量中；客户端只保存可轮换的 MCP token。多用户共享场景继续使用 `auth_configure_session`，不要共用一个静态 token。

### 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 部署（推荐）

```bash
# HTTP
docker compose up -d --build

# HTTPS（需先准备证书，见 deploy/nginx/ssl/）
docker compose -f docker-compose.ssl.yml up -d --build
```

必需环境变量：

```env
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
# 初始化
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

```env
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
```

客户端启动命令：

```bash
node dist/src/server/index.js
```

### CLI 怎么用

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

| 你要做什么 | 用哪种模式 | 凭证从哪里来 |
| --- | --- | --- |
| 在自己电脑或 CI 里直接调用 CodeArts | 本地模式 | 本机环境变量里的 `HUAWEICLOUD_AK` / `HUAWEICLOUD_SK` |
| 调用已经部署好的团队共享 MCP 服务 | 远程模式 | 共享服务返回的 `auth_token` |

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

先设置 AK/SK：

```powershell
$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"
```

然后调用：

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

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

```powershell
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](docs/wiki/CLI-Usage.md)。

## API 文档入口

| 文档 | 用途 |
| --- | --- |
| [CLI Usage](docs/wiki/CLI-Usage.md) | 命令行调用 MCP 工具：本地模式、远程模式、profile、表格输出和补全 |
| [HTTP MCP Interface](docs/wiki/HTTP-MCP-Interface.md) | HTTP 端点、MCP JSON-RPC、鉴权会话、请求响应和接入示例 |
| [Function API Reference](docs/wiki/Function-API-Reference.md) | 完整 MCP 功能 API 总目录；完整参数表、字段对应和 JSON Schema 按模块拆分到明细页 |
| [CodeArts MCP API Reference](docs/wiki/API-Reference.md) | 8 个 CodeArts 服务的 MCP API 总览、基础 URL、工具清单和 live 边界 |
| [Req MCP API Reference](docs/wiki/Req-API-Reference.md) | Req 深度 API 文档，包含 Scrum、需求池、IPD、写入 gate 和 smoke 样本缺口 |
| [Module Functions Overview](docs/wiki/Module-Functions-Overview.md) | 按模块解释每个服务能做什么、适合什么场景 |
| [Capability Matrix](docs/wiki/Capability-Matrix.md) | 各模块读写规模、live 状态和关键缺口 |

## 模块现状总表

<!-- GENERATED:readme-exposure-summary:start -->
- `8` product modules
- `2346` product tools
- `2` session/auth tools for shared `http` mode
- `2348` 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 | 364 | 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 | 146 | 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` 的浏览器来源，多个值用英文逗号分隔 | — |
| `MCP_HTTP_SESSION_IDLE_TIMEOUT_MS` | 无请求的有状态 MCP 会话回收时间（毫秒）；`0` 表示不因空闲主动失效，改用 `MCP_HTTP_MAX_SESSIONS` 控制内存 | `0`（关闭） |
| `MCP_HTTP_MAX_SESSIONS` | 单个共享 HTTP 实例允许保留或正在初始化的 MCP session 总数；每个 session 都会持有一套 MCP 工具服务器，达到上限时一次回收最多 16 个最老的空闲 session，只有全部 session 都在处理请求时才返回 `429` | `128` |
| `MCP_HTTP_MAX_REQUEST_BODY_BYTES` | HTTP MCP JSON 请求体最大字节数；超限请求返回 `413`，用于防止恶意或误配置请求耗尽内存 | `8388608`（8 MiB） |
| `NODE_OPTIONS` | Node.js 运行时参数；共享容器默认将堆上限设为 2560 MB | `--max-old-space-size=2560` |
| `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_STATIC_TOKEN` | 可选单账号 HTTP 模式的固定 Bearer token | — |
| `MCP_AUTH_ALLOW_CLIENT_CREDENTIAL_HEADERS` | 允许共享服务从 MCP 客户端 Header 接收每用户 AK/SK；仅限 HTTPS | `false` |
| `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 或单账号 HTTP 模式） | — |
| `HUAWEICLOUD_SK` | 默认 SK（stdio 或单账号 HTTP 模式） | — |
| `HUAWEICLOUD_REGION` | 默认区域（stdio 或单账号 HTTP 模式） | — |

CodeArts 的部分列表接口在数据量较大时可能需要十几秒才返回响应头，客户端读取请求默认等待 30 秒并对 GET 请求重试一次。

### 产品 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
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` 这类本地二进制，先执行：

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

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

```powershell
.\scripts\dev-shell.cmd
```

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

```powershell
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` 必须稳定保存，否则服务重启后无法恢复已有会话。

## 项目结构

```text
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`