qualien-mcp

복합 MCP 게이트웨이 — 여러 Model Context Protocol 서버를 하나의 연결로 통합하며, SDET / QE 워크플로우에 맞게 구성되었습니다. AI 어시스턴트에 다섯 개를 추가하는 대신 서버 하나만 추가하세요.

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

전체 형태는 qualien-mcp.config.example.json을 참조하세요 (command, args, env, enabled, tools.allow / tools.deny).

기본 제공 카탈로그

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는 카탈로그 서버를 다른 키로 마운트합니다 (예: 두 데이터베이스): { "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 → Settings → Developer settings → OAuth Apps → New. 콜백 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"] } }는 경로 인수가 해당 디렉토리를 벗어나는 모든 호출을 거부합니다.

• 파괴적 인프라 도구 차단 — 이름이 파괴적으로 보이는(delete/remove/prune/kill/…) docker/kubernetes 도구는 { "allowDestructive": true }가 없으면 거부됩니다.

• 추가로 서버별 tools.deny / tools.allow 큐레이션.

정직한 범위: 이는 LLM이 우발적으로 손상을 입히는 것을 막습니다. SQL 검사는 파서가 아닌 키워드 기반(휴리스틱)입니다 — 적대적 샌드박싱이 아닙니다. 실제 격리는 다운스트림 자체의 권한이나 컨테이너가 필요합니다.

복합 QE 도구

단순 전달 외에도 qualien-mcp는 하나의 호출에서 여러 다운스트림을 조율하는 자체 구현 도구(네임스페이스 qe__)를 제공합니다 — 게이트웨이의 QE 효과입니다.

qe__verify_api_vs_db — API↔DB 일관성을 한 번의 호출로 종단 간 검증합니다. 두 개의 하위 호출(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에서 페이지 객체, 불안정(flaky) 테스트 분류).

작동 방식

단일 프로세스에서 qualien-mcp는 어시스턴트에게는 MCP 서버이고 각 다운스트림에게는 MCP 클라이언트입니다:

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

• tools/list는 모든 다운스트림으로 전파하고 큐레이션 규칙으로 필터링한 다음 각각을 <server>__<tool>로 네임스페이스합니다.

• tools/call은 해당 접두사로 소유 서버에 라우팅하고 응답을 그대로 전달합니다.

• 리소스와 프롬프트는 다운스트림이 제공할 때 동일한 방식으로 집계됩니다.

• 시작에 실패한 다운스트림은 기록되고 건너뜁니다 — 게이트웨이는 나머지를 계속 제공합니다.

• 로그는 stderr로 이동합니다 (stdout은 프로토콜); 호스트는 이를 MCP 로그에 표시합니다.

로드맵

• v0.1 — Playwright + Filesystem, 네임스페이스, 큐레이션, 로깅, 깔끔한 수명 주기 ✅

• 다음 — 구성 기반 확장(호스팅 OAuth MCP를 통한 GitHub, DB, Sequential-Thinking, Memory, Chrome DevTools), 복합 QE 도구 (예: 한 번의 호출로 API ↔ DB 일관성 검증), 안전 범위.

라이선스

MIT