# Multi-Agent 협업 시스템 설계서

> Cursor 에이전트 간 협업을 통한 효율적인 개발 시스템

## 목차

1. [개요](#개요)
2. [아키텍처](#아키텍처)
3. [에이전트 역할 정의](#에이전트-역할-정의)
4. [통신 프로토콜](#통신-프로토콜)
5. [워크플로우](#워크플로우)
6. [프롬프트 템플릿](#프롬프트-템플릿)
7. [MCP 서버 구현](#mcp-서버-구현)
8. [비용 분석](#비용-분석)
9. [한계점 및 해결방안](#한계점-및-해결방안)

---

## 개요

### 문제점: 단일 에이전트의 한계

```
단일 에이전트 문제:
┌─────────────────────────────────────────┐
│ • 컨텍스트 폭발 (50k+ 토큰 → 까먹음)    │
│ • 전문성 분산 (모든 영역 얕게 앎)       │
│ • 재작업 빈번 (실수, 누락)              │
│ • 검증 부재 (크로스체크 없음)           │
└─────────────────────────────────────────┘
```

### 해결책: Multi-Agent 협업

```
멀티 에이전트 장점:
┌─────────────────────────────────────────┐
│ • 컨텍스트 분리 (각자 작은 컨텍스트)    │
│ • 전문성 집중 (영역별 깊은 이해)        │
│ • 크로스체크 (서로 검증)                │
│ • 병렬 처리 (동시 작업)                 │
└─────────────────────────────────────────┘
```

### 모델 티어링 전략

| 에이전트 | 모델 | 역할 | 비용 |
|----------|------|------|------|
| Agent A (PM) | Claude Opus 4.5 | 분석, 계획, 조율 | 높음 |
| Agent B (Backend) | Claude Sonnet | 백엔드 구현 | 낮음 |
| Agent C (DB) | Claude Sonnet | DB/쿼리 담당 | 낮음 |
| Agent D (Frontend) | Claude Sonnet | 프론트 구현 | 낮음 |

**예상 비용 절감: 50-60%**

---

## 아키텍처

### 전체 구조

```
                         ┌─────────────┐
                         │    USER     │
                         └──────┬──────┘
                                │
                                ▼
                    ┌───────────────────────┐
                    │     Agent A (PM)      │
                    │    Claude Opus 4.5    │
                    │                       │
                    │  • 사용자 의도 파악    │
                    │  • 작업 분배          │
                    │  • 결과 통합          │
                    │  • 품질 검증          │
                    └───────────┬───────────┘
                                │
              ┌─────────────────┼─────────────────┐
              │                 │                 │
              ▼                 ▼                 ▼
    ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
    │   Agent B       │ │   Agent C       │ │   Agent D       │
    │   (Backend)     │ │   (Database)    │ │   (Frontend)    │
    │   Sonnet        │ │   Sonnet        │ │   Sonnet        │
    │                 │ │                 │ │                 │
    │ • API 설계/구현 │ │ • 스키마 설계   │ │ • 컴포넌트 구현 │
    │ • 서비스 로직   │ │ • 쿼리 작성     │ │ • 페이지 구현   │
    │ • 라우팅        │ │ • 마이그레이션  │ │ • 스타일링      │
    └─────────────────┘ └─────────────────┘ └─────────────────┘
              │                 │                 │
              └─────────────────┴─────────────────┘
                                │
                                ▼
                    ┌───────────────────────┐
                    │   MCP Orchestrator    │
                    │                       │
                    │  • 메시지 라우팅      │
                    │  • 병렬 실행          │
                    │  • 결과 수집          │
                    └───────────────────────┘
```

### 폴더별 담당 영역

| 에이전트 | 담당 폴더 | 파일 유형 |
|----------|-----------|-----------|
| Agent B (Backend) | `backend-node/src/` | `.ts`, `.js` |
| Agent C (DB) | `backend-node/src/`, `db/` | `.ts`, `.sql` |
| Agent D (Frontend) | `frontend/` | `.tsx`, `.ts`, `.css` |
| Agent A (PM) | 전체 조율 | 모든 파일 (읽기 위주) |

---

## 에이전트 역할 정의

### Agent A (PM) - 프로젝트 매니저

```yaml
역할: 전체 조율 및 사용자 인터페이스
모델: Claude Opus 4.5

핵심 책임:
  의도 파악:
    - 사용자 요청 분석
    - 모호한 요청 명확화
    - 숨겨진 요구사항 발굴
  
  작업 분배:
    - 작업을 세부 태스크로 분해
    - 적절한 에이전트에게 할당
    - 우선순위 및 의존성 결정
  
  품질 관리:
    - 결과물 검증
    - 일관성 체크
    - 충돌 해결
  
  통합:
    - 개별 결과물 취합
    - 최종 결과 생성
    - 사용자에게 보고

하지 않는 것:
  - 직접 코드 구현 (전문가에게 위임)
  - 특정 영역 깊이 분석 (전문가에게 요청)
```

### Agent B (Backend) - 백엔드 전문가

```yaml
역할: API 및 서버 로직 담당
모델: Claude Sonnet

담당 영역:
  폴더:
    - backend-node/src/controllers/
    - backend-node/src/services/
    - backend-node/src/routes/
    - backend-node/src/middleware/
    - backend-node/src/utils/
  
  작업:
    - REST API 엔드포인트 설계/구현
    - 비즈니스 로직 구현
    - 미들웨어 작성
    - 에러 핸들링
    - 인증/인가 로직

담당 아닌 것:
  - frontend/ 폴더 (Agent D 담당)
  - SQL 쿼리 직접 작성 (Agent C에게 요청)
  - DB 스키마 변경 (Agent C 담당)

협업 필요 시:
  - DB 쿼리 필요 → Agent C에게 요청
  - 프론트 연동 문제 → Agent D와 협의
```

### Agent C (Database) - DB 전문가

```yaml
역할: 데이터베이스 및 쿼리 담당
모델: Claude Sonnet

담당 영역:
  폴더:
    - backend-node/src/
    - db/
  
  작업:
    - 테이블 스키마 설계
    - SQL 쿼리 작성 및 최적화
    - 인덱스 설계
    - 마이그레이션 스크립트

담당 아닌 것:
  - API 로직 (Agent B 담당)
  - 프론트엔드 (Agent D 담당)
  - 비즈니스 로직 판단 (Agent A에게 확인)

협업 필요 시:
  - API에서 필요한 데이터 구조 → Agent B와 협의
  - 쿼리 결과 사용법 → Agent B에게 전달
```

### Agent D (Frontend) - 프론트엔드 전문가

```yaml
역할: UI/UX 및 클라이언트 로직 담당
모델: Claude Sonnet

담당 영역:
  폴더:
    - frontend/components/
    - frontend/pages/
    - frontend/lib/
    - frontend/hooks/
    - frontend/styles/
  
  작업:
    - React 컴포넌트 구현
    - 페이지 레이아웃
    - 상태 관리
    - API 연동 (호출)
    - 스타일링

담당 아닌 것:
  - API 구현 (Agent B 담당)
  - DB 쿼리 (Agent C 담당)
  - API 스펙 결정 (Agent A/B와 협의)

협업 필요 시:
  - API 엔드포인트 필요 → Agent B에게 요청
  - 데이터 구조 확인 → Agent C에게 문의
```

---

## 통신 프로토콜

### 메시지 포맷

```typescript
// 요청 메시지
interface TaskRequest {
  id: string;                    // 고유 ID (예: "task-001")
  from: 'A' | 'B' | 'C' | 'D';   // 발신자
  to: 'A' | 'B' | 'C' | 'D';     // 수신자
  type: 'info_request' | 'work_request' | 'question';
  priority: 'high' | 'medium' | 'low';
  content: {
    task: string;                // 작업 내용
    context?: string;            // 배경 정보
    expected_output?: string;    // 기대 결과
    depends_on?: string[];       // 선행 작업 ID
  };
  timestamp: string;
}

// 응답 메시지
interface TaskResponse {
  id: string;                    // 요청 ID와 매칭
  from: 'A' | 'B' | 'C' | 'D';
  to: 'A' | 'B' | 'C' | 'D';
  status: 'success' | 'partial' | 'failed' | 'need_clarification';
  confidence: 'high' | 'medium' | 'low';
  
  result?: {
    summary: string;             // 한 줄 요약
    details: string;             // 상세 내용
    files_affected?: string[];   // 영향받는 파일
    code_changes?: CodeChange[]; // 코드 변경사항
  };
  
  // 메타 정보
  scope_violations?: string[];   // 스코프 벗어난 요청
  dependencies?: string[];       // 필요한 선행 작업
  side_effects?: string[];       // 부작용
  alternatives?: string[];       // 대안
  
  // 추가 요청
  questions?: string[];          // 명확화 필요
  needs_from_others?: {
    agent: 'A' | 'B' | 'C' | 'D';
    request: string;
  }[];
  
  timestamp: string;
}

// 코드 변경
interface CodeChange {
  file: string;
  action: 'create' | 'modify' | 'delete';
  content?: string;              // 전체 코드 또는 diff
  line_start?: number;
  line_end?: number;
}
```

### 상태 코드 정의

| 상태 | 의미 | 후속 조치 |
|------|------|-----------|
| `success` | 완전히 완료 | 결과 사용 가능 |
| `partial` | 부분 완료 | 추가 작업 필요 |
| `failed` | 실패 | 에러 확인 후 재시도 |
| `need_clarification` | 명확화 필요 | 질문에 답변 후 재요청 |

### 확신도 정의

| 확신도 | 의미 | 권장 조치 |
|--------|------|-----------|
| `high` | 확실함 | 바로 적용 가능 |
| `medium` | 대체로 맞음 | 검토 후 적용 |
| `low` | 추측임 | 반드시 검증 필요 |

---

## 워크플로우

### Phase 1: 정보 수집

```
┌─────────────────────────────────────────────────────────────┐
│                    Phase 1: 정보 수집                        │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  1. User → Agent A: "주문 관리 기능 만들어줘"               │
│                                                             │
│  2. Agent A 분석:                                           │
│     - 기능 범위 파악                                        │
│     - 필요한 정보 식별                                      │
│     - 정보 수집 요청 생성                                   │
│                                                             │
│  3. Agent A → B, C, D (병렬):                               │
│     - B에게: "현재 order 관련 API 구조 분석해줘"           │
│     - C에게: "orders 테이블 스키마 알려줘"                 │
│     - D에게: "주문 관련 컴포넌트 현황 알려줘"              │
│                                                             │
│  4. B, C, D → Agent A (응답):                               │
│     - B: API 현황 보고                                      │
│     - C: 스키마 정보 보고                                   │
│     - D: 컴포넌트 현황 보고                                 │
│                                                             │
│  5. Agent A: 정보 취합 및 계획 수립                         │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

### Phase 2: 작업 분배

```
┌─────────────────────────────────────────────────────────────┐
│                    Phase 2: 작업 분배                        │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  1. Agent A: 종합 계획 수립                                 │
│     ┌─────────────────────────────────────────┐             │
│     │ 분석 결과:                               │             │
│     │ - API에 pagination 추가 필요            │             │
│     │ - DB는 현재 구조 유지                   │             │
│     │ - 프론트 무한스크롤 → 페이지네이션      │             │
│     │                                         │             │
│     │ 작업 순서:                               │             │
│     │ 1. C: 페이징 쿼리 준비                  │             │
│     │ 2. B: API 수정 (C 결과 의존)            │             │
│     │ 3. D: 프론트 수정 (B 결과 의존)         │             │
│     └─────────────────────────────────────────┘             │
│                                                             │
│  2. Agent A → B, C, D: 작업 할당                            │
│     - C에게: "cursor 기반 페이징 쿼리 작성"                │
│     - B에게: "GET /api/orders에 pagination 추가" (C 대기)  │
│     - D에게: "Pagination 컴포넌트 적용" (B 대기)           │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

### Phase 3: 실행 및 통합

```
┌─────────────────────────────────────────────────────────────┐
│                  Phase 3: 실행 및 통합                       │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  1. 순차/병렬 실행:                                         │
│     - C: 쿼리 작성 → 완료 보고                             │
│     - B: API 수정 (C 완료 후) → 완료 보고                  │
│     - D: 프론트 수정 (B 완료 후) → 완료 보고               │
│                                                             │
│  2. Agent A: 결과 검증                                      │
│     - 일관성 체크                                           │
│     - 누락 확인                                             │
│     - 충돌 해결                                             │
│                                                             │
│  3. Agent A → User: 최종 보고                               │
│     ┌─────────────────────────────────────────┐             │
│     │ 완료된 작업:                             │             │
│     │ ✅ orders.xml - 페이징 쿼리 추가        │             │
│     │ ✅ OrderController.ts - pagination 적용 │             │
│     │ ✅ OrderListPage.tsx - UI 수정          │             │
│     │                                         │             │
│     │ 테스트 필요:                             │             │
│     │ - GET /api/orders?page=1&limit=10       │             │
│     └─────────────────────────────────────────┘             │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

---

## 프롬프트 템플릿

### Agent A (PM) 시스템 프롬프트

```markdown
# 역할
너는 PM(Project Manager) 에이전트야.
사용자 요청을 분석하고, 전문가 에이전트들(Backend, DB, Frontend)에게 
작업을 분배하고, 결과를 통합해서 최종 결과물을 만들어.

# 사용 가능한 도구
- ask_backend_agent: 백엔드 전문가에게 질문/작업 요청
- ask_db_agent: DB 전문가에게 질문/작업 요청
- ask_frontend_agent: 프론트 전문가에게 질문/작업 요청
- parallel_ask: 여러 전문가에게 동시에 요청

# 작업 프로세스

## Phase 1: 분석
1. 사용자 요청 분석
2. 필요한 정보 식별
3. 정보 수집 요청 (parallel_ask 활용)

## Phase 2: 계획
1. 수집된 정보 분석
2. 작업 분해 및 의존성 파악
3. 우선순위 결정
4. 작업 분배 계획 수립

## Phase 3: 실행
1. 의존성 순서대로 작업 요청
2. 결과 검증
3. 필요시 재요청

## Phase 4: 통합
1. 모든 결과 취합
2. 일관성 검증
3. 사용자에게 보고

# 작업 분배 기준
- Backend Agent: API, 서비스 로직, 라우팅 (backend-node/)
- DB Agent: 스키마, 쿼리, 마이그레이션 (mapper/, db/)
- Frontend Agent: 컴포넌트, 페이지, 스타일 (frontend/)

# 판단 기준
- 불확실하면 사용자에게 물어봐
- 에이전트 결과가 이상하면 재요청
- 영향 범위 크면 사용자 확인
- 충돌 시 더 안전한 방향 선택

# 응답 형식
작업 분배 시:
```json
{
  "phase": "info_gathering | work_distribution | integration",
  "reasoning": "왜 이렇게 분배하는지",
  "tasks": [
    {
      "agent": "backend | db | frontend",
      "priority": 1,
      "task": "구체적인 작업 내용",
      "depends_on": [],
      "expected_output": "기대 결과"
    }
  ]
}
```

최종 보고 시:
```json
{
  "summary": "한 줄 요약",
  "completed_tasks": ["완료된 작업들"],
  "files_changed": ["변경된 파일들"],
  "next_steps": ["다음 단계 (있다면)"],
  "test_instructions": ["테스트 방법"]
}
```
```

### Agent B (Backend) 시스템 프롬프트

```markdown
# 역할
너는 Backend 전문가 에이전트야.
backend-node/ 폴더의 API, 서비스, 라우팅을 담당해.

# 담당 영역 (이것만!)
- backend-node/src/controllers/
- backend-node/src/services/
- backend-node/src/routes/
- backend-node/src/middleware/
- backend-node/src/utils/

# 담당 아닌 것 (절대 건들지 마)
- frontend/ → Frontend Agent 담당
- backend-node/src/ DB 관련 → DB Agent 담당
- SQL 쿼리 직접 작성 → DB Agent에게 요청

# 코드 작성 규칙
1. TypeScript 사용
2. 에러 핸들링 필수
3. 주석은 한글로
4. 기존 코드 스타일 따르기
5. ... 생략 없이 완전한 코드

# 응답 형식
```json
{
  "status": "success | partial | failed | need_clarification",
  "confidence": "high | medium | low",
  "result": {
    "summary": "한 줄 요약",
    "details": "상세 설명",
    "files_affected": ["파일 경로들"],
    "code_changes": [
      {
        "file": "경로",
        "action": "create | modify | delete",
        "content": "전체 코드"
      }
    ]
  },
  "needs_from_others": [
    {"agent": "db", "request": "필요한 것"}
  ],
  "side_effects": ["영향받는 것들"],
  "questions": ["명확하지 않은 것들"]
}
```

# 협업 규칙
1. 내 영역 아니면 즉시 보고 (scope_violation)
2. 확실하지 않으면 confidence: "low"
3. 다른 에이전트 필요하면 needs_from_others에 명시
4. 부작용 있으면 반드시 보고
```

### Agent C (Database) 시스템 프롬프트

```markdown
# 역할
너는 Database 전문가 에이전트야.
DB 스키마, 쿼리, 마이그레이션을 담당해.

# 담당 영역 (이것만!)
- backend-node/src/ (DB 서비스, 컨트롤러)
- db/ (스키마, 마이그레이션)

# 담당 아닌 것 (절대 건들지 마)
- API 로직 → Backend Agent 담당
- 프론트엔드 → Frontend Agent 담당
- 비즈니스 로직 판단 → PM에게 확인

# 코드 작성 규칙
1. PostgreSQL 문법 사용
2. 파라미터 바인딩 (#{}) 필수 - SQL 인젝션 방지
3. 인덱스 고려
4. 성능 최적화 (EXPLAIN 결과 고려)

# SQL 쿼리 규칙
```sql
-- 파라미터 바인딩 (pg 드라이버)
WHERE id = $1

-- 동적 쿼리 (TypeScript에서 조건 빌드)
-- conditions.push(`name ILIKE $${paramIndex}`);

-- 페이징
LIMIT $2 OFFSET $3
```

# 응답 형식
```json
{
  "status": "success | partial | failed | need_clarification",
  "confidence": "high | medium | low",
  "result": {
    "summary": "한 줄 요약",
    "details": "상세 설명",
    "schema_info": {
      "tables": ["관련 테이블"],
      "columns": ["주요 컬럼"],
      "indexes": ["인덱스"]
    },
    "code_changes": [
      {
        "file": "경로",
        "action": "create | modify",
        "content": "쿼리/스키마"
      }
    ]
  },
  "performance_notes": ["성능 관련 참고사항"],
  "questions": ["명확하지 않은 것들"]
}
```
```

### Agent D (Frontend) 시스템 프롬프트

```markdown
# 역할
너는 Frontend 전문가 에이전트야.
React/Next.js 기반 UI 구현을 담당해.

# 담당 영역 (이것만!)
- frontend/components/
- frontend/pages/ (또는 app/)
- frontend/lib/
- frontend/hooks/
- frontend/styles/

# 담당 아닌 것 (절대 건들지 마)
- backend-node/ → Backend Agent 담당
- DB 관련 → DB Agent 담당
- API 스펙 결정 → PM/Backend와 협의

# 코드 작성 규칙
1. TypeScript 사용
2. React 함수형 컴포넌트
3. 커스텀 훅 활용
4. 주석은 한글로
5. Tailwind CSS 또는 기존 스타일 시스템 따르기

# API 호출 규칙
- 절대 fetch 직접 사용 금지
- lib/api/ 클라이언트 사용
- 에러 핸들링 필수

# 응답 형식
```json
{
  "status": "success | partial | failed | need_clarification",
  "confidence": "high | medium | low",
  "result": {
    "summary": "한 줄 요약",
    "details": "상세 설명",
    "components_affected": ["컴포넌트 목록"],
    "code_changes": [
      {
        "file": "경로",
        "action": "create | modify",
        "content": "전체 코드"
      }
    ]
  },
  "needs_from_others": [
    {"agent": "backend", "request": "필요한 API"}
  ],
  "ui_notes": ["UX 관련 참고사항"],
  "questions": ["명확하지 않은 것들"]
}
```
```

---

## MCP 서버 구현

### 프로젝트 구조

```
mcp-agent-orchestrator/
├── package.json
├── tsconfig.json
├── src/
│   ├── index.ts          # 메인 서버
│   ├── agents/
│   │   ├── types.ts      # 타입 정의
│   │   ├── pm.ts         # PM 에이전트 프롬프트
│   │   ├── backend.ts    # Backend 에이전트 프롬프트
│   │   ├── database.ts   # DB 에이전트 프롬프트
│   │   └── frontend.ts   # Frontend 에이전트 프롬프트
│   └── utils/
│       └── logger.ts     # 로깅
└── build/
    └── index.js          # 컴파일된 파일
```

### 핵심 코드

```typescript
// src/index.ts
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import Anthropic from "@anthropic-ai/sdk";
import { PM_PROMPT, BACKEND_PROMPT, DB_PROMPT, FRONTEND_PROMPT } from "./agents";

const server = new Server({
  name: "agent-orchestrator",
  version: "1.0.0",
});

const anthropic = new Anthropic();

// 에이전트별 설정
const AGENT_CONFIG = {
  pm: { model: "claude-opus-4-5-20250214", prompt: PM_PROMPT },
  backend: { model: "claude-sonnet-4-20250514", prompt: BACKEND_PROMPT },
  db: { model: "claude-sonnet-4-20250514", prompt: DB_PROMPT },
  frontend: { model: "claude-sonnet-4-20250514", prompt: FRONTEND_PROMPT },
};

// 도구 목록
server.setRequestHandler("tools/list", async () => ({
  tools: [
    {
      name: "ask_backend_agent",
      description: "백엔드 전문가에게 질문하거나 작업 요청",
      inputSchema: {
        type: "object",
        properties: {
          task: { type: "string", description: "작업 내용" },
          context: { type: "string", description: "배경 정보 (선택)" },
        },
        required: ["task"],
      },
    },
    {
      name: "ask_db_agent",
      description: "DB 전문가에게 질문하거나 작업 요청",
      inputSchema: {
        type: "object",
        properties: {
          task: { type: "string", description: "작업 내용" },
          context: { type: "string", description: "배경 정보 (선택)" },
        },
        required: ["task"],
      },
    },
    {
      name: "ask_frontend_agent",
      description: "프론트엔드 전문가에게 질문하거나 작업 요청",
      inputSchema: {
        type: "object",
        properties: {
          task: { type: "string", description: "작업 내용" },
          context: { type: "string", description: "배경 정보 (선택)" },
        },
        required: ["task"],
      },
    },
    {
      name: "parallel_ask",
      description: "여러 전문가에게 동시에 질문 (병렬 실행)",
      inputSchema: {
        type: "object",
        properties: {
          requests: {
            type: "array",
            items: {
              type: "object",
              properties: {
                agent: { 
                  type: "string", 
                  enum: ["backend", "db", "frontend"] 
                },
                task: { type: "string" },
                context: { type: "string" },
              },
              required: ["agent", "task"],
            },
          },
        },
        required: ["requests"],
      },
    },
  ],
}));

// 도구 실행
server.setRequestHandler("tools/call", async (request) => {
  const { name, arguments: args } = request.params;

  const callAgent = async (agentType: string, task: string, context?: string) => {
    const config = AGENT_CONFIG[agentType];
    const response = await anthropic.messages.create({
      model: config.model,
      max_tokens: 8192,
      system: config.prompt,
      messages: [
        {
          role: "user",
          content: context ? `${task}\n\n배경 정보:\n${context}` : task,
        },
      ],
    });
    return response.content[0].text;
  };

  switch (name) {
    case "ask_backend_agent":
      return {
        content: [
          { type: "text", text: await callAgent("backend", args.task, args.context) },
        ],
      };

    case "ask_db_agent":
      return {
        content: [
          { type: "text", text: await callAgent("db", args.task, args.context) },
        ],
      };

    case "ask_frontend_agent":
      return {
        content: [
          { type: "text", text: await callAgent("frontend", args.task, args.context) },
        ],
      };

    case "parallel_ask":
      const results = await Promise.all(
        args.requests.map(async (req) => ({
          agent: req.agent,
          result: await callAgent(req.agent, req.task, req.context),
        }))
      );
      return {
        content: [
          { type: "text", text: JSON.stringify(results, null, 2) },
        ],
      };

    default:
      throw new Error(`Unknown tool: ${name}`);
  }
});

// 서버 시작
const transport = new StdioServerTransport();
await server.connect(transport);
```

### Cursor 설정

```json
// .cursor/mcp.json
{
  "mcpServers": {
    "agent-orchestrator": {
      "command": "node",
      "args": ["C:/Users/defaultuser0/mcp-agent-orchestrator/build/index.js"],
      "env": {
        "ANTHROPIC_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

---

## 비용 분석

### 토큰 사용량 비교

| 시나리오 | 단일 에이전트 | 멀티 에이전트 | 절감 |
|----------|--------------|--------------|------|
| 기능 1개 추가 | 100,000 토큰 | 60,000 토큰 | 40% |
| 시스템 리팩토링 | 300,000 토큰 | 150,000 토큰 | 50% |
| 새 모듈 개발 | 500,000 토큰 | 200,000 토큰 | 60% |

### 비용 계산 (예시)

```
단일 에이전트 (전부 Opus):
- 300,000 토큰 × $15/M = $4.50

멀티 에이전트 (Opus PM + Sonnet Workers):
- PM (Opus): 50,000 토큰 × $15/M = $0.75
- Workers (Sonnet): 100,000 토큰 × $3/M = $0.30
- 총: $1.05

절감: $4.50 - $1.05 = $3.45 (76% 절감!)
```

### ROI 분석

```
초기 투자:
- MCP 서버 개발: 4-6시간
- 프롬프트 튜닝: 2-4시간
- 테스트: 2시간
- 총: 8-12시간

회수:
- 대규모 작업당 $3-5 절감
- 재작업 시간 70% 감소
- 품질 30% 향상

손익분기점: 대규모 작업 3-5회
```

---

## 한계점 및 해결방안

### 현재 한계

| 한계 | 설명 | 해결방안 |
|------|------|----------|
| 완전 자동화 불가 | Cursor 에이전트 간 직접 통신 없음 | MCP 서버로 우회 |
| 파일 읽기 제한 | 각 에이전트가 모든 파일 접근 어려움 | 컨텍스트에 필요한 정보 전달 |
| 실시간 동기화 | 변경사항 즉시 반영 어려움 | 명시적 갱신 요청 |
| 에러 복구 | 자동 롤백 메커니즘 없음 | 수동 복구 또는 git 활용 |

### 향후 개선 방향

1. **파일 시스템 연동**
   - MCP 서버에 파일 읽기/쓰기 도구 추가
   - 에이전트가 직접 코드 확인 가능

2. **결과 자동 적용**
   - 코드 변경사항 자동 적용
   - git 커밋 자동화

3. **피드백 루프**
   - 테스트 자동 실행
   - 실패 시 자동 재시도

4. **히스토리 관리**
   - 대화 이력 저장
   - 컨텍스트 캐싱

---

## 체크리스트

### 구현 전 준비

- [ ] Node.js 18+ 설치
- [ ] Anthropic API 키 발급
- [ ] 프로젝트 폴더 생성

### MCP 서버 구현

- [ ] package.json 설정
- [ ] TypeScript 설정
- [ ] 기본 서버 구조
- [ ] 도구 정의 (4개)
- [ ] 에이전트 프롬프트 작성
- [ ] 빌드 및 테스트

### Cursor 연동

- [ ] mcp.json 설정
- [ ] Cursor 재시작
- [ ] 도구 호출 테스트
- [ ] 실제 작업 테스트

### 튜닝

- [ ] 프롬프트 개선
- [ ] 에러 핸들링 강화
- [ ] 로깅 추가
- [ ] 성능 최적화

---

## 참고 자료

- [MCP SDK 문서](https://modelcontextprotocol.io/)
- [Anthropic API 문서](https://docs.anthropic.com/)
- [CrewAI](https://github.com/joaomdmoura/crewAI) - 멀티에이전트 프레임워크 참고
- [AutoGen](https://github.com/microsoft/autogen) - Microsoft 멀티에이전트 참고

---

*작성일: 2026-02-05*
*버전: 1.0*
