Librarian MCP 服务器

<div align="center"> <img src="./logo.svg" alt="Librarian Logo" width="300" height="200"> <h3>知识触手可及</h3> </div>

概述

Librarian 是一个模型上下文协议 (MCP) 服务器，它提供了一个 API，用于列出、搜索和检索以结构化方式存储的 markdown 文件。它充当大型语言模型 (LLM) 的知识库，根据需要为它们提供所需的信息。

Librarian 不提供任何写入操作 - 它是一个只读服务，旨在通过 MCP 框架有效地将文档内容传递给 LLM。

特性

• 结构化文档组织：文档按部分组织（例如，daisyui/components/button.md）
• 基于标签的过滤：按 frontmatter 中定义的标签过滤文档
• 分层标签继承：标签从父目录继承
• 灵活的搜索功能：
  • 简单的字符串搜索（不区分大小写）
  • 具有可自定义标志的正则表达式搜索
• 高效的文档检索：通过路径快速访问特定文档
• 标签发现：列出所有可用标签，包括使用计数和可选的文件路径
• MCP 集成：与模型上下文协议无缝集成

项目结构

Librarian MCP 服务器被组织成模块化组件：

• src/lib/config.ts: 配置的类型定义和加载器
• src/lib/load.ts: 文档加载和处理功能
• src/lib/librarian.ts: 带有模式的核心 librarian 实现
• src/lib/util.ts: 纯文本响应的格式化实用程序
• src/lib/server.ts: MCP 服务器实现
• src/bin.ts: CLI 入口点
• src/index.ts: 库入口点

这种模块化设计允许轻松扩展和维护，并具有清晰的关注点分离。

安装

前提条件

• Node.js (v14 或更高版本)
• npm 或 pnpm

安装步骤

# 克隆仓库
git clone https://github.com/yourusername/mcp-server-librarian.git
cd mcp-server-librarian

# 安装依赖
pnpm install

# 构建项目
pnpm build

配置

可以使用以下方法配置文档文件夹路径（按优先级排序）：

命令行参数

node dist/bin.js --docs-root /path/to/your/docs

环境变量

LIBRARIAN_DOCS_ROOT=/path/to/your/docs node dist/bin.js

文档结构

组织

文档按部分组织，遵循分层结构：

<docs_root>/
├── daisyui/
│   ├── index.md              # 带有标签的 DaisyUI 部分信息
│   └── components/
│       ├── index.md          # 带有标签的组件部分信息
│       ├── button.md         # 带有特定标签的文档
│       └── card.md           # 另一个带有特定标签的文档
└── tailwind4/
    ├── index.md              # 带有标签的 Tailwind 部分信息
    └── getting-started.md    # 带有特定标签的文档

Frontmatter

每个 markdown 文档都可以包含带有 tags 字段的 frontmatter：

---
tags: ["frontend", "ui", "button"]
---

# Button Component

This document describes the button component...

标签继承

标签通过文件夹层次结构继承：

1. 文档从其父目录中的 index.md 文件继承所有标签
2. 标签从最通用（根）到最具体（文档）合并

例如，如果我们有：

• /daisyui/index.md 带有标签：["ui"]
• /daisyui/components/index.md 带有标签：["components"]
• /daisyui/components/button.md 带有标签：["interactive", "form"]

那么 /daisyui/components/button.md 将有效地拥有所有标签：["documentation", "ui", "components", "interactive", "form"]

文件夹描述

您可以通过在文件夹中创建一个 index.md 文件来描述文件夹本身。此文件可以包含 frontmatter（带有标签）和描述该部分用途的内容。

API 参考

Librarian MCP 服务器提供以下工具：

getDocuments

按路径检索多个文档。

参数：

• filepaths：要检索的文件路径数组

响应：

**/path/to/document1.md**
- tags: tag1, tag2, tag3
======
Document 1 content
======

**/path/to/document2.md**
- tags: tag1, tag4, tag5
======
Document 2 content
======

getDocument

按路径检索特定文档。

参数：

• filepath：文档的路径

响应：

**/path/to/document.md**
- tags: tag1, tag2, tag3
======
Document content
======

listDocuments

列出所有文档，并可选择按目录和标签进行过滤。

参数：

• directory（可选）：要列出文档的目录路径（默认值："/"）
• tags（可选）：要过滤的标签数组（默认值：[]）
• includeContents（可选）：是否在结果中包含文档内容（默认值：false）
• depth（可选）：要遍历的最大目录深度（-1 表示无限，默认值：-1）

响应：（当 includeContents 为 false 时）

- /path/to/document1.md
  - tags: tag1, tag2, tag3
- /path/to/document2.md
  - tags: tag1, tag4, tag5
...

响应：（当 includeContents 为 true 时）

**/path/to/document1.md**
- tags: tag1, tag2, tag3
======
Document 1 content
======

**/path/to/document2.md**
- tags: tag1, tag4, tag5
======
Document 2 content
======

searchDocuments

使用字符串或正则表达式模式搜索文档内容。

参数：

• query：搜索查询（字符串或正则表达式模式）
• mode（可选）：搜索模式（"string" 或 "regex"，默认值："string"）
• caseSensitive（可选）：搜索是否应区分大小写（默认值：false）
• directory（可选）：要在其中搜索的目录路径（默认值："/"）
• tags（可选）：要过滤的标签数组（默认值：[]）
• includeContents（可选）：是否在结果中包含文档内容（默认值：false）
• depth（可选）：要遍历的最大目录深度（-1 表示无限，默认值：-1）

响应：（当 includeContents 为 false 时）

- /path/to/document1.md
  - tags: tag1, tag2, tag3
