qualien-mcp

qualien-mcp

Playwright、テストファイル、GitHub、Jira、Postgres などの QA ツールキットを、1 つの接続で AI アシスタントに提供する MCP サーバーです。

qualien-mcp は、SDET / QE 業務向けの複合型 MCP ゲートウェイです。Model Context Protocol サーバーを1 つの接続の背後に集約し、テスト関連のサーバーを厳選した 21 種類のカタログ、ツールごとの許可／拒否設定、デフォルトで読み取り専用のガードレールを提供します。5 つのサーバーを追加する代わりに、Claude Code、Claude Desktop、Cursor、VS Code のいずれかに 1 つのサーバーを追加できます。

npx qualien-mcp

初期状態では、QE スターターペアとして Playwright MCP（ブラウザー自動化、DOM、スクリーンショット）と Filesystem MCP（プロジェクトファイル、ページオブジェクト、テストユーティリティの読み取り／編集）を、設定不要で提供します。ツールは playwright__… および filesystem__… という名前空間でアシスタントに公開されます。

ゲートウェイを使う理由

アシスタントはすでに多くの MCP サーバーに直接接続できます。つまり、ゲートウェイが存在意義を発揮するのは、サーバーを寄せ集めてもできないことを実現するときです。

• 1 つのエンドポイントを、どのクライアントにも追加できます（Claude Code、Claude Desktop、Cursor、…）。
• 厳選 — サーバーごと、およびツールごとに有効／無効を設定できます。ツールの数を絞り、名前をわかりやすくすると、モデルによるツール選択の精度が上がります（200 個ものツールを与えると、かえって悪化します）。
• 一元化されたルーティング／ログ記録 — すべての呼び出しが、接続先、ツール、レイテンシーとともに stderr に記録されます。
• クリーンなライフサイクル — 各接続先を子プロセスとして起動し、終了時にすべて終了させます（ブラウザープロセスが残りません）。
• QE 向けに厳選 — 汎用プロキシではなく、SDET 向けに方針を定めたツールキットです。

アシスタントで使う

Claude Code：

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

または .mcp.json／ユーザー設定に記述します：

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

Claude Desktop（claude_desktop_config.json）および Cursor（~/.cursor/mcp.json または .cursor/mcp.json）：mcpServers の下に同じ形式で記述します。

Claude Desktop 拡張機能：最新リリースから qualien-mcp-<version>.mcpb をダウンロードして開きます。Claude Desktop からプロジェクトフォルダーを指定するよう求められます。Filesystem ツールはそのフォルダー内に制限され、フォルダー内に qualien-mcp.config.json を置くと、ほかのサーバーが有効になります。Smithery にも掲載されています。

VS Code（.vscode/mcp.json）：

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

このエントリー 1 つで、集約されたすべてのサーバーのツールをアシスタントが利用できます。

サーバーを追加する

作業ディレクトリに 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 には、既知のサーバーを厳選したカタログが 21 件含まれており（それぞれ 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 を実行すると、それぞれに必要なものとあわせて一覧表示できます。現在のカタログは次のとおりです。

キー	内容	必要なもの
playwright (デフォルト)	ブラウザーの自動化、DOM、スクリーンショット	—
filesystem (デフォルト)	プロジェクトファイルの読み取り・編集	許可するディレクトリ（デフォルトは cwd）
github	PR、課題、コードレビュー	login github（下記参照）
sequential-thinking	構造化された推論／デバッグ	—
memory	永続的なナレッジグラフ	—
chrome-devtools	ネットワーク、コンソール、パフォーマンス、ストレージ	—
postgres	SQL／バックエンドデータの検証	DATABASE_URI
mysql	SQL／バックエンドデータの検証	MySQL 環境変数
slack	Slack の読み取り／投稿	SLACK_MCP_XOXP_TOKEN
docker	コンテナの管理	Docker デーモン
kubernetes	クラスターの調査／操作	kubeconfig
openapi	仕様から任意の REST API を操作	API_BASE_URL、OPENAPI_SPEC_PATH
jira	Jira の課題の読み取り／更新	Atlassian API トークンの環境変数
figma	Figma デザインの読み取り	FIGMA_API_KEY
confluence	テスト計画、リリースノート、常に更新されるドキュメント	Atlassian API トークンの環境変数
azure-devops	作業項目、リポジトリ、パイプライン、テスト計画	引数として指定する ADO 組織とサインイン
selenium	Selenium WebDriver を介したブラウザー操作	PATH 上のブラウザーとドライバー
webdriverio	ブラウザーとネイティブモバイルの自動化	—（クラウドの認証情報は任意）
browserstack	実ブラウザー／デバイスのクラウド、テスト実行の読み取り	BROWSERSTACK_USERNAME、BROWSERSTACK_ACCESS_KEY
ms-365	Excel、Word、Outlook、Teams、SharePoint	AZURE_CLIENT_ID、AZURE_TENANT_ID
sentry	実際のユーザーに表示されたエラー → 新しいテスト	Sentry 認証トークン

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）にユーザーごとに保存され、qualien-mcp によって同梱、共有、送信されることはありません。

