AI导哈

聊天AI服务器

一个基于MCP协议的对话式AI角色聊天服务器，提供用户管理、对话历史存储和基础聊天功能。

  • by waifuai
  • Python
  • 本地部署
  • 4 星标
  • 更新于
在 GitHub 查看 waifuai/mcp-waifu-chat

使用说明

MCP外富聊天服务器

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

特性

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

需求

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

安装

  1. 克隆存储库：

    git clone <repository_url>
cd mcp-waifu-chat

  2. 安装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

  2. 安装依赖项：

    .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

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

其他配置(.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端口。根据需要调整工人数量和端口。

  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配置，包括测试数据库和测试客户端的夹具。
    • test_db.py：单元测试 db.py 模块。
    • test_api.py：中API终结点的单元测试 api.py.
  • run.py:：运行服务器的简单文件（注意： uv run mcp-waifu-chat 是优选的）。

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

相关 MCP