Skip to content
BranchesTags

Repository files navigation

kb-mcp-lite

面向AI代理的轻量级本地知识库 · 团队协作友好

pip install kb-mcp-lite — 让任何AI编程助手都拥有结构化、可查询、可同步的团队"第二大脑"

PyPI version Python License: MIT MCP Status: 测试版

🎯 解决什么问题

当前的知识管理工具存在明显的断层：

  • 面向人类的知识库（Notion/Obsidian）：需要手动维护，AI无法直接高效访问
  • 向量数据库：需要复杂配置，没有结构化Schema，团队协作困难
  • 团队文档散落在各个地方：代码注释、Wiki、PR描述、飞书文档，AI找不到也用不了

kb-mcp-lite 专门填补这个空白：专为AI代理设计，同时兼顾人类编辑和团队协作，让AI编程助手可以直接调用团队沉淀的所有技术知识。

对比维度 Notion/Obsidian Chroma/LanceDB等向量库 kb-mcp-lite
服务对象 人类 模型嵌入 AI代理 + 人类开发者
访问方式 Web UI SDK调用 MCP标准协议（AI原生） + CLI + Web管理后台
结构规范 自由格式 无结构 强Schema（标准化文档类型）
存储方案 云服务/私有部署 本地文件 SQLite + FTS5 单文件存储
团队协作 在线协作 无协作能力 Git原生同步，纯文本版本管理
部署成本 账号/服务器 安装配置 pip install 开箱即用，零配置
数据隐私 云服务存储 本地 完全本地存储，无云服务，无遥测

✨ 核心能力详解

1. 📐 强Schema标准化与结构化Metadata

内置9种开箱即用的文档类型，覆盖技术团队90%的知识沉淀场景，所有类型支持结构化Typed Metadata并可通过Python子类扩展：

文档类型 ID前缀 用途说明 结构化Metadata亮点
project proj 项目/仓库说明文档 记录技术栈、负责人、状态、部署流程
decision dec 架构决策记录(ADR) 结构化记录 status(accepted/superseded)、决策人、替代方案
lesson lesson 经验教训/踩坑记录 结构化记录 severity、根因归类、避坑准则
glossary glossary 术语表 统一业务/技术专有名词标准定义
person person 人员档案 团队成员技术栈、模块分工与联系方式
faq faq 常见问题 沉淀高频问答，消除重复咨询
api api API接口文档 结构化记录 HTTP Method、Path、鉴权与限流要求
runbook runbook 运维手册(SOP) 标准化运维及应急处置步骤
release release 发布日志 版本号、变更清单、影响范围与回滚步骤

优势：

  • 真实结构化元数据：支持 JSON 字段与 Frontmatter 无损互转，AI 可精确抽取与检索事实；
  • 自动生成稳定ID（比如 dec/use-sqlite-fts5），可被跨文档可靠引用；
  • 支持自定义扩展文档类型，满足团队个性化需求。

2. ⚡ Section 级细粒度切片与 Token 保护

传统知识库全量返回整篇文档极易挤占 Agent 上下文空间，造成 Token 浪费。

  • 章节按需获取：kb_get(id="...", section="Architecture") / kb get --section "..." 仅提取目标标题章节；
  • 智能目录感知：未指定章节时或章节不存在时，自动返回可用章节目录清单；
  • 精准降耗：将长文档上下文消耗降低 70%~90%。

3. 🔍 多模式智能搜索

支持四种搜索模式，满足不同场景的查询需求：

  • 词法搜索（默认）：基于 SQLite FTS5，BM25 排序，中英文混合优化，精准匹配关键词，适合查找确定的技术点与专有名词
  • 模糊搜索：基于 Trigram 索引，容错拼写错误、缩写、别名，适合模糊记忆的查询
  • 语义搜索（需安装 kb-mcp-lite[vec]）：基于 sqlite-vec 向量扩展，支持自然语言向量嵌入与语义距离匹配，适合通过模糊概念查找相关知识
  • 混合检索（RRF 融合）：倒数排名融合（Reciprocal Rank Fusion）算法，智能加权词法、模糊与向量检索，自动优雅降级（未启用向量扩展时自动使用 FTS 混合）

