Lumi

对 Hermes Agent 暴露带用户隔离语义的 WeKnora MCP 代理工具（错题库检索、错题列表、作业统计、小孩列表）。本服务独立于主后端部署，对 PostgreSQL 只读。

工具列表

工具	说明
search_user_mistakes	按学科检索当前小孩的错题库（WeKnora 混合检索 + 按小孩过滤）
list_user_mistakes	从 PostgreSQL 列出最近错题
get_homework_summary	作业检查统计
list_user_students	列出当前用户的小孩
web_search	网络搜索（自建 SearXNG 聚合搜索，JSON API），替代易被反爬的裸爬
read_web_page	通过 r.jina.ai 阅读器代理读取网页为 markdown，可打开电商等反爬页面

前 4 个工具调用需传 conversation_id，服务根据会话解析用户，实现用户隔离；web_search / read_web_page 是公共工具，无需 conversation_id。

配置

复制 .env.example 为 .env，修改：

• DATABASE_URL：Lumi 主库连接串（建议配只读账号）
• WEKNORA_BASE_URL / WEKNORA_API_KEY：WeKnora 连接
• SEARXNG_BASE_URL：web_search 工具使用的自建 SearXNG 地址（需已开启 json 输出格式）
• MCP_PROXY_API_KEY：SSE 接口鉴权密钥，Hermes 通过 Authorization: Bearer 传递

启动

Docker（推荐）

本服务有独立的 docker-compose.yml，通过 external 方式加入主项目的 lumi-network（访问 PostgreSQL、被 Hermes 访问），因此需先启动主项目栈（根目录 docker-compose up -d）：

cd mcp-server
cp .env.example .env   # 首次，按需修改
docker-compose up -d --build

本地开发

cd mcp-server
python -m venv venv
# Windows: venv\Scripts\activate    macOS/Linux: source venv/bin/activate
pip install -r requirements.txt

# SSE 模式，端口 8001
uvicorn app.mcp_sse:mcp_sse_app --host 0.0.0.0 --port 8001 --reload

# stdio 模式（供 Hermes 作为子进程启动）
python -m app.mcp_proxy_server

Hermes 接入

mcp_servers:
  lumi_weknora_proxy:
    transport: sse
    # Docker 网络内使用服务名；本机直连用 http://localhost:8001/sse
    url: http://mcp-server:8001/sse
    headers:
      Authorization: "Bearer 与 MCP_PROXY_API_KEY 相同的值"

维护约定

app/models.py 是主库 5 张表（conversations、students、user_knowledge_bases、homework_checks、homework_mistakes）的只读镜像。新增迁移脚本或 backend/app/models.py 中对应表结构变更时，必须同步修改本文件。