qualien-mcp

Ein Composite-MCP-Gateway — es bündelt mehrere Model Context Protocol-Server hinter einer Verbindung, kuratiert für SDET / QE-Workflows. Fügen Sie Ihrem KI-Assistenten einen Server hinzu, statt fünf.

npx qualien-mcp

Von Haus aus liefert es das QE-Starterset — Playwright MCP (Browser-Automatisierung, DOM, Screenshots) und Filesystem MCP (Projektdateien lesen/bearbeiten, Page Objects, Test-Utilities) — ohne Konfiguration. Die Tools werden Ihrem Assistenten mit Namensraum als playwright__… und filesystem__… bereitgestellt.

Warum ein Gateway?

Ihr Assistent kann sich bereits direkt mit vielen MCP-Servern verbinden — ein Gateway verdient seinen Platz also dadurch, dass es etwas tut, was ein Haufen Server nicht kann:

• Ein Endpunkt — zu jedem Client hinzufügbar (Claude Code, Claude Desktop, Cursor, …).

• Kuration — pro Server und pro Tool aktivierbar/deaktivierbar. Weniger, besser benannte Tools = bessere Tool-Auswahl durch das Modell (200 Tools auf einmal zu geben macht es schlechter).

• Eine Routing-/Logging-Oberfläche — jeder Aufruf wird mit Downstream, Tool und Latenz auf stderr protokolliert.

• Sauberer Lebenszyklus — startet jeden Downstream als Kindprozess und beendet sie alle beim Exit (keine verwaisten Browserprozesse).

• Für QE kuratiert — ein meinungsstarkes SDET-Toolkit, kein generischer Proxy.

So verwenden Sie es mit Ihrem Assistenten

Claude Code (.mcp.json oder Benutzereinstellungen):

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

Claude Desktop (claude_desktop_config.json) — gleiche Struktur unter mcpServers.

Dieser einzelne Eintrag gibt Ihrem Assistenten jedes Tool von jedem aggregierten Server.

Weitere Server hinzufügen

Legen Sie eine qualien-mcp.config.json in Ihr Arbeitsverzeichnis (oder übergeben Sie --config <path>). Einträge überlagern die eingebauten Standardwerte — definieren Sie einen Schlüssel neu, um ihn zu ändern, oder setzen Sie enabled: false, um eine Standardeinstellung zu deaktivieren. Kein neues Release nötig.

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

Siehe qualien-mcp.config.example.json für die vollständige Struktur (command, args, env, enabled, tools.allow / tools.deny).

Eingebauter Katalog

qualien-mcp bringt einen kuratierten Katalog bekannter Server mit (gegen npm verifiziert), sodass Sie einen per Schlüssel nur mit Ihren Secrets aktivieren können — ohne sich Pakete oder Befehle merken zu müssen:

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

Führen Sie npx qualien-mcp catalog aus, um alle mit ihren Anforderungen aufzulisten. Aktueller Katalog:

use mountet einen Katalog-Server unter einem anderen Schlüssel (z. B. zwei Datenbanken): { "db-prod": { "use": "postgres", "enabled": true, "env": {…} } }. Alles, was nicht im Katalog ist, definieren Sie weiterhin vollständig (command/args oder type/url).

Remote- und OAuth-Server (z. B. GitHub)

Downstreams können sowohl remote (Streamable HTTP) als auch lokal sein. Ein Remote-Server ist { "type": "http", "url": "…" }, und wenn er OAuth benötigt, meldet sich jeder Benutzer mit seinem eigenen Konto an — Tokens werden pro Benutzer unter ~/.qualien-mcp/credentials.json (0600) gespeichert und niemals gebündelt oder geteilt.

Das gehostete MCP von GitHub ist der Referenzfall. Es unterstützt keine dynamische Client-Registrierung, daher registrieren Sie Ihre eigene GitHub-OAuth-App einmal und geben qualien-mcp deren Client-ID:

1. GitHub → Einstellungen → Entwicklereinstellungen → OAuth-Apps → Neu. Legen Sie die Callback-URL auf http://127.0.0.1:41999/callback fest. Kopieren Sie die Client-ID.

