Local MCP Rag Server

LM Studio的本地上下文MCP服务器

Markdown知识库的本地离线RAG。文档被索引到ChromaDB中，通过MCP工具搜索，并通过LM Studio嵌入。

这支持什么

• 纯Markdown索引，无需特殊格式
• 用于元数据和可过滤搜索的可选YAML frontmatter
• Markdown感知分块 保留文档结构和层次结构
• 节元数据 包括分层路径和父标头
• 维基链接提取 用于交叉引用实体
• 带有删除检测和内容哈希的增量索引
• 紧凑的候选检索，然后进行集中块读取
• 仅通过LM Studio和ChromaDB进行本地操作

先决条件

• Python 3.12+（使用Python 3.12开发和测试）
• LM Studio在本地运行
• LM Studio中加载的嵌入模型

推荐的嵌入模型： nomic-embed-text-v1.5

配置

项目从以下位置读取配置 .env 在项目根中。

支持的环境变量：

• DOCUMENTS_DIR
• CHROMA_DB_PATH
• COLLECTION_NAME
• INDEX_STATE_PATH
• LM_STUDIO_BASE_URL
• EMBEDDING_MODEL
• SEARCH_DEFAULT_RESULTS
• SEARCH_SNIPPET_CHARS
• SEARCH_MAX_CONTEXT_CHARS
• CHUNK_TARGET_SIZE
• CHUNK_MIN_SIZE
• CHUNKING_STRATEGY （标记或段落）
• CHUNK_INCLUDE_PARENT_HEADERS （真/假）
• CHUNK_EXTRACT_WIKILINKS （真/假）
• READ_DEFAULT_WINDOW_BEFORE
• READ_DEFAULT_WINDOW_AFTER
• LOG_LEVEL

相对路径 .env 从项目根解析。

摄入工作流程

为配置的文档文件夹建立索引：

python ingest.py

从头开始重建索引：

python ingest.py --reset

使用另一个源文件夹：

python ingest.py --documents-dir /path/to/documents

增量行为：

• 跳过未更改的文件
• 更改的文件会重新嵌入并同步
• 已删除的文件将从索引中删除

如果你改变 CHUNK_TARGET_SIZE, CHUNK_MIN_SIZE，或 CHUNKING_STRATEGY，跑 python ingest.py --reset 因此，所存储的块边界与新的检索设置相匹配。

分块策略

该系统支持两种组块策略，由 CHUNKING_STRATEGY 在 .env:

Markdown感知分块（默认值： CHUNKING_STRATEGY=markdown)

此策略解析Markdown结构以创建智能块：

特征：

• 尊重文档层次结构（H1、H2、H3标题）
• 保留父标题的节上下文
• 提取和索引维基链接([[entity]])用于交叉引用
• 将相关内容放在一起（列表、小节）
• 向每个块添加节元数据

优点：

• 结构化内容的检索精度更高
• 在搜索结果中保留分层上下文
• 具有父标头上下文的自包含块
• 通过维基链接跟踪实体关系

配置：

• CHUNK_INCLUDE_PARENT_HEADERS=true -将父标头预置到块中
• CHUNK_EXTRACT_WIKILINKS=true -提取物 [[wikilinks]] 作为元数据

例子： 在字符文件中搜索“Talion”将返回带有元数据的块，显示它来自“关系>Talion--起源/无论什么”，使上下文清晰，而不需要获取父节。

基于段落的分块(CHUNKING_STRATEGY=paragraph)

回到基于双换行的简单段落分割。适用于没有清晰标题结构的文档。

可选元数据

平原 .md 文件在没有任何元数据的情况下工作。

如果你想要可过滤的搜索，你可以添加YAML frontmatter：

---
title: Example Title
category: guides
tags:
  - metadata
  - filters
source_type: file
status: draft
---

已识别字段：

• title
• category
• tags
• source_type

其他frontmatter字段作为额外的元数据保留，并使用 meta_ 前缀。

示例模板已上线 documents/.

LM Studio MCP配置

Windows配置示例：

{
  "mcpServers": {
    "local-context": {
      "command": "C:/path/to/local-mcp-rag-server/venv/Scripts/python.exe",
      "args": ["C:/path/to/local-mcp-rag-server/mcp_server.py"]
    }
  }
}

macOS/Linux配置示例：

{
  "mcpServers": {
    "local-context": {
      "command": "/path/to/local-mcp-rag-server/venv/bin/python",
      "args": ["/path/to/local-mcp-rag-server/mcp_server.py"]
    }
  }
}

将路径替换为项目目录的实际绝对路径。

暴露于MCP的工具

• search_documents
• get_document_chunk
• list_documents
• list_categories

搜索文档

返回紧凑的候选项，而不是完整的文档正文。

可选输入：

• n_results
• min_score
• max_context_chars
• mode: vector, keyword，或 hybrid
• category
• source_type
• filepath_contains
• title_contains
• tags

返回的候选人包括：

• doc_id
• chunk_id
• 标题/路径/类别/源元数据
• 得分
• 紧凑的片段
• 定位器信息通过 chunk_index

get_document_chunk

获取一个块的全文，可选地使用相邻的块窗口：

• doc_id
• chunk_id
• window_before
• window_after

这是预期的第二步 search_documents.

list_文档

列出索引文档，包括：

• limit
• cursor
• 可选元数据筛选器

列表_类别

列出知识库中当前包含块计数的所有文档类别。

分块元数据（Markdown策略）

当使用Markdown感知分块时，每个分块都包含丰富的元数据：

标准元数据：

• filepath, filename, title, category, tags_text
• chunk_index -文档中的位置

节元数据：

• section_h1, section_h2, section_h3 -标题层次结构
• section_path -完整的层次结构路径（例如，“摘要>关系>Talion”）
• linked_entities -在部分中找到的维基链接数组

子块元数据（用于分割部分）：

• sub_chunk_index -分割部分内的索引
• sub_chunk_total -该部分中的子块总数

此元数据是可搜索的，并出现在搜索结果中，在不获取完整文档的情况下提供丰富的上下文。

检索说明

当前默认值已针对平衡上下文使用进行了调整：

• SEARCH_DEFAULT_RESULTS=5
• SEARCH_SNIPPET_CHARS=450
• SEARCH_MAX_CONTEXT_CHARS=2500
• CHUNK_TARGET_SIZE=1400
• CHUNK_MIN_SIZE=350

这保持 search_documents 紧凑的同时让 get_document_chunk 仅在需要时获取更广泛的上下文。

日志记录

日志记录旨在在不淹没控制台的情况下有用：

• 启动/配置摘要位于 INFO
• 在以下位置摄取摘要和更改/删除的文件活动 INFO
• 以下位置的文件格式错误或被跳过 WARNING
• 失败在 ERROR
• 额外细节可通过以下方式获得 LOG_LEVEL=DEBUG

测试

运行：

python -m unittest discover tests

测试涵盖了分块、前体解析、增量索引规划和元数据过滤器匹配。

故障排除

无法连接到LM Studio

• 确保LM Studio正在运行
• 确保本地服务器已启用
• 确保已加载嵌入模型
• 验证 LM_STUDIO_BASE_URL 匹配LM工作室

搜索未返回任何结果

• 跑 python ingest.py
• 如果文件已更改，请运行 python ingest.py --reset

MCP服务器无法启动

• 验证 mcp_server.py LM Studio中的路径
• 安装依赖项 pip install -r requirements.txt