MCP 통합 가이드

### 목적

ai-rules와 MCP(Model Context Protocol) 도구를 연동하는 3가지 시나리오 구현 가이드. 각 시나리오는 독립적으로 적용 가능.

---

시나리오 1: Linear/Jira MCP → INTENT.md 자동 생성

목적

Linear 또는 Jira 티켓 내용을 가져와 ai-rules 표준 INTENT.md로 자동 변환. "이슈 번호만 말하면 작업 지시서가 생성" 수준의 편의성 제공.

입력 / 출력

복사입력: Linear 티켓 (예: ENG-1234) 또는 Jira 이슈 (예: PROJ-567)
      - 제목, 설명, 담당자, 우선순위, 레이블, 관련 이슈

출력: INTENT.md (ai-rules 표준 포맷)
      - 목표, 범위, 영향 파일, 검증 방법, 비기능 요구사항

INTENT.md 표준 포맷

복사# INTENT — {티켓 제목}

## 목표
{티켓 설명 → 1~3줄 요약}

## 범위
- [ ] {구현 태스크 1}
- [ ] {구현 태스크 2}

## 영향 파일 (예상)
- `src/components/{관련 컴포넌트}.tsx`
- `backend/api/{관련 엔드포인트}.py`

## 검증 방법
- [ ] tsc --noEmit 통과
- [ ] {기능별 수동 테스트 항목}

## 비기능 요구사항
- 우선순위: {Linear 우선순위 → High/Medium/Low}
- 마감: {due date}
- 관련 이슈: {링크}

## context
source: linear://{티켓 ID}
branch: feature/{YYMMDD}-{티켓 슬러그}

구현 방법

A. Claude Code 내 MCP 직접 활용

Claude Code에서 Linear MCP가 활성화된 경우 사용자가 직접 요청:

복사"ENG-1234 티켓으로 INTENT.md 만들어줘"

→ AI 실행 흐름:
1. mcp__linear__get_issue(id: "ENG-1234") 호출
2. 티켓 내용 파싱 (제목, 설명, 레이블, 우선순위)
3. INTENT.md 포맷으로 변환
4. 브랜치명 생성: feature/{YYMMDD}-{slugify(제목)}
5. INTENT.md 작성

B. ai-rules scripts/linear-to-intent.mjs (독립 스크립트)

복사// scripts/linear-to-intent.mjs
// 사용: node scripts/linear-to-intent.mjs ENG-1234

import { LinearClient } from '@linear/sdk'

const client = new LinearClient({ apiKey: process.env.LINEAR_API_KEY })

async function toIntent(issueId) {
  const issue = await client.issue(issueId)

  const today = new Date().toISOString().slice(2, 10).replace(/-/g, '')
  const slug = issue.title.toLowerCase()
    .replace(/[^a-z0-9]+/g, '-')
    .slice(0, 30)
    .replace(/-$/, '')
  const branch = `feature/${today}-${slug}`

  const priority = { 0: 'None', 1: 'Urgent', 2: 'High', 3: 'Medium', 4: 'Low' }

  const content = `# INTENT — ${issue.title}

## 목표
${issue.description || '(티켓 설명 없음 — 직접 작성 필요)'}

## 범위
- [ ] (구현 태스크를 여기에 작성)

## 영향 파일 (예상)
- (영향 파일을 여기에 작성)

## 검증 방법
- [ ] tsc --noEmit 통과
- [ ] (기능별 테스트 항목)

## 비기능 요구사항
- 우선순위: ${priority[issue.priority] || 'Unknown'}
- 상태: ${issue.state?.name || 'Unknown'}
- 담당자: ${issue.assignee?.name || 'Unassigned'}
- 관련 이슈: https://linear.app/issue/${issueId}

## context
source: linear://${issueId}
branch: ${branch}
`

  // INTENT.md 작성 (기존 파일 덮어쓰기 전 사용자 확인 필요)
  console.log('--- INTENT.md 미리보기 ---')
  console.log(content)
  console.log(`브랜치: ${branch}`)
}

toIntent(process.argv[2])

C. ai-rules 연동 방식