- /path/to/document2.md
  - tags: tag1, tag4, tag5
...

响应：（当 includeContents 为 true 时）

**/path/to/document1.md**
- tags: tag1, tag2, tag3
======
Document 1 content
======

**/path/to/document2.md**
- tags: tag1, tag4, tag5
======
Document 2 content
======

listTags

列出所有标签，包括计数和可选的文件路径。

参数：

• directory（可选）：要列出标签的目录路径（默认值："/"）
• includeFilepaths（可选）：是否在结果中包含文件路径（默认值：false）
• depth（可选）：要遍历的最大目录深度（-1 表示无限，默认值：-1）

响应：（当 includeFilepaths 为 false 时）

- tag1 (5)
- tag2 (3)
- tag3 (2)
...

响应：（当 includeFilepaths 为 true 时）

- tag1 (5)
  - /path/to/document1.md
  - /path/to/document2.md
  - ...
- tag2 (3)
  - /path/to/document3.md
  - ...

使用示例

启动服务器

# 使用默认配置启动
node dist/bin.js

# 使用自定义文档目录启动
node dist/bin.js --docs-root ./my-documentation

# 使用环境变量启动
LIBRARIAN_DOCS_ROOT=./my-documentation node dist/bin.js

示例查询

列出文档

// 列出所有文档
const allDocs = await mcp.useTool("librarian", "listDocuments", {});

// 列出特定目录中的文档
const uiDocs = await mcp.useTool("librarian", "listDocuments", {
  directory: "/daisyui/components",
});

// 列出带有特定标签的文档
const buttonDocs = await mcp.useTool("librarian", "listDocuments", {
  tags: ["button", "interactive"],
});

// 列出带有深度限制的文档
const topLevelDocs = await mcp.useTool("librarian", "listDocuments", {
  directory: "/daisyui",
  depth: 1, // 仅包括直接子项，不包括嵌套子目录
});

搜索文档

// 简单的字符串搜索
const results = await mcp.useTool("librarian", "searchDocuments", {
  query: "button styling",
});

// 正则表达式搜索
const regexResults = await mcp.useTool("librarian", "searchDocuments", {
  query: "\\bbutton\\b.*\\bstyle\\b",
  mode: "regex",
  caseSensitive: true,
  includeContents: true,
});

// 使用标签过滤进行搜索
const filteredResults = await mcp.useTool("librarian", "searchDocuments", {
  query: "installation",
  tags: ["tutorial"],
  directory: "/tailwind4",
});

// 使用深度限制进行搜索
const topLevelResults = await mcp.useTool("librarian", "searchDocuments", {
  query: "component",
  directory: "/daisyui",
  depth: 1, // 仅在直接子项中搜索，不包括嵌套子目录
});

检索文档

// 获取特定文档
const document = await mcp.useTool("librarian", "getDocument", {
  filepath: "/daisyui/components/button.md",
});

检索多个文档

// 获取多个特定文档
const documents = await mcp.useTool("librarian", "getDocuments", {
  filepaths: ["/daisyui/components/button.md", "/daisyui/components/card.md"],
});

列出标签

// 列出所有标签
const allTags = await mcp.useTool("librarian", "listTags", {});

// 列出特定目录中的标签
const tailwindTags = await mcp.useTool("librarian", "listTags", {
  directory: "/tailwind",
});

// 列出带有文件路径的标签
const tagsWithFiles = await mcp.useTool("librarian", "listTags", {
  includeFilepaths: true,
});

// 列出带有深度限制的标签
const topLevelTags = await mcp.useTool("librarian", "listTags", {
  directory: "/daisyui",
  depth: 1, // 仅包括直接子项中的标签，不包括嵌套子目录
});

与 LLM 集成

Librarian 旨在通过模型上下文协议与 LLM 无缝协作。以下是 LLM 如何使用 Librarian：

1. 标签发现：LLM 可以列出可用的标签以了解知识分类
2. 文档发现：LLM 可以列出可用的文档以了解可用的知识
3. 搜索：当 LLM 需要特定信息时，它可以跨文档进行搜索
4. 检索：一旦 LLM 识别出相关文档，它就可以检索其完整内容
5. 上下文构建：LLM 可以使用检索到的内容来构建上下文以生成响应

错误处理

Librarian 使用标准的 MCP 错误响应，并带有适当的错误代码和消息：

• INVALID_ARGUMENT：当提供的参数无效时
• NOT_FOUND：当请求的文档或目录不存在时
• INTERNAL：对于意外的服务器错误

每个错误响应包括：

• 一个错误代码
• 一条描述性消息
• 用于调试的可选详细信息

故障排除

常见问题

找不到文档

如果您收到 NOT_FOUND 错误：

• 检查文档路径是否正确
• 验证 --docs-root 是否指向正确的目录
• 确保文件权限允许服务器读取文件

搜索未返回任何结果

如果搜索未返回预期的结果：

• 检查查询语法是否正确（尤其是对于正则表达式搜索）
• 验证文档是否包含预期的内容
• 尝试扩大搜索范围或使用更简单的模式

标签过滤不起作用

如果标签过滤未按预期工作：

• 验证标签是否在 frontmatter 中正确定义
• 检查继承层次结构以了解哪些标签适用于哪些文档
• 确保标签名称完全匹配（标签区分大小写）

许可证

该项目已获得 MIT 许可证的许可 - 有关详细信息，请参阅 LICENSE 文件。

贡献

欢迎贡献！请随时提交 Pull Request。

90% 的代码是凭感觉写的。这段代码质量不是我的。我可以写出更好的代码，但速度会慢得多 :)