搜索能力特性：

  • 支持按文档类型、标签精确过滤
  • 支持 vault="*" 跨库联合搜索
  • 自动关联相关文档的反向链接与一跳邻居节点
  • 搜索结果返回完整结构化信息与相关度评分，AI 可以直接消费
  • 语义搜索采用异步嵌入队列机制，后台静默索引，不阻塞前台文档增删改写入

4. 📜 完整版本控制与审计

所有文档的增删改操作都会被完整记录：

  • 查看任意文档的完整修改历史，每次变更都有版本号
  • 支持版本对比，字段级差异展示，清楚知道改了什么
  • 支持恢复到任意历史版本，误修改可以一键回滚
  • 软删除机制，删除的文档可以随时恢复，不会丢失数据
  • 审计日志记录所有操作，支持审计追踪

5. 🔗 类型化知识图谱

文档之间可以创建带关系的链接：

  • 支持10种标准关系类型：relates-to、supersedes、superseded-by、depends-on、blocks、implements、references、governs、owned-by、tagged-with
  • 支持自定义关系类型（在配置文件中定义）
  • 自动生成反向链接，查找某个决策影响哪些项目，某个Bug关联哪些经验
  • 支持影响分析：当文档变更时，自动识别所有下游受影响的文档
  • 支持决策演进链追踪：查看决策如何随时间演变
  • 支持知识图谱可视化（Web管理后台），直观看到知识之间的关联关系
  • 链接完整性校验，自动检测失效链接

6. 🤝 Git原生团队协作 & 智能三方合并

完全基于Git的团队同步机制，学习成本为零：

  • 智能元数据合并 (3-Way Merge)：多人同时修改文档时，对 tags / aliases / links / metadata 自动做集合并集合并，杜绝 Git 冲突；
  • 自动化文件监听 (Auto-Watcher)：提供 kb watch 命令，支持事件驱动（Linux inotify、macOS FSEvents、Windows ReadDirectoryChangesW）和轮询模式，本地编辑 Markdown 文件实时增量同步至 SQLite 数据库；
  • 自动链接提取：文档添加或更新时，自动从Markdown正文中提取文档引用（[text](id) 和 `id` 语法），创建 references 关系链接；
  • 数据库文件本地存储，不会提交到Git，每个成员有独立的本地实例；
  • 完全兼容现有Git工作流，支持PR评审、分支管理、Code Owner等机制。

7. 🗄️ 多 Vault 隔离与跨库联合检索

支持创建多个独立的知识库，数据完全隔离且支持 MCP 动态路由：

  • 不同项目、不同团队使用独立的vault，互不干扰；
  • 跨库联合搜索：在 MCP 中支持 kb_search(query="...", vault="*")，一次调用同时检索全局公共库与当前项目私有库；
  • 动态单库切换：kb_get(id="...", vault="work") 无需重启服务，随时精准路由；
  • Vault管理：支持创建、切换、列出vault，以及Git同步操作。

8. ⏰ 智能计划任务

内置APScheduler任务调度器，支持自动维护任务：

  • 自动提交：定时导出vault变更并Git提交（默认30分钟）
  • 自动嵌入：定时处理嵌入队列（默认5分钟）
  • 自动重建索引：定时重建FTS5索引（默认每天凌晨3点）
  • 健康检查：定时运行健康检查（默认每周一上午9点）
  • 清理任务：定时清理软删除超过30天的文档（默认每周日凌晨2点）
  • 支持自定义任务间隔和Cron表达式
  • 任务失败自动禁用，支持手动重新启用
  • 跨进程安全，防止并发执行

10. 🖥️ 现代化 Web 管理控制台 (SPA)

