Project Jessica (ElevenLabs TTS MCP)

This project integrates ElevenLabs Text-to-Speech capabilities with Cursor through the Model Context Protocol (MCP). It consists of a FastAPI backend service and a React frontend application.

Features

• Text-to-Speech conversion using ElevenLabs API
• Voice selection and management
• MCP integration for Cursor
• Modern React frontend interface
• WebSocket real-time communication
• Pre-commit hooks for code quality
• Automatic code formatting and linting

Project Structure

Requirements

• Python 3.11+
• Poetry (for backend dependency management)
• Node.js 18+ (for frontend)
• Cursor (for MCP integration)

Local Development Setup

Backend Setup

Frontend Setup

Development Servers

Starting the Backend

The backend provides:

• REST API: http://localhost:9020
• WebSocket: ws://localhost:9020/ws
• MCP Server: http://localhost:9020/sse (integrated with the main API server)

Starting the Frontend

Frontend development server:

• http://localhost:5173

Environment Configuration

Backend (.env)

Frontend (.env)

Code Quality Tools

Backend

Frontend

Production Deployment

AWS ECR and GitHub Actions Setup

To enable automatic building and pushing of Docker images to Amazon ECR:

1. Apply the Terraform configuration to create the required AWS resources:
   cd terraform terraform init terraform apply
2. The GitHub Actions workflow will automatically:
   • Read the necessary configuration from the Terraform state in S3
   • Build the Docker image on pushes to main or develop branches
   • Push the image to ECR with tags for latest and the specific commit SHA
3. No additional repository variables needed! The workflow fetches all required configuration from the Terraform state.

How it Works

The GitHub Actions workflow is configured to:

1. Initially assume a predefined IAM role with S3 read permissions
2. Fetch and extract configuration values from the Terraform state file in S3
3. Re-authenticate using the actual deployment role from the state file
4. Build and push the Docker image to the ECR repository defined in the state

This approach eliminates the need to manually configure GitHub repository variables and ensures that the CI/CD process always uses the current infrastructure configuration.

Quick Overview

• Frontend: Served from S3 via CloudFront at jessica.georgi.io
• Backend API: Available at api.georgi.io/jessica
• WebSocket: Connects to api.georgi.io/jessica/ws
• Docker Image: Stored in AWS ECR and can be deployed to ECS/EKS
• Infrastructure: Managed via Terraform in this repository

MCP Integration with Cursor

1. Start the backend server
2. In Cursor settings, add new MCP server:
   • Name: Jessica TTS
   • Type: SSE
   • URL: http://localhost:9020/sse

Troubleshooting

Common Issues

1. API Key Issues
   • Error: "Invalid API key"
   • Solution: Check .env file
2. Connection Problems
   • Error: "Cannot connect to MCP server"
   • Solution: Verify backend is running and ports are correct
3. Port Conflicts
   • Error: "Address already in use"
   • Solution: Change ports in .env
4. WebSocket Connection Failed
   • Error: "WebSocket connection failed"
   • Solution: Ensure backend is running and WebSocket URL is correct

For additional help, please open an issue on GitHub.

License

MIT