Librarian MCP Server

Librarian MCP 服务

概述

Librarian 是一种模型上下文协议（MCP）服务，提供用于列出、搜索和检索以结构化方式存储的 Markdown 文件的 API。它充当大模型（LLM）的知识库，按需为其提供所需信息。

Librarian 不提供任何写入操作，而是一个只读服务，旨在通过 MCP 框架高效地向大模型提供文档内容。

功能

• 结构化文档组织：按章节组织文档（例如，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

安装步骤

# Clone the repository
git clone https://github.com/yourusername/mcp-server-librarian.git
cd mcp-server-librarian

# Install dependencies
pnpm install

# Build the project
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 section info with tags
│   └── components/
│       ├── index.md          # Components section info with tags
│       ├── button.md         # Document with specific tags
│       └── card.md           # Another document with specific tags
└── tailwind4/
    ├── index.md              # Tailwind section info with tags
    └── getting-started.md    # Document with specific tags

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
  - ...

使用示例

启动服务

# Start with default configuration
node dist/bin.js

# Start with custom docs directory
node dist/bin.js --docs-root ./my-documentation

# Start with environment variable
LIBRARIAN_DOCS_ROOT=./my-documentation node dist/bin.js

查询示例

列出文档

// List all documents
const allDocs = await mcp.useTool("librarian", "listDocuments", {});

// List documents in a specific directory
const uiDocs = await mcp.useTool("librarian", "listDocuments", {
  directory: "/daisyui/components",
});

// List documents with specific tags
const buttonDocs = await mcp.useTool("librarian", "listDocuments", {
  tags: ["button", "interactive"],
});

// List documents with depth limit
const topLevelDocs = await mcp.useTool("librarian", "listDocuments", {
  directory: "/daisyui",
  depth: 1, // Only include direct children, not nested subdirectories
});

搜索文档

// Simple string search
const results = await mcp.useTool("librarian", "searchDocuments", {
  query: "button styling",
});

// Regex search
const regexResults = await mcp.useTool("librarian", "searchDocuments", {
  query: "\\bbutton\\b.*\\bstyle\\b",
  mode: "regex",
  caseSensitive: true,
  includeContents: true,
});

// Search with tag filtering
const filteredResults = await mcp.useTool("librarian", "searchDocuments", {
  query: "installation",
  tags: ["tutorial"],
  directory: "/tailwind4",
});

// Search with depth limit
const topLevelResults = await mcp.useTool("librarian", "searchDocuments", {
  query: "component",
  directory: "/daisyui",
  depth: 1, // Only search in direct children, not nested subdirectories
});

检索文档

// Get a specific document
const document = await mcp.useTool("librarian", "getDocument", {
  filepath: "/daisyui/components/button.md",
});

检索多份文档

// Get multiple specific documents
const documents = await mcp.useTool("librarian", "getDocuments", {
  filepaths: ["/daisyui/components/button.md", "/daisyui/components/card.md"],
});

列出标签

// List all tags
const allTags = await mcp.useTool("librarian", "listTags", {});

// List tags in a specific directory
const tailwindTags = await mcp.useTool("librarian", "listTags", {
  directory: "/tailwind",
});

// List tags with filepaths
const tagsWithFiles = await mcp.useTool("librarian", "listTags", {
  includeFilepaths: true,
});

// List tags with depth limit
const topLevelTags = await mcp.useTool("librarian", "listTags", {
  directory: "/daisyui",
  depth: 1, // Only include tags from direct children, not nested subdirectories
});

与大模型集成

Librarian 旨在通过 Model Context Protocol 与大模型无缝协作。大模型可以通过以下方式使用 Librarian：

1. 发现标签：大模型可以列出可用标签，了解知识分类体系
2. 发现文档：大模型可以列出可用文档，了解有哪些知识可供使用
3. 搜索：需要特定信息时，大模型可以搜索文档
4. 检索：确定相关文档后，大模型可以检索其完整内容
5. 构建上下文：大模型可以使用检索到的内容构建上下文，以生成回复

错误处理

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

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

每个错误响应都包含：

• 错误代码
• 描述性消息
• 可选的调试详情

故障排除

常见问题

找不到文档

如果出现 NOT_FOUND 错误：

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

搜索没有返回结果

如果搜索没有返回预期结果：

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

标签筛选不起作用

如果标签筛选未按预期工作：

• 确认 frontmatter 中的标签定义正确
• 检查继承层级，了解哪些标签适用于哪些文档
• 确保标签名称完全匹配（标签区分大小写）

许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。

贡献

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

90% 是氛围编程写出来的。这代码质量可不是我的水平。我能写出更好的代码，只是速度会慢得多 :)