2. In qualien-mcp.config.json:

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

3. Autorisieren (öffnet Ihren Browser, einmalig):

npx qualien-mcp login github

Danach verbindet sich das Gateway nicht-interaktiv mit GitHub (aktualisiert Tokens bei Bedarf) und stellt github__*-Tools bereit. Wenn ein Remote-Server noch nicht angemeldet ist, überspringt ihn das Gateway mit einem Hinweis (run: npx qualien-mcp login github) und bedient weiterhin alles andere — es blockiert nie den Start. Server, die doch dynamische Registrierung unterstützen, benötigen keine clientId.

Standardmäßig sicher

qualien-mcp setzt Schutzmaßnahmen zentral, vor der Weiterleitung eines Aufrufs durch — sie gelten also unabhängig davon, was der Downstream erlaubt, und auch Composite-Tools können sie nicht umgehen:

• Datenbanken sind schreibgeschützt — postgres/mysql-Aufrufe mit Schreib-/DDL-SQL (INSERT/UPDATE/DELETE/DROP/…) werden abgelehnt. Opt-in mit { "postgres": { "readOnly": false } }.

• Dateisystem-Wurzeln — { "filesystem": { "roots": ["./src", "./tests"] } } lehnt jeden Aufruf ab, dessen Pfadargument diese Verzeichnisse verlässt.

• Destruktive Infrastruktur-Tools blockiert — docker/kubernetes-Tools, deren Name destruktiv klingt (delete/remove/prune/kill/…), werden abgelehnt, außer { "allowDestructive": true }.

• Plus Pro-Server-Kuration über tools.deny / tools.allow.

Ehrlicher Umfang: Diese stoppen ein LLM davor, versehentlich Schaden anzurichten. Die SQL-Prüfung ist schlüsselwortbasiert (heuristisch), kein Parser — sie ist kein adversarielles Sandboxing. Echte Isolation erfordert die eigenen Berechtigungen des Downstreams oder einen Container.

Composite-QE-Tools

Über Passthrough hinaus bringt qualien-mcp Tools mit, die es selbst implementiert (Namespace qe__) und die mehrere Downstreams in einem Aufruf orchestrieren — der QE-Nutzen eines Gateways.

qe__verify_api_vs_db — End-to-End-API↔DB-Konsistenz in einem Aufruf. Geben Sie ihm zwei Unteraufrufe (Namespaced-Tools, die Sie über tools/list entdecken können); er führt beide aus und vergleicht die Payloads per Diff:

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

Composite-Tools erscheinen nur, wenn ihre erforderlichen Downstreams verbunden sind (qe__verify_api_vs_db benötigt einen database-Server). Weitere folgen (repro-from-Jira, page-object-from-URL, flaky triage).

So funktioniert es

In einem Prozess ist qualien-mcp gleichzeitig ein MCP-Server für Ihren Assistenten und ein MCP-Client für jeden Downstream:

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

• tools/list fächert zu jedem Downstream auf, filtert nach Ihren Kurationsregeln und vergibt Namensräume als <server>__<tool>.

• tools/call routet über dieses Präfix zum besitzenden Server und reicht die Antwort direkt durch.

• Ressourcen und Prompts werden auf dieselbe Weise aggregiert, wenn ein Downstream sie bereitstellt.

• Ein Downstream, der nicht startet, wird protokolliert und übersprungen — das Gateway bedient weiterhin den Rest.

• Protokolle gehen an stderr (stdout ist das Protokoll); Ihr Host zeigt sie in seinen MCP-Protokollen an.

Roadmap

• v0.1 — Playwright + Filesystem, Namespacing, Kuration, Logging, sauberer Lebenszyklus ✅

• Als Nächstes — konfigurationsgetriebene Erweiterung (GitHub über sein gehostetes OAuth-MCP, DB, Sequential-Thinking, Memory, Chrome DevTools), Composite-QE-Tools (z. B. API ↔ DB-Konsistenz in einem Aufruf prü