qualien-mcp

一个 复合 MCP 网关 —— 它将多个 Model Context Protocol 服务器聚合到一个连接后面，专为 SDET / QE 工作流打造。为你的 AI 助手添加一个服务器，而不是五个。

npx qualien-mcp

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

为什么需要网关？

你的助手已经可以直接连接许多 MCP 服务器 —— 因此网关的价值在于它能做到一堆服务器做不到的事情：

• 一个端点，可添加到任何客户端（Claude Code、Claude Desktop、Cursor、……）。

• 精选 —— 可按服务器和按工具启用/禁用。更少、命名更好的工具 = 模型能更好地选择工具（一次倾倒 200 个工具反而会让它更糟）。

• 统一的路由/日志面 —— 每次调用都会将下游、工具和延迟记录到 stderr。

• 干净的生命周期 —— 将每个下游作为子进程生成，并在退出时全部关闭（不会留下孤立的浏览器进程）。

• 为 QE 定制 —— 一个主观的 SDET 工具集，而非通用代理。

与你的助手一起使用

Claude Code（.mcp.json 或用户设置）：

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

Claude Desktop（claude_desktop_config.json）—— 在 mcpServers 下结构相同。

这一条配置就为你的助手提供了来自所有聚合服务器的每个工具。

添加更多服务器

在工作目录中放置 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 附带一个精选的已知服务器目录（已针对 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 可列出所有服务器及其所需项。当前目录：

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），绝不会打包或共享。

GitHub 托管的 MCP 是参考案例。它不支持动态客户端注册，因此你需要一次性注册自己的 GitHub OAuth 应用，并将客户端 ID 提供给 qualien-mcp：

1. GitHub → Settings → Developer settings → OAuth Apps → New。将回调 URL 设置为 http://127.0.0.1:41999/callback。复制 Client ID。

2. 在 qualien-mcp.config.json 中：

   {
     "servers": {
       "github": {
         "type": "http",
         "url": "https://api.githubcopilot.com/mcp/",
         "oauth": true,
         "clientId": "<your client id>"
       }
     }
   }

3. 授权（会打开你的浏览器，仅一次）：

   npx qualien-mcp login github

之后，网关以非交互方式连接 GitHub（按需刷新令牌），并暴露 github__* 工具。如果远程服务器尚未登录，网关会跳过并给出提示（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 配置。

诚实说明：这些措施能防止 LLM 意外造成损害。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 服务器）。更多功能即将推出（repro-from-Jira、page-object-from-URL、flaky triage）。

工作原理

在单个进程中，qualien-mcp 既是面向你助手的 MCP 服务器，又是面向每个下游的 MCP 客户端：

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

• tools/list 分发到每个下游，根据你的配置规则进行过滤，并将每个工具命名为 <server>__<tool>。

• tools/call 根据该前缀路由到所属服务器，并将响应直接传递回去。

• 当下游提供资源和提示时，也以相同方式聚合。

• 无法启动的下游会被记录并跳过 —— 网关仍会提供其余服务。

• 日志输出到 stderr（stdout 是协议通道）；你的宿主会在其 MCP 日志中展示它们。

路线图

• v0.1 — Playwright + Filesystem、命名空间、精选、日志、干净的生命周期 ✅

• 下一步 —— 配置驱动的扩展（通过其托管的 OAuth MCP 接入 GitHub、DB、Sequential-Thinking、Memory、Chrome DevTools）、复合 QE 工具（例如一次调用验证 API ↔ DB 一致性）、安全范围界定。

许可证

MIT