qualien-mcp

qualien-mcp

Um servidor MCP que dá ao seu assistente de IA um kit de ferramentas de QA: Playwright, seus arquivos de teste, GitHub, Jira, Postgres e muito mais, atrás de uma única conexão.

qualien-mcp é um gateway MCP composto para trabalho de SDET / QE. Ele agrega servidores Model Context Protocol atrás de uma conexão, com um catálogo selecionado de 21 servidores relevantes para testes, permissão/negação por ferramenta e proteções somente-leitura por padrão. Adicione um servidor ao Claude Code, Claude Desktop, Cursor ou VS Code em vez de cinco.

npx qualien-mcp

Pronto para uso, ele serve o par inicial de QE: Playwright MCP (automação de navegador, DOM, capturas de tela) e Filesystem MCP (ler/editar arquivos do projeto, page objects, utilitários de teste), com zero configuração. As ferramentas são expostas ao seu assistente com namespace playwright__… e filesystem__….

Por que um gateway?

Seu assistente já pode se conectar diretamente a muitos servidores MCP — então um gateway ganha seu lugar fazendo o que uma pilha de servidores não consegue:

• Um endpoint para adicionar a qualquer cliente (Claude Code, Claude Desktop, Cursor, …).
• Curadoria — habilite/desabilite por servidor e por ferramenta. Menos ferramentas, com nomes melhores = melhor seleção de ferramentas pelo modelo (despejar 200 ferramentas nele o torna pior).
• Uma superfície de roteamento/logging — cada chamada é registrada no stderr com o downstream, a ferramenta e a latência.
• Ciclo de vida limpo — inicia cada downstream como um processo filho e os encerra todos na saída (sem processos de navegador órfãos).
• Selecionado para QE — um kit de ferramentas SDET opinativo, não um proxy genérico.

Use com seu assistente

Claude Code:

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

ou em .mcp.json / configurações do usuário:

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

Claude Desktop (claude_desktop_config.json) e Cursor (~/.cursor/mcp.json ou .cursor/mcp.json): o mesmo formato sob mcpServers.

VS Code (.vscode/mcp.json):

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

Essa única entrada dá ao seu assistente todas as ferramentas de cada servidor agregado.

Adicione mais servidores

Coloque um qualien-mcp.config.json no seu diretório de trabalho (ou passe --config <path>). As entradas mesclam sobre os padrões embutidos — redefina uma chave para alterá-la, ou defina enabled: false para desativar um padrão. Nenhuma nova versão necessária.

{
  "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"] }
    }
  }
}

Veja qualien-mcp.config.example.json para o formato completo (command, args, env, enabled, tools.allow / tools.deny).

Catálogo embutido

qualien-mcp traz um catálogo selecionado de 21 servidores conhecidos (cada um verificado no npm), então você habilita um por chave apenas com seus segredos — sem precisar lembrar pacotes ou comandos:

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

Execute npx qualien-mcp catalog para listar todos com o que cada um precisa. Catálogo atual:

Chave	O que faz	Necessita
playwright (padrão)	Automação de navegador, DOM, capturas de tela	—
filesystem (padrão)	Ler/editar arquivos do projeto	um diretório para permitir (padrão: cwd)
github	PRs, issues, revisão de código	login github (veja abaixo)
sequential-thinking	Raciocínio estruturado / depuração	—
memory	Grafo de conhecimento persistente	—
chrome-devtools	Rede, console, desempenho, armazenamento	—
postgres	SQL / validar dados de backend	DATABASE_URI
mysql	SQL / validar dados de backend	env MySQL
slack	Ler/postar no Slack	SLACK_MCP_XOXP_TOKEN
docker	Gerenciar contêineres	daemon Docker
kubernetes	Inspecionar/operar um cluster	kubeconfig
openapi	Conduzir qualquer API REST a partir de sua spec	API_BASE_URL, OPENAPI_SPEC_PATH
jira	Ler/atualizar issues do Jira	token de API Atlassian env
figma	Ler designs do Figma	FIGMA_API_KEY
confluence	Planos de teste, notas de versão, documentação viva	token de API Atlassian env
azure-devops	Work items, repositórios, pipelines, planos de teste	sua org ADO como argumento + login
selenium	Conduzir um navegador via Selenium WebDriver	um navegador + driver no PATH
webdriverio	Automação de navegador e mobile nativo	— (credenciais de nuvem opcionais)
browserstack	Nuvem real de navegador/dispositivo; ler execuções de teste	BROWSERSTACK_USERNAME, BROWSERSTACK_ACCESS_KEY
ms-365	Excel, Word, Outlook, Teams, SharePoint	AZURE_CLIENT_ID, AZURE_TENANT_ID
sentry	Erros reais voltados ao usuário → novos testes	um token de autenticação Sentry

use monta um servidor do catálogo sob uma chave diferente (ex.: dois bancos de dados): { "db-prod": { "use": "postgres", "enabled": true, "env": {…} } }. Qualquer coisa fora do catálogo você ainda define por completo (command/args ou type/url).

Servidores remotos e OAuth (ex.: GitHub)