GitHub のホスト型 MCP がその代表例で、1 つのコマンド以外にセットアップは必要ありません。

1. qualien-mcp.config.json で有効にします。

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

2. 1 回だけ認証します。

   npx qualien-mcp login github
   

login を実行すると、短いコードと URL が表示されます。github.com で承認すれば完了です。登録する OAuth App も、どこかに設定するクライアントシークレットもありません。

なぜデバイスフローなのですか？

GitHub では、認証コードを交換する際に client_secret が必要です。PKCE を使ってもこの要件は解消されません。GitHub はパブリッククライアントとコンフィデンシャルクライアントを区別しないためです。qualien-mcp は npm で配布されるため、パッケージ内のシークレットは公開済みのシークレットになってしまいます。デバイスフローは、GitHub がシークレットなしで許可している唯一のグラントであり、CLI に推奨しているグラントでもあります。そのため qualien-mcp が同梱するのはパブリッククライアント IDのみです。これは識別子であって認証情報ではありません。また、すべてのユーザーのトークンは各自のマシン上で発行され、そのマシンに保存されます。

同梱の GitHub OAuth App ではなく、独自の GitHub OAuth App を使うには、clientId を設定します（また、Settings → Developer settings → OAuth Apps でデバイスフローを有効にします）。

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

リモートサーバーにまだログインしていない場合、ゲートウェイはヒントを表示してそのサーバーをスキップします（run: npx qualien-mcp login github）。それ以外のサーバーは引き続き利用でき、起動がブロックされることはありません。動的なクライアント登録に対応しているサーバーでは、clientId は不要です。

デフォルトで安全

qualien-mcp は、呼び出しを転送する前に、中央でガードレールを適用します。そのため、下流側で何が許可されていてもガードレールが機能し、複合ツールから回避されることもありません。

• データベースは読み取り専用です — 書き込みや DDL の SQL（INSERT/UPDATE/DELETE/DROP/…）を含む postgres／mysql の呼び出しは拒否されます。{ "postgres": { "readOnly": false } } で明示的に有効化できます。
• ファイルシステムのルート — { "filesystem": { "roots": ["./src", "./tests"] } } を設定すると、パス引数がこれらのディレクトリの外に出る呼び出しは拒否されます。
• 破壊的なインフラツールをブロック — 名前が破壊的な操作（delete/remove/prune/kill/…）を示す docker／kubernetes のツールは、{ "allowDestructive": true } を設定しない限り拒否されます。
• サーバーごとの tools.deny／tools.allow による選別にも対応しています。

適用範囲について：これらの機能は、LLM が誤って損害を与えるのを防ぎます。SQL チェックはキーワードベースのヒューリスティックであり、パーサーではありません。敵対的な操作に対するサンドボックスではありません。実際の隔離には、下流側の権限設定またはコンテナーが必要です。

複合 QE ツール

単なるパススルーに加えて、qualien-mcp には複数の下流サーバーを1回の呼び出しでオーケストレーションする、独自に実装したツール（名前空間 qe__）が含まれています。ゲートウェイならではの QE の利点です。

qe__verify_api_vs_db — API と DB の整合性を、1回の呼び出しでエンドツーエンドに検証します。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 サーバーが必要です）。今後さらに追加予定です（Jira からの再現、URL からのページオブジェクト生成、不安定なテストのトリアージ）。

仕組み

1つのプロセスで、qualien-mcp はアシスタントに対する MCP サーバーであると同時に、各下流サーバーに対する MCP クライアントでもあります。

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

• tools/list はすべての下流サーバーに要求を送り、選別ルールに基づいてフィルタリングしたうえで、それぞれに <server>__<tool> という名前空間を付けます。
• tools/call はそのプレフィックスに基づいて呼び出しを該当サーバーにルーティングし、応答をそのまま転送します。
• 下流サーバーがリソースやプロンプトを提供している場合は、同様に集約されます。
• 下流サーバーの起動に失敗した場合はログに記録され、スキップされます。ゲートウェイは残りのサーバーを引き続き提供します。
• ログは stderr に出力されます（stdout はプロトコル用です）。ホスト側では MCP ログに表示されます。

ロードマップ

• ✅ Playwright と Filesystem、名前空間、選別、ログ記録、クリーンなライフサイクル
• ✅ 21 サーバーの設定駆動型カタログ、リモート／OAuth サーバー（デバイスフロー経由の GitHub）、デフォルトで安全なガードレール、qe__verify_api_vs_db
• 次の予定：複合 QE ツールの追加（Jira からの再現、URL からのページオブジェクト生成、不安定なテストのトリアージ）

フィードバック

バグを見つけた場合、カタログへのサーバー追加を希望する場合、またはアイデアがある場合は、[email protected] にメールするか、イシューを作成してください。qualien-mcp は qualien.ai の一部です。qualien.ai は、平易な英語の指示からウェブアプリ（Olympus）やネイティブ Android アプリ（Pulse）をテストする AI エージェントも開発しています。

ライセンス

MIT