profiles/*.yaml에 MCP 설정 추가:

복사# profiles/ax-studio-plan.yaml
integrations:
  linear:
    enabled: true
    team_id: "ENG"
    intent_template: core/templates/intent-from-linear.md
  jira:
    enabled: false

INTENT.md 생성 후 ai-rules 표준 워크플로우 자동 연결:

1. INTENT.md 생성 → feature/{branch} 자동 생성 안내
2. G1 게이트 통과 (사용자 승인)
3. builder 에이전트 소환

---

시나리오 2: Figma MCP → UI 자산 탐색 및 DESIGN_TOKENS.md 생성

목적

Figma 파일에서 디자인 토큰을 추출하여 DESIGN_TOKENS.md를 자동 생성. 08-ui-first.md 규칙("목업 없으면 확인 후 진행")과 연동.

입력 / 출력

복사입력: Figma 파일 URL 또는 파일 ID
      - Colors, Typography, Spacing, Component variants

출력: docs/design/DESIGN_TOKENS.md
      - CSS 변수, Tailwind 클래스 매핑, 컴포넌트 패턴

DESIGN_TOKENS.md 표준 포맷

복사# Design Tokens — {프로젝트명}

> Auto-generated from Figma: {figma_url}
> Last sync: {timestamp}

## 색상 팔레트

| 토큰 | 값 | CSS 변수 | Tailwind |
|------|-----|---------|---------|
| Primary | #2563EB | --color-primary | blue-600 |
| Surface | #F8FAFC | --color-surface | slate-50 |

## 타이포그래피

| 역할 | Font | Size | Weight |
|------|------|------|--------|
| Heading 1 | Inter | 32px | 700 |
| Body | Inter | 16px | 400 |

## 간격 스케일

Figma spacing → Tailwind 클래스 매핑:
- 4px → p-1 / m-1
- 8px → p-2 / m-2
- 16px → p-4 / m-4

## 컴포넌트 패턴

### Button
- Primary: bg-blue-600 text-white px-4 py-2 rounded-lg
- Secondary: border border-gray-300 px-4 py-2 rounded-lg

## 주의사항
- 하드코딩 색상값 직접 사용 금지 (02-code Hard Ban)
- CSS 변수 또는 Tailwind 시맨틱 클래스 사용

구현 방법

A. Figma MCP 직접 활용

Claude Code에 Figma MCP 연결 시:

복사"figma.com/file/XXX에서 디자인 토큰 추출해줘"

→ AI 실행 흐름:
1. mcp__figma__get_file(file_id: "XXX") 호출
2. styles (colors, typography) 추출
3. component variants 파싱
4. Tailwind 클래스 매핑 (추론 기반)
5. DESIGN_TOKENS.md 생성
6. 08-ui-first.md 탐색 절차 완료로 처리

B. scripts/figma-to-tokens.mjs

복사// scripts/figma-to-tokens.mjs
// 사용: FIGMA_TOKEN=xxx node scripts/figma-to-tokens.mjs FILE_ID

const FIGMA_API = 'https://api.figma.com/v1'

async function getStyles(fileId) {
  const res = await fetch(`${FIGMA_API}/files/${fileId}/styles`, {
    headers: { 'X-Figma-Token': process.env.FIGMA_TOKEN }
  })
  return res.json()
}

async function toDesignTokens(fileId) {
  const { meta } = await getStyles(fileId)
  const styles = meta.styles

  const colors = styles
    .filter(s => s.style_type === 'FILL')
    .map(s => ({
      name: s.name,
      // 실제 색상값은 /nodes API 추가 호출 필요
    }))

  // DESIGN_TOKENS.md 생성
  // ... (색상, 타이포그래피, 간격 포맷팅)
}

C. ai-rules 08-ui-first.md 연동

Figma 토큰 추출이 완료되면 08-ui-first.md 요구사항 자동 충족:

복사# INTENT.md context 섹션에 추가
context:
  docs:
    - docs/design/DESIGN_TOKENS.md  # Figma에서 자동 생성됨
  mockups: []                        # Figma가 소스이므로 HTML 목업 불필요

---

시나리오 3: DB MCP → Migration 안전성 검증

목적

DB 스키마 변경 전 07-db.md 규칙을 자동으로 체크. "migration 명령어 실행 전 자동 안전 검증" 단계를 MCP로 구현.

입력 / 출력

복사입력: 예정된 migration SQL 또는 schema 변경 내용
      + 현재 DB 상태 (현재 테이블 목록, 인덱스, 관계)

출력: 안전성 검증 리포트
      - 위험도 등급 (Safe / Warning / Critical)
      - 07-db.md 규칙 위반 여부
      - 사람 승인 필요 여부
      - 권장 백업 명령어

안전성 체크 규칙 매핑 (07-db.md 기반)

감지 패턴	위험도	07-db.md 규칙	조치
DROP TABLE	Critical	2절 금지 명령어	차단 + 보고
DROP COLUMN	Critical	2절	백업 후 승인 필요
ALTER COLUMN ... NOT NULL	Warning	3절 프로세스	기존 데이터 NULL 확인
TRUNCATE	Warning	2절 금지 명령어	차단 + 보고
ADD COLUMN ... DEFAULT NULL	Safe	—	자동 진행 가능
CREATE INDEX	Safe	—	자동 진행 가능
DB 이름 중복 감지	Critical	1절 충돌 방지	즉시 차단

구현 방법

A. Claude Code 내 DB MCP 직접 활용

PostgreSQL MCP (또는 Prisma MCP)가 활성화된 경우:

복사"Page 모델에 layoutSchema Json? 컬럼 추가 migration 검증해줘"

→ AI 실행 흐름:
1. mcp__postgres__query("SELECT tablename FROM pg_tables...") — 현재 스키마 확인
2. 변경 내용 분석: ADD COLUMN layoutSchema JSONB NULL
3. 07-db.md 규칙 체크:
   - DROP/TRUNCATE 없음 ✅
   - Optional 컬럼 추가 → 데이터 영향 없음 ✅
   - 새 컬럼에 FK 없음 → 인덱스 불필요 ✅
4. 안전성 리포트 출력
5. Safe → 07-db.md 표준 보고 형식으로 사용자에게 안내

B. scripts/validate-migration.mjs

복사// scripts/validate-migration.mjs
// 사용: node scripts/validate-migration.mjs migration.sql

import { readFileSync } from 'fs'

const CRITICAL_PATTERNS = [
  /DROP\s+TABLE/i,
  /DROP\s+DATABASE/i,
  /TRUNCATE/i,
  /DELETE\s+FROM\s+\w+\s*;/i,  // WHERE 없는 DELETE
  /DROP\s+COLUMN/i,
]

const WARNING_PATTERNS = [
  /ALTER\s+COLUMN.*NOT\s+NULL/i,
  /ALTER\s+COLUMN.*TYPE/i,
]

const DB_NAME_BLACKLIST = ['postgres', 'test', 'dev', 'app', 'database', 'mydb']

function validateMigration(sqlPath) {
  const sql = readFileSync(sqlPath, 'utf-8')
  const issues = []

  for (const pattern of CRITICAL_PATTERNS) {
    if (pattern.test(sql)) {
      issues.push({ level: 'CRITICAL', message: `금지 패턴 감지: ${pattern}` })
    }
  }

  for (const pattern of WARNING_PATTERNS) {
    if (pattern.test(sql)) {
      issues.push({ level: 'WARNING', message: `데이터 손실 가능: ${pattern}` })
    }
  }

  // DB 이름 블랙리스트 체크
  for (const name of DB_NAME_BLACKLIST) {
    if (new RegExp(`CREATE\\s+DATABASE\\s+${name}\\b`, 'i').test(sql)) {
      issues.push({ level: 'CRITICAL', message: `금지된 DB 이름: ${name}` })
    }
  }

  return {
    safe: issues.filter(i => i.level === 'CRITICAL').length === 0,
    issues,
    requiresApproval: issues.length > 0,
    backupCommand: extractDbName(sql)
      ? `pg_dump -U postgres ${extractDbName(sql)} > backup_$(date +%Y%m%d_%H%M).sql`
      : null,
  }
}

function extractDbName(sql) {
  const match = sql.match(/(?:DATABASE|INTO|FROM)\s+(\w+)/i)
  return match?.[1] || null
}

const result = validateMigration(process.argv[2])
console.log(JSON.stringify(result, null, 2))

if (!result.safe) {
  console.error('CRITICAL 이슈 감지 — 사람 승인 필요')
  process.exit(1)
}

C. ai-rules 연동 방식

복사# profiles/*.yaml
integrations:
  db_validation:
    enabled: true
    script: scripts/validate-migration.mjs
    # migration 파일 생성 시 자동 실행
    auto_run_on: ["**/migrations/*.sql", "**/migrations/*.py"]
    # Critical 감지 시 커밋 차단
    block_commit_on_critical: true

Hook 통합 (09-hooks-guide.md MUST-HOOK 목록에 추가):

복사// .claude/settings.json
{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "node scripts/validate-migration.mjs",
        "condition": "input contains 'prisma migrate' or 'alembic upgrade'"
      }]
    }]
  }
}

안전성 리포트 출력 형식 (07-db.md 보고 포맷 준수)

복사### DB Migration 안전성 검증
- 대상 DB: ax_studio_plan @ localhost:5432
- Migration: 20260401_add_layout_schema_to_page
- 분석 내용: Page 모델에 layoutSchema JSONB NULL 컬럼 추가

### 규칙 체크 결과
- [OK] DROP/TRUNCATE 없음
- [OK] 데이터 손실 위험 없음 (Optional 컬럼 추가)
- [OK] DB 이름 충돌 없음

### 판정: Safe — 자동 진행 가능
실행 명령어:
  cd backend/api && npx prisma migrate deploy

---

공통 ai-rules 연동 원칙

1. MCP는 정보 수집 전용 — 실제 변경(파일 쓰기, DB 수정)은 기존 ai-rules 워크플로우 통해
2. 07-db.md 규칙이 우선 — MCP 도구가 Safe 판정해도 금지 명령어 목록은 절대 실행 불가
3. 사람 승인 게이트 유지 — MCP 자동화로 G1~G4 게이트를 건너뛰지 않음
4. 실패 시 FAILURE_LOG 갱신 — MCP 연동 오류 패턴도 기존 실패 학습 프로토콜 적용