文档处理与语义搜索服务器

doc-lib-mcp-mcp服务器

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

组件

资源

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

鼓励

• 提供提示：
  • 总结笔记：创建所有存储笔记的摘要
    • 可选的“style”参数，用于控制详细程度（简短/详细）
    • 生成将所有当前注释与样式首选项组合的提示

工具

服务器实现了广泛的工具：

• 添加注释：将新笔记添加到内存中的笔记存储中
  • 论据： name （字符串）， content （字符串）
• 摄取字符串：摄取并分块通过消息提供的标记或纯文本字符串
  • 论据： content （字符串，必填）， source （字符串，可选）， tags （字符串列表，可选）
• 摄入降价：摄取并分块一个markdown（.md）文件
  • 论据： path （字符串）
• 摄取python：摄取并分块一个Python（.py）文件
  • 论据： path （字符串）
• ingest-openapi 的：摄取并分块OpenAPI JSON文件
  • 论据： path （字符串）
• 摄取html：摄取并分块HTML文件
  • 论据： path （字符串）
• 摄取html url：从URL中摄取和分块HTML内容（可选使用Playwright处理动态内容）
  • 论据： url （字符串）， dynamic （布尔值，可选）
• 智能决策：使用Gemini从文件中提取所有技术相关内容，然后使用健壮的markdown逻辑对其进行分块。
  • 论据：
    • path （字符串，必填）：要摄取的文件路径。
    • prompt （字符串，可选）：用于Gemini的自定义提示。
    • tags （字符串列表，可选）：用于分类的可选标签列表。
  • 使用Gemini 2.0 Flash 001仅提取代码、配置、标记结构和技术定义（没有摘要或评论）。
  • 将提取的内容传递给基于mistune 3.x的分块器，该分块器将代码块和markdown/叙述内容作为单独的块保留。
  • 每个块都被嵌入并存储用于语义搜索和检索。
• 搜索块：对摄入的内容进行语义搜索
  • 论据：
    • query （string）：语义搜索查询。
    • top_k （整数，可选，默认值3）：要返回的顶部结果数。
    • type （string，可选）：按块类型过滤结果（例如。， code, html, markdown).
    • tag （字符串，可选）：按块元数据中的标签过滤结果。
  • 返回给定查询的最相关块，可选择按类型和/或标记进行筛选。
• 删除源：删除给定源中的所有块
  • 论据： source （字符串）
• 按id删除块：按id删除一个或多个块
  • 论据： id （整数，可选）， ids （整数列表，可选）
  • 您可以通过指定删除单个块 id，或通过指定一次删除多个块 ids.
• 更新块类型：按id更新块的类型属性
  • 论据： id （整数，必填）， type （字符串，必填）
• 摄入批次：批量摄取和分块多个文档文件（markdown、OpenAPI JSON、Python）
  • 论据： paths （字符串列表）
• 列出来源：列出已摄入并存储在内存中的所有唯一源（文件路径），并可选择按标签或语义搜索进行过滤。
  • 论据：
    • tag （字符串，可选）：按块元数据中的标签过滤源。
    • query （字符串，可选）：语义搜索查询，查找相关来源。
    • top_k （整数，可选，默认值10）：使用查询时返回的顶级源的数量。
• 获取上下文：检索相关内容块（仅内容）用作AI上下文，并按标签、类型和语义相似性进行过滤。
  • 论据：
    • query （字符串，可选）：语义搜索查询。
    • tag （string，可选）：按块元数据中的特定标记过滤结果。
    • type （字符串，可选）：按块类型过滤结果（例如“code”、“markdown”）。
    • top_k （整数，可选，默认值5）：要检索的最相关块的数量。
• 更新块元数据：按id更新块的元数据字段
  • 论据： id （整数）， metadata （对象）
• 按来源标记块：将指定的标记添加到与给定源（URL或文件路径）关联的所有块的元数据中。与现有标签合并。
  • 论据： source （字符串）， tags （字符串列表）
• 列出注释：列出当前存储的所有笔记及其内容。

分块和代码提取

• Markdown、Python、OpenAPI和HTML文件被拆分为逻辑块，以实现高效检索和搜索。
• markdown分块器使用mistune 3.x的AST API和regex，通过代码块和叙述对内容进行稳健分割，保留所有原始格式。
• 代码块和标记/叙述内容都作为单独的块保留。
• HTML分块器使用 readability-lxml 库首先提取主要内容，然后从中提取块代码片段 <pre> 标记为专用的“代码”块。内联 <code> 内容仍然是叙事块的一部分。

语义搜索

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

元数据管理

• 块包括 metadata 用于分类和标记的字段。
• 这 update-chunk-metadata 该工具允许通过其id更新任何块的元数据。
• 这 tag-chunks-by-source 该工具允许在一次操作中向来自特定源的所有块添加标签。标记将新标记与现有标记合并，保留以前的标记。

配置

服务器需要以下环境变量（可以在.env文件中设置）：

Ollama配置

• OLLAMA_HOST:OLLAMA API的主机名（默认值：localhost）
• OLLAMA_PORT:OLLAMA API的端口（默认值：11434）
• RAG_AGENT：用于RAG响应的Ollama模型（默认：llama3）
• OLLAMA_MODEL：用于嵌入的OLLAMA模型（默认：nomic-embed-ext-v2-moe）

数据库配置

• HOST：PostgreSQL数据库主机（默认：localhost）
• DB_PORT:PostgreSQL数据库端口（默认值：5432）
• DB_NAME：PostgreSQL数据库名称（默认：doclibdb）
• DB_USER:PostgreSQL数据库用户（默认：doclibdb_USER）
• DB_PASSWORD：PostgreSQL数据库密码（默认：doclibdb_PASSWORD）

重新排序器配置

• RERANKER_MODEL_PATH：重新链接器模型的路径（默认：/srv/samba/fileshare2/AI/models/bge-ranker-v2-m3）
• RERANKER_USE_FP6:是否使用FP16进行重新登录（默认值：True）

快速启动

安装

克劳德桌面

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

发展

建筑与出版

准备分发包裹：

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

uv sync

2. 构建包分发：

uv build

这将在 dist/ 目录。

3. 发布到PyPI：

uv publish

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

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

调试

由于MCP服务器在stdio上运行，调试可能具有挑战性。为了达到最佳调试效果 经验，我们强烈建议使用 MCP检查员.

您可以通过以下方式启动MCP检查器 npm 使用此命令：

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

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