笔记本库MCP服务器
用于底物AI代理的令牌高效文档检索。将PDF、文本文件和markdown放入笔记本文件夹中——它们会被分块、嵌入和索引以进行语义搜索。查询只返回最相关的段落（约2500个标记），而不是加载整个文档（50000+）。
它的作用
您的AI代理将获得 notebook_library 工具执行以下操作：
| 动作 | 描述 |
|---|---|
list_notebooks | 查看所有可用笔记本 |
create_notebook | 创建新的笔记本收藏 |
query_notebook | 笔记本中的语义搜索（最主要的！） |
browse_notebook | 在笔记本中列出文档 |
read_document | 逐块深度读取特定文档 |
notebook_stats | 获取笔记本的统计信息 |
sync_notebook | 添加/更改文件后重新同步 |
remove_document | 从搜索索引中删除文档 |
支持的文件格式： .pdf, .txt, .md, .text, .markdown
建筑
data/
├── notebooks/ # Your document folders
│ ├── Research_Papers/ # Each subfolder = one notebook
│ │ ├── paper1.pdf
│ │ └── notes.md
│ └── Business_Docs/
│ └── plan.txt
└── notebook_chromadb/ # Vector database (auto-created)
└── manifests/ # File change tracking
mcp_servers/
└── notebook_library/
├── server.py # MCP server (if running standalone)
├── notebook_manager.py # Core: ChromaDB ingestion + search
├── document_processor.py # Text extraction + chunking
├── file_watcher.py # Auto-ingestion on file changes
└── requirements.txt
backend/tools/
├── notebook_library_tool.py # Tool wrapper for consciousness loop
└── notebook_library_tool_schema.json # Tool schema definition嵌入策略（多层回退）：
- 拥抱脸 (
jinaai/jina-embeddings-v2-base-de)--本地、免费、多语言 - 奥拉玛 (
nomic-embed-text)--如果HF失败，则进行本地回退
不需要外部API密钥。一切都在本地运行。
安装指南
1.安装依赖项
从您的基质根：
pip install -r mcp_servers/notebook_library/requirements.txt关键依赖关系：
chromadb==0.4.18--矢量数据库transformers+torch--拥抱面部嵌入（初级）ollama--嵌入回退PyMuPDF--PDF文本提取watchdog--文件系统监控
注： 第一次运行将下载拥抱脸嵌入模型（约270MB）。这是一次性下载。
2.创建数据目录
mkdir -p data/notebooks
mkdir -p data/notebook_chromadb3.复制MCP服务器文件
复制整个 mcp_servers/notebook_library/ 目录到您的基板：
your_substrate/
└── mcp_servers/
└── notebook_library/
├── __init__.py
├── server.py
├── notebook_manager.py
├── document_processor.py
├── file_watcher.py
└── requirements.txt4.复制工具包装
将这两个文件复制到您的 backend/tools/ 目录：
backend/tools/notebook_library_tool.py --你的意识循环调用的工具功能。这个进口 NotebookManager 直接（无子流程）。
backend/tools/notebook_library_tool_schema.json --工具模式，以便您的代理知道如何调用它。
5.在你的意识循环中注册该工具
三个集成点：
a） 导入 integration_tools.py
添加到您的导入中：
from tools.notebook_library_tool import notebook_library_tool as _notebook_library_tool将包装器方法添加到您的 IntegrationTools 类别：
def notebook_library(self, **kwargs) -> Dict[str, Any]:
"""
Notebook Library — token-efficient document retrieval.
"""
try:
result = _notebook_library_tool(**kwargs)
return result
except Exception as e:
return {
"status": "error",
"message": f"Notebook library error: {str(e)}"
}添加 'notebook_library_tool' 将JSON模式添加到您的工具模式加载列表中，以便提取JSON模式。
b） 在中添加工具调用处理程序 consciousness_loop.py
在您的工具执行块中（您处理 elif tool_name == "..." 案例），添加：
elif tool_name == "notebook_library":
result = self.tools.notebook_library(**arguments)c） 验证架构加载
工具架构文件(notebook_library_tool_schema.json)必须在 backend/tools/ 与其他工具模式一起。如果模式加载器遵循与其他工具相同的模式，它应该会自动拾取它。
6.添加文档
创建笔记本文件夹并将文件放入：
mkdir -p data/notebooks/My_Research
cp ~/some_paper.pdf data/notebooks/My_Research/
cp ~/notes.md data/notebooks/My_Research/当您的代理首次查询笔记本时，文档会自动获取，或者您可以通过以下方式触发手动同步 sync_notebook 行动。
环境变量（可选）
所有这些都有合理的违约。仅在需要时覆盖：
| 变量 | 默认值 | 描述 |
|---|---|---|
NOTEBOOK_LIBRARY_PATH | data/notebooks | 笔记本文件夹所在的位置 |
NOTEBOOK_CHROMADB_PATH | data/notebook_chromadb | 矢量数据库存储 |
OLLAMA_BASE_URL | http://192.168.2.175:11434 | Ollama服务器（回退嵌入） |
OLLAMA_EMBEDDING_MODEL | nomic-embed-text | Olama型号名称 |
NOTEBOOK_CHUNK_SIZE | 2000 | 每块字符数 |
NOTEBOOK_CHUNK_OVERLAP | 200 | 块之间的重叠 |
重要提示： 更新 OLLAMA_BASE_URL 如果你使用Ollama回退，请指向你自己的Ollama实例。默认值指向原始开发人员的本地网络。
运作原理
- 摄入： 文档被分割成块（每个约2000个字符，重叠200个字符），使用Hugging Face或Ollama嵌入，并存储在ChromaDB集合中（每个笔记本电脑一个）。
- 查询： 代理的查询嵌入了相同的模型，然后ChromaDB通过余弦相似度找到最相似的块。仅返回前N个段落（默认值5）。
- 文件跟踪： 清单系统（MD5哈希）跟踪哪些文件已被摄入。更改的文件会被重新处理；跳过未更改的文件。
- 文件监视： 基于监视器的文件监视器监视笔记本文件夹，并通过2秒的去抖动自动摄取新的/修改的文件。
代理使用示例
一旦集成，您的代理可以像这样使用它：
# List what's available
notebook_library(action="list_notebooks")
# Search for something specific
notebook_library(action="query_notebook", notebook="Research_Papers", query="transformer attention mechanisms")
# Browse a notebook's contents
notebook_library(action="browse_notebook", notebook="Research_Papers")
# Deep-read a specific document
notebook_library(action="read_document", notebook="Research_Papers", filename="paper1.pdf")
# Create a new notebook
notebook_library(action="create_notebook", name="Meeting_Notes", description="Weekly team meetings")故障排除
“未找到笔记本” --确保 data/notebooks/ 存在，并且至少有一个子文件夹包含文件。
第一次查询速度慢 --对笔记本的第一个查询会触发摄取（分块+嵌入所有文档）。后续查询很快。对于大型收藏，请运行 sync_notebook 第一。
嵌入模型下载 --第一次运行下载Jina嵌入模型（约270MB）。如果这在防火墙后失败，系统将回退到Ollama。确保HF模型访问或Ollama实例可用。
ChromaDB版本不匹配 --固定到 chromadb==0.4.18.较新的版本可能有突破性的API更改。
OLLAMA_BASE_URL地址 --如果你看到Ollama连接错误，而你没有使用Ollama，那很好——这只是HF成功后的回退失败。如果HF也失败，请将此URL更新到您的Ollama实例。