MCP 服务器

wiki-mcp

Retrieval-augmented MCP server for company project documents (Markdown, Word, Excel, PDF) with vector search, offline embedding, and token-based project authorization.

README

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）。

快速开始（开发环境）

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 仓库）：

{
  "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 理论兼容但未做测试）：

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

然后：

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 不能出网时）

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

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

systemd 示例

[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 规模足够；再大再考虑换专用向量库。