Citepath

本地服务

github.com记忆与知识01 周前更新

代码仓库访问官网

关于 Citepath

Citepath 是面向使用 AI 编码 Agent 的开发者和 AI 应用构建者的可自托管文档搜索工具。它索引网站和本地文件，并以关键词检索返回带引用的排序段落，而非使用嵌入向量。

主要功能

01索引文档网站和本地文件夹
02按关键词和标识符搜索
03返回带精确引用的段落
04优先采用当前索引版本
05提供 CLI 和本地 HTTP API

适用场景

01编码时查找最新框架文档
02在本地搜索私有 Wiki 和运行手册
03为 AI 应用添加带引用的检索
04将项目文档连接到助手

MCP 相关

Citepath 提供 MCP 服务，让 AI 助手搜索本地文档索引并获取带引用的段落。助手获得只读访问权限。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "arif-js-citepath": {
      "command": "npx",
      "args": [
        "-y",
        "citepath"
      ]
    }
  }
}

启动命令npx -y citepath

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npmcitepath0.1.4stdio

工具

收录的工具列表 · 更新于 1 周前

参数	类型	必填	说明
limit	integer	否	段落数（默认值 5，最大值 25）。
query	string	是	要查找的内容：问题、关键词或标识符。
source_ids	array	否	仅搜索这些来源 ID（由 list_sources 返回）。省略则搜索所有来源。
path_prefix	string	否	仅包含 URL（网页来源）或根相对路径（本地来源）以此前缀开头的段落，例如文档章节或之前搜索中返回的 other_versions path_prefix。

详细介绍

Citepath

为 AI 助手和应用提供可自托管的文档搜索，并附带引用。

为文档网站和本地文件夹建立索引，然后让 Claude、Cursor 或任何 MCP 客户端从最新文档中查找答案，并为所用的每个章节附上链接。

快速开始 · 演示 · 为什么不用 RAG？ · 命令 · 文档 · 贡献

状态：预发布版（0.1）。 1.0 之前可能会有破坏性变更。

功能

📚 为文档建立索引： 文档网站（从站点地图获取，或通过跟随链接获取，并遵守 robots.txt），以及本地 Markdown、MDX 或文本文件夹。
🔗 返回带引用的段落： 每条搜索结果都链接到其来源所在的具体页面章节或文件行。
🧠 理解代码和日常语言： getUserName、--dry-run 和“如何配置缓存”都能正常搜索。
🤖 连接 AI 助手： Claude Code、Cursor 和其他 MCP 客户端可以搜索你的文档；你自己的工具则可以使用 CLI 或本地 HTTP API。
🔒 在本地运行： 无需账户或 API 密钥，也不会收集遥测数据。助手只有只读权限，同步失败也绝不会删除已有的有效数据。

Citepath 负责查找段落，不负责撰写答案。你的助手会根据这些段落撰写答案并附上引用，方便你核查每一项说法。

演示

只需为当前的 Next.js 文档建立一次索引，然后进行搜索：

citepath add nextjs --url https://nextjs.org/docs/app --include '/docs/app/**' --sync

使用 citepath 搜索 Next.js 文档

也可以在助手中进行同样的搜索：

你：使用 citepath，如何设置 Next.js 缓存数据的存续时间？

Claude： 为函数添加 'use cache'，并调用 cacheLife('hours')，或者传入 { stale, revalidate, expire }。这需要在 next.config.ts 中设置 cacheComponents: true。来源：cacheLife、use cache、cacheComponents

适用对象

使用 AI 编码助手的开发者： 获取基于框架和服务最新文档的答案，而不是模型记忆中的内容。
构建 AI 工具的人： 为任何模型提供检索层，以 JSON 格式返回经过排序并附带引用的段落。
小型团队： 无需托管平台，即可让助手搜索内部 Wiki、运维手册和文档文件夹。
开源项目维护者： 让用户轻松将项目文档连接到自己的助手。

为什么不用 RAG 或网页搜索？

