dsh-mcp — MCP 서버 관리 플러그인(DSH용 MCP 서버 매니저)

DSH Web GUI에 MCP(Model Context Protocol) 서버 관리 기능을 제공합니다:

• 서버 목록: 「설정 → MCP」 페이지에서 MCP 서버를 추가 / 편집 / 삭제할 수 있으며, stdio(하위 프로세스), Streamable HTTP 및 SSE(서버 전송 이벤트) 세 가지 전송 방식을 지원하고, JSON 일괄 추가도 가능합니다. 구성은 ~/.dsh/dsh-mcp.json(0600, 원자적 쓰기)에 저장됩니다.

• 활성화 / 비활성화: 각 서버에 전역 스위치가 있습니다. 비활성화하면 연결이 끊기고 해당 도구는 더 이상 등록되지 않습니다.

• 세션별 연결 선택: 세션 바(제목 행)에 「MCP」 선택기가 추가되어, 이번 세션에서 연결할 MCP 서버를 선택할 수 있습니다(기본값은 활성화된 전체, 「연결 안 함」을 명시적으로 선택할 수도 있음). 선택하지 않은 서버는 이번 세션에서 사용되지 않습니다. 「설정 → MCP」 페이지의 「세션 연결」 탭에서도 조정할 수 있으며, 선택 즉시 적용됩니다.

• 도구 등록: 연결된 서버의 도구는 mcp__<서버id>__<도구명> 형식으로 세션 스코프 도구로 등록됩니다 (agent.ctx.tools.register 경유). 선택된 세션에서만 보이며, 호출은 MCP 프로토콜을 통해 전달됩니다.

• 연결 관리: 연결 끊김 시 지수 백오프로 자동 재연결(최대 10회), notifications/tools/list_changed 도구 목록 핫 동기화 지원. GUI에서 원클릭 연결 테스트 제공. 서버의 「도구 수」를 클릭하면 해당 서버가 제공하는 도구를 나열할 수 있습니다.

• OAuth 브라우저 인증: Bearer 인증이 필요한 HTTP/SSE 서버(401 챌린지)의 경우, 「인증」을 클릭하면 인증 패널이 열리고 외부 브라우저에서 로그인을 완료합니다(RFC 9728/8414 디스커버리 + 동적 클라이언트 등록 + PKCE). 토큰은 ~/.dsh/dsh-mcp-oauth/<id>.json(0600)에 영속화된 후 자동으로 첨부되며, 연결 끊김 시 자동 재연결 시 자동으로 갱신됩니다. 콜백 리스너는 고정 포트 3085를 사용합니다(점유 시 랜덤 포트로 폴백하고, 무효화된 등록을 자동으로 제거한 후 재등록). 인증 완료 후 자동 재연결되며, 서버 삭제 시 토큰도 함께 제거됩니다.

• 세션 바 MCP 선택기: 제목 행의 「MCP n」 버튼 드롭다운 패널은 적응형 펼침 방향을 지원합니다 — 세션 이름이 아무리 짧고 창이 아무리 좁아도 패널이 완전히 보이며, 창 가장자리에 잘리지 않습니다.

• Agent 도구: mcp_list는 구성된 서버와 실행 상태를 나열합니다. 시스템 프롬프트가 모델에 이 플러그인을 자동으로 알립니다.

아키텍처

