keiailab-plugins-official/keiailab-mcp

이 저장소는 둘을 담는다. 둘은 서로 독립이다.

	무엇	어디	소비 방식
①	Claude Code 플러그인 마켓플레이스	.claude-plugin/marketplace.json · plugins/	클라이언트가 이 저장소를 git URL 로 직접 읽는다
②	FastMCP 서버 keiailab-mcp	app/ (+ 차트 deploy/chart)	https://plugins.keiailab.com/mcp

⚠ ①의 파일을 저장소 루트에서 옮기거나 지우면 안 된다. ~/.claude/plugins/known_marketplaces.json 이 keiailab-plugins-official → https://git.keiailab.com/keiailab-plugins-official/keiailab-mcp.git 를 git source 로 참조한다. 경로가 바뀌면 등록된 모든 머신에서 플러그인이 끊긴다. marketplace.json 의 source 는 ./plugins/... 상대경로라, 주변에 파일을 더하는 것은 안전하다.

⚠ plugins.keiailab.com 은 마켓플레이스를 서빙하지 않는다. 도메인 이름 탓에 헷갈리지만 그 호스트가 여는 경로는 /mcp(+ .well-known) 뿐이고, 마켓플레이스는 클라이언트가 git.keiailab.com 을 직접 clone 해서 읽는다. 그래서 아래 설치 명령이 ①과 ② 두 벌이다. 서버 내부명은 keiailab-mcp 지만 도메인은 plugins.keiailab.com 그대로다.

① 마켓플레이스

플러그인	버전	내용
keiailab-personal	0.1.2	graphify(지식그래프) · natural-writing(글쓰기) · resume-tailoring(이력서)
keiailab-ops	0.1.0	플랫폼 운영 규율 — MCP-first SessionStart 훅(0.2.0~) + /keiailab-connect(MCP 등록 1커맨드)

어느 URL 로 등록하나 — 익명 접근 코드가 고른다

취향이 아니다. 원본은 자격을 요구하고 미러는 안 한다(2026-08-17 실측):

채널	URL	익명	쓰는 곳
원본	git.keiailab.com/keiailab-plugins-official/keiailab-mcp.git	401	사내 — git 자격이 이미 있는 머신
dist 미러	git.keiailab.com/keiailab-plugins-official/dist.git	200	무자격 진입 · CI · 신규 머신

scripts/dist-sync.sh 가 stable push 마다 화이트리스트 서브트리만 dist 로 스냅샷 force-push 한다. 내부 docs/specs/CI 는 안 실린다. 원본 등록자는 dist 를 타지 않는다 — dist 가 멈춰도 기존 머신은 안 끊긴다.

어느 쪽인지 직접 확인:

curl -s -o /dev/null -w '%{http_code}\n' 'https://git.keiailab.com/keiailab-plugins-official/keiailab-mcp.git/info/refs?service=git-upload-pack'
curl -s -o /dev/null -w '%{http_code}\n' 'https://git.keiailab.com/keiailab-plugins-official/dist.git/info/refs?service=git-upload-pack'

2026-08-14 개명으로 구 URL .../keiailab-plugins-official/mcp.git 은 죽었다 — Forgejo 가 Cannot find repository 를 던진다. 리다이렉트가 없으므로 구 URL 로 등록된 머신은 등록만 남고 marketplace update 가 전진하지 못한다. 아래 확인 절이 이 상태를 잡아낸다.

설치

# 1) 마켓플레이스 등록 — 사내(자격 있는 머신)
#    --sparse: 이 레포는 FastMCP 서버까지 담은 모노레포다. 클라이언트에 필요한 건 이 둘뿐
claude plugin marketplace add https://git.keiailab.com/keiailab-plugins-official/keiailab-mcp.git --sparse .claude-plugin plugins

# 1') 자격이 없으면 dist 미러 — 이미 화이트리스트만 담고 있어 --sparse 불요
claude plugin marketplace add https://git.keiailab.com/keiailab-plugins-official/dist.git

# 2) 플러그인 설치 (기본 scope=user — 이 머신 전체)
claude plugin install keiailab-personal@keiailab-plugins-official
claude plugin install keiailab-ops@keiailab-plugins-official        # 플랫폼 운영 규율(MCP-first)

# 이 프로젝트에만 매려면
claude plugin install keiailab-personal@keiailab-plugins-official --scope project

세션 안에서는 슬래시 형태도 같다 — /plugin marketplace add <URL> · /plugin install <name>. 적용은 재시작부터다(claude plugin update --help 가 restart required to apply 라고 말한다).

keiailab-ops 설치 후 MCP 서버 등록(아래 ②)은 /keiailab-connect 커맨드 하나로 된다. 플러그인이 서버를 직접 싣지는 않는다 — 접두가 mcp__plugin_…__* 로 바뀌고 user-scope 등록과 중복 시 169개 도구가 두 벌 로드되기 때문이다(specs/2026-08-20-mcp-first-plugin-design.md §3). claude mcp list 에 bare plugins: 와 plugin:…:plugins 가 동시에 보이면 그 중복 상태다 — claude mcp remove plugins 로 정리한다.

확인

./scripts/check-plugin-install.sh            # ①②  ·  --plugin / --server 로 한쪽만