它就是 RAG：检索部分，在本地运行。 Citepath 使用关键词索引，而不是嵌入和向量数据库。这意味着无需嵌入 API 或密钥，能精确匹配 cacheLife 这类标识符，同一查询始终得到相同结果，并且引用精确到章节。代价是：它匹配的是词语，而不是含义，所以搜索“登录”不会找到只提到“身份验证”的页面。

对于宽泛的临时问题，网页搜索更合适。 在以下情况下，Citepath 更合适：

文档是私有的： 内部 Wiki、运行手册和代码仓库文档不会出现在网上；
版本很重要： 你可以选择要建立索引的内容，而且搜索会优先使用页面的当前版本，而非旧版本；
你希望少读一些内容： 对于 Next.js 文档，搜索“如何设置缓存生命周期”得到的 5 段引用内容约有 4,200 个字符，而这 5 段所在页面共有约 51,000 个字符的文本（仅 cacheLife 页面就有约 1 MB 的 HTML）；
你处于离线状态， 或者你的助手没有网页搜索功能。

“模型已经了解这些文档了。” 它只了解训练时接触到的版本。对于 Next.js cacheLife、cacheComponents 或新的双参数 revalidateTag 这类快速变化的 API，模型往往会依据过时的记忆作答。

“为什么不把文档直接粘贴到提示词里？” 只有几页时这样做行得通。Next.js 文档有 845 页；搜索能挑出最相关的几段内容。

成本与限制。 在笔记本电脑上使用 Next.js 和 Vercel 文档进行测量：

免费运行： 无需账户或 API 密钥，也没有按搜索次数收费。搜索只需几毫秒（约 30,000 段内容的 p95 延迟为 13 ms）。
设置耗时和磁盘空间： 按每秒 2 个请求的默认温和速率同步 845 个 Next.js 页面约需 7.5 分钟；两个网站共占用 83 MB。
时效性： 结果的新旧取决于你上次同步的时间。没有内置调度程序，因此请通过 cron 运行 citepath sync。
未建立索引的内容： 需要 JavaScript 才能渲染的网站、PDF，以及需要登录才能访问的文档。
单用户： 一个 API 令牌，没有按用户划分的权限。

宽泛问题请使用其他方案（网页搜索）；基于含义的搜索请使用其他方案（嵌入）；团队访问控制也请使用其他方案。请参阅已知限制。

快速开始

需要 Node.js 22.16 或更高版本。

npm install -g citepath

citepath add my-docs --path ~/work/project/docs --sync
citepath search "how do I configure authentication"

# Connect Claude Code (all projects)
claude mcp add citepath -s user -- citepath mcp

在 Claude Code 中运行 /mcp 检查连接。有关其他助手和作用域选项，请参阅 MCP 设置。如需从源代码运行，请参阅 CONTRIBUTING.md。

命令

命令	功能
`citepath init`	创建配置文件。
`citepath add <id> --url <url>`	添加文档网站。重复使用 `--url` 可添加多个网站。添加 `--sync` 可立即建立索引。
`citepath add <id> --path <dir>`	添加本地文档文件夹。重复使用 `--path` 可添加多个文件夹。
`citepath remove <id>`	移除来源及其已索引内容。
`citepath sync [id...]`	获取来源并建立索引，同时显示实时进度。再次运行可获取变更或重试失败项。
`citepath sources`	列出来源及其文档数量和上次同步状态。
`citepath status [id]`	显示索引位置，或来源上次同步的情况：失败项、移除项和警告。
`citepath search "<query>"`	查找匹配的段落并附上引用。使用 `--source`、`--path-prefix`、`--limit` 进行筛选。
`citepath get <passage-id>`	显示完整段落；使用 `--neighbors <n>` 显示前后章节。
`citepath mcp`	为 AI 助手提供 MCP 服务。由助手启动，无需手动运行。
`citepath serve`	在 `127.0.0.1:7345` 提供只读本地 HTTP API。
`citepath export`、`eval`、`compact`、`unlock`	导出为 JSONL、评估搜索质量、优化索引、清除卡住的同步锁。