Project Jessica (ElevenLabs TTS MCP)

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

功能

• 使用 ElevenLabs API 进行文本转语音转换
• 语音选择和管理
• 用于 Cursor 的 MCP 集成
• 现代 React 前端界面
• WebSocket 实时通信
• 用于代码质量的 Pre-commit 钩子
• 自动代码格式化和 Linting

项目结构

jessica/
├── src/
│   ├── backend/          # FastAPI 后端服务
│   └── frontend/         # React 前端应用程序
├── terraform/            # 基础设施即代码
├── tests/               # 测试套件
└── docs/                # 文档

要求

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

本地开发设置

后端设置

# 克隆仓库
git clone https://github.com/georgi-io/jessica.git
cd jessica

# 创建 Python 虚拟环境
python -m venv .venv
source .venv/bin/activate  # 在 Windows 上：.venv\Scripts\activate

# 安装后端依赖
poetry install

# 配置环境
cp .env.example .env
# 使用您的 ElevenLabs API 密钥编辑 .env

# 安装 pre-commit 钩子
poetry run pre-commit install

前端设置

# 导航到前端目录
cd src/frontend

# 安装依赖
npm install

开发服务器

启动后端

# 如果未激活，则激活虚拟环境
source .venv/bin/activate  # 在 Windows 上：.venv\Scripts\activate

# 启动后端
python -m src.backend

后端提供：

• REST API: http://localhost:9020
• WebSocket: ws://localhost:9020/ws
• MCP Server: http://localhost:9020/sse (与主 API 服务器集成)

启动前端

# 在 src/frontend 目录中
npm run dev

前端开发服务器：

• http://localhost:5173

环境配置

后端 (.env)

# ElevenLabs API
ELEVENLABS_API_KEY=your-api-key

# 服务器配置
HOST=127.0.0.1
PORT=9020

# 开发设置
DEBUG=false
RELOAD=true

前端 (.env)

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

代码质量工具

后端

# 运行所有 pre-commit 钩子
poetry run pre-commit run --all-files

# 运行特定工具
poetry run ruff check .
poetry run ruff format .
poetry run pytest

前端

# Lint
npm run lint

# 类型检查
npm run type-check

# 测试
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 过程始终使用当前的infrastructure配置。

快速概览

• 前端：通过 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 上提出 issue。

许可证

MIT