llmstxt-doc-search

llmstxt-doc-search

在任意数量的 llms.txt 文档站点中进行实时排名搜索——包括 Strands、Kiro、AWS 指南，以及你在运行时添加的任何站点。

llmstxt-doc-search 是一个模型上下文协议（MCP）服务，可将文档站点发布的 llms.txt 索引转换为快速、带排名的搜索工具，供你的 Agent 调用。它会在启动时为标题编制索引，使用 BM25 对查询进行排名，并仅在打开搜索结果时获取完整文档，因此几乎不占用本地存储空间，同时还能获取最新文档。它基于 @praveenc/mcp-docs-server 的搜索引擎构建，并将其扩展为可在运行时注册来源。

它通过 stdio 实现 MCP 2026-07-28 规范，并且仍可与使用 2025 协议的客户端配合使用，这些客户端会通过 initialize 握手启动。需要 Node.js 20 或更高版本。

---

为什么选择它

llms.txt 文件是文档站点整理的页面索引，供此类工具使用。这些索引可能很大——AWS Bedrock 的索引约有一千份文档——因此下载所有内容既浪费资源，又很快会过时。

此服务采用了更精简的方式：

• 延迟构建仅含标题的索引。 首次搜索某个来源时，只为页面标题编制索引。构建速度快，占用的内存也很少。
• 使用 BM25 排名。 查询采用 BM25 评分，并结合 Porter 词干提取、二元词组和 Markdown 感知加权（标题、代码和链接的权重更高）。mcp、json 和 stdio 等技术术语会保留原样，不进行词干提取。
• 按需获取内容。 只有调用 fetch_doc 时，才会获取搜索结果的完整 Markdown 或 HTML 内容。

因此，它很适合内容广泛且快速变化的参考资料，与将文档快照存入本地资料库的取舍方式正好相反。

---

安装

快速开始（推荐）

将此服务添加到你的 MCP 客户端配置中（Claude Desktop、Kiro 等）。它会通过 npx 按需下载并运行，无需手动构建：

{
  "mcpServers": {
    "llmstxt-doc-search": {
      "command": "npx",
      "args": ["-y", "@praveenc/llmstxt-doc-search"]
    }
  }
}

全局安装

npm install -g @praveenc/llmstxt-doc-search

然后，将 MCP 客户端指向已安装的二进制文件：

{
  "mcpServers": {
    "llmstxt-doc-search": {
      "command": "llmstxt-doc-search"
    }
  }
}

---

快速开始

连接服务后，典型流程包含三次调用：

1. docs_home() ——了解已注册的来源，以及如何搜索和获取文档。
2. search_docs("prompt caching", "aws-bedrock-userguide") ——为匹配的文档排名。省略来源即可搜索所有内容。
3. fetch_doc(url) ——阅读你感兴趣的搜索结果的完整内容。

你可以随时添加自己的来源；它会立即编入索引，并保存以供后续运行使用：

add_doc_source("langgraph", "https://langchain-ai.github.io/langgraph/llms.txt")

---

工具

工具	用途
docs_home()	入门指引：已注册的来源，以及如何搜索和获取内容。请先调用此工具。
list_doc_sources()	列出来源及其 llms.txt URL 和索引状态，包括索引失败来源的最近一次错误。
search_docs(query, source?, k?)	BM25 搜索。省略 source 可搜索全部来源，也可限定单个来源。返回排序后的 {source, url, title, score, snippet}，其中 score（0-1）可跨来源比较。k 默认为 5（最大值为 50）。
fetch_doc(url)	获取结果 URL 的完整内容。URL 必须位于已注册来源的 llms.txt 目录下，或列在已通过搜索、添加或刷新建立索引的来源的 llms.txt 中。
add_doc_source(name, llms_txt_url)	在运行时注册并索引新的 llms.txt 来源。此操作会持久保存。如果该 llms.txt 已注册或不包含任何链接，则会被拒绝。
remove_doc_source(name)	移除已注册的来源。
refresh_doc_source(name)	重新索引来源，以获取新增或变更的文档。无法成功建立索引的来源会跳过 5 分钟；调用此工具会立即重试。

docs_home、list_doc_sources、search_docs 和 fetch_doc 标记为只读，因此客户端无需提示即可批准这些工具。add_doc_source、remove_doc_source 和 refresh_doc_source 会更改持久保存的注册表，其中 remove_doc_source 标记为破坏性操作。工具列表固定，因此会公布为可缓存 1 小时。

默认来源

首次运行时会将以下来源加入注册表：

strands、kiro、aws-bedrock-userguide、aws-agentic-ai-lens、aws-bedrock-agentcore-devguide、mcp。

注册表持久保存在 ~/.config/llmstxt-doc-search/sources.json（可通过 LLMSTXT_REGISTRY_PATH 覆盖）。运行时添加、移除或刷新的任何内容都会保存到此处。

---

配置

所有配置均通过环境变量完成；无需设置任何变量。

