ERP-node/mcp-agent-orchestrator/README.md

# Multi-Agent Orchestrator MCP Server v2.0

Cursor Agent CLI를 활용한 멀티에이전트 시스템입니다.
**Cursor Team Plan만으로 동작** - 외부 API 키 불필요!

## 아키텍처

```
┌─────────────────────────────────────────┐
│         Cursor IDE (PM Agent)           │
│            Claude Opus 4.5              │
└────────────────────┬────────────────────┘
                     │ MCP Tools
    ┌────────────────┼────────────────┐
    ▼                ▼                ▼
┌────────┐     ┌────────┐      ┌────────┐
│Backend │     │   DB   │      │Frontend│
│ Agent  │     │ Agent  │      │ Agent  │
│ via CLI│     │ via CLI│      │ via CLI│
│Sonnet  │     │Sonnet  │      │Sonnet  │
└────────┘     └────────┘      └────────┘
      ↑              ↑               ↑
      └──────────────┴───────────────┘
              Cursor Agent CLI
           (Team Plan 크레딧 사용)
```

## 특징

- **API 키 불필요**: Cursor Team Plan 크레딧만 사용
- **크로스 플랫폼**: Windows, Mac, Linux 지원
- **진짜 병렬 실행**: `parallel_ask`로 동시 작업
- **모델 티어링**: PM=Opus, Sub-agents=Sonnet

## 사전 요구사항

1. **Cursor Team/Pro Plan** 구독
2. **Cursor Agent CLI** 설치 및 로그인
   ```bash
   # 설치 후 로그인 확인
   agent status
   ```

## 설치

```bash
cd mcp-agent-orchestrator
npm install
npm run build
```

## Cursor 설정

### Windows

`.cursor/mcp.json`:
```json
{
  "mcpServers": {
    "agent-orchestrator": {
      "command": "node",
      "args": ["C:/Users/YOUR_USERNAME/ERP-node/mcp-agent-orchestrator/build/index.js"]
    }
  }
}
```

### Mac

`.cursor/mcp.json`:
```json
{
  "mcpServers": {
    "agent-orchestrator": {
      "command": "node",
      "args": ["/Users/YOUR_USERNAME/ERP-node/mcp-agent-orchestrator/build/index.js"]
    }
  }
}
```

**주의**: Mac에서 agent CLI가 PATH에 있어야 합니다.
```bash
# agent CLI 위치 확인
which agent
# 보통: ~/.cursor-agent/bin/agent 또는 /usr/local/bin/agent

# PATH에 없으면 추가 (.zshrc 또는 .bashrc)
export PATH="$HOME/.cursor-agent/bin:$PATH"
```

## 사용 가능한 도구

### ask_backend_agent
백엔드 전문가에게 질문/작업 요청
- API 설계, 서비스 로직, 라우팅
- 담당 폴더: `backend-node/src/`

### ask_db_agent
DB 전문가에게 질문/작업 요청
- 스키마, 쿼리, MyBatis 매퍼
- 담당 폴더: `src/com/pms/mapper/`, `db/`

### ask_frontend_agent
프론트엔드 전문가에게 질문/작업 요청
- React 컴포넌트, 페이지, 스타일
- 담당 폴더: `frontend/`

### parallel_ask
여러 전문가에게 동시에 질문 (진짜 병렬 실행!)
- 정보 수집 단계에서 유용

### get_agent_info
에이전트 시스템 정보 확인

## 워크플로우 예시

### 1단계: 정보 수집 (병렬)
```
parallel_ask([
  { agent: "backend", task: "현재 order 관련 API 구조 분석" },
  { agent: "db", task: "orders 테이블 스키마 분석" },
  { agent: "frontend", task: "주문 관련 컴포넌트 현황 분석" }
])
```

### 2단계: 개별 작업 (순차)
```
ask_db_agent("cursor 기반 페이징 쿼리 작성")
ask_backend_agent("GET /api/orders에 pagination 추가")
ask_frontend_agent("Pagination 컴포넌트 적용")
```

## 모델 설정

| Agent | Model | 역할 |
|-------|-------|------|
| PM (Cursor IDE) | Opus 4.5 | 전체 조율, 사용자 대화 |
| Backend | Sonnet 4.5 | API, 서비스 로직 |
| DB | Sonnet 4.5 | 스키마, 쿼리 |
| Frontend | Sonnet 4.5 | 컴포넌트, UI |

**비용 최적화**: PM만 Opus, 나머지는 Sonnet 사용

## 환경 변수

- `LOG_LEVEL`: 로그 레벨 (debug, info, warn, error)

## 트러블슈팅

### Windows: agent 명령어가 안 됨
```powershell
# PowerShell 실행 정책 확인
Get-ExecutionPolicy -List

# 필요시 변경
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
```

### Mac: agent 명령어를 찾을 수 없음
```bash
# agent CLI 위치 확인
ls -la ~/.cursor-agent/bin/

# PATH 추가
echo 'export PATH="$HOME/.cursor-agent/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
```

### 응답이 오래 걸림
- 정상입니다! 각 에이전트 호출에 15-30초 소요
- `parallel_ask`로 병렬 처리하면 시간 절약

## 개발

```bash
# 개발 모드 (watch)
npm run dev

# 빌드
npm run build

# 테스트 실행
npm start
```

## 라이선스

MIT