Skip to main content
Glama
Mortis-RAG-MCP

Mortis-RAG-MCP

by moton16

Mortis'RAG MCP

CI License: Apache 2.0 Version: 0.9.1

English | 简体中文

面向 Obsidian 与本地知识库的现代化 RAG(检索增强生成)MCP 服务。 纯标准库高能实现,源文件安全驻留本地;深度支持语义检索、跨模态以文搜图、虚拟文档库、多库智能路由与精准阅读。


🚀 当前版本:v0.9.1(修复与性能补丁)

v0.9.1 修复了「本机零成本推理端点被付费闸门误拦、导致索引长时间停摆」的问题,并显著提升大知识库下的检索与重建性能。面向付费端点的安全闸门行为保持不变。

  • 🛡️ 零成本端点不再被误拦:指向回环地址(如 127.0.0.1)且未配置 API 凭据的端点不再进入付费台账,也不会被历史未决请求牵连;已计费风险一侧的 fail-closed 闸门一字未动。

  • 🔓 未决请求不再永久冻死索引:结果落账失败会补位重试一次;零成本端点上的 prepared 请求超过租约后自动放行,可能已计费的 submission_unknown 仍需人工对账。

  • 🔎 堵点可观测:kb_stats 新增 paid_route_blocked,指出每个请求类型当前被哪一条真正卡住(确有堵点时才出现)。

  • ⚡ 更快更省:单次检索的读库次数由 3 次降至 1 次(同步预热后实测 0 次)。本机同一脚本对照下,2,892 文档 / 9,316 切片规模 kb_search 中位耗时 36.1 ms → 20.3 ms(探针相对口径,非跨环境保证);一次 kb_rebuild 只执行一轮全量同步(冷启动 3 → 1、温启动 2 → 1)。


Related MCP server: Smart Connections MCP Server

🏁 上一里程碑:v0.9.0(重大功能发布)

v0.9.0 迎来了架构级的全面跃迁,正式切换至商业友好的 Apache-2.0 开源许可,并带来以下核心突破:

  • 🏢 全新虚拟文档库(Virtual Doc Store):外部文档(PDF/Word/PPT/Excel)解析产物默认入库底层虚拟文档系统,源文件零改写、原笔记目录零污染(不再生成 .mortis-parsed/ 镜像文件),内置代际管理、CAS 校验与段级原子断点续传。

  • 🖼️ 跨模态图文检索打通(Text-to-Image):打通多模态向量对齐空间,支持直接使用自然语言文本检索召回笔记中的插图与图表;新增 kb_read_media 工具支持在受控预算(budget_bytes)内安全直读媒体(注:文字检索图片已跑通,部分外部客户端富媒体展示与特定付费端点装配尚未全量验收)。

  • 🧩 自适应 Token 估算切块(estimated_tokens):新知识库默认启用 Token 粒度自适应切片,语义上下文更连贯完整;建库与检索支持独立 {text} 提示词模板注入;原生收录 .markdown 扩展名。

  • 🔄 工业级摄取重试与未决请求台账:kb_ingest 全新支持 retry 动作,失败/取消任务可精准断点续跑;CLI 新增 --list-requests 与 --abandon-request 管控未决请求意图。

  • 🧹 架构解耦与纯粹化(Breaking Change):彻底剔除重型且低频的外部 ffmpeg 音频转录链路,配置中残留的 [audio] 字段自动静默兼容忽略;已有文本笔记索引与向量缓存 100% 平滑继承。

  • 🪟 Windows 平台加固与防死锁:彻底修复 UTF-8 BOM 配置文件被静默错解进而被 doctor 误判为 BROKEN 的陈年顽疾;重构读写并发锁,消除异步索引自排队假死。

完整变更细节与升级指引见 CHANGELOG_user.md。


