MCP Servers

A collection of Model Context Protocol servers, templates, tools and more.

S
Scripting Docs MCP
by @JaxsonWang
GitHub Repo(2 stars)

MCP server by JaxsonWang

Created 12/15/2025
Updated about 15 hours ago
README
View Source
Repository documentation and setup instructions

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、扩展名过滤、清理策略等。

工作流总览

┌────────────┐   ┌─────────────┐   ┌────────────────────┐   ┌──────────────────┐
│ 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. 克隆文档仓库

    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)

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 的官方模型列表，按需替换 --embedding-model 后重建索引即可。
  1. 命令行验收 (使用 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

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

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

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

  1. 接入 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

Quick Setup
Installation guide for this server

Install Package (if required)

uvx scripting-docs-mcp

Cursor configuration (mcp.json)

{ "mcpServers": { "jaxsonwang-scripting-docs-mcp": { "command": "uvx", "args": [ "scripting-docs-mcp" ] } } }