docs-manage

文档管理

在本地 Grounded Docs 存储中为库文档编制索引、刷新索引并移除文档。这些命令会更改索引，并在标准输出中打印纯文本结果。

适用场景

• 某个库尚未编入索引，而你需要搜索其文档。
• 已编入索引的文档可能已过时，而你想获取已更改的页面。
• 你想从索引中移除某个库版本。
• 移除内容后，存储文件仍然很大，而你想缩小它。

命令

每个命令都接受以下标志：

标志	说明
--server-url <url>	使用远程工作器（例如 http://localhost:8080/api），而非本地存储
--quiet	仅记录错误
--verbose	记录调试输出

scrape

从 URL 或本地文件夹下载文档并编入索引。索引完成后命令才会返回。

npx @arabold/docs-mcp-server@latest scrape <library> <url> [options]

标志	别名	默认值	说明
--version <ver>	-v	无版本	为索引指定的版本标签
--max-pages <n>	-p	1000	编入索引的最大页面数
--max-depth <n>	-d	3	从起始 URL 开始的最大链接深度
--max-concurrency <n>	-c	3	同时抓取的页面数
--scope subpages|hostname|domain		subpages	抓取范围：起始 URL 的路径、其主机名，或包含子域名的域名
--include-pattern <pattern>			仅抓取符合条件的 URL（glob，或 /pattern/ 格式的正则表达式；可重复指定）
--exclude-pattern <pattern>			跳过符合条件的 URL（可重复指定；优先于 include）
--scrape-mode auto|fetch|playwright		auto	auto 和 playwright 会在无头 Chromium 中渲染 HTML；fetch 不执行 JavaScript
--header "Name: Value"			自定义 HTTP 标头（可重复指定）
--no-follow-redirects		跟随重定向	将 HTTP 重定向视为错误
--no-ignore-errors		忽略错误	页面抓取失败时直接使整个抓取失败，而不是跳过该页面
--preserve-hashes		false	保留 #/route 片段，用于通过 URL 哈希路由的文档站点
--replace		false	如果该版本已存在，则重建该版本
--no-clean			将文档添加到现有版本，而不是报错
--embedding-model <model>			嵌入模型，例如 openai:text-embedding-3-small

页面数、深度和并发数的默认值来自服务配置，在用户的机器上可能有所不同。

示例：

# Index React docs under a version
npx @arabold/docs-mcp-server@latest scrape react https://react.dev/reference/react --version 19.0.0

# Index a local folder
npx @arabold/docs-mcp-server@latest scrape mylib file:///Users/me/Documents/my-library

# Limit the crawl
npx @arabold/docs-mcp-server@latest scrape nextjs https://nextjs.org/docs --max-pages 200 --max-depth 3

# Send an auth header with every request
npx @arabold/docs-mcp-server@latest scrape internal-api https://docs.example.com \
  --header "Authorization: Bearer tok_xxx"

# Skip changelog pages
npx @arabold/docs-mcp-server@latest scrape react https://react.dev/reference/react \
  --exclude-pattern "**/changelog*"

成功时会打印 Successfully scraped <n> pages。即使忽略错误，起始 URL 抓取失败，或其他页面中超过一半抓取失败（默认情况下）时，抓取仍会失败。

refresh

就地更新已编入索引的版本。未更改的页面会跳过：网页依据 HTTP ETag 判断，本地文件依据修改时间判断。已删除的页面会被移除，并抓取新的链接。上次索引未完成的版本会从头重新抓取。系统会沿用原始抓取选项。

npx @arabold/docs-mcp-server@latest refresh <library> [options]

标志	别名	说明
--version <ver>	-v	要刷新的版本。仅在文档未指定版本时省略。
--preserve-hashes		覆盖此次刷新的已存哈希路由设置
--embedding-model <model>		嵌入模型

示例：

npx @arabold/docs-mcp-server@latest refresh react --version 19.0.0

该版本必须已编入索引；新版本请使用 scrape。成功时会打印 Successfully refreshed <n> pages。

remove

从索引中移除某个库版本。移除库的最后一个版本后，该库也会被移除。

npx @arabold/docs-mcp-server@latest remove <library> [options]

标志	别名	说明
--version <ver>	-v	要移除的版本。若不指定，命令会移除未指定版本的文档。

示例：

npx @arabold/docs-mcp-server@latest remove react --version 18.3.1

命令会打印 Successfully removed [email protected].；如果该库未编入索引，则会失败。移除操作无法撤销；再次运行 scrape 可重新编入索引。请先运行 list（docs-search 技能）以获取准确的版本标签。

compact

通过回收未使用的空间来缩小存储文件。删除文档本身不会缩小文件。压缩需要获取独占锁，因此搜索可能要等到操作完成。它还需要可用磁盘空间来存储临时副本。请在没有其他程序使用该存储时运行。

npx @arabold/docs-mcp-server@latest compact [--force]

标志	描述
--force	即使 SQLite 报告没有空闲页，也重写存储

它会打印 Compacted store from <size> to <size> (reclaimed <size>). 或 Store is already compact.

输出行为

每条命令都会在 stdout 上打印一行纯文本结果，并忽略 --output。日志会输出到 stderr：在终端中会包含进度行，例如 📄 Scraping react v19.0.0: 3/10 pages；在终端外只记录错误。设置 LOG_LEVEL=INFO 或传入 --verbose 可查看进度。命令失败时会以非零状态码退出。

典型工作流

# 1. Index documentation for the first time
npx @arabold/docs-mcp-server@latest scrape react https://react.dev/reference/react --version 19.0.0

# 2. Later, pick up changed pages
npx @arabold/docs-mcp-server@latest refresh react --version 19.0.0

# 3. Remove an old version
npx @arabold/docs-mcp-server@latest remove react --version 18.3.1

# 4. Shrink the store if needed
npx @arabold/docs-mcp-server@latest compact

重要说明

• 抓取需要时间。 大型网站可能需要几分钟。只需要网站部分内容时，请使用 --max-pages 和 --max-depth。
• scrape 不会意外覆盖内容。 抓取已存在的版本会失败，并保留原有内容。传入 --replace 可重新构建，使用 refresh 可原地更新，或传入 --no-clean 添加内容。
• 库名称保留其大小写（React、Next.js Docs），匹配时不区分大小写，因此 react 会匹配到 React。名称中的任何字符都没有特殊含义：请使用 --version 18，而非 react@18。
• 本地文件需要使用包含绝对路径的 file:// URL。默认情况下，只能为用户 Documents 文件夹中的文件建立索引。若要为其他文件夹建立索引，请先征得用户同意，再使用 DOCS_MCP_SCRAPER_SECURITY_FILE_ACCESS_ALLOWED_ROOTS=/path/to/folder 运行命令。
• 默认拒绝访问 localhost 或 10.x.x.x 等专用网络地址。用户可在服务配置 (scraper.security.network) 中允许访问。