プロジェクト ジェシカ (ElevenLabs TTS MCP)

このプロジェクトは、ElevenLabsのテキスト読み上げ機能を、モデルコンテキストプロトコル（MCP）を介してCursorに統合します。FastAPIバックエンドサービスとReactフロントエンドアプリケーションで構成されています。

特徴

• ElevenLabs APIを使用したテキスト読み上げ変換

• 音声の選択と管理

• カーソルのMCP統合

• モダンなReactフロントエンドインターフェース

• WebSocketリアルタイム通信

• コード品質のための事前コミットフック

• 自動コードフォーマットとリンティング

Related MCP server: Cursor DB MCP Server

プロジェクト構造

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+（フロントエンド用）

• カーソル（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. 必要な AWS リソースを作成するには、Terraform 構成を適用します。

   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. Dockerイメージをビルドし、状態で定義されたECRリポジトリにプッシュします。

このアプローチにより、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 で問題を報告してください。

ライセンス

マサチューセッツ工科大学