VoiceStudio MCP Server

Kokoro MCP Server 开发环境设置指南

本指南将详细说明如何设置 Kokoro MCP Server 项目的开发环境。

前提条件

开发 Kokoro MCP Server 需要以下软件：

• Python 3.10 或更高版本
• uv 包管理器
• Git
• Docker 和 Docker Compose
• Kokoro 语音合成引擎（在真实模式下使用时）

基本设置

1. 克隆仓库

# リポジトリのクローン
git clone https://github.com/yourusername/Kokoro-MCP-Server.git
cd Kokoro-MCP-Server

2. 安装 uv 并创建虚拟环境

# uvのインストール（macOS/Linux）
curl -sSf https://astral.sh/uv/install.sh | sh
# または（Windows）
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# 仮想環境の作成
uv venv

# 仮想環境の有効化（Windows）
.venv\Scripts\activate

# 仮想環境の有効化（macOS/Linux）
source .venv/bin/activate

3. 安装依赖包

# 依存パッケージのインストール
uv pip install -r requirements.txt

# 開発用パッケージのインストール
uv pip install -r requirements-dev.txt

4. 安装 PyOpenJTalk

在 Windows 上安装 PyOpenJTalk 时，可能需要进行额外设置：

# Linuxの場合
CMAKE_POLICY_VERSION_MINIMUM=3.5 uv pip install pyopenjtalk

# Windowsの場合
$env:CMAKE_POLICY_VERSION_MINIMUM = "3.5"; uv pip install pyopenjtalk

# インストールに問題がある場合は、ビルド済みホイールを試す
uv pip install https://github.com/r9y9/pyopenjtalk/releases/download/v0.3.0/pyopenjtalk-0.3.0-cp39-cp39-win_amd64.whl

设置 MeCab 和 fugashi

1. 安装 MeCab（Linux）

sudo apt-get update
sudo apt-get install -y mecab libmecab-dev mecab-ipadic-utf8

2. 安装 fugashi 和 unidic-lite

uv pip install fugashi[unidic] unidic-lite ipadic

3. Windows 特有设置

在 Windows 上，可能需要手动设置 MeCab 配置文件的路径：

# mecab_windows_setup.pyを実行
python mecab_windows_setup.py

开发设置

1. 启用开发模式

在开发模式下，调试日志会启用，所做的更改也会自动生效。

# 開発モードで実行
MOCK_TTS=true python src/main.py --dev

2. 日志设置

调整日志级别即可显示详细的调试信息。

# デバッグログを有効にして実行
python src/main.py --log-level debug

3. 使用模拟模式

即使环境中没有 Kokoro 语音合成引擎，也可以使用模拟模式进行开发：

# モックモードで実行
MOCK_TTS=true python src/main.py

测试环境

1. 运行测试

项目包含自动化测试套件。

2. 测试客户端

Docker 环境

1. 构建并运行 Docker 容器

# イメージをビルド
make build

# コンテナを起動
make up

# ログを確認
make logs

# コンテナ内でシェルを実行
make shell

2. 多架构构建

可以为多种架构（amd64、arm64）构建镜像：

# Docker Hub ユーザー名を設定
export DOCKER_HUB_USERNAME="your-username"

# マルチアーキテクチャビルドを実行
./build-multi-arch.sh

3. 部署到生产环境

按照以下步骤部署到生产环境：

1. 准备配置文件：

# 設定ファイルをコピーして編集
cp claude_desktop_config.json.example claude_desktop_config.json

2. 编辑配置文件：

• 设置 API 密钥
• 设置卷路径
• 设置资源限制

3. 执行部署：

# デプロイスクリプトを実行
./deploy.sh

4. 在开发模式下运行 Docker

# 開発モードでコンテナを起動（モックTTSを使用）
make dev

调试方法

1. 启用调试日志

调整日志级别即可查看详细的调试信息。

# デバッグログを有効にして実行
python src/main.py --log-level debug

2. 使用 Python 调试器

可以使用 Python 调试器以交互方式调试代码：

# コード内でデバッグポイントを設定
import pdb; pdb.set_trace()

3. 记录请求/响应日志

可以记录并查看 MCP 请求和响应：

# リクエスト/レスポンスのロギングを有効化
python src/main.py --log-level debug --log-requests

代码质量工具

1. 使用 Black 格式化代码

# コードのフォーマット
black src/ tests/

2. 使用 isort 整理导入项

# インポートの整理
isort src/ tests/

3. 使用 flake8 进行代码检查

# コードのリント
flake8 src/ tests/

4. 使用 mypy 进行类型检查

# 型チェック
mypy src/

常见问题及解决方法

1. MeCab 相关错误

如果找不到 MeCab，或者无法访问 mecabrc 文件，请尝试以下解决方法：

# MeCabの設定ファイルを探す
find / -name mecabrc 2>/dev/null

# 環境変数の設定
export MECABRC=/path/to/mecabrc

# または、シンボリックリンクの作成
sudo ln -sf /path/to/mecabrc /usr/local/etc/mecabrc

2. fugashi 和 unidic 相关错误

# まず、既存のパッケージをアンインストール
uv pip uninstall fugashi ipadic unidic-lite

# インストールし直す
uv pip install fugashi[unidic] unidic-lite ipadic

3. PyTorch 相关错误

# PyTorchの再インストール
uv pip uninstall torch
uv pip install torch

MCP 开发最佳实践

1. 明确工具定义：明确界定 MCP 工具的参数和返回值
2. 错误处理：妥善处理所有 MCP 请求中的错误
3. 测试驱动开发：添加新功能前先编写测试
4. 文档：为所有 API 和工具编写适当的文档

获取帮助

开发过程中遇到问题时：

• 在 GitHub Issues 中报告错误
• 参阅项目 Wiki
• 查看 README.md、ARCHITECTURE.md 等文档

环境变量

可以使用以下环境变量自定义服务的行为：

• OPENAI_API_KEY：OpenAI API 密钥
• CLAUDE_API_KEY：Claude API 密钥
• LOG_LEVEL：日志级别（DEBUG、INFO、WARNING、ERROR）
• MOCK_TTS：启用模拟模式（true/false）
• PORT：服务端口号（默认值：8080）

故障排除

1. Docker 相关问题

• 如果镜像构建失败：

  # キャッシュを使用せずにビルド
  make build-no-cache
  

• 如果容器无法启动：

  # ログを確認
  docker logs kokoro-mcp-server
  

2. PyOpenJTalk 相关问题

如果出现与 CMake 版本相关的错误：

# 環境変数を設定してインストール
CMAKE_POLICY_VERSION_MINIMUM=3.5 uv pip install pyopenjtalk

至此，Kokoro MCP Server 的开发环境已准备就绪。祝编码愉快！