🌟 核心特性

  • 🖼️ 跨模态图文检索与媒体直读(0.9.0):支持多模态向量嵌入空间,支持以文搜图(Text-to-Image);新增 kb_read_media 工具精准定位并按字节预算(budget_bytes)按需读取多媒体内容,杜绝上下文溢出。

  • 🏢 非侵入式虚拟文档库(0.9.0):外部复杂文档解析结果默认收敛至用户缓存层虚拟文档系统,保持本地笔记目录 100% 纯净,支持段级断点续传与多代版本原子恢复。

  • 🧩 自适应 Token 估算切块与统一模板(0.9.0):基于 Token 估算的自适应语义切块(estimated_tokens),长文本切分自然连贯;建库与查询支持统一与独立的 {text} 提示词模板定制。

  • 🔄 摄取断点重试与意图台账(0.9.0):kb_ingest 支持指定 job_id 对失败或取消的任务进行断点重试;CLI 随时查阅与管理未决任务,索引生命周期(index_state)多态解耦。

  • ⚡ 紧凑初筛与章节直读(0.8.1):新增 compact=true 极简结构化投影与整块预算续页控制;kb_read 支持按 heading 物理章节与小说分卷直读,附带行号越界精准诊断。

  • 📂 自由挂载,零路径绑定:通过 kb_init 一键挂载任意本地文件夹为知识库,持久化注册表管理,不绑定死路径,换电脑或多库迁移极简。

  • 📖 切片原地展开与双链直读(0.8.0):命中切片后直接由 kb_read(chunk_id=...) 原地展开上下文,省去手工换算行号;遇到 [[双链]] 引用直接按短名快速寻址阅读。

  • 🏷️ 别名检索与硬词保底(0.8.0):原生支持 Obsidian frontmatter aliases 别名;支持 exact_terms 专有名词硬包含保底,生僻术语与专有代号绝不漏召回。

  • 🛡️ 搜索预算控制与本地诊断(0.8.0):支持 budget_bytes 字节硬预算,避免大搜索撑爆模型上下文或击穿客户端缓冲区;支持脱敏本地诊断日志。

  • 📚 库名直呼与多库定向(0.7.2):检索时可直接传库名(如 vault_path="我的笔记"),无需拼接 Windows 漫长路径;支持通过 vault_paths 数组同时指定多个目标库定向检索。

  • 🔍 轻量预览与二段式精读(0.7.2):支持 preview=true 快速返回高光切片与行号,正文配合 kb_read 按需精准精读,大幅降低模型 Token 冗余。

  • 📄 多格式原生收录(.md / .txt / .markdown):纯文本 .txt(小说/分卷/资料)与 .markdown 与标准 Markdown 享有同等一等公民地位,支持小说章节标题自动识别。

  • 🔍 Agent 信任锚,免预检开箱即搜(0.7.1):一条 python -m mortis_rag_mcp --doctor 生成本机环境凭证(STATUS.md)。AI 助手读到 ✅ 即不再做任何环境/依赖/key 预检,首次提问就直接检索,省掉每次调用前的反复试探。

  • 🎯 智能定向路由与权重分配(0.7.0):支持为知识库配置自然语言描述(kb_describe),支持跨库检索权重调整(kb_set_weight),AI 检索时按意图精准选库。

  • 🔒 私密独立库(solo)隔离:支持注册独立私密库(kb_init_solo),默认不参与跨库全局搜索,仅在显式指定时查询,妥善保护个人隐私。

  • ⚡ 混合检索与毫秒级增量同步:融合关键词全文检索(BM25/FTS)与语义向量召回,配合自动重排序;支持原生文件监听与读优先后台增量同步,笔记随写随搜。

  • 📦 轻量纯粹,零沉重运行时依赖:核心功能纯标准库实现(dependencies = []),轻量可靠,可选依赖(pymupdf、sqlite-vec 等)按需热插拔。


🛠️ 完整工具一览(16 个核心 MCP 工具)

Mortis'RAG MCP 提供了 16 个标准化 MCP 工具,覆盖从知识库注册、混合检索、多模态直读到文档摄取与运维全生命周期:

1. 知识库挂载与多库管理

工具

用途说明

kb_init

注册并挂载新知识库(指定物理文件夹路径与显示名称)

kb_init_solo

注册/转换为私密独立库(默认排除在跨库盲搜外,仅显式指定时检索)

kb_list

查看当前已注册的全部知识库列表、路径与状态

kb_describe

设置知识库自然语言描述,引导 AI 按意图进行智能路由选库

kb_set_weight

设置指定知识库在跨库联合检索中的打分权重比重

kb_remove

从注册表移除知识库(安全操作,绝不删除本地实际笔记文件)

2. 混合检索与原文精读