内置基于 React + Tailwind CSS + HeroUI 打造的现代化管理后台（kb admin start 自动启动）：

  • 深色/浅色主题适配：完美支持系统与手动切换，高对比度排版与磨砂玻璃质感；
  • 知识图谱可视化：基于 vis-network 的交互式关系图谱拓扑展示，支持节点筛选、高亮与多跳关系钻取；
  • 文档全生命周期管理：提供实时双栏 Markdown 协同编辑器、文档标签/类型过滤、版本差异对比（Diff Viewer）及一键历史回滚；
  • 关系边与语义动词管理：带中文解释的标准关联动词选择器，直观建立文档间的前后置依赖、规范约束及决策替代链；
  • Git 同步与冲突可视化：实时检查本地 SQLite 数据库与 Git 工作区状态，可视化查看未提交文档差异，支持一键拉取（Pull）与推送（Push）；
  • 任务调度与健康看板：直观管理 APScheduler 自动化任务状态、嵌入队列进度及知识库健康诊断修复。

11. 🌐 MCP协议原生支持 (25工具/13资源/7提示)

完全兼容MCP（Model Context Protocol）标准协议，任何支持MCP的客户端（Claude Desktop、Cursor、Composio等）都可以直接接入，AI自动获得以下能力：

25个内置工具

工具名称 功能说明 AI使用场景
kb_add 创建文档 (支持 aliases, metadata, source, id) AI学习到新知识后，自动沉淀结构化事实到知识库
kb_get 获取文档详情 (支持 vault 参数) AI按需拉取完整内容或指定章节，节省上下文 Token
kb_update 更新文档 (支持 aliases, metadata, source) 文档内容过时，AI自动更新补充
kb_delete 软删除文档 废弃的文档，AI可以删除
kb_restore 恢复到指定版本 误修改后回滚
kb_restore_deleted 恢复软删除文档 误删后恢复
kb_search 全文搜索 (支持 mode, vault 通配符) AI遇到问题时，先搜索团队知识库有没有相关解决方案
kb_list 按类型/标签/Vault筛选文档 AI查看所有架构决策、所有项目信息等
kb_link 创建带类型的文档链接 AI发现文档之间的关联关系，自动建立链接
kb_unlink 移除链接 关联关系失效时删除
kb_rel_spec 列出或查看关系类型详情 AI了解可用的文档关系类型
kb_query_relations 多跳图遍历 AI分析文档之间的复杂关系网络
kb_impact 影响分析 AI评估文档变更的影响范围
kb_decision_chain 决策演进链追踪 AI了解决策的演变历史
kb_expand 1跳图扩展 AI查看文档的直接关联文档
kb_similar 嵌入相似度搜索 AI找相关上下文，避免重复沉淀
kb_duplicates 近似重复检测 AI发现并合并重复知识
kb_embed_status 嵌入队列状态 AI了解嵌入处理进度
kb_embed_retry 重新排队失败嵌入 AI修复嵌入失败问题
kb_schedule_list 列出计划任务 AI查看自动任务配置
kb_schedule_status 调度器状态 AI了解任务运行状态
kb_schedule_run 手动触发任务 AI立即执行维护任务
kb_schedule_history 任务执行历史 AI查看任务执行记录
kb_history 版本历史 AI想知道某个决策的变更过程
kb_diff 版本差异对比 AI查看文档修改了什么内容
kb_doctor 健康检查 AI先确认知识库结构和索引是否正常
kb_diff_check Git差异分析 AI分析代码变更并推荐相关文档

批量导入/导出、prune、reindex、vault 和 Git 同步属于 CLI/Admin 生命周期能力，不会作为 MCP 文件系统工具暴露。

13个结构化资源

资源URI 返回内容
kb://doc/{type}/{slug} 完整文档信息
kb://links/{type}/{slug} 文档的所有入站和出站链接
kb://types 所有文档类型的列表
kb://stats 知识库统计信息
kb://graph/{type}/{slug} 以该文档为中心的知识图谱
kb://graph/{type}/{slug}/{depth} 指定深度的知识图谱
kb://list 所有文档列表
kb://list/{type} 按类型筛选的文档列表
kb://changes 最近变更记录
kb://history/{type}/{slug} 指定文档的版本历史
kb://search/{query} 搜索结果
kb://export/{type}/{slug} 导出文档为Markdown
kb://help/{doc} 帮助文档

7个交互Prompt

Prompt名称 用途
new-doc 引导式创建新文档
link-analysis 分析文档链接关系
search-guide 智能搜索助手
import-docs 导入文档指引
doctor 知识库健康检查
maintenance 知识库维护指导
onboarding 新手上手指南

