# wiki-mcp — 公司项目知识库 MCP Server

把项目资料（原理图说明、客户需求、接口约定等）向量化入库，通过 MCP 协议
提供给 Claude Code 做检索增强（对应《AI Coding 系统项目规划书》§4.3 / P3 阶段）。

- **完全离线可运行**：embedding 用本地 ONNX 模型（fastembed + bge-small-zh），纯 CPU 即可，无外部依赖。
- **格式支持**：Markdown / txt / Word (.docx) / Excel (.xlsx) / PDF。
- **按项目授权**：Bearer token → 可访问项目列表，检索与读取都强制过滤。
- **MCP 工具**：`search_wiki`（语义检索）、`read_doc`（读全文）、`list_projects`。

> **安全红线**：本仓库只含代码与模拟数据。真实业务资料只在公司内网
> （Server A）上入库，绝不进入外部开发环境。MCP 返回的文档内容一律视为
> 不可信输入（防 prompt injection，见规划书 §07）。

## 快速开始（开发环境）

```bash
python3 -m venv .venv && .venv/bin/pip install -e .
cp config.example.yaml config.yaml
cp tokens.example.yaml tokens.yaml        # 改成真实 token，勿提交 git

# 用模拟数据验证
.venv/bin/python scripts/make_sample_office_docs.py
.venv/bin/wiki-mcp ingest sample_data/demo-alpha -p demo-alpha
.venv/bin/wiki-mcp ingest sample_data/demo-beta  -p demo-beta
.venv/bin/wiki-mcp search "温度采集用的什么芯片"   # 本地测检索
.venv/bin/wiki-mcp serve                            # http://0.0.0.0:9000/mcp
```

## CLI

| 命令 | 说明 |
| --- | --- |
| `wiki-mcp ingest <目录> -p <项目> [--wipe]` | 入库（--wipe 先清空该项目） |
| `wiki-mcp serve` | 启动 MCP server |
| `wiki-mcp search "<问题>" [-p 项目] [-k N]` | 本地测试检索（不走鉴权） |
| `wiki-mcp projects` | 列出库中项目 |

## Claude Code 侧接入

项目仓库的 `.mcp.json`（模板见 team-skills 仓库）：

```json
{
  "mcpServers": {
    "company-wiki": {
      "type": "http",
      "url": "https://server-a.internal:9000/mcp",
      "headers": { "Authorization": "Bearer ${WIKI_TOKEN}" }
    }
  }
}
```

工程师在 shell profile 里 `export WIKI_TOKEN="wk-个人token"`。

## 部署到 Server A

### 方式一：在线部署（Server A 能出网时，推荐）

Server A 为 Ubuntu 22.04 时，先装 Python 3.12（与开发环境一致；
系统自带的 3.10 理论兼容但未做测试）：

```bash
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt install python3.12 python3.12-venv
```

然后：

```bash
git clone <本仓库地址> /opt/wiki-mcp && cd /opt/wiki-mcp
python3.12 -m venv .venv
# 国内服务器 pip 建议走镜像：
.venv/bin/pip install -e . -i https://pypi.tuna.tsinghua.edu.cn/simple
cp config.example.yaml config.yaml
cp tokens.example.yaml tokens.yaml    # 生成真实 token
# 国内服务器连不上 huggingface.co，首次 ingest 前设置 HF 镜像：
export HF_ENDPOINT=https://hf-mirror.com
.venv/bin/wiki-mcp ingest <内网文档目录> -p <项目名>
.venv/bin/wiki-mcp serve
```

模型只在首次下载，之后缓存在 `models/`，运行期不再依赖外网。

### 方式二：离线包部署（备选，Server A 不能出网时）

1. 在本机（能上网、与 Server A 同为 linux x86_64、Python 大版本一致）执行：
   `bash scripts/build_offline_bundle.sh` → 产出 `wiki-mcp-offline-bundle.tar.gz`
   （含依赖 wheels + embedding 模型 + 源码 + 安装脚本）。
2. 拷贝到 Server A：`tar xzf ... && cd offline_bundle && ./install.sh`。
3. 配置 `config.yaml` / `tokens.yaml`，对内网文档目录执行 `ingest`，再 `serve`。

注意：wheels 与构建机的平台/Python 版本绑定（当前包为 linux x86_64 + cp312）。

### systemd 示例

```ini
[Unit]
Description=wiki-mcp knowledge base MCP server
After=network.target

[Service]
User=wikimcp
WorkingDirectory=/opt/wiki-mcp
ExecStart=/opt/wiki-mcp/.venv/bin/wiki-mcp serve
Restart=always

[Install]
WantedBy=multi-user.target
```

### TLS

服务本身是明文 HTTP，生产环境在前面放 nginx/caddy 做 TLS 终结
（内网也要 HTTPS，token 不能明文过网），Claude Code 侧 URL 用 `https://`。

## 运维要点

- **token 生命周期**：入职添加、离职删除（tokens.yaml 改后重启服务）、定期轮换。
- **换 embedding 模型**：整库重建（删除 `data/wiki.db` 后全部重新 ingest），
  库内 meta 会校验模型一致性，混用会报错。
- **检索质量升级（可选）**：默认 bge-small-zh 纯 CPU 毫秒级，wiki 规模够用。
  若试点后觉得检索质量不足，改 `config.yaml` 的 `model: BAAI/bge-m3` 并重建库；
  bge-m3 在 CPU 上入库偏慢，Server A 有 GPU 时可
  `pip install fastembed-gpu` 替换 fastembed 加速（检索本身单条查询 CPU 也够）。
- **更新文档**：重跑 `ingest` 即可，按 `(project, path)` 覆盖更新。
- **规模**：brute-force 检索在 10 万 chunk 量级下毫秒级返回，wiki 规模足够；
  再大再考虑换专用向量库。