gdc-claude-plugin

Claude Code(및 Claude Desktop)에서 GDC(gdc-service) 를 쓰기 위한 플러그인이다. MCP 도구 + 슬래시 커맨드 + 진행률 자동 동기화 훅을 한 번에 설치한다. 기본 연결 대상은 운영 서버 `https://gdc.gemiso.com`.

📘 사용 안내서 — https://seonmikii.github.io/gdc-claude-plugin/ 설치부터 일상적인 사용까지 화면과 예시로 안내한다. Claude Code / Claude Desktop 탭 전환, 한국어·English 지원. 처음 쓴다면 여기부터.

구성 요소

• MCP 서버(`gdc-local`, stdio) — 태스크 조회/생성/수정, 태스크 숨기기·삭제·복구, 태스크 댓글, 작업 요청 문서 연동, 진행률 동기화, GitHub PR 연결, 건의사항 제출 등 도구 34종. (Claude Code·Desktop 공통)
• 슬래시 커맨드 13종 — /gdc-login /gdc-switch /gdc-my-tasks /gdc-tasks /gdc-task /gdc-task-new /gdc-task-from-doc /gdc-doc-from-task /gdc-link-task /gdc-apply /gdc-sync /gdc-suggest /gdc-update. (Claude Code 전용)
• PostToolUse 훅 — docs/requests/**/*.md 편집 시 연결된 태스크 진행률 자동 동기화. (Claude Code 전용)

전제조건

• `uv` 설치 (MCP 서버를 uv run으로 기동). https://docs.astral.sh/uv/
• Python 3.13+ (uv가 자동 관리).

Claude Code에서 사용

설치 (각 사용자가 자기 PC에서 1회)

마켓플레이스 추가와 설치는 사용자별 설정(~/.claude)이라, 팀원 모두 각자 한 번씩 실행해야 한다.

# 1) 마켓플레이스 추가 (사용자당 1회)
/plugin marketplace add seonmikii/gdc-claude-plugin
# 2) 플러그인 설치
/plugin install gdc-claude-plugin@gdc-marketplace
# 3) 적용
/reload-plugins        # 또는 Claude Code 재시작

적용 후 /mcp 또는 /plugin에서 gdc-local이 ✓ Connected로 뜨면 정상.

업데이트 (새 버전 반영)

/gdc-update

터미널 CLI·VSCode 확장 모두 동작한다(환경을 감지해 알아서 분기한다). 실행 후 Claude Code를 재시작해야 반영된다.

설치/업데이트가 EBUSY: resource busy or locked 로 막히면, 실행 중인 MCP 서버가 캐시 폴더를 점유한 것이다. 플러그인을 Disable 후 재설치하거나, Claude Code를 완전 재시작한 뒤 다시 실행한다.

인증 (브라우저 핸드오프)

/gdc-login

브라우저 창이 열리면 평소처럼 로그인(Google·로컬 모두 가능)하고 워크스페이스/프로젝트를 선택한 뒤 "연결 허용"을 누른다.

• 인증 토큰은 ~/.gdc-mcp/credentials.json 에 저장된다(사용자 단위 공유, 커밋 금지).
• 선택한 워크스페이스/프로젝트는 현재 레포(폴더)에만 적용된다 → 레포마다 한 번씩 /gdc-login 하면 레포별로 다른 프로젝트를 쓴다.
• 콜백은 127.0.0.1 loopback + 1회용 state로 한정된다.

슬래시 커맨드

Claude Desktop에서 사용

Claude Desktop은 플러그인/마켓플레이스/슬래시 커맨드/훅을 지원하지 않는다. 대신 MCP 서버를 직접 등록하면 아래 도구와 프롬프트(슬래시 커맨드 대응)를 모두 쓸 수 있다.

1. 레포를 로컬에 클론한다.

   git clone https://github.com/seonmikii/gdc-claude-plugin

1. Claude Desktop 설정 파일에 MCP 서버를 추가한다.

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

   {
     "mcpServers": {
       "gdc-local": {
         "command": "uv",
         "args": ["run", "--directory", "<클론 경로>/gdc-claude-plugin", "python", "-m", "gdc_mcp.server"],
         "env": {
           "GDC_BASE_URL": "https://gdc.gemiso.com",
           "GDC_WEB_URL": "https://gdc.gemiso.com"
         }
       }
     }
   }

1. Claude Desktop을 재시작한다. 인증은 대화창에서 `gdc_login` 프롬프트(입력창 "+" 메뉴)를 실행하거나 "gdc 로그인"이라고 요청한다.

Desktop에서는 진행률 자동 동기화 훅과 /gdc-* 슬래시 커맨드는 동작하지 않는다. 동일 기능을 MCP 프롬프트 12종(gdc_login/gdc_switch/gdc_my_tasks/gdc_tasks/gdc_task/gdc_task_new/gdc_task_from_doc/gdc_doc_from_task/gdc_link_task/gdc_apply/gdc_sync/gdc_suggest)으로 "+" 메뉴에서 호출할 수 있고, 진행률 동기화는 sync_doc_progress(또는 gdc_sync 프롬프트)로 수동 실행한다.

>

※ /gdc-update는 플러그인 CLI(마켓플레이스) 관리 커맨드라 대응 MCP 프롬프트가 없다. Desktop은 플러그인 개념이 없어(MCP 서버를 직접 등록) git pull로 최신 코드를 받아 Desktop을 재시작하면 반영된다.

MCP 도구 (Code·Desktop 공통)

자연어로 요청하면 Claude가 아래 도구를 호출한다("내 태스크 보여줘", "김철수 담당 태스크 조회해줘" 등).

본문·댓글 자동 링크(v0.6.x): 평문으로 넘긴 태스크 본문·댓글은 HTML로 변환될 때 ① http(s):// URL과 ② 같은 프로젝트의 태스크 언급 #번호가 자동으로 링크된다(#409 → 해당 태스크 페이지 + 뒤에 (제목) 표시). 현재 프로젝트에 없는 번호·숨김 태스크는 평문 그대로 두고, 색상 코드(#fff)나 URL 프래그먼트는 링크하지 않는다. 이미 HTML로 넘긴 본문은 변환 없이 통과하므로 자동 링크도 적용되지 않는다.

입력 규칙(참고): 담당자/관련자는 user id 또는 멤버 이름(자동 id 해석, 비멤버면 멤버 목록 안내). 날짜는 YYYY-MM-DD이며 예상/실제 시작일 ≤ 종료일, 실제 종료일은 미래 불가(미충족 시 안내·차단). 완료 계열 상태(category=='done')로 태스크를 생성하면 진행률 100%·실제 종료일=오늘이 자동 주입된다.

로컬 개발 override

기본 연결은 운영 서버다. 로컬 gdc-service로 붙이려면 환경변수로 덮어쓴다(.env.example 참고). Code는 플러그인 .mcp.json의 env, Desktop은 위 설정의 env를 바꾸면 된다.

GDC_BASE_URL=http://localhost:8000
GDC_WEB_URL=http://localhost:5173

주의

• 인증은 브라우저 핸드오프 전용이다(username/password 자동 로그인 없음).
• 토큰·시크릿은 저장 파일·메모리로만 다루며 커밋·로그에 노출하지 않는다.
• 기본 연결(운영)은 HTTPS다. dev 서버(http://se.gemiso.com:11521)로 override 시 HTTP(평문) — 토큰 평문 전송 위험은 인지된 상태이며 별도 보완(후속) 대상이다.