# Scripting Docs MCP

这个仓库提供一套最小可用的工具链：把 [`ScriptingApp/ScriptingApp.github.io`](https://github.com/ScriptingApp/ScriptingApp.github.io) 中的 Markdown/MDX 文档转为可检索的 LlamaIndex 索引，并通过 Model Context Protocol（MCP）对外暴露。同时还附带一个本地 CLI 检索脚本，方便将上下文灌入 Codex／Claude／Gemini 等命令行客户端。

## 核心特性

- **多语言索引**：`--docs-root PATH[:LANG]` 可重复传入，默认 `docs/en:en`，可一次构建中英文等多语向量库，语言标签写入元数据以供下游过滤。
- **嵌入后端可选**：默认使用 HuggingFace 上的 `BAAI/bge-base-zh-v1.5`（兼顾中英文，CPU/GPU 均可运行），也可切换 `--embed-backend openai` 与任意兼容模型名，方便在本地/云端之间切换。
- **可移植存储**：索引持久化至 `storage/llamaindex`，CLI 查询与 MCP 服务器共用该目录，便于共享部署。
- **CLI+MCP 双模式**：`query_docs.py` 输出可直接喂给 CLI 模型；`mcp_docs_server.py` 以 stdio 暴露 `scripting_docs_query`，为 Codex/Claude/Gemini CLI 提供统一工具。
- **最小依赖脚本**：3 个 Python 文件+一个 requirements，结构简单，易于自定义 chunking、扩展名过滤、清理策略等。

## 工作流总览

```
┌────────────┐   ┌─────────────┐   ┌────────────────────┐   ┌──────────────────┐
│ Markdown   │   │ ingest_docs │   │ storage/llamaindex │   │ query_docs / MCP │
│ docs/en zh │ → │ + Sentence  │ → │ VectorStore+config │ → │ LLM prompt构造    │
└────────────┘   │ splitter    │   └────────────────────┘   └──────────────────┘
                 │ + Embedding │
                 └─────────────┘
```

1. 从 `ScriptingApp.github.io/docs/<lang>` 读取 `.md/.mdx`，按语言打标签。
2. SentenceSplitter 切块后通过 HuggingFace 或 OpenAI 嵌入，写入统一 storage 目录。
3. `query_docs.py` 或 MCP 服务器加载同一持久化目录，检索 top-k chunk 并格式化上下文。
4. 输出可直接进入终端 LLM，或通过 `scripting_docs_query` 工具注入到 Codex/Claude/Gemini CLI。

> **提示**：本仓库不包含实际文档，请单独克隆官方文档仓库，并在摄取脚本中指向它的 `docs/en`、`docs/zh` 等目录。

## 目录结构

```
.
├── README.md                 # 使用指南（本文件）
├── requirements.txt          # Python 依赖（LlamaIndex、MCP SDK 等）
└── scripts/
    ├── ingest_docs.py        # 构建单/多语言文档向量库
    ├── query_docs.py         # 查询索引 / 分发到 CLI 模型
    └── mcp_docs_server.py    # FastMCP 服务器，提供 `scripting_docs_query`
```

## 环境要求

- Python 3.10+（已在 3.12/3.13 验证）
- 可访问 `ScriptingApp.github.io` 仓库中的英文/中文文档内容（按需选择）
- （可选）如需改用 OpenAI 嵌入，请准备 `OPENAI_API_KEY`

## 快速上手

1. **克隆文档仓库**
   ```bash
   git clone https://github.com/ScriptingApp/ScriptingApp.github.io.git
   ```

2. **安装 uv (Rust-based Python 包管理器)**
   `uv` 能够自动管理 Python 环境和依赖，推荐作为 `pip` 和 `venv` 的替代。
   如果尚未安装 `uv`，可以通过以下命令安装：
   ```bash
   curl -LsSf https://astral.sh/uv/install.sh | sh
   # 确保 uv 在你的 PATH 中，如果需要，请将其添加到你的 shell 配置文件中。
   ```

   > 如果你习惯 `pip/venv`，仍可运行 `uv pip install -r requirements.txt` 复现同一套依赖。

   **无需克隆的快捷方式**：仓库已发布 console script，可直接远程执行
   第一次运行会自动创建隔离环境并缓存依赖，后续命令可直接复用。推荐在任何改动入口点后本地执行以下 smoke test，确保 wiring 正常：
   ```bash
   uvx --from git+https://github.com/JaxsonWang/Scripting-Docs-MCP ingest-docs --help
   uvx --from git+https://github.com/JaxsonWang/Scripting-Docs-MCP query-docs --help
   uvx --from git+https://github.com/JaxsonWang/Scripting-Docs-MCP mcp-docs-server --help
   ```

3. **摄取文档 (使用 uv run / uvx)**
  ```bash
  uv run scripts/ingest_docs.py \
    --docs-root /path/to/ScriptingApp.github.io/docs/zh:zh \
    --persist-dir storage/llamaindex --clean
  # 或者（无需克隆）：
  uvx --from git+https://github.com/JaxsonWang/Scripting-Docs-MCP ingest-docs \
    --docs-root /path/to/ScriptingApp.github.io/docs/zh:zh \
    --persist-dir storage/llamaindex --clean
  ```
  - `--embed-backend openai` 可切换至 OpenAI 嵌入（需 `OPENAI_API_KEY`）。
  - `--docs-root` 可重复传入，格式 `路径:语言`；漏写 `:语言` 会默认使用目录名或 `en`，若完全省略该参数则默认载入 `docs/en:en`。
  - `--extensions .md .mdx ...` 可扩展索引的文件类型；每个 `--docs-root` 会共享该过滤条件。

### 模型选择
- `--embedding-model BAAI/bge-base-zh-v1.5`（默认）：FlagEmbedding 的中文，体积适中， CPU 即可跑满，适合当前中文文档。
- `--embedding-model BAAI/bge-base-en-v1.5`：英文检索表现最佳，若仓库后续仅包含英文，可切换至该模型降低语义偏移。
- `--embedding-model BAAI/bge-m3`（不推荐）：多语旗舰但参数量巨大，本地推理成本高；只有在需要跨语+长上下文+多向量特性时才考虑。
- 更多可用模型参考 FlagEmbedding 的[官方模型列表](https://github.com/FlagOpen/FlagEmbedding/blob/master/README.md#model-list)，按需替换 `--embedding-model` 后重建索引即可。

4. **命令行验收 (使用 uv run / uvx)**
   ```bash
   uv run scripts/query_docs.py "如何自定义导航栏？" --model raw
   # 或直接从 Git 远程运行（无需克隆）：
   uvx --from git+https://github.com/JaxsonWang/Scripting-Docs-MCP query-docs "如何自定义导航栏？" --model raw
   ```
   将输出管道给任意本地模型 CLI（例如 `| ollama run llama3`）。

## 脚本命令

### `scripts/ingest_docs.py`

```bash
uv run scripts/ingest_docs.py \
  --docs-root /abs/path/docs/en:en \
  --docs-root /abs/path/docs/zh:zh \
  --persist-dir storage/llamaindex --clean \
  --embedding-model BAAI/bge-m3 \
  --embed-backend huggingface
# 无需克隆的等价命令：
uvx --from git+https://github.com/JaxsonWang/Scripting-Docs-MCP ingest-docs \
  --docs-root /abs/path/docs/en:en \
  --docs-root /abs/path/docs/zh:zh \
  --persist-dir storage/llamaindex --clean \
  --embedding-model BAAI/bge-m3 \
  --embed-backend huggingface
```

- `--docs-root PATH[:LANG]`：可重复，缺省为 `docs/en:en`。`:LANG` 省略时会取目录名（或 `en`），写入 metadata 供过滤。
- `--persist-dir`：索引输出目录，默认 `storage/llamaindex`，加 `--clean` 可在构建前删除旧索引。
- `--chunk-size / --chunk-overlap`：SentenceSplitter 的块大小与重叠（默认 750/120 tokens）。
- `--extensions`：摄取的扩展名列表，默认 `.md .mdx`。
- `--embedding-model`：详见“模型选择”，可指向任何 FlagEmbedding 或 OpenAI 模型。
- `--embed-backend`：`huggingface`（本地）或 `openai`。

### `scripts/query_docs.py`

```bash
uv run scripts/query_docs.py \
  "How do I customize navigation?" \
  --persist-dir storage/llamaindex \
  --k 5 \
  --model codex \
  --embedding-model BAAI/bge-base-en-v1.5
# 远程执行示例：
uvx --from git+https://github.com/JaxsonWang/Scripting-Docs-MCP query-docs \
  "How do I customize navigation?" \
  --persist-dir storage/llamaindex \
  --k 5 \
  --model codex \
  --embedding-model BAAI/bge-base-en-v1.5
```

- `question`（位置参数）：用户问题。
- `--persist-dir`：指向摄取阶段的目录，默认 `storage/llamaindex`。
- `--k`：返回 chunk 数，默认 4。
- `--model`：`raw`（纯文本）、`codex`/`claude`/`gemini`（附带提示头）、`mcp`（stdout JSON）。
- `--embedding-model / --embed-backend`：需与索引保持一致；用于在查询侧构造 Retrieval 模型以匹配存储。
- `--cli-path`：当 `--model codex|claude|gemini` 时覆盖执行的 CLI 模型命令。

### `scripts/mcp_docs_server.py`

```bash
uv run scripts/mcp_docs_server.py \
  --persist-dir storage/llamaindex \
  --embedding-model BAAI/bge-base-zh-v1.5 \
  --default-k 4
# 无需克隆：
uvx --from git+https://github.com/JaxsonWang/Scripting-Docs-MCP mcp-docs-server \
  --persist-dir storage/llamaindex \
  --embedding-model BAAI/bge-base-zh-v1.5 \
  --default-k 4
```

- `--persist-dir`：索引目录（默认 `storage/llamaindex`）。
- `--embedding-model / --embed-backend`：与摄取阶段一致，避免向量维度不匹配。
- `--default-k`：MCP 客户端未传 `k` 时的默认 chunk 数。
- 服务器会暴露 `scripting_docs_query` 工具，输入 `{ "question": "...", "k": 4 }`，返回 top-k 文段及 metadata。

## MCP 服务器使用

1. **以 stdio 模式启动服务器 (使用 uv run / uvx)**
  ```bash
  uv run --quiet scripts/mcp_docs_server.py --persist-dir storage/llamaindex
  # 或直接远程执行：
  uvx --from git+https://github.com/JaxsonWang/Scripting-Docs-MCP mcp-docs-server \
    --persist-dir storage/llamaindex --quiet
  ```
   该进程常驻，并暴露单一工具：`scripting_docs_query`。

2. **接入 Codex / Claude / Gemini CLI**

   MCP 配置示例：
   ```json
   {
     "servers": {
       "scripting_docs": {
         "command": "uvx",
         "args": [
           "--from",
           "git+https://github.com/JaxsonWang/Scripting-Docs-MCP",
           "mcp-docs-server",
           "--persist-dir",
           "/absolute/path/to/Scripting-Docs-MCP/storage/llamaindex",
         ]
       }
     }
   }
   ```
   重启 CLI 后，就能在 MCP 工具列表中看到 `scripting_docs_query`。

---

## License

MIT License