MCP Waifu Chat Server

MCP Waifu 聊天服务

此项目实现了一个基础的 MCP（Model Context Protocol）服务，用于对话式 AI「waifu」角色。它使用 Python 的 mcp 库处理协议细节，并通过 FastMCP 轻松搭建服务。

功能

• 用户管理（创建、检查是否存在、删除、计数）
• 对话历史存储（获取、设置、重置）
• 基础聊天功能（使用 OpenRouter API）
• 采用模块化设计，便于扩展
• 通过环境变量和 API 密钥文件进行配置
• 使用 SQLite 数据库持久化数据
• 全面的单元测试

要求

• Python 3.10+
• uv
• OpenRouter API 密钥

安装

1. 克隆代码仓库：

   git clone <repository_url>
   cd mcp-waifu-chat
   

2. 安装 uv（如果尚未安装） 使用 curl：

   curl -LsSf https://astral.sh/uv/install.sh | sh
   

或使用 powershell：

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

3. 创建虚拟环境并确保其中已安装所需工具：

   python -m uv venv .venv
   .venv/Scripts/python.exe -m ensurepip
   .venv/Scripts/python.exe -m pip install uv
   

4. 安装依赖项：

   .venv/Scripts/python.exe -m uv pip install -e .[test]
   

配置

服务通过 API 密钥文件和环境变量（或 .env 文件）进行配置。

API 密钥：

OpenRouter（默认）：

• 优先使用环境变量：OPENROUTER_API_KEY
• 备用方式：单行密钥文件 ~/.api-openrouter
• 模型选择优先级：
  1. OPENROUTER_MODEL_NAME
  2. ~/.model-openrouter
  3. openrouter/free

你可以从 OpenRouter 获取密钥。

其他配置（.env 文件或环境变量）： 项目提供了一个 .env.example 示例文件，用于配置其他设置：

DATABASE_FILE=dialogs.db
DEFAULT_RESPONSE="I'm sorry, I'm having trouble connecting to the AI model."
DEFAULT_GENRE="Fantasy"
FLASK_PORT=5000
OPENROUTER_MODEL_NAME=openrouter/free

• DATABASE_FILE：SQLite 数据库文件的路径（默认值：dialogs.db）。
• DEFAULT_RESPONSE：AI 模型不可用时发送的默认回复（默认值：「AI 模型目前不可用，请稍后再试。」）。
• DEFAULT_GENRE：默认对话类型（默认值：「Romance」）。
• FLASK_PORT：服务监听的端口（默认值：5000）。
• OPENROUTER_MODEL_NAME：要使用的特定 OpenRouter 模型（默认值：openrouter/free）。

将 .env.example 复制为 .env，并根据需要自定义各项值（API 密钥除外，该密钥从 ~/.api-openrouter 读取）。

运行服务

确保已正确设置 ~/.api-openrouter 文件。然后使用以下命令运行服务：

uv run mcp-waifu-chat

这会运行 mcp_waifu_chat/api.py 文件（FastMCP 实例在此文件中定义），并启动服务。

运行测试

运行单元测试：

uv run pytest

这将使用 pytest 执行 tests/ 目录中的所有测试。测试包括数据库测试和 API 端点测试。

API 端点

服务提供以下符合 MCP 规范的端点（使用 FastMCP 的自动路由）：

服务状态

• /v1/server/status (GET)：检查服务状态。返回 {"status": "ok"}。这是一个标准 MCP 端点。

用户管理工具

这些功能以 MCP 工具的形式实现。

• create_user (user_id: str)：创建新用户。
• check_user (user_id: str)：检查用户是否存在。返回 {"user_id": str, "exists": bool}。
• delete_user (user_id: str)：删除用户。
• user_count：返回当前用户在数据库中的用户数量。

对话管理工具

• reset_dialog (user_id: str)

资源

• /v1/user/dialog/json/{user_id}：动态资源，以 JSON 格式返回对话。
• /v1/user/dialog/str/{user_id}：动态资源，以字符串形式返回对话。

聊天工具

• chat (message: str, user_id: str)：发送聊天消息，并获取由 OpenRouter 生成的回复。

LLM 集成（OpenRouter）

mcp_waifu_chat/ai.py 中的调度器会选择提供商并生成响应。

提供商：openrouter

模型解析优先级：

• OpenRouter 模型名称：使用 OPENROUTER_MODEL_NAME 环境变量；否则使用 ~/.model-openrouter；否则使用 openrouter/free。

凭据：

• OpenRouter：使用 OPENROUTER_API_KEY 环境变量；否则使用 ~/.api-openrouter。

调用方式：

• OpenRouter：向 https://openrouter.ai/api/v1/chat/completions 发送 HTTPS POST 请求，并附带一条用户消息。

此流程包含防御性解析和错误处理；服务不可用时会返回 config.default_response。

部署到生产环境

在生产环境部署时，你应该：

1. **使用适用于生产环境的 WSGI/ASGI 服务端：**推荐使用 Gunicorn，且已在 pyproject.toml 中包含。命令示例：

   gunicorn --workers 4 --bind 0.0.0.0:8000 mcp_waifu_chat.api:app -k uvicorn.workers.UvicornWorker
   

   该命令会使用由 Gunicorn 管理的 4 个 Uvicorn 工作进程，在端口 8000 上运行 mcp_waifu_chat/api.py 中的 app 对象（我们的 FastMCP 实例）。请根据需要调整工作进程数量和端口。

2. **使用可靠的数据库：**考虑使用 PostgreSQL 或 MySQL 替代 SQLite，以提高并发能力和可扩展性。

3. **实施适当的日志记录：**配置日志，将日志写入文件、集中式日志服务或监控系统。

4. **保护服务器安全：**使用 HTTPS，实施身份验证和授权，并遵循 Web 应用的安全最佳实践。

5. **考虑使用反向代理：**使用 Nginx 或 Apache 等反向代理处理 TLS 终止、负载均衡和静态文件服务。

6. 容器化 使用 Docker 简化部署。

项目结构说明

• mcp_waifu_chat/（主包）：
  • __init__.py：将目录设为 Python 包。
  • api.py：核心 FastMCP 应用、工具和资源定义，以及请求处理逻辑。
  • config.py：负责加载和验证配置项。
  • db.py：所有数据库交互逻辑（建表、查询、更新）。
  • models.py：用于请求和响应数据验证及序列化的 Pydantic 模型。
  • utils.py：辅助函数，例如 dialog_to_json 和 json_to_dialog。
  • ai.py：此模块负责与 OpenRouter API 交互。
• tests/（测试套件）：
  • conftest.py：pytest 配置，包括测试数据库和测试客户端的 fixtures。
  • test_db.py：针对 db.py 模块的单元测试。
  • test_api.py：针对 api.py 中 API 端点的单元测试。
• run.py：：用于运行服务端的简单文件（注意：更推荐使用 uv run mcp-waifu-chat）。

此结构提升了模块化、可测试性和可维护性。每个模块都有明确的职责，因此更容易理解、修改和扩展代码库。