kdymcp — MCP 서버 관리

프로젝트의 MCP 서버 설정을 관리한다. 카탈로그에서 서버를 검색하고 .mcp.json에 추가/제거하며, 설정 검증과 건강 점검을 수행한다.

인수 처리

사용자가 제공한 인수: $ARGUMENTS

인수	설명
(없음) 또는 `list`	현재 프로젝트 `.mcp.json`의 서버 목록 표시
`add <name> [name2...]`	카탈로그에서 서버를 찾아 `.mcp.json`에 추가
`remove <name>`	`.mcp.json`에서 서버 제거 (확인 후)
`validate`	`.mcp.json` 구문 + 환경변수 + 도구 참조 검증
`health`	등록된 MCP 서버 실행 가능 여부 점검
`template [preset]`	프리셋 기반 `.mcp.json` 생성
`catalog [category]`	카탈로그 서버 목록 조회

Phase 0: 컨텍스트 탐지

0-1. 프로젝트 루트 결정

# CWD가 프로젝트 루트
pwd

0-2. .mcp.json 존재 여부

ls -la .mcp.json 2>/dev/null

.mcp.json이 없고 서브커맨드가 list, add, remove, validate, health이면:

AskUserQuestion: ".mcp.json이 없습니다. 빈 템플릿을 생성할까요?"
승인 시 {"mcpServers": {}} 생성

0-3. 카탈로그 경로 설정

GENERAL_PRO 결정 순서:
1. 환경변수 GENERAL_PRO_PATH
2. CWD가 00-general-pro* 내부이면 해당 루트
3. ~/{develop,dev}/00-general-pro-web 존재 탐색
4. 실패 시 AskUserQuestion: "00-general-pro-web 경로를 입력해주세요"

CATALOG="$GENERAL_PRO/02-reusable-code/14-mcp-catalog"
PRESETS="$GENERAL_PRO/01-dev-rules-system/03-dev-templates/mcp/presets"

0-4. 서브커맨드 파싱

$ARGUMENTS에서 첫 단어를 서브커맨드로, 나머지를 인수로 분리. 미지정 시 기본값: list

Phase 1: 서브커맨드별 분기

[list] — 현재 MCP 서버 목록

.mcp.json 파싱 (Read)
mcpServers 각 항목을 테이블로 출력:

서버명	Transport	Command/URL	환경변수

서버가 0개면 "등록된 MCP 서버 없음. /kdymcp add <name> 또는 /kdymcp template으로 추가하세요."

[add <name>] — 서버 추가

카탈로그에서 서버 검색:

# 카탈로그 전체에서 이름 매칭
find "$CATALOG" -name "<name>.md" -not -path "*/_shared/*"

