orchestry-mcp/MCP_SETUP.md

Orchestry MCP Server for multi-session task management

# BMAD Task Manager - MCP 설정 가이드

## 🤖 다른 Claude 세션에서 사용하기

### 1. Claude Desktop 설정 파일 위치
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- Linux: `~/.config/Claude/claude_desktop_config.json`

### 2. MCP 서버 설정 추가

claude_desktop_config.json에 다음 내용을 추가하세요:

```json
{
  "mcpServers": {
    "bmad-task-manager": {
      "command": "node",
      "args": ["/Users/dumbokim/Develop/bmad-task-manager/server/dist/index.js"],
      "env": {
        "RUN_MODE": "stdio",
        "API_PORT": "7531",
        "WEB_PORT": "7530",
        "DB_PATH": "/Users/dumbokim/Develop/bmad-task-manager/server/bmad.db"
      },
      "cwd": "/Users/dumbokim/Develop/bmad-task-manager",
      "description": "BMAD Task Management System"
    }
  }
}
```

### 3. 환경별 포트 설정

여러 프로젝트를 동시에 사용할 경우, 각각 다른 포트를 설정하세요:

#### 프로젝트 A (기본)
```json
{
  "env": {
    "API_PORT": "7531",
    "WEB_PORT": "7530"
  }
}
```

#### 프로젝트 B
```json
{
  "env": {
    "API_PORT": "7541",
    "WEB_PORT": "7540"
  }
}
```

#### 프로젝트 C
```json
{
  "env": {
    "API_PORT": "7551",
    "WEB_PORT": "7550"
  }
}
```

### 4. 서버 빌드 및 실행

#### 사전 준비
```bash
cd /Users/dumbokim/Develop/bmad-task-manager
npm install
cd server && npm run build
```

#### MCP 모드로 실행
```bash
# 기본 포트 (7531)
cd server && npm run start:mcp

# 커스텀 포트
API_PORT=7541 npm run start:mcp
```

### 5. Claude에서 사용하기

Claude 세션에서 다음과 같이 사용할 수 있습니다:

```
# 프로젝트 생성
create_project("새 프로젝트", "설명")

# Business 생성
create_business(projectId, {
  title: "비즈니스 목표",
  objectives: ["목표1", "목표2"]
})

# 칸반 보드 조회
get_board(projectId)

# BMAD 계층 구조 조회
get_bmad_hierarchy(projectId)
```

### 6. Web UI 접속

MCP 서버와 별도로 Web UI를 보려면:

```bash
# 터미널 1: API 서버
cd server && API_PORT=7531 npm run dev:web

# 터미널 2: Web UI
cd web && WEB_PORT=7530 API_PORT=7531 npm run dev
```

브라우저에서 `http://localhost:7530` 접속

### 7. 포트 충돌 해결

포트가 이미 사용 중인 경우:

```bash
# 특정 포트 사용 중인 프로세스 확인
lsof -i :7531

# 프로세스 종료
kill -9 [PID]

# 또는 자동 정리
./stop.sh
```

## 🎯 권장 포트 범위

프로젝트별로 다음 범위 사용을 권장합니다:

- **BMAD 프로젝트 1**: 7530-7539
- **BMAD 프로젝트 2**: 7540-7549
- **BMAD 프로젝트 3**: 7550-7559
- **기타 개발 프로젝트**: 3000-3999, 8000-8999

## 📝 환경변수 우선순위

1. 명령줄: `API_PORT=7541 npm run dev`
2. .env 파일: `/bmad-task-manager/.env`
3. MCP 설정: `claude_desktop_config.json`의 env
4. 기본값: 코드에 하드코딩된 값 (7531/7530)

## 🔧 문제 해결

### MCP 서버가 연결되지 않을 때
1. 서버 빌드 확인: `cd server && npm run build`
2. 경로 확인: MCP 설정의 경로가 정확한지 확인
3. 권한 확인: 실행 권한이 있는지 확인

### 포트 충돌
1. 다른 포트로 변경
2. .env 파일 수정
3. MCP 설정 업데이트

### 데이터베이스 문제
1. DB 파일 권한 확인
2. 경로 확인
3. 필요시 새 DB 생성: `rm server/bmad.db`