• 호스트 측(Host, src/index.ts): cordis 플러그인 name = 'mcp', /api/dsh-mcp/* 라우트(loopback 펜스), mcp_list 도구, 시스템 프롬프트 문단을 마운트하고, agent/created / agent/disposed를 수신하여 각 세션의 스코프 도구 등록을 유지합니다.

• 엔진(src/engine.ts + src/engine/connection.ts + src/engine/bridge.ts): 서버당 하나의 연결(@modelcontextprotocol/sdk), 연결 공유, 세션별 등록.

• 저장소(src/store.ts): 서버 CRUD + 세션 선택, 순수 파일 I/O, cordis 의존성 없음.

• 클라이언트(src/client/*): 공식 슬롯 마운트 — 「설정」 사이드바의 settings.section(id mcp, 서버 / 세션 두 탭) + 세션 바 conversation.session.header.actions의 MCP 선택기. 색상은 --dsw-alias-* 테마 변수 사용(라이트/다크 테마 자동 대응).

Related MCP server: MCP Proxy Server

설치

# 在 dsh web profile（默认 web）中安装（link 方式，随源码热更新）
dsh plugin --profile web add "link:<本包绝对路径>"

설치 후 dsh를 재시작(dsh --profile web)하면 적용됩니다: 호스트는 노드 측을 로드하고, Web GUI는 브라우저 측 (/plugins/dsh-mcp/client.js)을 로드합니다.

다른 사람에게 설치 위임

dsh-mcp 폴더 전체를 상대방에게 전달하면 됩니다(node_modules 불필요, 단 lib/ 빌드 산출물은 유지해야 합니다 — 호스트 측 lib/index.js와 브라우저 측 lib/client.js를 포함하며, 이것이 dsh가 실제로 로드하는 내용입니다). 상대방의 절차:

# 1. 放到任意位置（如 ~/plugins/dsh-mcp）
# 2. 安装依赖（需 pnpm；lock 文件保证版本一致）
cd dsh-mcp
pnpm install

# 3. 若 lib/ 缺失（例如通过 git 交付且 .gitignore 忽略了它），先构建
pnpm run build

# 4. 可选：验证（34 个测试，含真实 stdio/SSE MCP 服务器与 OAuth 端到端）
pnpm run typecheck && pnpm test

# 5. 安装到 dsh web profile（link 方式，源码改动即热更新）
dsh plugin --profile web add "link:C:/path/to/dsh-mcp"

# 6. 重启 dsh 生效
dsh --profile web

Windows 주의사항:

• pnpm install 시 ERR_PNPM_UNEXPECTED_STORE(pnpm store 경로 충돌)가 발생하면, 프로필의 ~/.dsh/profiles/web/.npmrc에 store-dir=내 pnpm store 경로(예: C:/Users/<사용자>/AppData/Local/pnpm/store/v11)를 작성합니다.

• dsh plugin add 설치가 실패하면 수동 설치 가능: ~/.dsh/profiles/web에서 pnpm add --store-dir <위와 동일한 store 경로> link:C:/path/to/dsh-mcp를 실행하고, dsh-mcp를 해당 프로필의 dsh.profile.bundles 목록에 추가한 후 재시작합니다.

• 실행 환경 요구사항: Node ≥ 22.19(package.json engines).

사용법

1. 「설정」을 열고 사이드바에서 「MCP」를 선택하여 서버 관리 페이지로 이동합니다.

2. 「서버」 탭: 서버 추가(양식 또는 「JSON에서 추가」, stdio는 시작 명령/인자/환경 변수 입력, 또는 Streamable HTTP / SSE는 URL/요청 헤더 입력), 「테스트」 클릭으로 연결 확인. 「도구 수」 클릭으로 도구 나열. 편집 시 양식에 저장된 인자/환경 변수가 자동으로 미리 채워지며, 「JSON 보기」로 전환하여 전체 구성을 확인하고 복사할 수도 있습니다.

3. 세션 바 제목 행에서 「MCP」 선택기를 클릭하고, 이번 세션에서 연결할 서버를 선택(또는 「전체 활성화」/ 「연결 안 함」 클릭)하면 즉시 적용됩니다 — 해당 세션의 모델이 해당 mcp__… 도구를 호출할 수 있습니다. 「설정 → MCP → 세션 연결」 탭에서도 동일하게 조정할 수 있습니다.

4. 서버에 Bearer 인증이 필요한 경우: 서버를 편집하고 HTTP/SSE 양식에서 「OAuth 브라우저 인증 활성화」를 켠 후 저장하고, 목록에서 「인증」을 클릭합니다 — 브라우저에서 인증 페이지가 열리고, 완료 후 자동으로 연결됩니다(토큰은 ~/.dsh/dsh-mcp-oauth/<id>.json에 저장). 「인증 해제」로 다시 인증할 수 있습니다.

5. 세션에서 agent에게 「MCP 서버가 어떤 것들이 있나요?」라고 직접 물어볼 수 있습니다 — mcp_list로 답변합니다.

보안 모델

• 구성(stdio 환경 변수, HTTP 헤더의 Authorization 등)은 본인 기기의 개인 파일 ~/.dsh/dsh-mcp.json에 평문으로 저장됩니다 — dsh-ssh 비밀번호 저장과 동일한 신뢰 모델입니다. 목록 인터페이스는 키 값을 반환하지 않습니다. 「편집 상세」 인터페이스(loopback 한정)만 전체 구성을 반환하여 양식 미리 채움과 「JSON 보기」를 지원하므로, 편집 시 저장된 인자와 환경 변수가 실수로 지워지는 것을 방지합니다.

• stdio 전송은 호스트 프로세스 권한으로 사용자가 구성한 명령을 시작합니다. MCP 도구 출력은 원문 그대로 반환되며, 민감한 정보를 포함할 수 있습니다.

• OAuth 토큰(access/refresh token 및 PKCE verifier)은 ~/.dsh/dsh-mcp-oauth/<serverId>.json(0600)에 평문으로 저장됩니다 — 구성 파일과 동일한 신뢰 모델입니다. 인증 콜백은 127.0.0.1 루프백 포트에서 수신하며, 본인 기기에서만 접근 가능합니다. 콜백 리스너는 고정 포트 3085를 사용합니다(점유 시 랜덤 포트로 폴백). dsh 재시작 후에도 등록된 클라이언트가 일치하여 invalid redirect_uri가 발생하지 않습니다. 포트 변경이 감지되면 이전 등록을 자동으로 제거하고 재등록합니다.

• 모든 /api/dsh-mcp/* 라우트는 loopback으로만 제한됩니다(LAN 노출 방지).

개발

pnpm install
pnpm run typecheck   # tsc --noEmit
pnpm test            # vitest（store / bridge / engine 端到端）
pnpm run build       # tsc 声明 + tsdown（lib/index.js + lib/client.js）

엔진 엔드투엔드 테스트는 실제 stdio MCP 서버 하위 프로세스를 시작하여 연결, 디스커버리, 스코프 등록 및 호출 전달을 검증합니다.

알려진 제한 사항

• taskSupport: required가 필요한 MCP 도구는 지원하지 않습니다(브리지 계층에서 거부하고 오류 보고).

• 이미지류 도구 결과는 텍스트 플레이스홀더로 다운그레이드됩니다(첨부 저장소에 연결하지 않음).

• 서버 이름 변경은 도구 이름에 영향을 주지 않습니다(도구 이름은 id를 네임스페이스로 사용). 서버 삭제 시 연결이 끊기고 모든 세션 선택에서 제거됩니다.

버전 기록

• 0.2.0: OAuth 브라우저 인증 개선 — 인증 패널(외부 브라우저 완료, 자동 감지), 콜백 고정 포트 3085, 포트 변경 시 자동 재등록(invalid redirect_uri 수정), 서버 삭제 시 토큰 동기 제거, 인증 버튼 항상 표시(재인증 가능), 인증 완료 시 자동 재연결(verifier 스냅샷으로 오래된 연결 덮어쓰기 면역, 연결 401 시 더 이상 자동으로 인증 흐름을 시작하여 사용자 흐름을 방해하지 않음), 세션 바 선택기 드롭다운 적응형 잘림 방지, mcp_list 출력과 schema 정렬.

• 0.1.0: 기본 버전 — 서버 목록 추가/삭제/수정/활성화 비활성화/테스트, 세션별 연결 선택, 세션별 스코프 도구 등록, 연결 끊김 재연결, 도구 목록 핫 동기화, SSE 전송 지원, JSON 일괄 추가, 편집 미리 채움/JSON 보기.