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

PyOpenJTalk 在 Windows 上的安装可能需要额外的设置：

# Linux 情况下
CMAKE_POLICY_VERSION_MINIMUM=3.5 uv pip install pyopenjtalk

# Windows 情况下
$env:CMAKE_POLICY_VERSION_MINIMUM = "3.5"; uv pip install pyopenjtalk

# 如果安装有问题，尝试构建好的 wheel
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. 使用 Mock 模式

为了在没有 Kokoro 语音合成引擎的环境中也能进行开发，可以使用 Mock 模式：

# 在 Mock 模式下运行
MOCK_TTS=true python src/main.py

测试环境

1. 运行测试

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

2. 测试用客户端

Docker 环境

1. 构建和运行 Docker 容器

# 构建镜像
make build

# 启动容器
make up

# 查看日志
make logs

# 在容器内执行 shell
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

# 在开发模式下启动容器（使用 Mock TTS）
make dev

调试手法

1. 启用调试日志

要查看详细的调试信息，请调整日志级别。

# 启用调试日志并运行
python src/main.py --log-level debug

2. 使用 Python Debugger

可以使用 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 进行 Lint

# 代码 Lint
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: 启用 Mock 模式（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 的开发环境已经准备就绪。祝您编码愉快！