qualien-mcp

qualien-mcp

一个 MCP 服务，为你的 AI 助手提供 QA 工具包：Playwright、测试文件、GitHub、Jira、Postgres 等，全部通过一个连接使用。

qualien-mcp 是面向 SDET / QE 工作的组合式 MCP 网关。它通过一个连接聚合 Model Context Protocol 服务，提供精心筛选的 21 个与测试相关的服务目录、逐工具允许/拒绝控制，以及默认只读的防护措施。只需将一个服务添加到 Claude Code、Claude Desktop、Cursor 或 VS Code，而非五个。

npx qualien-mcp

开箱即用时，它提供 QE 入门组合：Playwright MCP（浏览器自动化、DOM、屏幕截图）和 Filesystem MCP（读取/编辑项目文件、页面对象、测试工具），无需任何配置。工具会以 playwright__… 和 filesystem__… 为命名空间，提供给你的助手。

为什么需要网关？

你的助手已经可以直接连接许多 MCP 服务了——因此，网关的价值在于实现一堆服务无法做到的事情：

• 一个端点即可添加到任意客户端（Claude Code、Claude Desktop、Cursor，……）。
• 精简筛选——可按服务和工具启用/禁用。工具更少、名称更清晰 = 模型能更好地选择工具（把 200 个工具一股脑塞给它，只会让效果更差）。
• 统一路由/日志界面——每次调用都会将下游服务、工具和延迟记录到 stderr。
• 简洁的生命周期管理——将每个下游服务作为子进程启动，并在退出时将其全部关闭（不会遗留孤立的浏览器进程）。
• 专为 QE 精选——一套有明确主张的 SDET 工具包，而非通用代理。

与你的助手搭配使用

Claude Code：

claude mcp add qualien -- npx -y qualien-mcp

或在 .mcp.json / 用户设置中：

{
  "mcpServers": {
    "qualien": { "command": "npx", "args": ["-y", "qualien-mcp"] }
  }
}

Claude Desktop（claude_desktop_config.json）和 Cursor（~/.cursor/mcp.json 或 .cursor/mcp.json）：在 mcpServers 下使用相同结构。

Claude Desktop 扩展：从最新版本下载 qualien-mcp-<version>.mcpb 并打开。Claude Desktop 会要求选择一个项目文件夹：Filesystem 工具的访问范围仅限于该文件夹，在其中添加 qualien-mcp.config.json 即可启用更多服务。也可在 Smithery 上找到。

VS Code（.vscode/mcp.json）：

{
  "servers": {
    "qualien": { "command": "npx", "args": ["-y", "qualien-mcp"] }
  }
}

这个条目即可让你的助手使用所有聚合服务中的每个工具。

添加更多服务

在工作目录中放入 qualien-mcp.config.json（或传入 --config <path>）。配置项会与内置默认值合并——重新定义某个键即可修改它，或将 enabled: false 设为关闭某个默认项。无需发布新版本。

{
  "servers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/abs/path/to/allow"]
    },
    "sequential-thinking": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
    },
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@latest"]
    },
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"],
      "tools": { "deny": ["browser_close"] }
    }
  }
}

完整结构（command、args、env、enabled、tools.allow / tools.deny）请参见 qualien-mcp.config.example.json。

内置目录

qualien-mcp 自带一个经过整理的目录，其中包含 21 个已知服务（均已通过 npm 验证），因此只需提供密钥，就能通过 键 启用服务——无需记住包名或命令：

{
  "servers": {
    "chrome-devtools": { "enabled": true },
    "postgres":  { "enabled": true, "env": { "DATABASE_URI": "postgres://…" } },
    "slack":     { "enabled": true, "env": { "SLACK_MCP_XOXP_TOKEN": "xoxp-…" } }
  }
}

运行 npx qualien-mcp catalog，即可查看所有服务及其所需信息。当前目录：

键	用途	所需信息
playwright (默认)	浏览器自动化、DOM、屏幕截图	—
filesystem (默认)	读取/编辑项目文件	允许访问的目录（默认是当前工作目录）
github	PR、议题、代码审查	login github（见下文）
sequential-thinking	结构化推理/调试	—
memory	持久化知识图谱	—
chrome-devtools	网络、控制台、性能、存储	—
postgres	SQL / 验证后端数据	DATABASE_URI
mysql	SQL / 验证后端数据	MySQL 环境变量
slack	读取/发布 Slack 消息	SLACK_MCP_XOXP_TOKEN
docker	管理容器	Docker 守护进程
kubernetes	检查/操作集群	kubeconfig
openapi	根据规范调用任意 REST API	API_BASE_URL、OPENAPI_SPEC_PATH
jira	读取/更新 Jira 议题	Atlassian API 令牌环境变量
figma	读取 Figma 设计稿	FIGMA_API_KEY
confluence	测试计划、发布说明、持续更新的文档	Atlassian API 令牌环境变量
azure-devops	工作项、代码仓库、流水线、测试计划	作为参数提供 ADO 组织名 + 登录
selenium	通过 Selenium WebDriver 驱动浏览器	PATH 中的浏览器和驱动
webdriverio	浏览器和原生移动端自动化	—（云凭据可选）
browserstack	真实浏览器/设备云；读取测试运行记录	BROWSERSTACK_USERNAME、BROWSERSTACK_ACCESS_KEY
ms-365	Excel、Word、Outlook、Teams、SharePoint	AZURE_CLIENT_ID、AZURE_TENANT_ID
sentry	真实用户遇到的错误 → 新测试	Sentry 身份验证令牌

