Scripting Docs MCP

这个仓库提供一套最小可用的工具链：把 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、扩展名过滤、清理策略等。

工作流总览

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 等目录。

目录结构

环境要求

• Python 3.10+（已在 3.12/3.13 验证）

• 可访问 ScriptingApp.github.io 仓库中的英文/中文文档内容（按需选择）

• （可选）如需改用 OpenAI 嵌入，请准备 OPENAI_API_KEY

快速上手

1. 克隆文档仓库

   git clone https://github.com/ScriptingApp/ScriptingApp.github.io.git

2. 安装 uv (Rust-based Python 包管理器) uv 能够自动管理 Python 环境和依赖，推荐作为 pip 和 venv 的替代。 如果尚未安装 uv，可以通过以下命令安装：

   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 正常：

   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)

• --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 的官方模型列表，按需替换 --embedding-model 后重建索引即可。

4. 命令行验收 (使用 uv run / uvx)

   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

• --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

• 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

• --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)

该进程常驻，并暴露单一工具：scripting_docs_query。

2. 接入 Codex / Claude / Gemini CLI

   MCP 配置示例：

   { "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