变量	默认值	含义
LLMSTXT_REGISTRY_PATH	~/.config/llmstxt-doc-search/sources.json	来源注册表的持久保存位置。
LLMSTXT_SNIPPET_HYDRATE_MAX	5	构建结果摘要时要获取的排名靠前结果数。
LLMSTXT_PAGE_CACHE_MAX	50	每个来源在内存中保留的已获取页面数上限（LRU）；超过此上限时会淘汰最近最少使用的页面。0 表示不设上限。
LLMSTXT_LOG_LEVEL	info	日志详细程度：debug、info、warn 或 error。日志仅输出到 stderr。

---

使用 MCP Inspector 进行测试

npx @modelcontextprotocol/inspector npx -y @praveenc/llmstxt-doc-search

Inspector 可使用任一协议时代进行连接；请参阅协议时代。

---

开发

克隆此仓库以进行本地开发（Node.js 20 或更高版本）：

git clone https://github.com/praveenc/llmstxt-doc-search.git
cd llmstxt-doc-search
npm install

命令

npm run dev         # run from source with tsx (no build)
npm test            # offline unit and protocol tests
npm run typecheck   # type-check without emitting
npm run build       # compile to dist/
npm run inspect:dev # MCP Inspector against the source

本地 MCP 客户端配置（开发）

将客户端指向源代码检出目录，而不是已发布的包：

{
  "mcpServers": {
    "llmstxt-doc-search": {
      "command": "npx",
      "args": ["tsx", "/ABS/PATH/llmstxt-doc-search/src/index.ts"]
    }
  }
}

或者，在运行 npm run build 后，指向编译后的入口点：

{
  "mcpServers": {
    "llmstxt-doc-search": {
      "command": "node",
      "args": ["/ABS/PATH/llmstxt-doc-search/dist/index.js"]
    }
  }
}

---

架构

src/
├── index.ts              # Tool registration and the stdio entry point (serves 2026-07-28 and 2025-era clients)
├── config.ts             # Defaults and environment configuration
├── tools/
│   └── docs.ts           # search_docs, fetch_doc, and source management
└── utils/
    ├── doc-fetcher.ts    # HTTP fetching, redirect handling, HTML parsing
    ├── indexer.ts        # BM25 search index
    ├── registry.ts       # Persisted source registry
    ├── store.ts          # In-memory document store
    ├── text-processor.ts # Tokenization and snippet helpers
    ├── url-validator.ts   # SSRF guard and URL validation
    ├── stopwords.ts      # Stop-word list
    └── logger.ts         # Logging utilities

---

搜索算法

排序使用 BM25（最佳匹配 25）算法，并进行了多项增强：

• Porter 词干提取可匹配词语变体（例如，running 和 run）。
• 二元词组可捕捉短语匹配（例如，prompt caching）。
• 加权评分会提高标题（3-8 倍）、标题层级（4 倍）、代码块（2 倍）和链接文本（2 倍）的权重。
• 保留领域术语，确保 mcp、json 和 stdio 等技术术语不进行词干提取，以便精确匹配。

---

安全性

此服务会在运行时获取用户提供的 URL，因此通过多层防护限制其 SSRF 攻击面：

• 限定范围的获取。 fetch_doc 只会获取已注册来源的 llms.txt 中明确列出的 URL，或位于该来源源站及路径前缀下的 URL（按路径边界匹配，而非直接进行字符串前缀匹配）。不会任意获取 URL。
• 协议允许列表。 拒绝非 http(s) 协议。
• 基于地址范围的拦截。 使用 IP 地址范围分类（ipaddr.js）拦截私有和保留地址，包括十进制、八进制和十六进制 IPv4、IPv4 映射的 IPv6、环回地址、链路本地地址、唯一本地地址、运营商级 NAT 以及其他保留范围，而不只是依赖主机名正则表达式。
• 连接时验证。 通过自定义 DNS 查询在连接时检查解析出的 IP，从而防止 DNS 重绑定；并重新验证每次重定向。
• 限制响应大小。 将响应正文限制在 10 MB 以内，以降低内存占用和正则表达式拒绝服务（ReDoS）风险。

运行时依赖未发现已知漏洞。

---

许可证

MIT - 版权所有 (c) 2026 Praveen Chamarthi

---

贡献

欢迎贡献。如果你发现了错误或有改进想法：

1. 提交 issue，描述问题或提议。
2. 如需更改代码，请 fork 仓库并创建功能分支。
3. 保持更改聚焦，添加或更新测试，并确保 npm test、npm run typecheck 和 npm run build 均通过。
4. 向 main 提交 pull request，并清楚说明更改内容及原因。

提交消息遵循 Conventional Commits 规范。

---

支持

• 问题和想法： 提交 GitHub issue。
• 错误： 请提供你的 MCP 客户端、执行的工具调用以及任何相关日志（设置 LLMSTXT_LOG_LEVEL=debug 可获取更多详细信息）。
• 安全问题： 提交标记为安全敏感的 issue，或直接联系维护者；请勿公开发布漏洞利用细节。

---