세 층을 대조하기 때문에 이 스크립트가 따로 있다. Claude Code 는 플러그인을 버전-키 캐시(~/.claude/plugins/cache/<marketplace>/<plugin>/<version>/)에서 실행하고, 그 캐시는 버전 문자열이 바뀔 때만 refresh 된다(사고 #101). 그래서 "설치됐나"와 "최신이 적용됐나"는 다른 질문이고, 한 곳만 봐서는 후자에 답이 안 나온다.

층	어디	전진시키는 명령
원격 SSOT	stable 의 marketplace.json	(푸시)
로컬 캐시	~/.claude/plugins/marketplaces/	claude plugin marketplace update
설치본	installed_plugins.json	claude plugin update

2026-08-17 이 머신 실측 — 셋이 갈라져 있었고, 갈라진 지점이 밀린 명령을 지목한다:

── ① 마켓플레이스 플러그인 keiailab-personal ──
  source : https://git.keiailab.com/keiailab-plugins-official/keiailab-mcp.git
  원격 SSOT (stable) : 0.1.2
  로컬 캐시          : 0.1.0
  설치본             : 0.1.1 enabled
  ✗ 캐시가 원격보다 뒤처졌다 → 두 명령을 순서대로:
     claude plugin marketplace update keiailab-plugins-official
     claude plugin update keiailab-personal@keiailab-plugins-official

낱개로 볼 때:

claude plugin marketplace list                # 등록된 마켓플레이스와 source URL
claude plugin list                            # 설치본 · 활성 여부  (--json 으로 기계 판독)
claude plugin details keiailab-personal       # 스킬 인벤토리와 예상 토큰 비용
claude plugin validate .                      # 이 레포의 매니페스트 자체 검증 (기여 전)

갱신은 캐시 먼저, 설치본 나중이다. 설치본은 캐시가 들고 있는 후보 목록에서 고르므로, 캐시가 0.1.0 이면 plugin update 는 그 이상을 볼 수 없다.

claude plugin marketplace update keiailab-plugins-official
claude plugin update keiailab-personal@keiailab-plugins-official

② FastMCP 서버

케이아이랩 운영 축을 MCP 툴 표면으로 노출한다(Forgejo · Keycloak · OpenBao · Harbor 외). 구조·툴 목록·실측 근거는 app/README.md, 작업 규칙은 CLAUDE.md, 설계는 docs/superpowers/specs/.

연결 · 확인

# 등록 — 대화형(사람). 첫 사용 시 /mcp 에서 authenticate → 브라우저 Keycloak 로그인
claude mcp add --transport http plugins https://plugins.keiailab.com/mcp

# 확인
./scripts/check-plugin-install.sh --server
claude mcp list                               # 등록 여부와 연결 상태

스크립트 없이 손으로 볼 때 — 판정선이 응답 코드다:

curl -s -o /dev/null -w '%{http_code}\n' https://plugins.keiailab.com/mcp
# 401 = 정상(JWT 게이트 활성) · 200 = 인증 꺼짐(사고) · 404 = HTTPRoute 미부착 · 000 = 도달 불가

curl -s https://plugins.keiailab.com/.well-known/oauth-protected-resource/mcp | python3 -m json.tool
# authorization_servers=[https://sso.keiailab.com/realms/keiailab] 가 나와야 로그인 시작점이 잡힌다
# 경로 접미형(RFC 9728)이라 접미 없는 .well-known 은 404 가 정상이다

MCP 로 붙은 세션에서는 health 툴이 백엔드(mongo·qdrant)와 외부 서비스 배선을 함께 답한다. 헤드리스(CI·cron·에이전트)용 client_credentials 경로와 배포 상태 판별은 deploy/README.md.

개발 · 배포

cd app && uv sync && uv run pytest -q     # 테스트는 클러스터 없이 통과해야 한다

배포는 Flux — GitRepository → HelmRelease keiailab-mcp → deploy/chart. 이미지는 harbor.keiailab.com/keiailab-plugins-official/keiailab-mcp, 태그 SSOT 는 app/pyproject.toml 의 version 이다(.forgejo/workflows/build-image.yml).

이력 — 2026-08-14 통합

이 저장소는 원래 구 keiailab MCP 서버(mcp.keiailab.com)와 마켓플레이스를 함께 담고 있었다. 포지가 Forgejo 로 바뀌면서 그 서버를 폐기하고, 별도 저장소(plugins-mcp)에 있던 FastMCP 서버를 여기로 합쳤다.

폐기	사유
구 서버 패키지 src/** · mcp.keiailab.com · 차트 deploy/chart/keiailab-mcp	서버 폐기
plugins/keiailab-platform (2.7.26)	.mcp.json 이 mcp.keiailab.com 을 물고 있어 서버 없이는 3 command + 6 skill 이 죽는다. 반쪽 죽은 플러그인을 배포하지 않는다
tools-registry.json · Makefile · 버전 동기화 3종 스크립트 · 루트 pyproject.toml/uv.lock/Dockerfile	전부 폐기 대상만 참조

MCP 표면은 이제 plugins.keiailab.com 하나다. 구 서버의 이력은 이 저장소 git 에, 구 plugins-mcp 저장소의 이력은 archive/plugins-mcp/* ref 에 남아 있다.

저장소 이름은 2026-08-14 통합 때 mcp → keiailab-mcp 로 바뀌었다. 구 이름은 리다이렉트되지 않는다 — 문서·매니페스트에 남은 구 URL 은 전부 죽은 링크다.