매칭 파일 Read → 설정 스니펫 추출 (```json 블록)
필수 환경변수 확인:
- 메타데이터 테이블에서 필수 환경변수 추출
- "없음"이 아니면 AskUserQuestion: "환경변수 KEY를 설정했는지 확인합니다. 설정되어 있나요?"
- 미설정 시 .env 파일에 추가할 키 안내
.mcp.json에 서버 추가:
- mcpServers 객체에 새 서버 병합
- 이미 존재하면 AskUserQuestion: "이미 등록된 서버입니다. 덮어쓸까요?"
- Edit으로 .mcp.json 수정
복수 서버(add playwright tavily) 시 각각 반복
결과 표시:
- 추가된 서버명, 제공 도구 요약
- 필수 환경변수 체크리스트

[remove <name>] — 서버 제거

.mcp.json에서 서버 존재 확인

프로젝트 내 해당 서버 도구 참조 검색:

# mcp__서버명__ 패턴 검색
Grep: pattern="mcp__<name>__"

참조가 있으면 경고: "이 서버의 도구가 N개 파일에서 참조됩니다. 제거하면 해당 호출이 실패합니다."
AskUserQuestion: "서버 <name>을 제거할까요?"
승인 시 .mcp.json에서 해당 서버 항목 제거

[validate] — 설정 검증

정적 분석만 수행 (서버 실행 없음).

검증 항목:

#	검증	심각도
V1	JSON 구문 유효성	Critical
V2	각 서버에 `type` + (`command` 또는 `url`) 존재	Critical
V3	`${VAR}` 환경변수 → `.env` 또는 시스템에 존재 여부	Important
V4	프로젝트 내 `mcp__서버명__` 패턴 → `.mcp.json` 등록 대조	Important
V5	`.mcp.json` 등록 서버 → 프로젝트 내 사용 여부 (미사용 서버)	Minor

실행:

V1: .mcp.json을 Read하여 JSON 파싱 시도
V2: 각 서버 항목의 필수 필드 확인:
- type === "stdio" → command 필수
- type === "http" → url 필수

V3: env 블록의 ${...} 패턴 추출 → 환경변수 존재 확인

# .env 파일에서 확인
grep "^KEY=" .env 2>/dev/null
# 시스템 환경변수 확인
echo "${KEY:-__NOT_SET__}"

V4: 프로젝트 소스에서 mcp__ 패턴 검색 → 등록 서버명 매칭
```
Grep: pattern="mcp__\w+__" path=프로젝트루트
```
V5: 등록 서버명 목록 vs V4에서 발견된 서버명 목록 비교

보고서 형식:

## MCP 설정 검증 결과

| # | 검증 항목 | 결과 | 상세 |
|---|----------|------|------|
| V1 | JSON 구문 | PASS/FAIL | |
| V2 | 필수 필드 | PASS/FAIL | |
| V3 | 환경변수 | PASS/WARN | 미설정: KEY1, KEY2 |
| V4 | 도구 참조 매칭 | PASS/WARN | 미등록 서버: xxx |
| V5 | 미사용 서버 | PASS/INFO | 미사용: yyy |

[health] — 서버 건강 점검

등록된 서버의 실행 가능 여부를 점검.

.mcp.json의 각 서버에 대해:
- stdio 서버: command 실행 가능 확인
```
which npx 2>/dev/null || where npx 2>/dev/null
```
- http 서버: URL 접근 확인 (HEAD 요청)
```
curl -sI --max-time 5 "<url>" 2>/dev/null | head -1
```
- 환경변수: 필수 환경변수 설정 여부
결과 테이블:

서버	Transport	Command/URL	실행가능	환경변수

[template [preset]] — 프리셋 기반 생성

프리셋 목록 표시:
```
ls "$PRESETS"/*.mcp.json
```
인수로 프리셋 지정 안 된 경우:
- 프로젝트 스택 감지 (package.json, pyproject.toml 등)
- 스택 기반 추천:
  감지 추천 프리셋
  package.json + Playwright 참조 web-crawler
  package.json + next web-fullstack
  pyproject.toml + psycopg/sqlalchemy data-pipeline
  package.json (API만) api-server
  기타 minimal
- AskUserQuestion으로 프리셋 선택 확인
프리셋 파일 Read → .mcp.json에 Write
- 기존 .mcp.json 있으면 AskUserQuestion: "기존 .mcp.json을 덮어쓸까요? 아니면 병합할까요?"
- 병합 선택 시 기존 서버 보존하며 신규만 추가
환경변수 안내 표시

감지	추천 프리셋
package.json + Playwright 참조	`web-crawler`
package.json + next	`web-fullstack`
pyproject.toml + psycopg/sqlalchemy	`data-pipeline`
package.json (API만)	`api-server`
기타	`minimal`

[catalog [category]] — 카탈로그 조회

카테고리 지정 시:

Read: $CATALOG/<category>/  각 .md 파일의 메타데이터 테이블

카테고리 미지정 시:

Read: $CATALOG/README.md → 서버 인덱스 테이블 출력

결과를 요약 테이블로 표시:

카테고리	서버명	패키지	환경변수 필요

Phase 2: 결과 보고

2-1. 실행 결과 요약

서브커맨드별 결과를 표시.

2-2. 변경 파일 목록

파일 변경이 있었으면:

### 변경 파일
- [생성/수정] .mcp.json
- [생성] .env (환경변수 키 추가)

2-3. 후속 권장 작업

상황	권장
add 후	`/kdymcp validate`로 설정 검증
template 후	`/kdymcp validate` + 환경변수 설정
validate 에서 Critical	즉시 수정 필요
validate 에서 Important	`/kdymcp health`로 실행 가능 여부 확인
미사용 서버 발견	`/kdymcp remove <name>` 검토

예외사항

.mcp.json이 프로젝트 루트에 없는 것은 정상 (아직 MCP 미사용)
카탈로그에 없는 서버는 수동으로 .mcp.json에 직접 추가 가능
validate의 Minor 이슈는 무시 가능

도구	역할	관계
`/kdysetting`	프로젝트 셋팅 시 .mcp.json 스캐폴딩	Trigger (kdysetting → kdymcp template)
`/kdygenesis`	프로젝트 생성 시 MCP 자동 설정	Invoke (kdygenesis → kdymcp add)
`/kdyconecttest`	MCP 도구 참조 연결성 검증	Recommend (validate 후 연결 검증)
`/inception`	MCP 서버 의존성 맵핑	Ref (MCP 관계 읽기)
`code-reviewer`	MCP 설정 보안 검토	Recommend (보안 이슈 시)

사용 예시

# 현재 MCP 서버 목록 확인
/kdymcp

# 서버 추가
/kdymcp add playwright
/kdymcp add playwright tavily memory

# 서버 제거
/kdymcp remove tavily

# 설정 검증
/kdymcp validate

# 서버 건강 점검
/kdymcp health

# 프리셋으로 .mcp.json 생성
/kdymcp template web-fullstack
/kdymcp template

# 카탈로그 조회
/kdymcp catalog
/kdymcp catalog browser

주의사항

환경변수 보안: API 키를 .mcp.json에 직접 입력하지 않는다. 반드시 ${VAR} 참조 사용
validate vs health: validate는 정적 분석(JSON 구문, 필드, 환경변수), health는 런타임 점검(실행 가능 여부)
카탈로그 경로: 00 general-pro의 02-reusable-code/14-mcp-catalog/를 참조. 프로젝트 외부 접근 필요

kdymcp