Project Jessica (ElevenLabs TTS MCP)

该项目通过模型上下文协议（MCP）将ElevenLabs的文本转语音功能与Cursor集成。它包括一个FastAPI后端服务和一个React前端应用程序。

功能

• 使用ElevenLabs API进行文本转语音转换
• 语音选择和管理
• 与Cursor的MCP集成
• 现代化的React前端界面
• WebSocket实时通信
• 预提交钩子以保证代码质量
• 自动代码格式化和检查

项目结构

jessica/
├── src/
│   ├── backend/          # FastAPI backend service
│   └── frontend/         # React frontend application
├── terraform/            # Infrastructure as Code
├── tests/               # Test suites
└── docs/                # Documentation

要求

• Python 3.11+
• Poetry（用于后端依赖管理）
• Node.js 18+（用于前端）
• Cursor（用于MCP集成）

本地开发设置

后端设置

# Clone the repository
git clone https://github.com/georgi-io/jessica.git
cd jessica

# Create Python virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install backend dependencies
poetry install

# Configure environment
cp .env.example .env
# Edit .env with your ElevenLabs API key

# Install pre-commit hooks
poetry run pre-commit install

前端设置

# Navigate to frontend directory
cd src/frontend

# Install dependencies
npm install

开发服务器

启动后端

# Activate virtual environment if not active
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Start the backend
python -m src.backend

后端提供：

• REST API: http://localhost:9020
• WebSocket: ws://localhost:9020/ws
• MCP服务器: http://localhost:9020/sse（与主API服务器集成）

启动前端

# In src/frontend directory
npm run dev

前端开发服务器：

• http://localhost:5173

环境配置

后端 (.env)

# ElevenLabs API
ELEVENLABS_API_KEY=your-api-key

# Server Configuration
HOST=127.0.0.1
PORT=9020

# Development Settings
DEBUG=false
RELOAD=true

前端 (.env)

VITE_API_URL=http://localhost:9020
VITE_WS_URL=ws://localhost:9020/ws

代码质量工具

后端

# Run all pre-commit hooks
poetry run pre-commit run --all-files

# Run specific tools
poetry run ruff check .
poetry run ruff format .
poetry run pytest

前端

# Lint
npm run lint

# Type check
npm run type-check

# Test
npm run test

生产环境部署

AWS ECR 和 GitHub Actions 设置

为了启用自动构建并将Docker镜像推送到Amazon ECR：

1. 应用Terraform配置以创建所需的AWS资源：

   cd terraform
   terraform init
   terraform apply
   

2. GitHub Actions工作流将自动：

   • 从S3中的Terraform状态读取必要的配置
   • 在推送至main或develop分支时构建Docker镜像
   • 将镜像推送到ECR，并标记为latest和特定的提交SHA

3. 不需要额外的仓库变量！工作流从Terraform状态中获取所有必需的配置。

工作原理

GitHub Actions工作流被配置为：

1. 初始时假设具有S3读取权限的预定义IAM角色
2. 从S3中的Terraform状态文件获取并提取配置值
3. 使用状态文件中的实际部署角色重新认证
4. 构建并将Docker镜像推送到状态中定义的ECR存储库

这种方法消除了手动配置GitHub仓库变量的需求，并确保CI/CD过程始终使用当前的基础架构配置。

快速概览

• 前端：通过CloudFront从S3提供服务，地址为jessica.georgi.io
• 后端API：可访问于api.georgi.io/jessica
• WebSocket：连接到api.georgi.io/jessica/ws
• Docker镜像：存储在AWS ECR中，可以部署到ECS/EKS
• 基础架构：通过此仓库中的Terraform管理

与Cursor的MCP集成

1. 启动后端服务器
2. 在Cursor设置中添加新的MCP服务器：
   • 名称：Jessica TTS
   • 类型：SSE
   • URL：http://localhost:9020/sse

故障排除

常见问题

1. API 密钥问题

   • 错误: "无效的 API 密钥"
   • 解决方案: 检查 .env 文件

2. 连接问题

   • 错误: "无法连接到 MCP 服务器"
   • 解决方案: 确认后端正在运行且端口正确

3. 端口冲突

   • 错误: "地址已被使用"
   • 解决方案: 在 .env 中更改端口

4. WebSocket 连接失败

   • 错误: "WebSocket 连接失败"
   • 解决方案: 确保后端正在运行且 WebSocket URL 正确

如需更多帮助，请在 GitHub 上提交问题。

许可证

MIT