# Docs Query MCP - Node.js

> 🚀 100% Node.js / TypeScript + 本地嵌入模型实现，可直接通过 `npx @jaxsonwang/docs-mcp <command>` 使用。

这是一个原生 Node.js/TypeScript 项目，所有功能都封装为 npm 包，可通过 `npm install` 本地运行，也可以在未克隆仓库的情况下用 `npx` 直接拉起 CLI。摄取目标不限于某个特定仓库，只要是 Markdown/MDX 文档（或你扩展的扩展名），即可构建本地向量索引与 MCP 工具，对任意项目实现“提取→检索→MCP 暴露”的通用流程。

## 亮点

- **通用文档提取**：任意 Markdown/MDX 目录都能摄取；你可为公司知识库、产品手册或博客生成同一套索引与 MCP 工具。
- **纯 Node 环境**：无需额外 runtime，直接 `npm install` 即可构建。
- **只支持本地模型**：默认使用 `@xenova/transformers` 提供的量化版 `Xenova/bge-base-zh-v1.5`，完全离线。
- **多入口 CLI**：`ingest-docs`、`query-docs`、`mcp-docs-server` 三个命令可单独执行，也可通过总入口 `docs-mcp <command>` 运行，方便 `npx` 调用（`npx @jaxsonwang/docs-mcp <command>`）。
- **统一持久化**：索引以 `storage/llamaindex/index.json` 存储，`ingest` / `query` / `MCP` 共用该文件。
- **FastMCP 支持**：`mcp-docs-server` 用 @modelcontextprotocol/sdk 暴露 `docs_query` 工具，CLI 可以直接挂载。

## 快速开始

```bash
# 1) 安装依赖并构建 TypeScript
npm install
npm run build

# 2) 摄取文档（示例：中英文文档库）
node dist/bin/ingest-docs.js \
  --docs-root ../your-docs-repo/docs/zh:zh \
  --docs-root ../your-docs-repo/docs/en:en \
  --persist-dir storage/llamaindex --clean

# 3) 查询
node dist/bin/query-docs.js "如何自定义导航栏？" --model raw

# 4) 启动 MCP 服务器（stdio）
node dist/bin/mcp-docs-server.js --persist-dir storage/llamaindex
```

### `npx` 使用方式

发布到 npm 之后，可直接通过下列命令远程执行（无需克隆）：

```bash
npx @jaxsonwang/docs-mcp ingest \
  --docs-root /abs/path/docs/zh:zh --persist-dir storage/llamaindex --clean

npx @jaxsonwang/docs-mcp query "How do I customize navigation?" --model raw

npx @jaxsonwang/docs-mcp mcp --persist-dir storage/llamaindex --default-k 6
```

`npx @jaxsonwang/docs-mcp <command>` 会根据 `<command>` 派发到对应二进制；如果你更喜欢直接调用，也可以 `npx @jaxsonwang/docs-mcp ingest-docs ...`。

## 命令详解

### ingest-docs

```bash
npx @jaxsonwang/docs-mcp ingest \
  --docs-root /abs/path/docs/en:en \
  --docs-root /abs/path/docs/zh:zh \
  --persist-dir storage/llamaindex --clean \
  --embedding-model Xenova/bge-base-zh-v1.5 \
  --chunk-size 750 --chunk-overlap 120
```

- `--docs-root PATH[:LANG]`：可重复传入，默认 `docs/en:en`。语言标签写入 metadata，用于后续过滤。
- `--persist-dir`：索引输出目录（默认 `storage/llamaindex`）。加 `--clean` 会先删除旧索引。
- `--extensions`：默认 `.md .mdx`。
- `--embedding-model`：任意 `@xenova/transformers` 支持的[本地模型](https://huggingface.co/models?sort=trending&search=Xenova%2Fbge)（建议 `Xenova/bge-base-zh-v1.5` / `Xenova/bge-base-en-v1.5`）。

摄取完成后会在 `persistDir/index.json` 写入：

```json
{
  "version": 1,
  "embeddingModel": "Xenova/bge-base-zh-v1.5",
  "documents": [
    {
      "id": "zh-0",
      "text": "...chunk...",
      "metadata": { "path": "guide/getting-started.md", "lang": "zh", "section": "guide" },
      "embedding": [0.01, -0.02, ...]
    }
  ]
}
```

### query-docs

```bash
npx @jaxsonwang/docs-mcp query "How do I customize navigation?" \
  --persist-dir storage/llamaindex --k 5 --model raw
```

- `--model`：`raw`（打印 prompt）、`codex|claude|gemini`（将 prompt 写入对应 CLI 的 stdin）、`mcp`（输出 JSON，方便管道）。
- `--cli-path`：当 `--model codex|claude|gemini` 时，覆盖默认 CLI 路径。
- `--embedding-model`：需要与 ingest 阶段一致，否则会提示警告。

### mcp-docs-server

```bash
npx @jaxsonwang/docs-mcp mcp \
  --persist-dir storage/llamaindex \
  --embedding-model Xenova/bge-base-zh-v1.5 \
  --default-k 4
```

- 以 stdio 模式运行 FastMCP 服务器，暴露 `docs_query({ question, k? })`。
- `k` 省略时回退到 `--default-k`。
- MCP 客户端配置示例：

```json
{
  "servers": {
    "docs_mcp": {
      "command": "npx",
      "args": ["@jaxsonwang/docs-mcp", "mcp", "--persist-dir", "/abs/path/storage/llamaindex"]
    }
  }
}
```

## 本地嵌入模型

项目只依赖 `@xenova/transformers`，默认启用 `env.allowLocalModels = true` 并加载量化模型。首次运行会自动在 `~/.cache` 下载一次模型文件（约 400MB），后续命令复用缓存。

- 如果需要英文数据集，推荐 `Xenova/bge-base-en-v1.5`。
- 如需更大的跨语模型，可切换 `Xenova/bge-m3`，但内存占用也会更高。

## 目录结构

```
.
├── package.json
├── tsconfig.json
├── src/
│   ├── bin/               # CLI 入口
│   ├── commands/          # ingest/query/mcp 实现
│   └── core/              # chunking、embedding、存储等工具
├── dist/                  # tsc 输出
└── storage/llamaindex     # 索引输出（未提交）
```

## License

MIT