🚀 快速开始使用

🔧 安装方式与依赖选项

kb-mcp-lite 默认采用纯净无 C 扩展的基础安装，保证极速且 100% 跨平台兼容。你可以根据功能需求选择安装对应的可选扩展包：

1. 推荐方式：通过 uv tool 安装 CLI / MCP 服务

# 基础安装（包含 FTS5 全文检索、模糊搜索、多 Vault、Git 同步及 Web 控制台）
uv tool install kb-mcp-lite

# 🌟 推荐：安装包含向量/语义搜索支持（自动集成 sqlite-vec + pysqlite3）
uv tool install "kb-mcp-lite[vec]"

# 🚀 全功能完整版（包含向量语义搜索 + 原生事件驱动文件监听 watchfiles）
uv tool install "kb-mcp-lite[vec,v0_8]"

2. 通过 pip 安装

# 基础安装
pip install kb-mcp-lite

# 开启语义搜索 (Semantic / Vector Search)
pip install "kb-mcp-lite[vec]"

# 开启全功能扩展 (包含 vec 与高性能文件监听)
pip install "kb-mcp-lite[vec,v0_8]"

📌 依赖扩展说明：

  • kb-mcp-lite[vec]：包含 sqlite-vec 与 pysqlite3。如果需要在 Web 控制台或 MCP 中使用 semantic（向量语义检索）或更高精度的 hybrid（混合排序），必须安装此扩展。未安装时系统将自动降级为 FTS5 全文及模糊检索。
  • kb-mcp-lite[v0_8]：包含 watchfiles（Rust 实现的原生文件系统事件监听，支持 Linux inotify、macOS FSEvents、Windows ReadDirectoryChangesW）。未安装时 kb watch 将自动回退为 1 秒间隔的轮询监听。

个人用户基础使用

1. 初始化知识库

kb init

会在默认路径 ~/.local/share/kb-mcp/ 创建默认vault的SQLite数据库。

2. 添加第一个文档

kb add --type project \
       --title "kb-mcp-lite" \
       --tags "mcp,knowledge-base,python" \
       --body "面向AI代理的轻量级本地知识库，基于SQLite + FTS5 + MCP协议开发。"

3. 搜索文档

# 默认搜索
kb search "MCP 知识库"

# 按类型过滤
kb search "sqlite" --type decision

# 模糊搜索
kb search "ft5" --fuzzy

4. 查看已有文档

# 查看所有文档
kb list

# 按类型过滤
kb list --type lesson

# 按标签过滤
kb list --tags "sqlite,bug"

5. 更多CLI命令

# 查看文档详情（完整）
kb get <文档ID>

# 按章节获取文档内容（仅提取特定标题内容，节省Token）
kb get <文档ID> --section "Architecture"

# 更新文档
kb update <文档ID> --title "新标题"

# 删除文档
kb delete <文档ID>

# 查看版本历史
kb history <文档ID>

# 对比版本差异
kb diff <文档ID> --v1 1 --v2 2

# 恢复到指定版本
kb restore <文档ID> --version 2

# 创建文档链接
kb link --from <文档ID1> --to <文档ID2> --rel "relates-to"

# 查看文档链接
kb links <文档ID>

# 影响分析
kb impact <文档ID>

# 决策演进链追踪
kb chain <决策文档ID>

# 关系类型管理
kb rel list                    # 列出所有标准关系类型
kb rel show supersedes         # 查看特定关系详情

# 自动监听 Markdown 目录实时增量同步入库
kb watch --interval 1.0

# 启动Web管理后台
kb admin start

# 计划任务管理
kb scheduler list              # 列出所有任务
kb scheduler status            # 查看调度器状态
kb scheduler run auto-commit   # 手动触发任务
kb scheduler history           # 查看执行历史

# 健康检查
kb doctor

# 统计信息
kb stats

# 清理软删除文档
kb prune --older-than 30

# Git差异分析
kb diff-check

👥 团队协作配置

首次配置团队知识库

  1. 管理员创建团队Git仓库（空仓库即可）
  2. 管理员本地初始化vault并关联Git 
    # 创建团队vault
