MCP Waifu Chat

MCP外富聊天服务器

该项目为对话式AI“waifu”角色实现了一个基本的MCP（模型上下文协议）服务器。它使用 mcp Python库，用于处理协议细节和 FastMCP 便于服务器设置。

特性

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

需求

• Python 3.10+
• uv
• 一个OpenRouter API密钥

安装

1. 克隆存储库：

   git clone 
   cd mcp-waifu-chat

1. 安装uv（如果未安装）

卷曲：

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

或者使用powershell：

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

1. 创建虚拟环境并确保其中的工具：

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

1. 安装依赖项：

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

配置

服务器使用API键的文件和环境变量的组合（或 .env 文件）用于其他配置。

API密钥：

OpenRouter（默认）：

• 首选通过环境变量： OPENROUTER_API_KEY
• 回退：单行密钥文件 ~/.api-openrouter
• 模型分辨率优先级：

1. OPENROUTER_MODEL_NAME 1. ~/.model-openrouter 1. openrouter/free

您可以从以下位置获取密钥 开放路由.

其他配置(.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：默认对话类型（默认：“浪漫”）。
• 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

这将执行 tests/ 目录使用 pytest。测试包括数据库测试和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 （用户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 env；否则 ~/.model-openrouter；否则 openrouter/free.

资格证书：

• OpenRouter： OPENROUTER_API_KEY env；否则 ~/.api-openrouter.

呼叫模式：

• OpenRouter：HTTPS POST到https://openrouter.ai/api/v1/chat/completions使用单个用户消息。

该路径包括防御性解析和错误处理，返回 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

这运行 app 对象（our FastMCP 实例）从 mcp_waifu_chat/api.py 使用由Gunicorn管理的4名Uvicorn工人，监听8000端口。根据需要调整工人数量和端口。

1. 使用强大的数据库： 考虑PostgreSQL或MySQL而不是SQLite，以获得更高的并发性和可扩展性。

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

1. 保护您的服务器： 使用HTTPS，实施身份验证/授权，并遵循web应用程序的安全最佳实践。

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

1. 容器化 使用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配置，包括测试数据库和测试客户端的夹具。 - test_db.py：单元测试 db.py 模块。 - test_api.py：中API终结点的单元测试 api.py.

• run.py:：运行服务器的简单文件（注意： uv run mcp-waifu-chat 是优选的）。

这种结构促进了模块化、可测试性和可维护性。每个模块都有特定的职责，使其更容易理解、修改和扩展代码库。