Downstreams podem ser remotos (HTTP Streamable) além de locais. Um servidor remoto é { "type": "http", "url": "…" }, e se precisar de OAuth, cada usuário faz login com sua própria conta — os tokens são armazenados por usuário em ~/.qualien-mcp/credentials.json (0600), na própria máquina do usuário, e nunca são agrupados, compartilhados ou enviados a qualquer lugar pelo qualien-mcp.

O MCP hospedado do GitHub é o caso de referência, e não precisa de configuração além de um comando:

1. Ative-o em qualien-mcp.config.json:

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

2. Autorize uma vez:

   npx qualien-mcp login github
   

login imprime um código curto e uma URL; você aprova em github.com e pronto. Não há OAuth App para registrar e nenhum client secret em lugar algum.

Por que o fluxo de dispositivo?

O GitHub exige um client_secret para trocar um código de autorização — PKCE não resolve isso, porque o GitHub não distingue clientes públicos de confidenciais. qualien-mcp é distribuído no npm, então um segredo no pacote seria um segredo publicado. O fluxo de dispositivo é a única concessão que o GitHub permite sem um segredo, e é a concessão que o GitHub recomenda para CLIs. Então o qualien-mcp distribui apenas um client id público — um identificador, não uma credencial — e os tokens de cada usuário são gerados e permanecem na própria máquina do usuário.

Para usar seu próprio OAuth App do GitHub em vez do distribuído, defina clientId (e habilite o fluxo de dispositivo nele em Settings → Developer settings → OAuth Apps):

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

Se um servidor remoto ainda não estiver conectado, o gateway o ignora com uma dica (run: npx qualien-mcp login github) e ainda serve todo o resto — nunca bloqueia a inicialização. Servidores que suportam registro dinâmico de cliente não precisam de clientId.

Seguro por padrão

qualien-mcp aplica proteções centralmente, antes de encaminhar uma chamada — então elas valem independentemente do que o downstream permite, e ferramentas compostas também não podem contorná-las:

• Bancos de dados são somente-leitura — chamadas postgres/mysql contendo SQL de escrita/DDL (INSERT/UPDATE/DELETE/DROP/…) são recusadas. Opte com { "postgres": { "readOnly": false } }.
• Raízes do filesystem — { "filesystem": { "roots": ["./src", "./tests"] } } recusa qualquer chamada cujo argumento de caminho escape desses diretórios.
• Ferramentas de infraestrutura destrutivas bloqueadas — ferramentas docker/kubernetes cujo nome pareça destrutivo (delete/remove/prune/kill/…) são recusadas a menos que { "allowDestructive": true }.
• Além de curadoria por servidor tools.deny / tools.allow.

Escopo honesto: isso impede um LLM de causar dano acidentalmente. A verificação de SQL é baseada em palavras-chave (heurística), não um parser — não é sandboxing adversarial. Isolamento real exige as próprias permissões do downstream ou um contêiner.

Ferramentas QE compostas

Além do passthrough, o qualien-mcp traz ferramentas que ele mesmo implementa (namespace qe__) que orquestram vários downstreams em uma única chamada — o retorno de QE de um gateway.

qe__verify_api_vs_db — consistência ponta a ponta API↔DB em uma chamada. Dê a ele duas sub-chamadas (ferramentas com namespace que você pode descobrir via tools/list); ele executa ambas e compara os payloads:

{
  "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" } ], … }

Ferramentas compostas aparecem apenas quando seus downstreams necessários estão conectados (qe__verify_api_vs_db precisa de um servidor database). Mais por vir (repro-from-Jira, page-object-from-URL, triagem de flaky).

Como funciona

Em um único processo, o qualien-mcp é ao mesmo tempo um servidor MCP para seu assistente e um cliente MCP para cada downstream:

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

• tools/list faz fan-out para cada downstream, filtra pelas suas regras de curadoria e aplica namespace em cada um como <server>__<tool>.
• tools/call roteia por esse prefixo para o servidor dono e passa a resposta diretamente.
• Recursos e prompts são agregados da mesma forma quando um downstream os fornece.
• Um downstream que falha ao iniciar é registrado e ignorado — o gateway ainda serve o resto.
• Logs vão para stderr (stdout é o protocolo); seu host os exibe nos logs MCP.

Roadmap

• ✅ Playwright + Filesystem, namespacing, curadoria, logging, ciclo de vida limpo
• ✅ Catálogo orientado por configuração de 21 servidores, servidores remotos/OAuth (GitHub via fluxo de dispositivo), proteções seguras por padrão, qe__verify_api_vs_db
• Próximo: mais ferramentas QE compostas (repro-from-Jira, page-object-from-URL, triagem de flaky)

Feedback

Encontrou um bug, quer um servidor adicionado ao catálogo ou tem uma ideia? Envie um e-mail para contact@qualien.ai ou abra uma issue. qualien-mcp faz parte da qualien.ai, que também constrói agentes de IA que testam aplicativos web (Olympus) e aplicativos Android nativos (Pulse) a partir de inglês simples.

Licença

MIT