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库首先提取主要内容，然后从中提取块代码片段 `
标记为专用的“代码”块。内联 ` 内容仍然是叙事块的一部分。
语义搜索
- 这
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
Development/Unpublished Servers Configuration
"mcpServers": {
"doc-lib-mcp": {
"command": "uv",
"args": [
"--directory",
"/home/administrator/python-share/doc-lib-mcp",
"run",
"doc-lib-mcp"
]
}
}Published Servers Configuration
"mcpServers": {
"doc-lib-mcp": {
"command": "uvx",
"args": [
"doc-lib-mcp"
]
}
}发展
建筑与出版
准备分发包裹：
- 同步依赖关系并更新锁文件：
uv sync- 构建包分发：
uv build这将在 dist/ 目录。
- 发布到PyPI：
uv publish注意：您需要通过环境变量或命令标志设置PyPI凭据：
- 令牌：
--token或UV_PUBLISH_TOKEN - 或用户名/密码：
--username/UV_PUBLISH_USERNAME和--password/UV_PUBLISH_PASSWORD
调试
由于MCP服务器在stdio上运行，调试可能具有挑战性。为了达到最佳调试效果 经验，我们强烈建议使用 MCP检查员.
您可以通过以下方式启动MCP检查器 使用此命令：
npx @modelcontextprotocol/inspector uv --directory /home/administrator/python-share/doc-lib-mcp run doc-lib-mcp启动后，检查器将显示一个URL，您可以在浏览器中访问该URL以开始调试。