kb vault create team --desc "XX团队公共知识库"
kb vault switch team

# 克隆团队Git仓库到本地
git clone <团队Git仓库地址> ~/team-kb

# 关联vault和Git同步目录
kb vault init-git --sync-dir ~/team-kb

# 导出已有文档到Git目录并提交
kb vault commit -m "初始化团队知识库"
kb vault push

新成员加入

# 1. 克隆团队知识库Git仓库
git clone <团队Git仓库地址> ~/team-kb

# 2. 创建本地vault
kb vault create team --desc "XX团队公共知识库"
kb vault switch team

# 3. 关联Git同步目录
kb vault init-git --sync-dir ~/team-kb

# 4. 拉取并导入所有文档
kb vault pull

日常协作流程

graph LR
A[AI自动/手动添加修改文档] --> B[拉取最新变更]
B --> C{是否有冲突?}
C -->|是| D[解决Markdown文件冲突]
C -->|否| E[提交本地变更]
D --> E
E --> F[推送到远程仓库]
Loading

日常操作命令：

# 写文档前先拉取最新
kb vault pull

# AI添加/修改文档后，提交变更
kb vault commit -m "添加XX项目部署流程文档"

# 推送到远程仓库
kb vault push

AI工具自动同步配置

如果希望AI调用kb add添加文档后自动同步到Git，可以配置post-hook脚本，在~/.config/kb-mcp/config.yaml中添加：

hooks:
  post_add: "kb vault commit -m 'AI自动添加文档: {doc_title}' && kb vault push"
  post_update: "kb vault commit -m 'AI自动更新文档: {doc_title}' && kb vault push"

🤖 MCP客户端接入配置

Claude Desktop 配置

编辑 ~/.config/claude_desktop_config.json 添加：

{
  "mcpServers": {
    "kb": {
      "command": "kb",
      "args": ["serve"]
    }
  }
}

重启Claude后，AI就可以直接访问你的知识库了。

Cursor 配置

在Cursor设置中找到MCP服务器配置，添加：

  • 名称：kb
  • 命令：kb
  • 参数：["serve"]

指定使用某个vault

如果有多个vault，可以指定启动时使用的vault：

"args": ["serve", "--vault", "team"]

Cline 配置

在Cline设置中找到MCP服务器配置，添加：

  • 名称：kb
  • 命令：kb
  • 参数：["serve"]

OpenCode 配置

在OpenCode配置文件中添加：

{
  "mcpServers": {
    "kb": {
      "command": "kb",
      "args": ["serve"]
    }
  }
}

🔌 高级用法

自定义文档类型

from kb_mcp_lite.schema import Document, Field


class ApiDoc(Document):
    """API接口文档类型"""

    type: str = "api"
    id_prefix: str = "api"

    # 自定义字段
    endpoint: str = Field(description="接口路径")
    method: str = Field(description="HTTP方法")
    version: str = Field(description="接口版本")

    class Config:
        schema_extra = {
            "example": {
                "title": "用户获取接口",
                "endpoint": "/api/v1/user/{id}",
                "method": "GET",
                "version": "v1",
                "tags": ["user", "api"],
                "body": "接口返回用户的基本信息...",
            }
        }

注册后就可以使用 kb add --type api 创建这种类型的文档。

批量导入现有Markdown文档

# 导入目录下所有Markdown文件
kb import ./docs/

# 试运行，查看会导入什么，不实际写入
kb import ./docs/ --dry-run

# 导入后输出JSON格式报告
kb import ./docs/ --json

要求Markdown文件顶部包含YAML frontmatter，至少有type和title字段。

导出知识库

# 导出所有文档到指定目录
kb export ./export_dir/

# 强制覆盖已有文件
kb export ./export_dir/ --force

💡 最佳实践

文档命名与分类规范

  1. 标题清晰准确：用动宾结构或者问题式标题，比如「Redis缓存击穿解决方案」而不是「Redis笔记」
  2. 标签统一规范：所有标签小写，用短横线分隔，比如 redis-cache, bug-fix
  3. 关联关系完整：创建文档时主动关联相关文档，比如决策记录关联对应的项目，经验教训关联对应的Bug决策
  4. 及时更新：文档过时后及时更新，不要保留错误信息