工具

用途说明

kb_search

语义向量与关键词混合检索(支持跨库/多库定向、目录过滤、分页、preview 预览模式、compact 紧凑投影与 exact_terms 硬词保底)

kb_read

精准读取原文笔记(支持按物理文件路径、行号区间、切片编号 chunk_id 原地展开、双链 [[短名]] 寻址或 heading 章节直读)

kb_read_media

(0.9.0 新增) 按版本(revision_id)与位置(occurrence_id)精准读取笔记中的图片与多媒体内容,支持受预算保护直读媒体块

3. 文档摄取与外部格式解析

工具

用途说明

kb_ingest

摄取并解析知识库内的 PDF / Office / 外部文档(支持 submit 提交、status 查状态、pending 查进度、retry 任务断点恢复)

4. 状态浏览、豁免与维护备份

工具

用途说明

kb_stats

查看知识库文件数、切片数、向量模型与底层加速依赖状态

kb_list_files

分页浏览知识库已收录的文件列表,支持目录前缀过滤

kb_exempt

管理知识库豁免规则与单文件排除(即时生效,毫秒级响应)

kb_rebuild

强制全量重新构建指定知识库的全文与向量索引

kb_export

导出知识库配置、权重与元数据备份快照

kb_import

从备份恢复知识库元数据,解耦反馈索引构建状态(index_state)


🚀 5 分钟快速上手

1. 安装

环境要求:Python 3.10+。

git clone https://github.com/moton16/Mortis-RAG-MCP.git
cd Mortis-RAG-MCP
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e .

可选依赖:

  • 本地 Office/PDF 解析支持:pip install -e ".[docs]"

  • 磁盘向量数据库加速:pip install -e ".[vec]"

2. 配置

从模板复制配置文件:

Copy-Item .\config\app.toml.example .\config\app.toml

(1) 基础配置:Embedding API Key(用于笔记语义检索)

推荐使用免费档硅基流动 BAAI/bge-m3:

  • 方式一(推荐):设置系统环境变量 MORTIS_RAG_API_KEY=你的API密钥(同时兼容旧名 VAULT_MCP_API_KEY)。

  • 方式二:直接在 config/app.toml 中配置你的服务商地址与密钥。

(2) 可选配置:MinerU 接入(用于 PDF / Office 文档解析摄取)

如果需要检索知识库内的 PDF、Word、PPT、Excel 文件:

  1. 打开 config/app.toml,在 [ingest] 小节将 enabled = true。

  2. 配置 MinerU Token(两种方式):

    • 高精度通道(推荐):前往 mineru.net 免费获取 API Token,设置系统环境变量 MINERU_API_TOKEN=你的Token(或在 config/app.toml 的 [ingest] 中填写 api_key = "你的Token"),享受每日 1000 页额度并支持文档插图提取。

    • 免登试用通道:留空 api_key 即可直接使用(适合 20 页以内的日常小文档体验;该通道为轻量纯文本提取,不返回图片)。

3. 接入 AI 客户端

服务以标准 stdio 模式运行,直接在你的 MCP 客户端中配置即可:

WorkBuddy / 自定义 JSON 连接器

{
  "mortis-rag-mcp": {
    "command": "python",
    "args": ["-m", "mortis_rag_mcp", "--serve-mcp-stdio", "--app-config", "C:\\你的路径\\config\\app.toml"],
    "env": {
      "MORTIS_RAG_API_KEY": "你的API密钥",
      "MINERU_API_TOKEN": "可选,用于PDF解析的MinerU密钥"
    }
  }
}

Codex / Trae / TOML 配置

[mcp_servers.mortis_rag_mcp]
command = "mortis-rag-mcp"
args = ["--serve-mcp-stdio", "--app-config", "C:\\你的路径\\config\\app.toml"]
enabled = true

4. 初始化与使用

连接成功后,在对话中对 AI 助手说:

"帮我用 kb_init 注册知识库:D:\我的笔记"

知识库即可在后台自动建立索引。之后只需自然提问:

"搜一下数电笔记里关于触发器的内容" "查一下知识库里关于项目架构的说明"


📚 详细文档与导航


📄 License

本项目自 v0.9.0 起采用 Apache License 2.0 开源许可(v0.8.1 及更早版本仍为 MIT,已发布版本的历史授权不受影响)。

