# lore-mcp-server

把 **LoreRAG**（《明日方舟》世界观 RAG 问答）的「混合检索 + 问答生成」封装成 **MCP（Model Context Protocol）工具**，供 [DeepSeek Harness（dsh）](https://github.com/deepseek-ai/dsh)、Claude Code 等任何 MCP client 通过 stdio 调用。

> 核心逻辑来自 `LoreRAG/scripts/`（`hybrid_search.py` / `generate.py` / `term_aliases.py`），本项目只做「路径抽离 + MCP 封装」，检索/生成算法原样保留。

## 数据流

```
用户问题
   │
   ▼
lore-mcp (stdio)
   ├─ search_lore ──► HybridSearcher ──► BM25 + 向量(RRF 融合) + 术语置顶
   │                       │
   │                       ├─ 向量召回：llama-server /embedding (8080)
   │                       └─ 词面召回：ChromaDB 内建 BM25 缓存
   ├─ ask_lore ──► search_lore + generate.ask ──► llama-server /v1/chat (8081)
   └─ list_lore_terms ──► 语料术语定义表
```

- **embedding 端点**（默认 `http://127.0.0.1:8080`）：Qwen3-Embedding-4B-Q8_0，`--pooling last`
- **chat 端点**（默认 `http://127.0.0.1:8081`）：Qwen3-8B-Q4_K_M（服务器上可换 Qwen3-0.6B）
- **索引**：ChromaDB（30,870 chunks × 2560 维）+ BM25 缓存，位于 `LORERAG_ROOT/index/`

## 目录结构

```
lore-mcp-server/
├── config.py           # 路径/端口集中配置，环境变量可覆盖
├── server.py           # FastMCP 入口 + 3 个工具（懒加载检索器）
├── hybrid_search.py    # BM25+向量混合检索（RRF + 术语置顶）
├── generate.py         # 封闭式问答生成（句尾 [资料N] 标注）
├── term_aliases.py     # 术语别名 → query 扩展
├── requirements.txt
└── docs/deploy-server.md   # 服务器部署 + 换 Qwen3-0.6B + swap
```

## 依赖

### Python

```bash
pip install -r requirements.txt
```

| 包 | 用途 |
|---|---|
| `mcp` | MCP SDK（含 `FastMCP`，stdio 传输） |
| `chromadb` | 向量库（PersistentClient） |
| `jieba` | 中文分词（BM25 关键词） |
| `rank-bm25` | BM25 检索实现 |

### 模型 + llama.cpp（需先于本服务运行）

| 角色 | 模型 | 端点 |
|---|---|---|
| embedding | Qwen3-Embedding-4B-Q8_0 | `:8080`（`/embedding`） |
| 生成 | Qwen3-8B-Q4_K_M（弱机换 0.6B） | `:8081`（`/v1/chat/completions`） |

启动命令见 `LoreRAG/scripts/run_llama_server.cmd` / `run_chat_server.cmd`。

## 快速开始（本地）

```bash
# 1. 启动两个 llama-server（embedding :8080 + chat :8081）—— 见 LoreRAG/scripts/
# 2. 装依赖
pip install -r requirements.txt
# 3. 启动 MCP（默认读 ../LoreRAG 的索引）
python server.py
```

## 工具

| 工具 | 说明 | 关键参数 |
|---|---|---|
| `search_lore` | 混合检索，返回 top-k 命中 | `query`, `k=5`, `type_filter=""` |
| `ask_lore` | 检索 + 生成，句尾标注 `[资料N]` | `query`, `k=5`, `max_tokens=512` |
| `list_lore_terms` | 列出语料术语定义清单 | — |

所有工具返回 JSON 字符串（`ensure_ascii=False`）。

## 环境变量

| 变量 | 默认值 | 说明 |
|---|---|---|
| `LORERAG_ROOT` | `../LoreRAG`（相对本仓库） | 含 `index/chroma`、`index/hybrid_cache.pkl` 的 LoreRAG 根目录 |
| `LORERAG_EMBED_URL` | `http://127.0.0.1:8080` | embedding 端点 |
| `LORERAG_CHAT_URL` | `http://127.0.0.1:8081/v1/chat/completions` | chat 端点 |

## 接入 DeepSeek Harness（dsh）

dsh 通过 `@deepseek-ai/dsh-mcp-client` 插件注册 MCP server。在 web profile 的
`cordis.patch.yml`（如 `~/.dsh/profiles/web/cordis.patch.yml`）追加：

```yaml
- id: mcp-lore
  name: '@deepseek-ai/dsh-mcp-client'
  config:
    serverName: lore
    transport: stdio
    command: python
    args: ['server.py']
    cwd: D:/dev/lore-mcp-server        # 换成你的仓库路径
    env:
      LORERAG_ROOT: D:/dev/LoreRAG     # 换成你的 LoreRAG 根目录
      LORERAG_EMBED_URL: http://127.0.0.1:8080
      LORERAG_CHAT_URL: http://127.0.0.1:8081/v1/chat/completions
```

注册后，三个工具在 dsh 里暴露为：

- `mcp__lore__search_lore`
- `mcp__lore__ask_lore`
- `mcp__lore__list_lore_terms`

> `serverName` 只能是 `[A-Za-z0-9_-]{1,32}`；`command`/`args`/`cwd` 走 stdio 拉起本服务。

## 部署到弱性能服务器

换小生成模型（Qwen3-0.6B）、换小 embedding、加 swap 的完整步骤见
**[docs/deploy-server.md](docs/deploy-server.md)**。