# @qcentriq/mcp 中文文档

规范地址：https://npmcn.com/package/%40qcentriq/mcp/

版本：0\.4\.6
npm 元数据更新时间：2026-11-02T04:16:25.810Z
中文译文更新时间：2026-11-02T06:40:25.574Z
软件包许可：Apache-2\.0

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40qcentriq/mcp
原文对照：https://npmcn.com/package/%40qcentriq/mcp/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：92.5 kB，4 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=22\.12\.0
- 运行依赖：3 个
- 首次发布：2026-09-09T06:27:40.354Z
- 最新版本发布：2026-11-02T04:16:25.641Z
- 已发布版本数：12（近 12 个月 12 个）

## 中文简介

用于QCentriq自动测试发现、诊断和执行的官方模型上下文协议（MCP）服务器。

## 安装

```sh
npm install @qcentriq/mcp
```

也可以使用：`pnpm add @qcentriq/mcp`、`yarn add @qcentriq/mcp`、`bun add @qcentriq/mcp`

## README

# @qcentriq / mcp

[![npm version](https://img.shields.io/npm/v/@qcentriq/mcp.svg?style=flat-square)](https://www.npmjs.com/package/@qcentriq/mcp) [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg?style=flat-square)](https://npmcn.com/package/%40qcentriq/mcp/LICENSE) [![Node.js](https://img.shields.io/badge/node-%3E%3D22.12.0-brightgreen.svg?style=flat-square)](https://nodejs.org/) [![MCP](https://img.shields.io/badge/protocol-Model%20Context%20Protocol-orange.svg?style=flat-square)](https://modelcontextprotocol.io/)

官方 [模型上下文协议（MCP）](https://modelcontextprotocol.io/) 服务器 **QCentriq** 自动测试发现、错误诊断、脚本检索和本地测试执行。

连接你的人工智能编码助手(**光标**， **克劳德桌面**， **VS Code Cline / Roo Code**， **风帆冲浪**， **Zed**，或者 **双子座/反重力**)直接到您的QCentriq QA项目，以检查测试用例，分析失败日志，检索剧作家测试脚本，并验证本地修复。

## ⚡亮点

-   **远程云发现和诊断**：通过经过身份验证的REST客户端端点立即查询测试用例、组、运行日志、故障堆栈跟踪和环境变量。
-   **本地剧作家测试执行**在本地安全地执行测试 `pytest` 不会触发不必要的云运行程序。支持跨Chromium、Firefox和WebKit的headless和headless模式。
-   **智能环境设置**：探测安装的本地Python包管理器(`uv`， `poetry`， `conda`，或标准 `venv`)并生成准备运行的设置命令（首选） `uv` 对于闪电般的快速设置)。
-   **直接工作区脚本保存**：将测试脚本及其辅助文件下载到专用的 `qcentriq_tests/` 工作空间目录（与您自己的目录分开） `tests/`所以一个存在的 `conftest.py` 永远不会被覆盖)。在每个地方运行之前， `qcentriq_run_local_test` 刷新 `conftest.py` QCentriq云运行使用路径遍历保护。
-   **Zero-Leak修订**：自动过滤所有传出的工具有效负载，屏蔽API密钥(`qc_...`)、承载令牌和URL凭证，然后将它们发送到LLM。
-   **严格的工作室隔离**：协议JSON-RPC帧通信干净 `stdout`，而所有诊断日志路由到 `stderr`.

## 🚀快速入门

### 使用 `npx` （无需安装）

直接启动MCP服务器 `npx`：

```bash
npx -y @qcentriq/mcp@latest --api-key "qc_your_api_key_here"
```

或者通过环境变量传递你的配置：

```bash
export QCENTRIQ_API_KEY="qc_your_api_key_here"
export QCENTRIQ_BASE_URL="https://api.qcentriq.com" # Optional, defaults to production
export QCENTRIQ_PROJECT_ID="your-project-uuid"      # Optional default project ID

npx -y @qcentriq/mcp@latest
```

### 全球安装

```bash
npm install -g @qcentriq/mcp
qcentriq-mcp --api-key "qc_your_api_key_here"
```

## 📋CLI选项和环境变量

| CLI选项 | 环境变量 | 默认的 | 描述 |
| :-- | :-- | :-- | :-- |
| `-k, --api-key <key>` | `QCENTRIQ_API_KEY` | _(必需)_ | 您的QCentriq API密钥(`qc_...`）。 |
| `-u, --base-url <url>` | `QCENTRIQ_BASE_URL` | `https://api.qcentriq.com` | QCentriq后端API的基础URL。 |
| `-p, --project-id <id>` | `QCENTRIQ_PROJECT_ID` | `undefined` | 可选的默认项目UUID（如果省略，则从API密钥推断）。 |
| `-d, --debug` | `DEBUG` 或者 `QCENTRIQ_DEBUG` | `false` | 为stderr启用详细调试日志。 |
| `-h, --help` | \- - - - - - | \- - - - - - | 显示命令行使用信息和标志。 |

## ⚙️辅助配置指南

### 1\. 克劳德桌面

将QCentriq添加到配置文件中：

-   **macOS**： `~/Library/Application Support/Claude/claude_desktop_config.json`
-   **窗户**： `%APPDATA%\Claude\claude_desktop_config.json`
-   **Linux**： `~/.config/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "qcentriq": {
      "command": "npx",
      "args": ["-y", "@qcentriq/mcp@latest"],
      "env": {
        "QCENTRIQ_API_KEY": "qc_your_api_key_here",
        "QCENTRIQ_BASE_URL": "https://api.qcentriq.com",
        "QCENTRIQ_PROJECT_ID": "optional-default-project-uuid"
      }
    }
  }
}
```

### 2\. 光标IDE

在光标中，打开 **设置** \\美元 **功能** \\美元 **MCP服务器** \\美元 **添加新的MCP服务器**，或编辑 `~/.cursor/mcp.json` (或 `.cursor/mcp.json` 在你的存储库根目录下)：

```json
{
  "mcpServers": {
    "qcentriq": {
      "command": "npx",
      "args": ["-y", "@qcentriq/mcp@latest"],
      "env": {
        "QCENTRIQ_API_KEY": "qc_your_api_key_here",
        "QCENTRIQ_BASE_URL": "https://api.qcentriq.com"
      }
    }
  }
}
```

### 3\. VS Code （Cline / Roo Code）

在VS Code中使用Cline或Roo Code扩展，打开 `cline_mcp_settings.json`：

```json
{
  "mcpServers": {
    "qcentriq": {
      "command": "npx",
      "args": ["-y", "@qcentriq/mcp@latest"],
      "env": {
        "QCENTRIQ_API_KEY": "qc_your_api_key_here"
      },
      "disabled": false,
      "autoApprove": [
        "qcentriq_list_tests",
        "qcentriq_get_test",
        "qcentriq_get_test_groups",
        "qcentriq_get_test_run_logs"
      ]
    }
  }
}
```

### 4\. 风帆冲浪

在 `~/.codeium/windsurf/mcp_config.json`：

```json
{
  "mcpServers": {
    "qcentriq": {
      "command": "npx",
      "args": ["-y", "@qcentriq/mcp@latest"],
      "env": {
        "QCENTRIQ_API_KEY": "qc_your_api_key_here"
      }
    }
  }
}
```

### 5\. Zed

在你的Zed里 `settings.json` (在 `experimental.context_servers`):

```json
{
  "context_servers": {
    "qcentriq": {
      "command": "npx",
      "args": ["-y", "@qcentriq/mcp@latest"],
      "env": {
        "QCENTRIQ_API_KEY": "qc_your_api_key_here"
      }
    }
  }
}
```

### 6\. 双子座/反重力IDE

在 `~/.gemini/config/mcp_config.json` (或 `.agents/mcp_config.json` 在工作区中):

```json
{
  "mcpServers": {
    "qcentriq": {
      "command": "npx",
      "args": ["-y", "@qcentriq/mcp@latest"],
      "env": {
        "QCENTRIQ_API_KEY": "qc_your_api_key_here",
        "QCENTRIQ_BASE_URL": "https://api.qcentriq.com"
      }
    }
  }
}
```

### 7\. Claude Code命令行

使用Claude CLI添加QCentriq MCP服务器：

```bash
claude mcp add qcentriq -- npx -y @qcentriq/mcp@latest --api-key "qc_your_api_key_here"
```

### 🎭添加剧作家MCP进行写作测试（推荐）

在编写测试计划或脚本之前，助手会被告知在真实的浏览器中使用 [剧作家MCP服务器](https://github.com/microsoft/playwright-mcp)． 这样，url、标签和选择器就来自页面本身，而不是猜测。QCentriq MCP不能调用剧作家MCP本身，所以把它添加到同一个客户端旁边 `qcentriq`：

```json
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    }
  }
}
```

使用Claude Code： `claude mcp add playwright -- npx @playwright/mcp@latest`． 如果剧作家MCP没有连接，助手应该在写计划之前说明。

**HTTP基本认证背后的站点** （在staging上很常见）在浏览器登录之前，用空白页回答401。助理被告知要注意到这一点，并继续自己的工作。它从您的请求或环境中获取凭据 `BASIC_AUTH_USERNAME` / `BASIC_AUTH_PASSWORD` 变量（或键） `QCENTRIQ_BASIC_AUTH_USERNAME_KEY` / `QCENTRIQ_BASIC_AUTH_PASSWORD_KEY` 名字)。然后它在URL中重新打开站点，Chromium会在会话的剩余时间内记住它们。它只在凭据作为秘密存储时询问您，因为QCentriq从不向助手发送秘密值。为了避免这个问题，可以先给剧作家MCP一个证书 `--config playwright-mcp.json`：

```json
{
  "browser": {
    "contextOptions": {
      "httpCredentials": { "username": "staging-user", "password": "staging-password" }
    }
  }
}
```

脚本从不包含凭据。这个 `conftest.py` QCentriq船应用它们 `BASIC_AUTH_USERNAME` / `BASIC_AUTH_PASSWORD`，店员递给他 `qcentriq_run_local_test` 在 `env_vars` 对于本地运行。

## 推荐️可用的MCP工具

QCentriq MCP服务器完全分离 **远程云发现/诊断** (通过经过身份验证的REST端点连接到 `/api/v1/mcp-client/`), **本地客户端操作** （完全在机器的本地工作空间中执行）：

### 🌐远程发现和诊断（云REST端点）

| 工具的名字 | 描述 | 关键参数 |
| :-- | :-- | :-- |
| `qcentriq_list_tests` | 发现具有状态、优先级和更新时间戳的测试用例和测试组。突出显示了脚本可用性。 | `project_id` _(uuid)_， `group_id` _(uuid)_， `priority` _(“低”|“介质”|“高”|“关键”)_， `test_type` _(“web”|“api”|“移动”)_， `limit` _(int)_， `offset` _(int)_ |
| `qcentriq_get_test` | 检索完整的测试用例定义、步骤描述、前提条件、最新的执行诊断和错误堆栈跟踪。 | `test_case_id` _(uuid,要求)_， `project_id` _(uuid)_ |
| `qcentriq_get_test_groups` | 发现并检查测试组、成员测试用例、测试计数和脚本可用性。 | `project_id` _(uuid)_， `group_id` _(uuid)_， `limit` _(int)_， `offset` _(int)_ |
| `qcentriq_download_script` | 下载剧作家Python测试脚本及其辅助文件，并将它们保存到 `./qcentriq_tests/` （同一目录） `qcentriq_save_script` 使用)。通过 `save_to_disk=false` 只返回内容。 | `group_id` _(uuid,要求)_， `project_id` _(uuid)_， `include_fixtures` _（bool，默认为true）_， `save_to_disk` _（bool，默认为true）_， `destination_dir` _（字符串，默认为“./qcentriq\_tests”）_ |
| `qcentriq_get_environment` | 检索目标环境配置、基本URL (`BASE_URL`)、环境变量，以及本地执行所需的秘密变量名。 | `project_id` _(uuid)_， `environment_id` _(uuid)_， `environment_name` _(字符串)_ |
| `qcentriq_get_test_run_logs` | 获取执行历史、日志、标准输出/标准错误以及跨单例和套件运行的堆栈跟踪。 | `test_case_id` _(uuid,要求)_， `project_id` _(uuid)_， `run_id` _(uuid)_， `status` _(“失败”|“传递”|“错误”)_， `latest_only` _(保龄球)_， `from_date` _(ISO日期)_， `to_date` _(ISO日期)_， `limit` _(int)_， `offset` _(int)_ |

### ✍️创作(云REST端点，写入要求 `test:write`）

预定的顺序是： `qcentriq_get_authoring_guide` 和 `qcentriq_get_environment`，然后使用 [剧作家MCP](https://npmcn.com/package/%40qcentriq/mcp/#readme--add-playwright-mcp-for-writing-tests-recommended),然后 `qcentriq_create_plan`，然后编写脚本，运行它 `qcentriq_run_local_test` 直到它通过，并上传它 `qcentriq_save_group_script`． 服务器将此命令作为其MCP指令发送给助手。

两个写工具在被调用时都会发送给QCentriq；MCP客户端自己的工具审批提示是上传前的检查(参见 [安全与隐私](https://npmcn.com/package/%40qcentriq/mcp/#readme--security--privacy)）。

| 工具的名字 | 描述 | 关键参数 |
| :-- | :-- | :-- |
| `qcentriq_get_authoring_guide` | 获取计划和脚本的契约：TaskPlan JSON模式、 `${VAR}` 环境变量约定 `@allure.id` 规则，以及可用的conftest fixture。只读的。 | \- - - - - - |
| `qcentriq_create_plan` | 从撰写的计划中创建测试组和测试用例。每个创建的测试用例返回一个UUID。可以创建流在浏览器中失败的case `status: "blocked"` 还有一个证据 `block_reason`;QCentriq重新验证它，并保持它被阻塞，只有当它看到同样的失败(`block_source` 显示 `client` 在那之前)。 **写道。** | `plan` _(对象、要求)_， `project_id` _(uuid)_ |
| `qcentriq_save_group_script` | 验证并存储组的测试脚本，替换现有的测试脚本。组中每个未阻塞的案例必须出现一次 `@allure.id('<case_id>')`;阻塞的情况可能会被忽略。只上传通过的脚本 `qcentriq_run_local_test` 使用这个确切的内容(参见 [上传前的本地通行证](https://npmcn.com/package/%40qcentriq/mcp/#readme--security--privacy)）. 根据此会话中最后一次下载或保存的组的版本进行检查，因此其他人的新编辑将作为冲突而不是覆盖而被拒绝。 **写道。** | `group_id` _(uuid,要求)_， `content` _(字符串,需要)_， `project_id` _(uuid)_， `filename` _(字符串)_， `fixtures` _(数组)_ |
| `qcentriq_update_test_case` | 编辑一个现有的测试用例（标题、描述、优先级、前提条件、步骤、预期结果、目标URL），而不是创建一个副本。需要 `last_updated_at` 从 `qcentriq_get_test`;其他人的新编辑被视为冲突而拒绝。报告 `script_stale` 当更改意味着需要更新组脚本时。阻塞状态不可编辑。 **写道。** | `test_case_id` _(uuid,要求)_， `expected_last_updated_at` _(字符串,需要)_，加上要改变的字段， `project_id` _(uuid)_ |
| `qcentriq_recheck_blocked_case` | 要求QCentriq针对活动站点重新验证阻塞的测试用例。QCentriq自己的代理决定裁决： `active` 解除阻塞案例并将其添加到组脚本中（在您编写脚本的组中，您自己添加测试）， `blocked` 刷新 `block_reason`． 呼叫者不能设置判决。可能需要几分钟（客户端超时7分钟）。 **写道。** | `test_case_id` _(uuid,要求)_， `project_id` _(uuid)_ |

### 💻本地客户端工具（在本地工作区中执行）

| 工具的名字 | 描述 | 关键参数 |
| :-- | :-- | :-- |
| `qcentriq_get_setup_instructions` | 检测哪些Python包管理器(`uv`， `poetry`， `conda`， `venv`)安装在本地系统上，并返回一步一步的命令来创建与QCentriq运行器容器匹配的虚拟环境。如果没有安装，则从安装开始 `uv`. _（只读指令，从不运行命令）。_ | `preferred_manager` _(“紫外线”|“诗歌”|“conda”|“venv”)_， `working_dir` _(字符串)_， `env_name` _（字符串，默认为“qcentriq-tests”）_， `python_version` _（字符串，默认为“3.12”）_， `playwright_version` _（字符串，默认为“1.56.0”）_ |
| `qcentriq_save_script` | 将下载的测试脚本和fixture直接保存到本地工作区中(默认为 `./qcentriq_tests/`)与路径穿越保护。 | `file_name` _(字符串,需要)_， `content` _(字符串,需要)_， `conftest_content` _(字符串)_， `destination_dir` _（字符串，默认为“./qcentriq\_tests”）_ |
| `qcentriq_run_local_test` | 通过本地运行测试 `pytest`． 在不触发云运行程序的情况下捕获标准输出、标准错误、执行持续时间和退出代码。完整文件的传递使该脚本符合以下条件 `qcentriq_save_group_script`． 如果没有安装Python包管理器，它会告诉您安装 `uv` 第一。 | `file_path` _(字符串,需要)_， `test_name` _(字符串)_， `headless` _（bool，默认为true）_， `browser` _（"chromium"|"firefox"|"webkit“，默认为”chromium"）_， `base_url` _(url)_， `env_vars` _(记录)_， `extra_args` _(数组)_， `timeout_seconds` _（int，默认为60）_， `working_dir` _(字符串)_ |

## 🔄端到端AI自愈工作流程

以下是AI助手（如Cursor或Claude）的使用方法 `@qcentriq/mcp` 诊断和修复失败的测试：

```mermaid
sequenceDiagram
    autonumber
    actor User
    participant AI as AI Assistant
    participant MCP as QCentriq MCP Server
    participant API as QCentriq Cloud API
    participant Local as Local Workspace & Subprocess

    User->>AI: "Fix the failing login test in QCentriq"
    AI->>MCP: qcentriq_list_tests(priority="high")
    MCP->>API: GET /api/v1/mcp-client/tests
    API-->>MCP: Test cases metadata
    MCP-->>AI: List of tests

    AI->>MCP: qcentriq_get_test_run_logs(test_case_id="...")
    MCP->>API: GET /api/v1/mcp-client/tests/{id}/run-logs
    API-->>MCP: Failure trace (e.g. SelectorTimeoutError)
    MCP-->>AI: Error diagnostics & stack trace

    AI->>MCP: qcentriq_get_setup_instructions()
    MCP-->>AI: Recommended setup commands (uv venv, uv pip install ...)

    AI->>MCP: qcentriq_download_script(group_id="...")
    MCP->>API: GET /api/v1/mcp-client/groups/{id}/script
    API-->>MCP: Script & helper files
    MCP->>Local: Write qcentriq_tests/test_login.py
    MCP-->>AI: File paths confirmed

    AI->>Local: Inspect and update selector in test_login.py
    AI->>MCP: qcentriq_run_local_test(file_path="qcentriq_tests/test_login.py", headless=false)
    MCP->>Local: Run pytest with Playwright
    Local-->>MCP: Test result (PASSED)
    MCP-->>AI: PASSED (exit code 0, 1.42s)
    AI->>User: "Fixed selector in qcentriq_tests/test_login.py and verified locally!"
```

## 🔒安全与隐私

-   **安全网络边界**：客户端MCP服务器连接 **专门** 来 `${baseUrl}/api/v1/mcp-client/` 使用HTTPS。发现和诊断工具只能读取。创作工具 `qcentriq_create_plan`， `qcentriq_update_test_case`， `qcentriq_save_group_script` 和 `qcentriq_recheck_blocked_case` 写入您的项目（创建和编辑测试组/用例，替换组的脚本，当QCentriq的实时复查确认它工作时解除阻塞用例），后端拒绝它们，除非API密钥携带 `test:write` 范围。
-   **上传前的本地通行证**： `qcentriq_save_group_script` 拒绝脚本，除非准确的内容通过 `qcentriq_run_local_test` 在当前服务器会话中，作为整个文件：否 `test_name`，节点id，或 `-k`/`-m`/`--deselect`/`--lf`样式过滤器，并且至少有一个测试通过（不是全部跳过）。每个伴随文件必须与运行期间脚本旁边的文件匹配，并且此后没有更改过。通过的运行保存在内存中，因此在重新启动脚本后必须再次运行。如果没有安装Python包管理器，则拒绝表示安装 [`uv`](https://docs.astral.sh/uv/getting-started/installation/) 首先（推荐），然后使用 `qcentriq_get_setup_instructions`.
-   **客户端控制**：执行测试、修改脚本和设置环境 **本地在您的机器上**． 在您不知情的情况下，不会上传本地代码或文件。
-   **Zero-Leak修订**：服务器主动扫描和编辑API密钥(`qc_...`)、承载令牌和嵌入的基本认证凭证，然后将数据返回给LLM。
-   **文件系统安全**：路径遍历攻击(例如： `../../etc/passwd`)在将测试脚本和fixture写入磁盘时被阻塞。
-   **它的完整性**：所有服务器诊断日志严格路由到 `stderr`． 标准输出(`stdout`)是纯粹为JSON-RPC 2.0通信保留的。

## 💻本地发展

```bash
# Clone the repository
git clone https://github.com/qcentriq/qcentriq.git
cd packages/qcentriq-mcp

# Install dependencies
npm install

# Run typecheck
npm run typecheck

# Run test suite
npm test

# Build production bundle with tsup
npm run build

# Run local development server with live reload
QCENTRIQ_API_KEY="qc_your_key" QCENTRIQ_BASE_URL="http://localhost:8787" npm run dev
```

## 📄许可证

apache - 2.0© [QCentriq](https://qcentriq.com/)

## 常见问题

### @qcentriq/mcp 是什么？

用于QCentriq自动测试发现、诊断和执行的官方模型上下文协议（MCP）服务器。

### 如何安装 @qcentriq/mcp？

在项目目录运行 npm install @qcentriq/mcp，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 qcentriq-mcp，可以用 npx qcentriq-mcp 直接运行。

### @qcentriq/mcp 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/qcentriq\_\_mcp 是否存在。

### @qcentriq/mcp 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @qcentriq/mcp 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.12\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @qcentriq/mcp 可以商用吗？

@qcentriq/mcp 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @qcentriq/mcp 还在维护吗？

最新版本 0\.4\.6 发布于 2026/11/02（1 天前）；至今共发布 12 个版本，其中过去 12 个月发布了 12 个；首次发布于 2026/09/09。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。