团队协作规范

  1. 提交信息规范：kb vault commit -m "提交信息" 要清晰说明修改内容
  2. PR评审机制：重要文档变更走PR评审，保证知识质量
  3. 定期清理：每个季度运行一次 kb doctor 检查知识库健康度，清理失效文档和链接

AI使用建议

  1. 要求AI解决问题前先搜索知识库，优先使用已有方案
  2. 解决完新问题后，要求AI自动沉淀到知识库作为经验
  3. 定期让AI整理知识库，优化结构、补充关联、更新过时内容

🛠️ 开发指南

本地开发环境搭建

git clone https://github.com/HelloTomBruce/kb-mcp-lite
cd kb-mcp-lite

# 安装依赖（推荐使用uv）
uv sync --extra dev

# 运行测试
uv run pytest

# 代码检查
uv run ruff check .
uv run mypy src/

# 格式化代码
uv run ruff format .
uv run ruff check --fix .

项目结构说明

src/kb_mcp_lite/
├── cli.py              # Click CLI (28 commands)
├── mcp_server.py       # FastMCP server (25 tools, 13 resources, 7 prompts)
├── schema.py           # Document, Link, SearchHit, TypeRegistry, exceptions
├── store.py            # Store Protocol (interface contract)
├── store/              # SQLite存储核心
│   ├── sqlite.py       # SqliteStore (composes 4 mixins)
│   ├── search.py       # SearchMixin — FTS5 + vec0 hybrid search
│   ├── embedding.py    # EmbeddingMixin — vec0 vectors, similarity, duplicates
│   ├── versioning.py   # VersioningMixin — history, snapshots, diff, restore
│   ├── maintenance.py  # MaintenanceMixin — doctor, prune, stats, subgraph
│   ├── embedding_queue.py # EmbeddingQueue — async queue with state machine
│   └── connection.py   # Shared sqlite3 connection factory
├── md_io.py            # Markdown frontmatter parser + bulk import/export
├── vault.py            # Multi-vault management
├── admin/              # FastAPI 后端与静态托管
│   ├── routes_docs.py  # Document CRUD + search
│   └── routes_meta.py  # Overview, links, graph, settings
├── static/app/         # 构建后的现代化 SPA 静态资源
├── migrations/         # Forward-only SQL migration runner
├── config.py           # XDG config loader
├── embedder.py         # OpenAI-compatible embedding client
├── worker.py           # Background embedding worker thread
├── watcher.py          # File watcher (event/poll modes)
├── scheduler.py        # APScheduler task scheduler (5 built-in tasks)
├── graph_query.py      # Multi-hop graph query engine (BFS)
├── relations.py        # Typed relation vocabulary + impact analysis
├── link_parser.py      # Body-level reference parser [text](id)
├── context_guard.py    # Git diff → relevant decisions/lessons
├── merge.py            # 3-way Markdown merge
├── migrations.py       # Forward-only SQL migration runner
└── concurrency/
    └── write_lock.py   # Cross-process flock-based write lock

web/                    # 前端单页应用源码 (React + Tailwind + HeroUI)
├── src/                # 前端组件与页面
│   ├── pages/          # Documents, DocDetail, Git, Links, Graph, Scheduler 等
│   └── components/     # MarkdownRenderer, DiffViewer, Badges 等
└── package.json        # 前端构建配置

📌 状态说明

当前处于Beta测试阶段：

  • API和存储格式从v0.5.0开始已经稳定，不会有破坏性变更
  • v0.8.0 新增：auto-link、关系词汇、调度器、嵌入队列、多跳图查询等
  • 生产环境使用建议锁定版本：kb-mcp-lite>=0.8,<0.9
  • 欢迎提交Issue和PR，贡献代码请查看 CONTRIBUTING.md

📄 许可证

MIT License，可自由使用、修改、分发，保留版权声明即可。

🔗 相关链接

About

No description, website, or topics provided.

Resources

Readme
MIT license

Code of conduct

Code of conduct

Contributing

Contributing
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages