doc-lib-mcp MCP 服务器

一个用于文档摄入、分块、语义搜索和笔记管理的模型上下文协议 (MCP) 服务器。

组件

资源

• 实现了一个简单的笔记存储系统，包括：
  • 自定义 note:// URI 方案，用于访问单个笔记
  • 每个笔记资源都有名称、描述和 text/plain MIME 类型

提示

• 提供了一个提示：
  • summarize-notes: 创建所有存储笔记的摘要
    • 可选的 "style" 参数来控制详细程度（简略/详细）
    • 根据当前所有笔记和风格偏好生成提示

工具

服务器实现了多种工具：

• add-note: 向内存中的笔记存储添加新的笔记
  • 参数: name (字符串), content (字符串)
• ingest-markdown: 摄入并分块一个 Markdown (.md) 文件
  • 参数: path (字符串)
• ingest-python: 摄入并分块一个 Python (.py) 文件
  • 参数: path (字符串)
• ingest-openapi: 摄入并分块一个 OpenAPI JSON 文件
  • 参数: path (字符串)
• ingest-html: 摄入并分块一个 HTML 文件
  • 参数: path (字符串)
• ingest-html-url: 从 URL 摄入并分块 HTML 内容（可选地使用 Playwright 处理动态内容）
  • 参数: url (字符串), dynamic (布尔值, 可选)
• search-chunks: 对摄入的内容进行语义搜索
  • 参数:
    • query (字符串): 语义搜索查询。
    • top_k (整数, 可选, 默认 3): 返回的顶部结果数量。
    • type (字符串, 可选): 按块类型过滤结果（例如，code, html, markdown）。
    • tag (字符串, 可选): 按块元数据中的标签过滤结果。
  • 返回给定查询最相关的块，可选地按类型和/或标签过滤。
• delete-source: 删除来自指定来源的所有块
  • 参数: source (字符串)
• ingest-batch: 批量摄入并分块多个文档文件（Markdown、OpenAPI JSON、Python）
  • 参数: paths (字符串列表)
• list-sources: 列出所有已摄入并存储在内存中的唯一来源（文件路径）
• update-chunk-metadata: 通过 ID 更新块的元数据字段
  • 参数: id (整数), metadata (对象)
• tag-chunks-by-source: 为与给定来源（URL 或文件路径）关联的所有块的元数据添加指定标签。与现有标签合并。
  • 参数: source (字符串), tags (字符串列表)
• list-notes: 列出所有当前存储的笔记及其内容。

分块和代码提取

• Markdown、Python、OpenAPI 和 HTML 文件被分割成逻辑块，以便高效检索和搜索。
• HTML 分块器使用 readability-lxml 库首先提取主要内容。
• 然后从 <pre> 标签中提取代码块作为专用的 "code" 块。内联的 <code> 内容仍然保留在叙述性块中。

语义搜索

• search-chunks 工具对所有摄入的内容执行基于向量的语义搜索，为给定查询返回最相关的片段。
• 支持可选的 type 和 tag 参数，在进行语义排序之前，根据片段类型（例如，code、html、markdown）和/或片段元数据中的标签来过滤结果。
• 这使得可以进行高度针对性的检索，例如“与‘成本和使用’相关的所有标记为‘langfuse’的代码片段”。

元数据管理

• 片段包含一个用于分类和标记的 metadata 字段。
• update-chunk-metadata 工具允许通过片段 ID 更新任何片段的元数据。
• tag-chunks-by-source 工具允许在一个操作中为来自特定源的所有片段添加标签。标签会将新标签与现有标签合并，保留之前的标签。

配置

[TODO: 添加特定于您的实现的配置细节]

快速开始

安装

Claude 桌面版

在 MacOS 上：~/Library/Application\ Support/Claude/claude_desktop_config.json
在 Windows 上：%APPDATA%/Claude/claude_desktop_config.json

开发

构建和发布

要准备包以供分发：

1. 同步依赖项并更新锁文件：

uv sync

1. 构建包分发：

uv build

这将在 dist/ 目录中创建源码和 wheel 分发。

1. 发布到 PyPI：

uv publish

注意：您需要通过环境变量或命令标志设置 PyPI 凭证：

• 令牌：--token 或 UV_PUBLISH_TOKEN
• 或用户名/密码：--username/UV_PUBLISH_USERNAME 和 --password/UV_PUBLISH_PASSWORD

调试

由于 MCP 服务器通过 stdio 运行，调试可能会有挑战性。为了获得最佳调试体验，我们强烈建议使用 MCP Inspector。

您可以使用以下命令通过 npm 启动 MCP Inspector：

npx @modelcontextprotocol/inspector uv --directory /home/administrator/python-share/documentation_library/doc-lib-mcp run doc-lib-mcp

启动后，Inspector 将显示一个 URL，您可以在浏览器中访问该 URL 开始调试。