qualien-mcp

複合MCPゲートウェイ — 複数の Model Context Protocol サーバーを1つの接続の背後に集約し、SDET / QE ワークフロー向けに厳選されています。AIアシスタントには5つではなく1つのサーバーを追加するだけです。

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 を使用すると、カタログサーバーを別のキーでマウントできます（例: 2つのデータベース）: { "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 Appを一度登録し、qualien-mcpにClient IDを渡します：

1. GitHub → 設定 → 開発者設定 → OAuth Apps → 新規作成。コールバック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は、1回の呼び出しで複数のダウンストリームを調整する、自ら実装したツール（名前空間 qe__）を同梱しています — ゲートウェイのQE効果です。

qe__verify_api_vs_db — 1回の呼び出しでAPI↔DBの一貫性をエンドツーエンドで検証します。2つのサブ呼び出しを指定します（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、名前空間、キュレーション、ロギング、クリーンなライフサイクル ✅

• 次回 — 設定駆動の拡張（GitHub（ホスト型OAuth MCP経由）、DB、Sequential-Thinking、Memory、Chrome DevTools）、複合QEツール（例: API↔DBの一貫性を1回の呼び出しで検証）、安全スコープ。

ライセンス

MIT