wizard-connector

Claude Code용 플러그형 커넥터 예제입니다. 하나의 로컬 stdio MCP 서버가 Notion 또는 Google Drive를 연동하고, 대화형 **설치 마법사(wizard)**가 인증부터 등록까지 단계별로 안내합니다. npm으로 배포해 npx로 설치/실행하며, macOS / Windows / Linux 를 모두 지원합니다.

노출하는 tool

MCP 서버는 provider-중립적인 tool 3종을 노출합니다. 어떤 서비스를 골라도 동일합니다.

Related MCP server: Claude RAG MCP Pipeline

사용 (git 소스 설치)

레지스트리에 게시하지 않고 git 소스에서 직접 npx로 설치합니다. 클론/빌드 불필요 — prepare 스크립트가 설치 시 자동 빌드합니다.

# 1) 설치 마법사 — provider 선택 → 인증 → 연결 테스트 → 설정 저장
npx -y github:harry-jang/mcp-wizard-sample setup

# 2) Claude Code에 등록 — 스코프는 사용자가 선택
#    팀 공유 없이 나만 쓰려면 (모든 프로젝트에서):
claude mcp add -s user wizard-connector -- npx -y github:harry-jang/mcp-wizard-sample
#    특정 프로젝트에서 팀과 공유하려면 (그 프로젝트의 .mcp.json에 기록):
claude mcp add -s project wizard-connector -- npx -y github:harry-jang/mcp-wizard-sample

npx -y github:harry-jang/mcp-wizard-sample (인자 없음)는 MCP 서버로 동작하고, Claude Code가 이 명령으로 서버를 띄웁니다. setup 인자를 붙이면 마법사가 실행됩니다 (단일 bin이 분기). 버전 고정이 필요하면 github:harry-jang/mcp-wizard-sample#v0.1.0 처럼 태그/커밋을 붙이세요.

참고: 이 repo는 MCP 서버 소스이지 소비 프로젝트가 아니므로 .mcp.json을 커밋하지 않습니다 (.gitignore 처리). MCP 등록 위치(project/user 스코프)는 위처럼 소비자가 직접 선택합니다.

설정/비밀값 저장 위치

비밀값은 패키지 옆이 아니라 사용자 홈 설정 디렉토리에 저장됩니다 (npx 설치 위치와 무관하게 항상 동일).

WIZARD_CONNECTOR_CONFIG(파일) 또는 WIZARD_CONNECTOR_CONFIG_DIR(디렉토리) 환경변수로 위치를 바꿀 수 있습니다. 비밀값이 등록 명령/.mcp.json에 들어가지 않으므로(셸을 거치지 않음) OS와 무관하게 안전합니다.

로컬 개발

npm install
npm run build       # dist/ 생성
npm run setup       # 마법사 (tsx로 소스 직접 실행)
npm run dev         # 서버를 소스에서 실행
npm run inspect     # 빌드 후 MCP Inspector로 점검

게시 전에 npx -y wizard-connector ... 흐름을 그대로 시험하려면 npm link 로 전역 심볼릭 링크를 만든 뒤 wizard-connector setup / claude mcp add -s user wizard-connector -- wizard-connector 를 사용하세요.

npm에 배포하기

# 1) 패키지 이름을 고유하게 (예: 스코프드 이름)
#    package.json의 "name"을 "@your-scope/wizard-connector" 등으로 변경
# 2) 게시 (prepublishOnly가 자동으로 build 실행)
npm publish --access public

files 필드에 dist만 포함되므로 소스(.ts)는 게시되지 않고 컴파일된 JS만 배포됩니다.

아키텍처 ("플러그형")

src/
  cli.ts               # bin 진입점: setup ↔ 서버 분기
  server.ts            # MCP stdio 서버 (runServer)
  config.ts            # 홈 설정 파일 read/write + 검증
  paths.ts             # OS별 설정 경로
  providers/
    types.ts           # Connector 공통 인터페이스
    notion.ts          # Notion 구현
    googledrive.ts     # Google Drive 구현
    registry.ts        # provider 팩토리
  tools/
    register.ts        # search/read/list tool (Connector로 위임)
  wizard/
    wizard.ts          # 설치 마법사 (runWizard)
    google-oauth.ts    # 로컬 loopback OAuth 흐름
    platform.ts        # OS별 브라우저 열기

새 provider 추가: providers/에 Connector 구현 → config.ts·registry.ts에 한 갈래씩 추가 → 마법사에 입력 단계 추가. tool 코드(tools/register.ts)는 그대로입니다.

사전 준비

Notion

1. https://www.notion.so/my-integrations 에서 integration 생성 → Internal Integration Secret 복사

2. 연동할 페이지/DB의 ... → Connections에서 integration 연결 (연결된 것만 검색·조회됨)

Google Drive

1. https://console.cloud.google.com 에서 프로젝트 생성

2. Google Drive API 사용 설정

3. OAuth 클라이언트 ID 생성 — 유형: 데스크톱 앱 (loopback 리다이렉트 자동 허용)

범위

읽기 위주(search/read/list) 예제입니다. 쓰기 기능은 Connector 인터페이스를 확장해 추가할 수 있습니다.