可选解析依赖(如 PyMuPDF)由用户自行安装,不在本项目的 Apache-2.0 授权范围内,各自的许可证见 NOTICE。

Available Tools

12 tools
kb_exemptA

查看、添加、删除知识库的 RAG 豁免项(排除不希望被检索的私密/草稿内容)。支持查看规则、添加/删除 .vaultignore 通配符、标记/取消单个文件豁免、检查文件豁免状态。

Inputs: action (required), method, source, pattern, +1 more.

kb_exportA

把知识库的索引快照(chunks + 向量 + FTS)导出为 zip 文件,用于换机/换目录迁移,导入后无需全量重新 embedding。要求缓存已启用且完成过至少一次索引。

Inputs: out_path (required), vault_path.

kb_importA

从 kb_export 生成的快照恢复索引缓存(先 kb_init 注册目标目录再调用)。导入后的下一次同步应当 0 次 embedding 调用;快照的向量模型/维度与本机配置不一致时拒绝,除非 force=true(此时只导入文本层并本地重嵌)。

Inputs: snapshot (required), force, vault_path.

kb_initA

注册(初始化)一个文件夹为知识库:校验目录、写入用户级注册表(跨重启保留)、后台建立索引并启动文件监听。首次使用或要纳入新文件夹时调用。

Inputs: path (required), name.

kb_listB

列出已索引的 Markdown 文件。可传 vault_path 指定知识库。

Inputs: vault_path.

kb_readA

读取知识库原文(不调用 LLM 生成回答;若索引有未同步的变更会先触发一次增量同步,可能调用 embedding API,建议带上 start_line/end_line 限定范围避免一次拉全篇)。多库环境下建议显式传 vault_path(fan-out 结果中的 source 是库内相对路径)。

Inputs: source (required), heading, end_line, start_line, +1 more.

kb_rebuildA

删除指定知识库的磁盘缓存并强制全量重建索引(首次建库或内容大改后用)。

Inputs: vault_path.

kb_set_weightA

设置知识库的检索权重:跨库检索时该库所有 chunk 的分数会乘以该系数,用于表达"这个库更重要"(默认 1.0,取值 0 < w <= 100)。

Inputs: weight (required), vault_path (required).

kb_statsB

返回指定知识库的索引状态、失败文件、最后同步时间和模型信息。

Inputs: vault_path.

kb_unregisterA

注销一个已注册的知识库:停止文件监听并从注册表移除(不影响文件夹本身)。

Inputs: path (required), purge_cache.

kb_vaultsA

列出所有已注册的知识库(含存活状态与索引进度)。

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 12 tools

    Disambiguation5/5

    Each tool targets a distinct operation in the RAG knowledge-base lifecycle: init/unregister manage registration, export/import handle snapshots, search/read retrieve content, and stats/vaults/exempt cover status and filtering. Even similar actions like rebuild and import are clearly separated by purpose and described preconditions.

    Naming Consistency4/5

    Tools consistently use a kb_ prefix and short snake_case names, with clear verb-style commands like kb_init, kb_search, and kb_export. Minor deviations exist: kb_vaults and kb_stats are noun-style rather than verb-based, and kb_exempt covers multiple exemption-related actions rather than a single operation.

    Tool Count5/5

    The 12 tools are well-scoped for a RAG knowledge-base management server, covering registration, indexing, migration, search, reading, statistics, weighting, and exemptions. Each tool serves a distinct and necessary role without bloat or redundancy.

    Completeness4/5

    The tool surface covers the core lifecycle well: registering, listing, searching, reading, exporting/importing, rebuilding, unregistering, and managing exemptions are all present. A minor gap is the lack of an explicit manual sync command, though file watching and read-triggered incremental sync largely mitigate this.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that provides always-fresh semantic search over Obsidian vaults, automatically watching file changes and using local embeddings via Ollama.
      67 npm
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      Enables local hybrid search over Obsidian and Markdown vaults via MCP, combining vector retrieval, full-text search, reranking, graph navigation, and safe CRUD while keeping data local.
      43
      1
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      Enables hybrid dense and BM25 search over a markdown vault, with tools for reading, writing, grepping, and managing notes through any MCP-compatible client.
      12
      MIT