프로젝트 제시카(ElevenLabs TTS MCP)

이 프로젝트는 모델 컨텍스트 프로토콜(MCP)을 통해 ElevenLabs의 텍스트-음성 변환 기능을 커서와 통합합니다. FastAPI 백엔드 서비스와 React 프런트엔드 애플리케이션으로 구성됩니다.

특징

• ElevenLabs API를 사용한 텍스트-음성 변환
• 음성 선택 및 관리
• 커서를 위한 MCP 통합
• 최신 React 프런트엔드 인터페이스
• WebSocket 실시간 통신
• 코드 품질을 위한 사전 커밋 후크
• 자동 코드 포맷팅 및 린팅

프로젝트 구조

지엑스피1

요구 사항

• 파이썬 3.11+
• Poetry(백엔드 종속성 관리용)
• Node.js 18+(프론트엔드용)
• 커서(MCP 통합용)

지역 개발 설정

백엔드 설정

프런트엔드 설정

개발 서버

백엔드 시작하기

백엔드는 다음을 제공합니다.

• REST API: http://localhost:9020
• 웹소켓: ws://localhost:9020/ws
• MCP 서버: http://localhost:9020/sse (주 API 서버와 통합)

프런트엔드 시작하기

프런트엔드 개발 서버:

• http://localhost:5173

환경 구성

백엔드(.env)

프런트엔드(.env)

코드 품질 도구

백엔드

프런트엔드

프로덕션 배포

AWS ECR 및 GitHub 작업 설정

Amazon ECR에 Docker 이미지를 자동으로 빌드하고 푸시하는 기능을 활성화하려면:

1. Terraform 구성을 적용하여 필요한 AWS 리소스를 생성합니다.
   cd terraform terraform init terraform apply
2. GitHub Actions 워크플로는 자동으로 다음을 수행합니다.
   • S3의 Terraform 상태에서 필요한 구성을 읽습니다.
   • main 또는 develop 브랜치에 푸시하여 Docker 이미지를 빌드합니다.
   • latest 및 특정 커밋 SHA에 대한 태그와 함께 이미지를 ECR에 푸시합니다.
3. 추가 저장소 변수가 필요하지 않습니다! 워크플로는 Terraform 상태에서 필요한 모든 구성을 가져옵니다.

작동 원리

GitHub Actions 워크플로는 다음과 같이 구성됩니다.

1. 처음에는 S3 읽기 권한이 있는 미리 정의된 IAM 역할을 가정합니다.
2. S3의 Terraform 상태 파일에서 구성 값을 가져오고 추출합니다.
3. 상태 파일의 실제 배포 역할을 사용하여 다시 인증합니다.
4. 상태에 정의된 ECR 저장소에 Docker 이미지를 빌드하고 푸시합니다.

이 접근 방식을 사용하면 GitHub 저장소 변수를 수동으로 구성할 필요가 없고 CI/CD 프로세스가 항상 현재 인프라 구성을 사용하게 됩니다.

빠른 개요

• 프런트엔드: jessica.georgi.io의 CloudFront를 통해 S3에서 제공됨
• 백엔드 API: api.georgi.io/jessica에서 사용 가능
• WebSocket: api.georgi.io/jessica/ws에 연결
• Docker 이미지: AWS ECR에 저장되며 ECS/EKS에 배포 가능
• 인프라: 이 저장소의 Terraform을 통해 관리됨

커서와 MCP 통합

1. 백엔드 서버를 시작합니다
2. 커서 설정에서 새 MCP 서버를 추가합니다.
   • 이름: 제시카 TTS
   • 유형: SSE
   • URL: http://localhost:9020/sse

문제 해결

일반적인 문제

1. API 키 문제
   • 오류: "잘못된 API 키"
   • 해결 방법: .env 파일을 확인하세요
2. 연결 문제
   • 오류: "MCP 서버에 연결할 수 없습니다"
   • 해결 방법: 백엔드가 실행 중이고 포트가 올바른지 확인하세요.
3. 항구 갈등
   • 오류: "주소가 이미 사용 중입니다"
   • 해결 방법: .env 에서 포트를 변경하세요.
4. WebSocket 연결에 실패했습니다
   • 오류: "WebSocket 연결에 실패했습니다"
   • 해결 방법: 백엔드가 실행 중이고 WebSocket URL이 올바른지 확인하세요.

추가 도움이 필요하면 GitHub에서 이슈를 열어주세요.

특허

MIT