# Confluence MCP Server

Confluence API에 접근하기 위한 Model Context Protocol 서버 시스템입니다. Personal Access Token을 사용하여 Confluence와 통신합니다. VPN 영역 내에서 Confluence API에 접근하기 위한 중개 서버 역할을 합니다.

## 시스템 구성

이 프로젝트는 두 가지 서버로 구성되어 있습니다:

1. **MCP 서버** (server.ts): Confluence API와 통신하여 데이터를 처리하는 주 서버입니다.
   - 기본 포트: 3000
   - RESTful API 제공
   - MCP 프로토콜 처리

2. **프록시 서버** (proxyServer.ts): MCP 클라이언트와 MCP 서버 사이의 프록시 역할을 합니다.
   - 기본 포트: 3001
   - MCP 클라이언트로부터 요청을 받아 주 서버로 전달

이 구조는 VPN 영역 문제를 해결하기 위해 설계되었습니다. MCP 서버는 VPN 내부에서 실행되어 Confluence API에 접근하고, 프록시 서버는 외부에서 접근 가능한 환경에서 실행됩니다.

## 기능

- 모든 Confluence 스페이스 목록 조회
- 특정 스페이스 내의 모든 페이지 조회
- 페이지 ID로 특정 페이지 정보 조회
- 새 페이지 생성
- 기존 페이지 업데이트

## 설치 및 설정

### 필수 조건

- Node.js 16.x 이상
- Bun 1.0.0 이상

### 설치

```bash
# 저장소 클론
git clone https://github.com/yourusername/confluence-mcp-server.git
cd confluence-mcp-server

# 의존성 설치
bun install
```

### 환경 변수 설정

`.env` 파일을 프로젝트 루트에 생성하고 다음 내용을 추가합니다:

```
PORT=3000
PROXY_PORT=3001
MCP_SERVER_URL=http://localhost:3000
CONFLUENCE_BASE_URL=https://wiki.musinsa.com
PERSONAL_ACCESS_TOKEN=your_personal_access_token
NODE_ENV=development
```

## 실행

### 개발 환경

```bash
# MCP 서버 실행 (Confluence API와 통신)
bun run dev

# 프록시 서버 실행 (MCP 클라이언트와 통신)
bun run dev:proxy

# MCP 서버 Stdio 모드 실행 (선택 사항)
bun run dev:stdio
```

### 프로덕션 환경

```bash
# 빌드
bun run build

# MCP 서버 실행
bun run serve

# 프록시 서버 실행
bun run serve:proxy
```

## 엔드포인트

### MCP 서버 엔드포인트 (기본 포트: 3000)

- **POST /mcp** - MCP 요청을 처리하는 메인 엔드포인트
- **GET /mcp/tools** - 사용 가능한 도구 목록 조회
- **GET /api/spaces** - 모든 스페이스 목록 조회
- **GET /api/spaces/:spaceKey/pages** - 특정 스페이스의 페이지 목록 조회
- **GET /api/pages/:pageId** - 특정 페이지 정보 조회
- **POST /api/pages** - 새 페이지 생성
- **PUT /api/pages/:pageId** - 페이지 업데이트
- **GET /health** - 서버 상태 확인

### 프록시 서버 엔드포인트 (기본 포트: 3001)

- **POST /mcp** - MCP 클라이언트 요청을 받아 MCP 서버로 전달
- **GET /tools** - 사용 가능한 도구 목록 조회
- **GET /health** - 프록시 서버 상태 확인

## 문제 해결

### VPN 영역 문제 해결

이 프로젝트는 VPN 영역 문제를 해결하기 위해 두 서버로 분리되었습니다:

1. **MCP 서버**는 VPN 내부에서 실행하여 Confluence API에 직접 접근합니다.
2. **프록시 서버**는 외부에서 접근 가능한 환경에서 실행하여 MCP 클라이언트의 요청을 받습니다.

이 구성은 MCP 클라이언트가 직접 Confluence API에 접근할 수 없는 상황에서 중개 역할을 합니다.

### "Error fetching spaces: Unable to connect" 오류

이 오류는 다음과 같은 문제로 발생할 수 있습니다:

1. **HTTPS 인증서 문제**: 개발 환경에서는 SSL 인증서 검증이 비활성화되어 있지만, 프로덕션 환경에서는 올바른 인증서 설정이 필요합니다.

2. **네트워크 연결 문제**: 방화벽이나 프록시 설정으로 인해 Confluence 서버에 접근할 수 없는 경우입니다.

3. **Personal Access Token 문제**: 토큰이 만료되었거나 잘못된 형식일 수 있습니다.

### 해결 방법

1. `.env` 파일의 `CONFLUENCE_BASE_URL`이 올바른지 확인합니다.
2. Personal Access Token이 유효한지 확인합니다.
3. 방화벽 설정을 확인하여 Confluence 서버에 접근할 수 있는지 확인합니다.
4. 네트워크 관리자에게 문의하여 접근 권한을 확인합니다.
5. MCP 서버와 프록시 서버 간의 연결이 올바르게 설정되었는지 확인합니다 (`MCP_SERVER_URL` 설정).

## 테스트

```bash
# 모든 테스트 실행
bun test

# 특정 테스트 실행
bun test src/test/getSpaces.test.ts
```

## 배포 구성

### 권장 배포 구성

프로덕션 환경에서는 다음과 같은 배포 구성을 권장합니다:

1. **MCP 서버**: VPN 내부 또는 Confluence 서버에 접근할 수 있는 네트워크에 배포
2. **프록시 서버**: MCP 클라이언트가 접근할 수 있는 네트워크에 배포

### 보안 고려사항

- 프록시 서버와 MCP 서버 간의 통신은 HTTPS를 사용하여 암호화하는 것을 권장합니다.
- Personal Access Token은 안전하게 관리하고, 필요에 따라 정기적으로 갱신하세요.
- 프로덕션 환경에서는 적절한 인증 메커니즘을 추가하여 프록시 서버에 대한 무단 접근을 방지하세요.

## 라이센스

MIT