book-mcp/docs/deploy.md

# book-mcp 部署文档

## 架构

```
Agent (任意 Agent 客户端)
   ↓ HTTP/JSON-RPC
book-mcp (8100) ──┬─→ MongoDB (27018/book_mcp) ← docker container
                  └─→ RustFS (fs.code-lab.cn/scan/) ← 对象存储
                  └─→ wordparse (8089) ← docker container docx4j
```

## 组件

| 组件 | 位置 | 端口 | 启动方式 |
|---|---|---|---|
| **book-mcp** | `~/WorkSpace/book-mcp/book_mcp_server.py` | 8100 | launchd `ai.book-mcp.server` |
| **MongoDB** | docker container `book-mcp-mongo` | 27018 | `docker start book-mcp-mongo` |
| **RustFS** | `fs.code-lab.cn` | 443 | 远程 |
| **wordparse (docx4j)** | docker container `wordparse-test` | 8089 | `docker start wordparse-test` |

## 安装（一次性）

### 1. MongoDB 容器

```bash
docker run -d \
  --name book-mcp-mongo \
  -p 27018:27017 \
  -e MONGO_INITDB_ROOT_USERNAME=book_admin \
  -e MONGO_INITDB_ROOT_PASSWORD=book_mongo_2026 \
  -e MONGO_INITDB_DATABASE=book_mcp \
  -v book-mcp-mongo-data:/data/db \
  --restart unless-stopped \
  mongo:8.0
```

### 2. Python venv（一次性）

```bash
python3.13 -m venv /tmp/wordparse_venv
/tmp/wordparse_venv/bin/pip install -r ~/WorkSpace/book-mcp/requirements.txt
```

依赖：`fastmcp boto3 pymongo pyyaml`

### 3. MongoDB 索引

```bash
/tmp/wordparse_venv/bin/python ~/WorkSpace/book-mcp/book_mcp_server.py --init-db
```

输出：
```
✓ MongoDB 已就绪（db: book_mcp, collections: [...]）
  ✓ 8 个索引创建完成
```

### 4. LaunchAgent

```bash
# 装（已装好：~/Library/LaunchAgents/ai.book-mcp.server.plist）
launchctl load -w ~/Library/LaunchAgents/ai.book-mcp.server.plist
```

## 日常运维

### 状态查询

```bash
# launchd 状态
launchctl print gui/501/ai.book-mcp.server | grep -E "state|pid"

# 端口
lsof -i :8100

# 健康
curl http://127.0.0.1:8100/mcp
# fastmcp 在 /mcp 走 HTTP

# 实时日志
tail -f ~/.hermes/services/book-mcp/logs/server.log
```

### 重启

```bash
# 软重启（SIGTERM，launchd 30s ThrottleInterval）
kill $(lsof -ti :8100)

# launchd 自动拉起
sleep 5
ps aux | grep book_mcp_server | grep -v grep
```

### 调试

```bash
# 1. 跑 e2e 测试
/tmp/wordparse_venv/bin/python ~/WorkSpace/book-mcp/tests/test_e2e.py

# 2. 直接调 MCP 工具（fastmcp client）
/tmp/wordparse_venv/bin/python << 'PYEOF'
import asyncio
from fastmcp.client import Client
async def main():
    async with Client("http://127.0.0.1:8100/mcp") as c:
        r = await c.call_tool('health', {})
        print(r.data)
asyncio.run(main())
PYEOF

# 3. mongo 直连
/tmp/wordparse_venv/bin/python << 'PYEOF'
from db import get_collection, COL_BOOK
print(f"books count: {get_collection(COL_BOOK).count_documents({})}")
PYEOF
```

## 配置

`~/WorkSpace/book-mcp/config.yaml`：

```yaml
server:
  port: 8100          # MCP server 端口
database:
  url: mongodb://book_admin:book_mongo_2026@127.0.0.1:27018/book_mcp?authSource=admin
  db_name: book_mcp
rustfs:
  endpoint: https://fs.code-lab.cn
  default_bucket: scan
wordparse:
  url: http://127.0.0.1:8089/api/v3/server_office_file/file/parse
  timeout: 600
```

## MCP 工具列表（15 个）

| # | 工具 | 类别 |
|---|---|---|
| 1 | create_book | 写入 |
| 2 | add_document | 写入 |
| 3 | mark_html_ready | 写入 |
| 4 | mark_json_ready | 写入 |
| 5 | mark_failed | 写入 |
| 6 | update_book_status | 写入 |
| 7 | get_book | 查询 |
| 8 | list_books | 查询 |
| 9 | get_document | 查询 |
| 10 | list_documents | 查询 |
| 11 | get_document_url | 查询 |
| 12 | upload_to_rustfs | 辅助 |
| 13 | soft_delete_book | 辅助 |
| 14 | retry_failed | 辅助 |
| 15 | health | 诊断 |

## 数据流

```
zip 上传 RustFS
  ↓ create_book(zip_sha256)
  → book.id
  ↓ 循环每 docx
  → add_document(filename, path)
  → doc.doc_id = sha1(book_id|path)[:16]
  → wordparse.convert_one (cleaner + docx4j + MathJax)
  → RustFS upload → mark_html_ready(url)
  → Agent 解析 HTML → structure.json
  → RustFS upload → mark_json_ready(url)
  → update_book_status("done")
```

## 故障排查

| 现象 | 原因 | 解决 |
|---|---|---|
| `mongo` health=False | 容器没起 | `docker start book-mcp-mongo` |
| `wordparse` health=False | docx4j 容器没起 | `docker start wordparse-test` |
| 8100 端口未 listen | 进程挂了 | `kill $(lsof -ti :8100)` 走 launchd 自动拉起 |
| `add_document` 报 NoneType | 数据库索引问题（已修复） | 重跑 `--init-db` |
| 上传 403 Forbidden | 桶不存在 | 检查 `default_bucket` 是否在 RustFS 实际存在 |
| e2e 测试报 `uk_name_version` | 同名教辅已存在 | 改 name 或 version 加时间戳 |

## 备份

- **MongoDB 数据**：`book-mcp-mongo-data` docker volume（在 docker 里）
- **RustFS 文件**：`https://fs.code-lab.cn/scan/book/<book_id>/...`
- **代码**：`~/WorkSpace/book-mcp/`

## 升级路径

```bash
# 1. 拉新代码
cd ~/WorkSpace/book-mcp
git pull  # 假设推到 git

# 2. 升级依赖
/tmp/wordparse_venv/bin/pip install -r requirements.txt --upgrade

# 3. 重启 launchd
kill $(lsof -ti :8100)
sleep 5
ps aux | grep book_mcp_server | grep -v grep
```

## 相关链接

- 设计文档：`docs/book-mcp-design.md`
- Schema：`db/schema_doc.md`
- wordparse 工具：`services/wordparse/`
- 启动日志：`~/.hermes/services/book-mcp/logs/server.log`
- 错误日志：`~/.hermes/services/book-mcp/logs/server.error.log`