use 可在其他键下挂载目录中的服务（例如两个数据库）：{ "db-prod": { "use": "postgres", "enabled": true, "env": {…} } }。目录中没有的服务仍需完整定义（command/args 或 type/url）。

远程服务与 OAuth 服务（例如 GitHub）

下游服务既可以是本地服务，也可以是远程服务（Streamable HTTP）。远程服务的定义为 { "type": "http", "url": "…" }。如果服务需要 OAuth，每位用户都使用自己的账户登录——令牌按用户存储在该用户自己的机器上的 ~/.qualien-mcp/credentials.json（权限为 0600）中，qualien-mcp 绝不会将令牌打包、共享或发送到任何地方。

GitHub 托管的 MCP 是参考示例，只需一条命令即可完成设置：

1. 在 qualien-mcp.config.json 中启用：

   { "servers": { "github": { "enabled": true } } }
   

2. 授权一次：

   npx qualien-mcp login github
   

login 会打印一个短代码和一个 URL；你在 github.com 上批准后即可完成。无需注册 OAuth App，也无需在任何地方设置客户端密钥。

为什么使用设备授权流程？

GitHub 要求使用 client_secret 交换授权码——PKCE 无法改变这一点，因为 GitHub 不区分公开客户端和机密客户端。qualien-mcp 发布在 npm 上，因此包中包含的密钥会成为公开发布的密钥。设备授权流程是 GitHub 允许在没有密钥的情况下使用的唯一授权类型，也是 GitHub 推荐用于 CLI 的授权类型。因此，qualien-mcp 只附带一个公开客户端 ID——它是标识符，而非凭据；每位用户的令牌都在其自己的机器上生成，并保留在该机器上。

如果要使用自己的 GitHub OAuth App，而不是随附的 App，请设置 clientId（并在该 App 的 Settings → Developer settings → OAuth Apps 下启用设备授权流程）：

{
  "servers": {
    "github": { "clientId": "<your client id>", "enabled": true }
  }
}

如果远程服务尚未登录，网关会跳过该服务并给出提示（run: npx qualien-mcp login github），同时继续提供其他所有服务——它绝不会阻止启动。支持动态客户端注册的服务无需设置 clientId。

默认安全

qualien-mcp 会在转发调用前集中实施防护措施——因此无论下游允许什么，这些措施都会生效，复合工具也无法绕过：

• 数据库为只读——包含写入/DDL SQL（INSERT/UPDATE/DELETE/DROP/…）的 postgres/mysql 调用会被拒绝。可通过 { "postgres": { "readOnly": false } } 选择启用写入。
• 文件系统根目录——{ "filesystem": { "roots": ["./src", "./tests"] } } 会拒绝路径参数超出这些目录范围的任何调用。
• 阻止破坏性基础设施工具——名称看起来具有破坏性的 docker/kubernetes 工具（delete/remove/prune/kill/…）会被拒绝，除非设置 { "allowDestructive": true }。
• 此外，还可通过每个服务的 tools.deny / tools.allow 进行筛选。

如实说明适用范围：这些措施可以避免大模型意外造成损害。SQL 检查基于关键字（启发式），并非解析器——它不是对抗性沙箱。真正的隔离需要依靠下游自身的权限或容器。

复合 QE 工具

除透传外，qualien-mcp 还提供自行实现的工具（命名空间为 qe__），可在一次调用中协调多个下游——这正是网关带来的 QE 优势。

qe__verify_api_vs_db——一次调用即可端到端验证 API↔DB 一致性。向它提供两个子调用（可通过 tools/list 发现的命名空间工具）；它会运行两者并对比载荷：

{
  "api": { "tool": "openapi__getUser", "arguments": { "id": 1 } },
  "db":  { "tool": "postgres__query", "arguments": { "sql": "select id, name from users where id = 1" } },
  "match": "subset"        // every field the DB returns must match the API (default)
}
// → { "match": false, "differences": [ { "path": "name", "api": "Ann", "db": "Bob" } ], … }

只有连接了所需下游时，才会出现复合工具（qe__verify_api_vs_db 需要一个 database 服务）。更多工具即将推出（从 Jira 复现问题、从 URL 生成页面对象、分析不稳定测试）。

工作原理

在一个进程中，qualien-mcp 既是面向助手的 MCP 服务，也是面向各个下游的 MCP 客户端：

assistant ⇄ qualien-mcp ⇄ playwright-mcp
                         ⇄ filesystem-mcp
                         ⇄ …

• tools/list 会向所有下游分发请求，按筛选规则过滤工具，并将每个工具命名为 <server>__<tool>。
• tools/call 会根据此前缀将调用路由到所属服务，并直接传递响应。
• 下游提供资源和提示词时，也会以相同方式聚合。
• 无法启动的下游会记录日志并跳过——网关仍会继续服务其余下游。
• 日志写入 stderr（stdout 用于协议）；宿主会在其 MCP 日志中显示这些日志。

路线图

• ✅ Playwright + Filesystem、命名空间、筛选、日志记录、清晰的生命周期管理
• ✅ 由配置驱动的 21 个服务目录、远程/OAuth 服务（通过设备授权流程连接 GitHub）、默认安全防护措施、qe__verify_api_vs_db
• 下一步：推出更多复合 QE 工具（从 Jira 复现问题、从 URL 生成页面对象、分析不稳定测试）

反馈

发现了 Bug、希望在目录中添加服务，或有其他想法？请发送邮件至 [email protected]，或提交 issue。qualien-mcp 是 qualien.ai 的一部分；该公司还会根据日常语言构建用于测试 Web 应用（Olympus）和原生 Android 应用（Pulse）的 AI Agent。

许可证

MIT