doc-lib-mcp MCP 服务器

用于文档提取、分块、语义搜索和注释管理的模型上下文协议 (MCP) 服务器。

成分

资源

• 实现一个简单的笔记存储系统：

  • 用于访问单个笔记的自定义note:// URI 方案

  • 每个笔记资源都有一个名称、描述和text/plain mimetype

提示

• 提供提示：

  • 总结笔记：创建所有存储笔记的摘要

    • 可选的“样式”参数用于控制详细程度（简要/详细）

    • 生成提示，结合所有当前注释和样式偏好

工具

该服务器实现了多种工具：

• add-note ：向内存笔记存储中添加新笔记

  • 参数： name （字符串）、 content （字符串）

• ingest-string ：提取并分块通过消息提供的 markdown 或纯文本字符串

  • 参数： content （字符串，必需）、 source （字符串，可选）、 tags （字符串列表，可选）

• 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 （布尔值，可选）

• smart_ingestion ：使用 Gemini 从文件中提取所有技术相关内容，然后使用强大的 markdown 逻辑对其进行分块。

  • 参数：

    • path （字符串，必需）：要摄取的文件路径。

    • prompt （字符串，可选）：用于 Gemini 的自定义提示。

    • tags （字符串列表，可选）：用于分类的可选标签列表。

  • 使用 Gemini 2.0 Flash 001 仅提取代码、配置、markdown 结构和技术定义（无摘要或评论）。

  • 将提取的内容传递给基于 mistune 3.x 的分块器，该分块器将代码块和 markdown/narrative 内容保存为单独的块。

  • 每个块都被嵌入并存储以用于语义搜索和检索。

• search-chunks ：对获取的内容进行语义搜索

  • 参数：

    • query （字符串）：语义搜索查询。

    • top_k （整数，可选，默认值为 3）：要返回的前结果数。

    • type （字符串，可选）：按块类型过滤结果（例如， code ， html ， markdown ）。

    • tag （字符串，可选）：通过块元数据中的标签过滤结果。

  • 返回给定查询最相关的块，可选择按类型和/或标签进行过滤。

• delete-source ：删除给定源的所有块

  • 参数： source （字符串）

• delete-chunk-by-id ：通过 id 删除一个或多个块

  • 参数： id （整数，可选）、 ids （整数列表，可选）

  • 您可以通过指定id删除单个块，或者通过指定ids一次删除多个块。

• update-chunk-type ：通过 id 更新块的类型属性

  • 参数： id （整数，必需）、 type （字符串，必需）

• ingest-batch ：批量提取和分块多个文档文件（markdown、OpenAPI JSON、Python）

  • 参数： paths （字符串列表）

• list-sources ：列出已摄取并存储在内存中的所有唯一源（文件路径），并可选择按标签或语义搜索进行过滤。

  • 参数：

    • tag （字符串，可选）：通过块元数据中的标签过滤源。

    • query （字符串，可选）：语义搜索查询以查找相关来源。

    • top_k （整数，可选，默认值为 10）：使用查询时返回的顶级源的数量。

• get-context ：检索相关内容块（仅内容）以用作 AI 上下文，并按标签、类型和语义相似性进行过滤。

  • 参数：

    • query （字符串，可选）：语义搜索查询。

    • tag （字符串，可选）：通过块元数据中的特定标签过滤结果。

    • type （字符串，可选）：按块类型过滤结果（例如，“代码”，“markdown”）。

    • top_k （整数，可选，默认值为 5）：要检索的顶级相关块的数量。

• update-chunk-metadata ：通过 id 更新块的元数据字段

  • 参数： id （整数）、 metadata （对象）

• tag-chunks-by-source ：将指定的标签添加到与给定源（URL 或文件路径）关联的所有块的元数据中。并与现有标签合并。

  • 参数： source （字符串）、 tags （字符串列表）

• list-notes ：列出所有当前存储的笔记及其内容。

分块和代码提取

• Markdown、Python、OpenAPI 和 HTML 文件被分成逻辑块，以便高效检索和搜索。

• markdown chunker 使用 mistune 3.x 的 AST API 和正则表达式通过代码块和叙述稳健地分割内容，保留所有原始格式。

• 代码块和 markdown/narrative 内容都作为单独的块保存。

• HTML 分块器首先使用readability-lxml库提取主要内容，然后从<pre>标签中提取代码块作为专用的“代码”块。内联<code>内容仍保留为叙述块的一部分。

语义搜索

• search-chunks工具对所有摄取的内容执行基于向量的语义搜索，返回与给定查询最相关的块。

• 支持可选的type和tag参数，以便在语义排名之前按块类型（例如， code 、 html 、 markdown ）和/或块元数据中的标签过滤结果。

• 这使得高度有针对性的检索成为可能，例如“所有标有‘langfuse’且与‘成本和使用情况’相关的代码块”。

元数据管理

• 块包括用于分类和标记的metadata字段。

• update-chunk-metadata工具允许通过其 id 更新任何块的元数据。

• tag-chunks-by-source工具允许一次性为来自特定来源的所有区块添加标签。添加标签会将新标签与现有标签合并，并保留旧标签。

配置

[TODO：添加特定于您的实现的配置详细信息]

快速入门

安装

克劳德桌面

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

发展

构建和发布

准备分发包：

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

2. 构建软件包分发版：

这将在dist/目录中创建源和轮子分布。

3. 发布到 PyPI：

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

• 令牌： --token或UV_PUBLISH_TOKEN

• 或用户名/密码： --username / UV_PUBLISH_USERNAME和--password / UV_PUBLISH_PASSWORD

调试

由于 MCP 服务器通过 stdio 运行，调试起来可能比较困难。为了获得最佳调试体验，我们强烈建议使用MCP Inspector 。

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

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