article

README

Confluence MCP Server

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

시스템 구성

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

MCP 서버 (server.ts): Confluence API와 통신하여 데이터를 처리하는 주 서버입니다.
- 기본 포트: 3000
- RESTful API 제공
- MCP 프로토콜 처리
프록시 서버 (proxyServer.ts): MCP 클라이언트와 MCP 서버 사이의 프록시 역할을 합니다.
- 기본 포트: 3001
- MCP 클라이언트로부터 요청을 받아 주 서버로 전달

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

기능

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

설치 및 설정

필수 조건

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

설치

# 저장소 클론
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

실행

개발 환경

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

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

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

프로덕션 환경

# 빌드
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 영역 문제를 해결하기 위해 두 서버로 분리되었습니다:

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

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

"Error fetching spaces: Unable to connect" 오류

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

HTTPS 인증서 문제: 개발 환경에서는 SSL 인증서 검증이 비활성화되어 있지만, 프로덕션 환경에서는 올바른 인증서 설정이 필요합니다.
네트워크 연결 문제: 방화벽이나 프록시 설정으로 인해 Confluence 서버에 접근할 수 없는 경우입니다.
Personal Access Token 문제: 토큰이 만료되었거나 잘못된 형식일 수 있습니다.

해결 방법

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

테스트

# 모든 테스트 실행
bun test

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

배포 구성

권장 배포 구성

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

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

보안 고려사항

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

라이센스

MIT

Confluence内容管理服务器