@qcentriq / mcp

官方 模型上下文协议（MCP） 服务器 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：

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

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

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

全球安装

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

📋CLI选项和环境变量

⚙️辅助配置指南

1. 克劳德桌面

将QCentriq添加到配置文件中：

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• 窗户： %APPDATA%\Claude\claude_desktop_config.json
• Linux： ~/.config/Claude/claude_desktop_config.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 在你的存储库根目录下)：

{
  "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：

{
  "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：

{
  "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):

{
  "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 在工作区中):

{
  "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服务器：

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

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

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

{
  "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：

{
  "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端点）

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

预定的顺序是： qcentriq_get_authoring_guide 和 qcentriq_get_environment，然后使用 剧作家MCP,然后 qcentriq_create_plan，然后编写脚本，运行它 qcentriq_run_local_test 直到它通过，并上传它 qcentriq_save_group_script． 服务器将此命令作为其MCP指令发送给助手。

两个写工具在被调用时都会发送给QCentriq；MCP客户端自己的工具审批提示是上传前的检查(参见 安全与隐私）。

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

🔄端到端AI自愈工作流程

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

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 首先（推荐），然后使用 qcentriq_get_setup_instructions.
• 客户端控制：执行测试、修改脚本和设置环境 本地在您的机器上． 在您不知情的情况下，不会上传本地代码或文件。
• Zero-Leak修订：服务器主动扫描和编辑API密钥(qc_...)、承载令牌和嵌入的基本认证凭证，然后将数据返回给LLM。
• 文件系统安全：路径遍历攻击(例如： ../../etc/passwd)在将测试脚本和fixture写入磁盘时被阻塞。
• 它的完整性：所有服务器诊断日志严格路由到 stderr． 标准输出(stdout)是纯粹为JSON-RPC 2.0通信保留的。

💻本地发展

# 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