feat: Admin MCP 게이트웨이(mcp) 추가

[Whale0928]

Summary

• workspace 루트에 격리형 Admin MCP 게이트웨이 mcp/ 추가
• 구조: 클라이언트 → MCP(Streamable HTTP) → 기존 admin-api (전용 /mcp/* 백엔드 API 없음)
• 패키지명 mcp (bottlenote- 접두사 없음)
• 백엔드 전용 MCP API PR(bottle-note-api-server#699)은 폐기·클로즈. MCP가 기존 Admin 계약을 호출

Admin / Agent client (Claude, Codex, Cursor)
        |  Streamable HTTP  /mcp
        |  Authorization: Bearer bn_agent_*
        v
 mcp/  (이 PR)
        |  allowlist only
        |  Agent Key → 내부 Admin JWT (클라이언트 미노출)
        v
 bottlenote-admin-api
   POST /admin/api/v1/auth/agent
   GET  /admin/api/v1/alcohols
   GET  /admin/api/v1/alcohols/{id}

Changes

• mcp/: Node 22 + TypeScript MCP 서버 스캐폴드
• 툴 v0.1: bottlenote_whisky_search, bottlenote_whisky_get (기존 /alcohols 매핑)
• multi-arch Dockerfile (linux/amd64, linux/arm64)
• root/mcp .gitignore 강화 (node_modules, .env, sops, kubeconfig, credentials 제외)
• private environment-variables 서브모듈은 포함하지 않음
• 페르소나 교차 규범: mcp/docs/PRINCIPLES.md
• 보안 보강: JWT 형태 Bearer 거부, prod에서 default Agent Key 금지, 툴 isError, description truncate, correlation 전파, graceful shutdown, server instructions

Authentication (현재 v0.1)

항목	내용
방식	원격 MCP + Agent Key Bearer (OAuth 2.1 전 단계)
클라이언트 제시	Authorization: Bearer bn_agent_* 만
서버 내부	POST /auth/agent 로 Admin JWT 교환 후 API 호출
금지	Admin/User JWT 클라이언트 전달(token passthrough), 키/JWT 로그·툴 결과 노출
기획자 온보딩	키 1개 + MCP URL + 클라이언트 설정 방법 (Admin 계정/JWT 불필요)

클라이언트 설정 예

{
  "mcpServers": {
    "bottlenote-admin": {
      "url": "https://mcp.bottlenote.com/mcp",
      "headers": {
        "Authorization": "Bearer bn_agent_REPLACE"
      }
    }
  }
}

이후 후보 (미구현)

• OAuth 2.1 Resource Server + Protected Resource Metadata (스펙 정석 원격 인증)
• 토큰 검증·scope는 MCP 서버, 발급은 별도 AS/IdP

백엔드 방화벽 / 개발 서버 방향 (합의 메모)

완전 잠금은 네트워크 격리 + 호출자 신원이 CORS보다 우선이다.

환경	권장
dev (공유 개발)	Admin API 공개 유지. FE는 포트포워드/k9s 없이 dev URL 직접 호출. MCP dev도 동일 Admin dev base URL
local	FE → dev API 또는 로컬 API. k9s 강요하지 않음
prod (목표)	Admin API 외부 최소화(ClusterIP/내부 DNS). 공개는 FE(BFF)·MCP. 내부 토큰/mTLS/NetworkPolicy 이중화

• FE가 pure SPA + 브라우저 직접 Admin 호출이면 prod에서 API를 완전 숨기기 어렵다 → 잠글 때는 BFF/SSR 또는 VPN/Zero Trust 필요
• 앱 레벨 INTERNAL_TOKEN 강제는 prod(또는 staging) 플래그로만 켜고, dev에서는 끄는 것을 권장

Security / gitignore

• 실키·JWT·node_modules·dist·sops·kubeconfig 미포함 확인 후 푸시
• .env.example 만 포함 (placeholder). BOTTLENOTE_AGENT_KEY 는 local smoke 전용, production 기동 시 설정 시 실패
• 아웃바운드 allowlist: POST /auth/agent, GET /alcohols, GET /alcohols/{id} (src/policy/allowlist.ts)
• NEVER: 삭제/bulk/무페이징 list, free-form HTTP 프록시, 외부 웹검색 툴

Related

• [Admin/MCP] Bottle Note Admin MCP 구축 #370
• [BE/Security] 에이전트 API Key 기반 기존 User/Admin 토큰 교환 #340 Agent Key 토큰 교환 (인증 기반)
• [BE/Data] 전 테이블 감사 정보를 actor ID·type·email snapshot 기반으로 표준화 #341 감사 actor 모델 (후속)
• backend 전용 MCP API 시도는 폐기: docs: Admin MCP(#370) 구현 조사 및 1차 결정 브리프 bottle-note-api-server#699 (closed)

Test plan

• PR 파일 목록에 node_modules / .env / sops / 실제 키 없음
• cd mcp && npm install && npm run typecheck
• (optional) admin-api 연동 후 whisky search/get 스모크
• JWT 형태 Bearer → 401, 누락 키 → 401
• NODE_ENV=production + BOTTLENOTE_AGENT_KEY 설정 시 기동 실패