qualien-mcp

Una puerta de enlace MCP compuesta — agrega múltiples servidores Model Context Protocol detrás de una conexión, seleccionados para flujos de trabajo SDET / QE. Añade un servidor a tu asistente de IA en lugar de cinco.

npx qualien-mcp

De serie incluye el par inicial de QE — Playwright MCP (automatización del navegador, DOM, capturas de pantalla) y Filesystem MCP (leer/editar archivos del proyecto, objetos de página, utilidades de prueba) — sin configuración. Las herramientas se exponen a tu asistente con espacios de nombres `playwright__…` y `filesystem__…`.

¿Por qué una puerta de enlace?

Tu asistente ya puede conectarse directamente a muchos servidores MCP, así que una puerta de enlace se gana su lugar haciendo lo que un montón de servidores no puede:

• Un único punto final que añadir a cualquier cliente (Claude Code, Claude Desktop, Cursor, …).

• Curación — habilitar/deshabilitar por servidor y por herramienta. Menos herramientas y mejor nombradas = mejor selección de herramientas por parte del modelo (arrojarle 200 herramientas lo empeora).

• Una única superficie de enrutamiento/registro — cada llamada se registra en stderr con el downstream, la herramienta y la latencia.

• Ciclo de vida limpio — lanza cada downstream como un proceso hijo y los destruye todos al salir (sin procesos de navegador huérfanos).

• Seleccionado para QE — un kit de herramientas SDET con criterio, no un proxy genérico.

Úsalo con tu asistente

Claude Code (`.mcp.json` o configuración de usuario):

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

Claude Desktop (`claude_desktop_config.json`) — misma estructura bajo `mcpServers`.

Esa única entrada le da a tu asistente todas las herramientas de todos los servidores agregados.

Añadir más servidores

Coloca un `qualien-mcp.config.json` en tu directorio de trabajo (o pasa `--config `). Las entradas se fusionan sobre los valores predeterminados integrados — redefine una clave para cambiarla, o pon `enabled: false` para desactivar un valor predeterminado. No se necesita ninguna versión nueva.

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

Consulta `qualien-mcp.config.example.json` para ver la estructura completa (`command`, `args`, `env`, `enabled`, `tools.allow` / `tools.deny`).

Catálogo integrado

qualien-mcp incluye un catálogo seleccionado de servidores conocidos (verificados contra npm), así que puedes habilitar uno por clave solo con tus secretos — sin necesidad de recordar paquetes o comandos:

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

Ejecuta `npx qualien-mcp catalog` para listarlos todos con lo que necesita cada uno. Catálogo actual:

`use` monta un servidor del catálogo bajo una clave diferente (p. ej. dos bases de datos): `{ "db-prod": { "use": "postgres", "enabled": true, "env": {…} } }`. Cualquier cosa que no esté en el catálogo aún la defines completa (`command`/`args` o `type`/`url`).

Servidores remotos y OAuth (p. ej. GitHub)

Los downstreams pueden ser remotos (Streamable HTTP) además de locales. Un servidor remoto es `{ "type": "http", "url": "…" }`, y si necesita OAuth, cada usuario inicia sesión con su propia cuenta — los tokens se almacenan por usuario en `~/.qualien-mcp/credentials.json` (0600) y nunca se empaquetan ni comparten.

El MCP alojado de GitHub es el caso de referencia. No admite registro dinámico de clientes, así que registras tu propia GitHub OAuth App una vez y le das a qualien-mcp su Client ID:

1. GitHub → Settings → Developer settings → OAuth Apps → New. Establece la URL de callback en `http://127.0.0.1:41999/callback\\\\`. Copia el Client ID.

2. En `qualien-mcp.config.json`:

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

3. Autoriza (abre tu navegador, una vez):

   npx qualien-mcp login github

Después, la puerta de enlace se conecta a GitHub de forma no interactiva (refrescando los tokens según sea necesario) y expone las herramientas `github__*`. Si un servidor remoto aún no ha iniciado sesión, la puerta de enlace lo omite con una pista (`run: npx qualien-mcp login github`) y sigue sirviendo todo lo demás — nunca bloquea el inicio. Los servidores que sí admiten registro dinámico no necesitan `clientId`.

Seguro por defecto

qualien-mcp aplica protecciones de forma central, antes de reenviar una llamada — así que se mantienen sin importar lo que permita el downstream, y las herramientas compuestas tampoco pueden saltárselas:

• Las bases de datos son de solo lectura — las llamadas `postgres`/`mysql` que contengan SQL de escritura/DDL (`INSERT/UPDATE/DELETE/DROP/…`) son rechazadas. Actívalo con `{ "postgres": { "readOnly": false } }`.

• Raíces del filesystem — `{ "filesystem": { "roots": ["./src", "./tests"] } }` rechaza cualquier llamada cuyo argumento de ruta escape de esos directorios.

• Herramientas de infraestructura destructivas bloqueadas — las herramientas `docker`/`kubernetes` cuyo nombre parezca destructivo (`delete/remove/prune/kill/…`) son rechazadas a menos que `{ "allowDestructive": true }`.

• Además, curación por servidor con `tools.deny` / `tools.allow`.

Alcance honesto: esto evita que un LLM cause daños accidentalmente. La comprobación de SQL se basa en palabras clave (heurística), no es un parser — no es un sandbox adversarial. El aislamiento real necesita los propios permisos del downstream o un contenedor.

Herramientas QE compuestas

Más allá de la transferencia, qualien-mcp incluye herramientas que implementa él mismo (espacio de nombres `qe__`) que orquestan varios downstreams en una sola llamada — la recompensa de QE de una puerta de enlace.

`qe__verify_api_vs_db` — consistencia API↔DB de extremo a extremo en una llamada. Dale dos subllamadas (herramientas con espacio de nombres que puedes descubrir mediante `tools/list`); ejecuta ambas y compara los 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" } ], … }

Las herramientas compuestas aparecen solo cuando sus downstreams requeridos están conectados (`qe__verify_api_vs_db` necesita un servidor `database`). Pronto habrá más (repro-from-Jira, page-object-from-URL, flaky triage).

Cómo funciona

En un solo proceso, qualien-mcp es a la vez un servidor MCP para tu asistente y un cliente MCP para cada downstream:

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

• `tools/list` se distribuye a cada downstream, filtra según tus reglas de curación y aplica un espacio de nombres a cada uno como `__`.

• `tools/call` enruta por ese prefijo al servidor propietario y pasa la respuesta directamente.

• Los recursos y los prompts se agregan de la misma manera cuando un downstream los proporciona.

• Un downstream que no puede iniciarse se registra y se omite — la puerta de enlace sigue sirviendo al resto.

• Los registros van a stderr (stdout es el protocolo); tu host los muestra en sus registros MCP.

Hoja de ruta

• v0.1 — Playwright + Filesystem, espacios de nombres, curación, registro, ciclo de vida limpio ✅

• Siguiente — expansión impulsada por configuración (GitHub mediante su MCP OAuth alojado, DB, Sequential-Thinking, Memory, Chrome DevTools), herramientas QE compuestas (p. ej. verificar la consistencia API ↔ DB en una llamada), alcance de seguridad.

Licencia

MIT